端到端扩展场景用例集 · 场景第五部分
项目 |
内容 |
|---|---|
官方仓库 |
|
业务场景 |
以 Incident Management 示例应用为主线,按 SAP BTP Developer's Guide 把变更记录、审计日志、附件与可观测性等企业级能力逐项加入 CAP 应用,再分别部署到 Cloud Foundry 与 Kyma |
技术栈 |
SAP BTP、CAP、Node.js、Cloud Foundry / Kyma、SAP Audit Log Service、SAP Cloud Logging、SAP Cloud ALM |
对应课程 |
|
对应路径 |
第 2 条 在 SAP BTP 上构建并行扩展 |
为什么值得做:这一部分把「企业级应用」拆成了一份可逐项照做的能力清单。同一套 Incident Management 示例应用,先把变更记录、审计日志、附件、可观测性依次补齐,再把应用分别部署到 Cloud Foundry 与 Kyma——每一步都能独立验证,出了问题也容易定位。
动手要点:
变更记录、审计日志、附件都靠
@cap-js插件加 CDS 注解实现;先在本地跑通,再谈部署。审计日志与可观测性依赖 BTP 上的服务实例,概览里列出的服务名要与子账户中实际分配的权利对应。
部署分 Cloud Foundry 与 Kyma 两条线,命令与清单文件不同,不要混用。
本页内容抓取自官方仓库 SAP-samples/btp-end-to-end-scenario-use-cases,共收录 42 篇官方文档(README 与 docs)。原仓库内容版权归 SAP SE,遵循其许可证。
遵循 SAP BTP Developer's Guide 开发企业级 CAP 应用
借助 SAP BTP Developer's Guide,你可以在 SAP BTP 上实现企业级的 SAP Cloud Application Programming Model(CAP)应用。
基于 SAP BTP Developer's Guide 中的建议,本次动手练习提供一个名为 Incident Management 的示例应用,可作为实用的学习工具,用来集成变更跟踪、审计日志记录、添加附件等企业级能力。

动手练习
设置项目
实现变更跟踪
实现审计日志
遵循 SAP BTP Developer's Guide 开发企业级 CAP 应用
借助 SAP BTP Developer's Guide,你可以在 SAP BTP 上实现企业级的 SAP Cloud Application Programming Model(CAP)应用。
基于 SAP BTP Developer's Guide 中的建议,本次动手练习提供一个名为 Incident Management 的示例应用,可作为实用的学习工具,用来集成变更跟踪、审计日志记录、添加附件等企业级能力。

动手练习
设置项目
实现附件
实现可观测性
设置项目
开始之前,你需要先有一个基础 CAP 应用。可以借助 notebook 按以下步骤快速生成 CAP 应用:
点击此处下载基础的 Incident Management 应用。
在桌面上新建一个文件夹 Handson;如果该文件夹已存在,则新建一个唯一命名的文件夹,例如 Handson-firstname。
将下载的压缩包 incident-management 复制到 Handson 目录并解压。
在 VSCode 中打开 incident-management 文件夹
转到 Terminal - New Terminal。

运行命令
npm install运行命令
cds watch在浏览器中打开应用:
http://localhost:4004
变更跟踪
变更跟踪(Change Tracking)功能用于帮助你监控和管理对数据与内容所做的修改,让你能够有效管理变更并做出有依据的决策。变更跟踪通过 @cap-js/change-tracking 包实现。@cap-js/change-tracking 是一个 CDS 插件,为建模实体的变更记录提供开箱即用的自动捕获、存储与查看支持。
添加变更跟踪插件
由于你已在首选的 IDE 中搭好 Incident Management 应用,接下来引入以下 npm 依赖。
打开 Terminal -> New Terminal
运行以下命令
npm add @cap-js/change-tracking
该包是一个 cds-plugin,意味着它会自动处理许多方面的工作,从而减少对大量配置与注解的需求。
为模型添加注解
引入 cds-plugin 之后,接着在 services.cds 文件中,把 @changelog 注解插入到需要跟踪变更的实体中。
从项目根目录导航到 srv/processor-service.cds,并在其中添加以下注解。
annotate ProcessorService.Incidents with @changelog: {
keys: [ customer.name, createdAt ]
} {
title @changelog;
status @changelog;
customer @changelog: [ customer.name ];
};
annotate ProcessorService.Incidents.conversation with @changelog: {
keys: [ author, timestamp ]
} {
message @changelog;
}
在此上下文中,实体 Incidents 与 Conversations 已被注解,用于监控变更,并指定了要有选择地跟踪的键字段与属性。例如,我们选择只跟踪 title、status 与 customer 这几个属性的修改,而不是监控所有字段。
测试流程
为了测试变更跟踪功能的行为与流程,我们走一个简单的场景。在本节中,我们会修改示例数据集,用该功能跟踪这些修改,然后查看变更历史,观察它如何捕获并记录修改。 开始吧!
在终端中运行
cds watch,在本地打开 Incident Management 应用。打开
http://localhost:4004,进入 incidents 网页应用。如果要求登录,用户名输入
alice,密码字段留空。页面会显示事件列表。打开一个事件并修改其明细。

打开某个事件后,你可以看到一个额外的标签页 Change History。该标签页显示在实现阶段标记为变更跟踪的字段上所做修改的详细信息。要添加新对话,选择 Edit。

新建一个对话并选择 Save。

由于 conversation 实体的 message 字段已标记为变更跟踪,它应当显示在 Change History 中。要查看变更历史,选择 Show More,再选择搜索图标。这样会加载变更跟踪数据。

message 字段的旧值与更新后的值都会显示,同时还会显示变更类型、用户 ID 与修改时间戳。
在 Change History 中,你可以修改事件的标题、状态或客户,并查看相应的变更。


小结
恭喜,你已经成功在应用中实现并测试了变更跟踪功能。
审计日志
审计日志是与安全相关的按时间顺序的记录,为系统活动(例如在给定时间段内执行的系统访问与操作)提供证据。
SAP Audit Log Service
SAP Audit Log 服务存储由 SAP BTP 服务写入的审计日志,这些日志代表了对你的账户与数据所执行的各种操作。 系统预定义了审计类别,代表操作的种类:
数据保护与隐私相关
audit.data-access: 对敏感个人数据访问的读取访问记录;
audit.data-modification: 对敏感个人数据的数据修改记录。
安全相关
audit.security-events: 记录登录、注销等一般安全事件;
audit.configuration: 记录安全关键的配置变更。

为个人数据添加注解
为了尽可能自动完成审计日志记录、个人数据管理与数据保留管理,应用开发者首先要做的、而且往往也是唯一要做的就是:用 @PersonalData 注解标识出(可能)保存个人数据的实体与元素。
在单独的文件 srv/data-privacy.cds 中为域模型添加注解,并填入以下内容:
using {sap.capire.incidents as my} from './services';
using {
cuid,
managed
} from '@sap/cds/common';
annotate my.Customers with @PersonalData: {
EntitySemantics: 'DataSubject',
DataSubjectRole: 'Customer',
} {
ID @PersonalData.FieldSemantics : 'DataSubjectID';
firstName @PersonalData.IsPotentiallyPersonal;
lastName @PersonalData.IsPotentiallyPersonal;
email @PersonalData.IsPotentiallyPersonal;
phone @PersonalData.IsPotentiallyPersonal;
creditCardNo @PersonalData.IsPotentiallySensitive;
}
annotate my.Addresses with @PersonalData: {
EntitySemantics: 'DataSubjectDetails'
} {
customer @PersonalData.FieldSemantics: 'DataSubjectID';
city @PersonalData.IsPotentiallyPersonal;
postCode @PersonalData.IsPotentiallyPersonal;
streetAddress @PersonalData.IsPotentiallyPersonal;
}
添加插件
将以下插件包添加到项目中
npm add @cap-js/audit-logging
执行以下命令构建应用
npm i
该包是一个 cds-plugin,因此会自动完成许多事情,把配置与注解降到最少。
在本地测试
上面的步骤就是自动记录个人数据相关事件所需的全部工作。
创建一个文件
request.http,内容如下:@host = http://localhost:4004 ### Service ### Reading sensitive data (creditCardNo) by default - NOT recommended! GET {{host}}/odata/v4/processor/Customers Authorization: Basic alice:wonderland ### Recommendation: Avoid reading sensitive data by explicitly selecting the fields you need GET {{host}}/odata/v4/processor/Customers?$select=name Authorization: Basic alice:wonderland ### AdminService ### Creating a customer with personal data # @name create_customer POST {{host}}/odata/v4/admin/Customers Authorization: Basic alice:wonderland Content-Type: application/json { "ID": "{{$guid}}", "firstName": "Bob", "lastName": "Builder", "email": "bob.builder@example.com" } ### Updating a customer with personal data details @customer = {{create_customer.response.body.ID}} PATCH {{host}}/odata/v4/admin/Customers('{{customer}}') Authorization: Basic alice:wonderland Content-Type: application/json { "addresses": [ { "city": "Walldorf", "postCode": "69190", "streetAddress": "Dietmar-Hopp-Allee 16" } ] }在
package.json中为alice添加admin角色。"alice": { "roles": ["support", "admin"] }
用户需要
admin角色才能访问admin服务并修改客户的明细。启动服务器。
cds watch
发送这些请求,观察响应中带有来自
\[audit-log\]的PersonalDataModified与SensitiveDataRead事件的日志。
添加自定义审计日志
在审计日志的使用中,有些场景需要生成自定义审计日志。例如,当用户没有相应角色却仍试图访问某些数据时,你想记录 403 - Forbidden 事件。 这可以通过在 CAP 应用中添加自定义处理器来实现。
在 CAP 应用中添加自定义审计日志
CAP 提供多种处理器,可用于捕获事件并添加自定义逻辑(例如自定义审计日志)。为此,请添加以下内容:
在 CAP 应用根目录下创建文件
server.js。添加以下代码:
const cds = require('@sap/cds') let audit cds.on('served', async () => { audit = await cds.connect.to('audit-log') }) const audit_log_403 = (resource, ip) => { // we need to start our own tx because the default tx may be burnt audit.tx(async () => { await audit.log('SecurityEvent', { data: { user: cds.context.user?.id || 'unknown', action: `Attempt to access restricted resource "${resource}" with insufficient authority` }, ip }) }) } // log for non-batch requests cds.on('bootstrap', app => { app.use((req, res, next) => { req.on('close', () => { if (res.statusCode == 403) { const { originalUrl, ip } = req audit_log_403(originalUrl, ip) } }) next() }) }) // log for batch subrequests cds.on('serving', srv => { if (srv instanceof cds.ApplicationService) { srv.on('error', (err, req) => { if (err.code == 403) { const { originalUrl, ip } = req.http.req if (originalUrl.endsWith('/$batch')) audit_log_403(originalUrl.replace('/$batch', req.req.url), ip) } }) } }) module.exports = cds.server
在这段自定义代码中,我们尝试为 403 forbidden 事件生成 security-events。也可以对它加以修改,以包含其他事件。
在本地测试
我们通过执行一些本地 REST 调用来看看自定义审计日志如何工作。
确保服务器已启动并在运行。如果没有,用以下命令启动服务器:
cds watch我们使用 SAP Business Application Studio 的 Rest Extension 来执行 REST 调用。
在文件
request.http中更新以下请求参数:# References @host = localhost:4004 # Service ## ### Get all properteis of all Customers will create Audit Log curl -X GET 'http://{{host}}/odata/v4/processor/Customers' --user 'a:' // change the username
在上面的请求中我们移除了正确的用户,因此它应当抛出 403 错误,从而生成自定义审计日志。
编辑器中会出现若干 Send Request 链接。响应会显示在右侧。
检查你的服务器监听在哪个端口上。必要时更新 @host 引用。
我们仔细看一看,发送请求并检查它们创建了哪些审计日志。 运行读取所有 Customers 的请求。在控制台日志中你会看到类似下面的输出:
[error] - 403 > { code: '403', message: 'Forbidden' }
[audit-log] - SecurityEvent: {
data: {
user: 's',
action: 'Attempt to access restricted resource "/odata/v4/processor/Customers" with insufficient authority'
},
ip: '::ffff:127.0.0.1',
uuid: '294608d9-8c60-4a0b-b122-36365c10b8f1',
tenant: undefined,
user: 's',
time: 2024-11-04T05:10:38.441Z
}
这里我们的自定义处理器正在生成这些自定义 security-events。
小结
恭喜,你已经成功在应用中实现并测试了审计日志功能。
附件
@cap-js/attachments 包是一个 CDS 插件,提供开箱即用的资产存储与处理能力。要使用它,通过预定义的名为 Attachments 的 aspect 扩展域模型即可。它还提供了 CAP 层面、易于使用的 SAP Object Store 集成。
Incident Management 应用中的附件服务简化了事件相关文件的存储与管理。它与 SAP Object Store 服务集成,为事件文档提供安全、高效且可扩展的存储。用户可以在应用内顺畅地上传、访问和管理文件,从而提高工作效率与流程效率。凭借安全存储、高效检索、版本控制与无缝集成等特性,附件服务简化了事件管理流程,使用户能够有效地记录并解决事件。

添加附件插件
要启用附件功能,把所需依赖添加到 package.json。在终端中进入 Incident Management 项目的根目录,运行以下命令:
npm add @cap-js/attachments
注意 - 要使用 Fiori 的 uploadTable 特性,必须确保应用的 index.html 中 SAPUI5 版本更新为 ^1.121.0。
使用附件
在 db 文件夹中创建新文件 attachments.cds。
将以下代码片段复制到新建的 attachments.cds 文件
using { sap.capire.incidents as my } from './schema'; using { Attachments } from '@cap-js/attachments'; extend my.Incidents with { attachments: Composition of many Attachments }
在本地运行并测试应用
我们来看附件存储在本地时的效果;部署之后,例如改用数据库或 S3 存储桶,工作方式也类似。
用以下命令运行应用:
cds watch
导航到事件
Solar panel broken的对象页:Attachments类型会在对象页底部生成一个附件表格:
4. 进入编辑模式并上传文件(使用 PDF 文件 Solar Panel Report.pdf),可以使用附件表格上的 Upload 按钮,也可以拖放。点击 Save 按钮保存文件:
6. 删除文件:进入编辑模式,选择文件,然后在附件表头点击 Delete,再选择 Save,即可从资源中删除该文件。我们通过删除先前上传的 PDF 文件 Solar Panel Report.pdf 来演示这一操作。

小结
恭喜,你已经成功在应用中实现并测试了审计日志功能。
遵循 SAP BTP Developer's Guide 开发企业级 CAP 应用
借助 SAP BTP Developer's Guide,你可以在 SAP BTP 上实现企业级的 SAP Cloud Application Programming Model(CAP)应用。
基于 SAP BTP Developer's Guide 中的建议,本次动手练习提供一个名为 Incident Management 的示例应用,可作为实用的学习工具,用来集成变更跟踪、审计日志记录、添加附件等企业级能力。

设置项目
设置项目
实现变更跟踪
实现变更跟踪
使用 SAP Audit Log Service 设置审计日志
实现审计日志
附件服务
实现附件
附件服务
引言
添加附件服务并在本地测试
添加附件服务
设置
要启用附件功能,把所需依赖添加到 package.json。在终端中进入 Incident Management 项目的根目录,运行以下命令:
npm add @cap-js/attachments
注意 - 要使用 Fiori 的 uploadTable 特性,必须确保应用的 index.html 中 SAPUI5 版本更新为 ^1.121.0。
使用附件
在 db 文件夹中创建新文件 attachments.cds。
将以下代码片段复制到新建的 attachments.cds 文件
using { sap.capire.incidents as my } from './schema'; using { Attachments } from '@cap-js/attachments'; extend my.Incidents with { attachments: Composition of many Attachments }
在本地运行并测试应用
我们来看附件存储在本地时的效果;部署之后,例如改用数据库或 S3 存储桶,工作方式也类似。
用以下命令运行应用:
cds watch
导航到事件
Solar panel broken的对象页:Attachments类型会在对象页底部生成一个附件表格:
4. 进入编辑模式并上传文件(使用 PDF 文件 Solar Panel Report.pdf),可以使用附件表格上的 Upload 按钮,也可以拖放。点击 Save 按钮保存文件:
6. 删除文件:进入编辑模式,选择文件,然后在附件表头点击 Delete,再选择 Save,即可从资源中删除该文件。我们通过删除先前上传的 PDF 文件 Solar Panel Report.pdf 来演示这一操作。

小结
恭喜,你已经成功在应用中实现并测试了审计日志功能。
引言
@cap-js/attachments 包是一个 CDS 插件,提供开箱即用的资产存储与处理能力。要使用它,通过预定义的名为 Attachments 的 aspect 扩展域模型即可。它还提供了 CAP 层面、易于使用的 SAP Object Store 集成。
业务场景
Incident Management 应用中的附件服务简化了事件相关文件的存储与管理。它与 SAP Object Store 服务集成,为事件文档提供安全、高效且可扩展的存储。用户可以在应用内顺畅地上传、访问和管理文件,从而提高工作效率与流程效率。凭借安全存储、高效检索、版本控制与无缝集成等特性,附件服务简化了事件管理流程,使用户能够有效地记录并解决事件。
要跟随本指南操作,请完成前提条件,并确保所有必需的系统都已就绪。
解决方案示意图

后续步骤
添加附件服务
实现审计日志
为个人数据添加注解
为了尽可能自动完成审计日志记录、个人数据管理与数据保留管理,应用开发者首先要做的、而且往往也是唯一要做的就是:用 @PersonalData 注解标识出(可能)保存个人数据的实体与元素。
在单独的文件 srv/data-privacy.cds 中为域模型添加注解,并填入以下内容:
using {sap.capire.incidents as my} from './services';
using {
cuid,
managed
} from '@sap/cds/common';
annotate my.Customers with @PersonalData: {
EntitySemantics: 'DataSubject',
DataSubjectRole: 'Customer',
} {
ID @PersonalData.FieldSemantics : 'DataSubjectID';
firstName @PersonalData.IsPotentiallyPersonal;
lastName @PersonalData.IsPotentiallyPersonal;
email @PersonalData.IsPotentiallyPersonal;
phone @PersonalData.IsPotentiallyPersonal;
creditCardNo @PersonalData.IsPotentiallySensitive;
}
annotate my.Addresses with @PersonalData: {
EntitySemantics: 'DataSubjectDetails'
} {
customer @PersonalData.FieldSemantics: 'DataSubjectID';
city @PersonalData.IsPotentiallyPersonal;
postCode @PersonalData.IsPotentiallyPersonal;
streetAddress @PersonalData.IsPotentiallyPersonal;
}
添加插件
将以下插件包添加到项目中
npm add @cap-js/audit-logging
执行以下命令构建应用
npm i
该包是一个 cds-plugin,因此会自动完成许多事情,把配置与注解降到最少。
在本地测试
上面的步骤就是自动记录个人数据相关事件所需的全部工作。
创建一个文件
request.http,内容如下:@host = http://localhost:4004 ### Service ### Reading sensitive data (creditCardNo) by default - NOT recommended! GET {{host}}/odata/v4/processor/Customers Authorization: Basic alice:wonderland ### Recommendation: Avoid reading sensitive data by explicitly selecting the fields you need GET {{host}}/odata/v4/processor/Customers?$select=name Authorization: Basic alice:wonderland ### AdminService ### Creating a customer with personal data # @name create_customer POST {{host}}/odata/v4/admin/Customers Authorization: Basic alice:wonderland Content-Type: application/json { "ID": "{{$guid}}", "firstName": "Bob", "lastName": "Builder", "email": "bob.builder@example.com" } ### Updating a customer with personal data details @customer = {{create_customer.response.body.ID}} PATCH {{host}}/odata/v4/admin/Customers('{{customer}}') Authorization: Basic alice:wonderland Content-Type: application/json { "addresses": [ { "city": "Walldorf", "postCode": "69190", "streetAddress": "Dietmar-Hopp-Allee 16" } ] }在
package.json中为alice添加admin角色。"alice": { "roles": ["support", "admin"] }
用户需要
admin角色才能访问admin服务并修改客户的明细。启动服务器。
cds watch
发送这些请求,观察响应中带有来自
\[audit-log\]的PersonalDataModified与SensitiveDataRead事件的日志。
添加自定义审计日志
在审计日志的使用中,有些场景需要生成自定义审计日志。例如,当用户没有相应角色却仍试图访问某些数据时,你想记录 403 - Forbidden 事件。 这可以通过在 CAP 应用中添加自定义处理器来实现。
在 CAP 应用中添加自定义审计日志
CAP 提供多种处理器,可用于捕获事件并添加自定义逻辑(例如自定义审计日志)。为此,请添加以下内容:
在 CAP 应用根目录下创建文件
server.js。添加以下代码:
const cds = require('@sap/cds') let audit cds.on('served', async () => { audit = await cds.connect.to('audit-log') }) const audit_log_403 = (resource, ip) => { // we need to start our own tx because the default tx may be burnt audit.tx(async () => { await audit.log('SecurityEvent', { data: { user: cds.context.user?.id || 'unknown', action: `Attempt to access restricted resource "${resource}" with insufficient authority` }, ip }) }) } // log for non-batch requests cds.on('bootstrap', app => { app.use((req, res, next) => { req.on('close', () => { if (res.statusCode == 403) { const { originalUrl, ip } = req audit_log_403(originalUrl, ip) } }) next() }) }) // log for batch subrequests cds.on('serving', srv => { if (srv instanceof cds.ApplicationService) { srv.on('error', (err, req) => { if (err.code == 403) { const { originalUrl, ip } = req.http.req if (originalUrl.endsWith('/$batch')) audit_log_403(originalUrl.replace('/$batch', req.req.url), ip) } }) } }) module.exports = cds.server
在这段自定义代码中,我们尝试为 403 forbidden 事件生成 security-events。也可以对它加以修改,以包含其他事件。
在本地测试
我们通过执行一些本地 REST 调用来看看自定义审计日志如何工作。
确保服务器已启动并在运行。如果没有,用以下命令启动服务器:
cds watch我们使用 SAP Business Application Studio 的 Rest Extension 来执行 REST 调用。
在文件
request.http中更新以下请求参数:# References @host = localhost:4004 # Service ## ### Get all properteis of all Customers will create Audit Log curl -X GET 'http://{{host}}/odata/v4/processor/Customers' --user 'a:' // change the username
在上面的请求中我们移除了正确的用户,因此它应当抛出 403 错误,从而生成自定义审计日志。
编辑器中会出现若干 Send Request 链接。响应会显示在右侧。
检查你的服务器监听在哪个端口上。必要时更新 @host 引用。
我们仔细看一看,发送请求并检查它们创建了哪些审计日志。 运行读取所有 Customers 的请求。在控制台日志中你会看到类似下面的输出:
[error] - 403 > { code: '403', message: 'Forbidden' }
[audit-log] - SecurityEvent: {
data: {
user: 's',
action: 'Attempt to access restricted resource "/odata/v4/processor/Customers" with insufficient authority'
},
ip: '::ffff:127.0.0.1',
uuid: '294608d9-8c60-4a0b-b122-36365c10b8f1',
tenant: undefined,
user: 's',
time: 2024-11-04T05:10:38.441Z
}
这里我们的自定义处理器正在生成这些自定义 security-events。
小结
恭喜,你已经成功在应用中实现并测试了审计日志功能。
后续步骤
实现并测试附件
部署到 SAP Business Technology Platform
根据你所选择的 SAP BTP 运行时,用以下两种方式之一部署应用:
方式 1 - 部署到 Cloud Foundry
方式 2 - 部署到 Kyma
在 Cloud Foundry 上部署并运行应用
使用 SAP Audit Log Service
在本地开发时,我们只是把审计日志消息输出到 stdout;而在生产环境里,我们会使用 SAP BTP 上的 SAP Audit Log Service。
设置服务实例并部署应用
要与 SAP Audit Log Service 集成,你需要:
把服务实例作为已有资源添加到 mta.yml。
resources: - name: incidents-auditlog parameters: service-plan: premium service: auditlog type: org.cloudfoundry.managed-service
在
incident-management-srv的 requires 部分将服务绑定到它。requires: - name: incidents-auditlog
更新
xs-security.json并添加admin角色。最终的xs-security.json如下所示:{ "scopes": [ { "name": "$XSAPPNAME.support", "description": "support" }, { "name": "$XSAPPNAME.admin", "description": "admin" } ], "attributes": [], "role-templates": [ { "name": "support", "description": "generated", "scope-references": [ "$XSAPPNAME.support" ], "attribute-references": [] }, { "name": "admin", "description": "generated", "scope-references": [ "$XSAPPNAME.admin" ], "attribute-references": [] }, { "name": "Token_Exchange", "description": "UAA", "scope-references": [ "uaa.user" ] } ] }
构建 mtar 并部署应用。
mbt build
检查 mta_archives 文件夹中是否已生成 mtar,然后运行:
cf deploy mta_archives/< mtar_name >.mtar
部署成功后,进入 SAP BTP cockpit。在 Subaccount-> Spaces -> Your Space 中检查应用是否已启动并在运行。
在 Service Bindings 中可以看到绑定到应用的服务,其中就有 audit log。

要通过 URL 访问应用,需要为用户分配角色。参见 Assign Application Roles。
编辑上一步创建的角色集合
Incident Management Support,并把admin角色加入其中。确保角色集合Incident Management Support已分配给你的用户。
测试应用
为了测试并生成审计日志,我们会使用以下 API 测试工具之一:
要访问下面的端点,用户需要
support角色,并且必须在请求头中传入xsuaa token。要生成令牌,请使用 XSUAA 实例服务密钥中的以下凭据:
clientId、clientsecret、<url>/oauth/token。

使用 Postman 生成访问令牌。 把授权类型设置为
OAuth 2.0,填入cf username、cf password,然后生成访问令牌。

使用
https://<org>-<space>-incidents-srv.cfapps.sap.hana.ondemand.com/odata/v4/processor/Customers发送请求(上图中的第 7 步)。如果成功,你会在响应中得到客户列表:
{
"@odata.context": "$metadata#Customers",
"value": [
{
"ID": "2b87f6ca-28a2-41d6-8c69-ccf16aa6389d",
"createdAt": null,
"createdBy": null,
"modifiedAt": null,
"modifiedBy": null,
"firstName": "Sunny",
"lastName": "Sunshine",
"email": "sunny.sunshine@demo.com",
"phone": "+01-555-789",
"creditCardNo": null,
"name": "Sunny Sunshine"
},
{
"ID": "8fc8231b-f6d7-43d1-a7e1-725c8e988d18",
"createdAt": null,
"createdBy": null,
"modifiedAt": null,
"modifiedBy": null,
"firstName": "Daniel",
"lastName": "Watts",
"email": "daniel.watts@demo.com",
"phone": "+44-555-123",
"creditCardNo": null,
"name": "Daniel Watts"
},
{
"ID": "feb04eac-f84f-4232-bd4f-80a178f24a17",
"createdAt": null,
"createdBy": null,
"modifiedAt": null,
"modifiedBy": null,
"firstName": "Stormy",
"lastName": "Weathers",
"email": "stormy.weathers@demo.com",
"phone": null,
"creditCardNo": null,
"name": "Stormy Weathers"
}
]
}
读取我们已用 @PersonalData 注解的客户数据时,Cloud Foundry 中会产生一条审计日志记录,你将在下一步中获取它。
在 Kyma 上部署并运行应用
构建镜像
要把源代码(或制品)转换为容器镜像,我们推荐使用 Cloud Native Buildpacks。
在本地开发场景中,可以使用 pack CLI 来使用 Cloud Native Buildpacks。
更多信息参见 About Cloud Native Buildpacks。
登录到你的容器镜像仓库:
docker login docker.io -u <your-user>
开始之前
请注意:
如果你使用的是非 x86 处理器的设备(例如 MacBook M1/M2),需要通过设置 DOCKER_DEFAULT_PLATFORM 环境变量,指示 Docker 使用 x86 镜像:export DOCKER_DEFAULT_PLATFORM=linux/amd64。 参见 Environment variables。
对应用执行生产构建,构建产物写入
gen文件夹。
cds build --production
更新版本号
<image-version>以反映 incident-management-srv 应用中的变更,然后构建incident-management-srv镜像:
pack build <your-container-registry>/incident-management-srv:<image-version> \
--path gen/srv \
--builder paketobuildpacks/builder-jammy-base \
--publish
更新版本号
<image-version>以反映 incident-management-hana-deployer 应用中的变更,然后构建数据库镜像:
pack build <your-container-registry>/incident-management-hana-deployer:<image-version> \
--path gen/db \
--builder paketobuildpacks/builder-jammy-base \
--publish
更新版本号
<image-version>以反映 incident-management-html5-deploye 应用中的变更,然后构建 HTML5 Deployer 镜像。
pack build <your-container-registry>/incident-management-html5-deployer:<image-version> \
--path ui-resources \
--builder paketobuildpacks/builder-jammy-base \
--publish
把容器镜像设置添加到
chart/values.yaml。
...
global:
imagePullSecret:
name: [<image pull secret name>]
...
srv:
image:
repository: <your-container-registry>/incident-management-srv
tag: <srv-image-version>
...
hana-deployer:
image:
repository: <your-container-registry>/incident-management-hana-deployer
tag: <db-deployer-image-version>
...
html5-apps-deployer:
image:
repository: <your-container-registry>/incident-management-html5-deployer
tag: <html5apps-deployer-image-version>
把
SAP_CLOUD_SERVICE的值改为incidents。
html5-apps-deployer:
env:
SAP_CLOUD_SERVICE: incidents
把审计日志服务配置添加到
charts/values.yaml:
auditlog:
serviceOfferingName: auditlog
servicePlanName: premium
在 srv/bindings 中添加:
auditlog:
serviceInstanceName: auditlog
导航到
chart/Charts.yaml,用以下代码更新 dependencies 部分:
- name: service-instance
alias: auditlog
version: ">0.0.0"
更新
xs-security.json并添加admin角色。最终的xs-security.json如下所示:{ "scopes": [ { "name": "$XSAPPNAME.support", "description": "support" }, { "name": "$XSAPPNAME.admin", "description": "admin" } ], "attributes": [], "role-templates": [ { "name": "support", "description": "generated", "scope-references": [ "$XSAPPNAME.support" ], "attribute-references": [] }, { "name": "admin", "description": "generated", "scope-references": [ "$XSAPPNAME.admin" ], "attribute-references": [] }, { "name": "Token_Exchange", "description": "UAA", "scope-references": [ "uaa.user" ] } ] }
将 CAP Helm Chart 部署到 Kyma
登录到你的 Kyma 集群。
创建一个命名空间。
kubectl create namespace incidents-namespace
kubectl label namespace incidents-namespace istio-injection=enabled
使用 Helm 命令部署:
helm upgrade --install incident-management --namespace incidents-namespace ./gen/chart \
--set-file xsuaa.jsonParameters=xs-security.json
该命令会从 chart 文件夹安装 Helm chart,发布名为 incident-management,命名空间为 incidents-namespace。
使用 helm upgrade --install 命令既可以安装新的 chart,也可以升级已有的 chart。
测试应用
为了测试并生成审计日志,我们会使用以下 API 测试工具之一:
要通过 URL 访问应用,需要为用户分配角色。参见 Assign Application Roles。
编辑上一步创建的角色集合
Incident Management Support,并把admin角色加入其中。确保角色集合 Incident Management Support 已分配给你的用户。进入你的 Kyma 集群。从 your-namespace -> Discovery and Networks -> API Rules -> incident-management-srv 获取应用端点。

要访问下面的端点,用户需要
support与admin角色,并且必须在请求头中传入xsuaa token。要生成令牌,请使用 XSUAA 实例中的以下凭据:
clientId、clientsecret、<url>/oauth/token。要获取 xsuaa 凭据,请按以下步骤操作:
转到 your namespace -> Configuration -> Secrets,选择你的 XSUAA 应用。

要解密数据,选择 Decode

使用以下凭据生成访问令牌:
clientId、clientsecret、url。
使用 Postman 生成访问令牌。把授权类型设置为
OAuth 2.0,填入cf username、cf password,然后生成访问令牌。
使用
<your application end point>/odata/v4/processor/Customers发送请求(上图中的第 7 步)。如果成功,你会在响应中得到客户列表:
{
"@odata.context": "$metadata#Customers",
"value": [
{
"ID": "2b87f6ca-28a2-41d6-8c69-ccf16aa6389d",
"createdAt": null,
"createdBy": null,
"modifiedAt": null,
"modifiedBy": null,
"firstName": "Sunny",
"lastName": "Sunshine",
"email": "sunny.sunshine@demo.com",
"phone": "+01-555-789",
"creditCardNo": null,
"name": "Sunny Sunshine"
},
{
"ID": "8fc8231b-f6d7-43d1-a7e1-725c8e988d18",
"createdAt": null,
"createdBy": null,
"modifiedAt": null,
"modifiedBy": null,
"firstName": "Daniel",
"lastName": "Watts",
"email": "daniel.watts@demo.com",
"phone": "+44-555-123",
"creditCardNo": null,
"name": "Daniel Watts"
},
{
"ID": "feb04eac-f84f-4232-bd4f-80a178f24a17",
"createdAt": null,
"createdBy": null,
"modifiedAt": null,
"modifiedBy": null,
"firstName": "Stormy",
"lastName": "Weathers",
"email": "stormy.weathers@demo.com",
"phone": null,
"creditCardNo": null,
"name": "Stormy Weathers"
}
]
}
读取我们已用 @PersonalData 注解的客户数据时,Cloud Foundry 中会产生一条审计日志记录,你将在下一步中获取它。
6-access-auditlog
使用 SAP Audit Log Viewer 服务访问审计日志
SAP Audit Log Viewer 服务显示你的 Cloud Foundry 账户中由你订阅的 SAP 应用与服务所产生的审计日志。 参见 Audit Log Viewer for the Cloud Foundry Environment。
要使用 SAP Audit Log Viewer 服务,请在 SAP BTP cockpit 中订阅它。 在 your subaccount -> Services-> Instances and Subscriptions -> Subscriptions 中,选择
default或free服务计划。
订阅完成后,选择 Go to Application 打开 SAP Audit Log Viewer 服务并登录。
要使用 SAP Audit Log Viewer 服务检索子账户的审计日志,你需要具备相应的授权。
创建一个角色集合
auditlog-viewer。在 your subaccount-> Role Collections 中选择 Create。添加以下角色并保存:

把这个角色集合分配到你的用户。
访问 Audit Log Viewer Service,你会看到审计日志列表。
按
data-access过滤日志,调整时间范围,你会看到类似的日志条目:
如果你看到如上所示的日志,说明你已成功集成 Audit Logging 服务。
使用 SAP Audit Log Viewer 服务访问自定义审计日志
在上一节自定义实现审计日志的过程中,你已经添加了生成自定义审计日志的步骤。 要访问这些日志,需要按以下步骤操作:
从你的用户上移除
Support角色。稍后可以再加回来。使用 Postman/Insomania 或你选择的其他工具,像上一节那样向
https://<org>-<space>-incidents-srv.cfapps.sap.hana.ondemand.com/odata/v4/admin/Customers发送请求。现在在
Audit Log Viewer应用中按security-events过滤日志。现在你就能看到自定义审计日志了。

使用 SAP Audit Log Service 实现审计日志
引言
前提条件
实现审计日志
将 Incident Management 应用部署到 SAP BTP Cloud Foundry 运行时
访问审计日志
使用 SAP Audit Log Service 设置审计日志
引言
前提条件
实现审计日志
将 Incident Management 应用部署到 SAP BTP Kyma 运行时
访问审计日志
引言
审计日志是与安全相关的按时间顺序的记录,为系统活动(例如在给定时间段内执行的系统访问与操作)提供证据。
SAP Audit Log Service
SAP Audit Log 服务存储由 SAP BTP 服务写入的审计日志,这些日志代表了对你的账户与数据所执行的各种操作。 系统预定义了审计类别,代表操作的种类:
数据保护与隐私相关
audit.data-access: 对敏感个人数据访问的读取访问记录;
audit.data-modification: 对敏感个人数据的数据修改记录。
安全相关
audit.security-events: 记录登录、注销等一般安全事件;
audit.configuration: 记录安全关键的配置变更。
解决方案示意图

后续步骤
实现审计日志并在本地测试
使用 SAP Audit Log Service 设置审计日志
引言
前提条件
实现审计日志
实现变更跟踪
本教程将介绍如何把变更跟踪功能集成到已有的 Incident Management 应用中。
设置
由于你已在首选的 IDE 中搭好 Incident Management 应用,接下来引入以下 npm 依赖。
打开 Terminal -> New Terminal
运行以下命令
npm add @cap-js/change-tracking
该包是一个 cds-plugin,意味着它会自动处理许多方面的工作,从而减少对大量配置与注解的需求。
为模型添加注解
引入 cds-plugin 之后,接着在 services.cds 文件中,把 @changelog 注解插入到需要跟踪变更的实体中。
把以下注解添加到 services.cds 文件中。
annotate ProcessorService.Incidents with @changelog: {
keys: [ customer.name, createdAt ]
} {
title @changelog;
status @changelog;
customer @changelog: [ customer.name ];
};
annotate ProcessorService.Incidents.conversation with @changelog: {
keys: [ author, timestamp ]
} {
message @changelog;
}
在此上下文中,实体 Incidents 与 Conversations 已被注解,用于监控变更,并指定了要有选择地跟踪的键字段与属性。例如,我们选择只跟踪 title、status 与 customer 这几个属性的修改,而不是监控所有字段。
在本地测试应用
在本地测试应用
小结
关键改动已成功实现,接下来该部署应用,以使用它提供的能力。
部署到 SAP Business Technology Platform
根据你打算把应用部署到 Cloud Foundry 还是 Kyma 运行时,选择下面的相应教程,同时要考虑在准备生产阶段所选择的目标平台。
参见:
部署到 Cloud Foundry
部署到 Kyma
小结
部署到 Cloud Foundry
用以下命令把所有内容组装成单个
mta.tar归档文件:
mbt build
有关基于 MTA 的部署的更多信息,参见 Multitarget Applications in the Cloud Foundry Environment。
确保已登录到你的子账户:
cf api <API-ENDPOINT> cf login -u <USER-ID> -p <PASSWORD> cf target -o <ORG> -s <SPACE>
提示:
你可以在子账户的 Overview 部分找到 API 端点。
导航到
mta_archives文件夹,把生成的归档文件部署到 Cloud Foundry:cf deploy incident-management_1.0.0.mtar
这个过程可能需要几分钟,最终会输出类似下面的日志:
[…]
Application "incident-management-srv" started and available at
"[org]-[space]-incident-management.landscape-domain.com"
要通过 URL 访问应用,你必须分配应用角色。
下一步,要在 launchpad 中访问应用,请继续阅读与 SAP Build Workzone 集成。
小结
变更跟踪已部署到 Cloud Foundry,并已集成到 SAP Build Workzone 中。
部署到 Kyma
构建镜像
要把源代码(或制品)转换为容器镜像,我们推荐使用 Cloud Native Buildpacks。
在本地开发场景中,可以使用 pack CLI 来使用 Cloud Native Buildpacks。
更多信息参见 About Cloud Native Buildpacks。
登录到你的容器镜像仓库:
docker login docker.io -u <your-user>
开始之前
请注意:
如果你使用的是非 x86 处理器的设备(例如 MacBook M1/M2),需要通过设置 DOCKER_DEFAULT_PLATFORM 环境变量,指示 Docker 使用 x86 镜像:export DOCKER_DEFAULT_PLATFORM=linux/amd64。 参见 Environment variables。
对应用执行生产构建,构建产物写入
gen文件夹:
cds build --production
使用以下命令构建 UI 应用:
cd app/incidents
npm run build
现在把终端切回应用根目录。
务必在文件发生变更时更新镜像版本。一旦遗漏,部署后将看不到新的改动。
更新版本号
<image-version>以反映 incident-management-srv 应用中的变更,然后构建incident-management-srv镜像。
pack build <your-container-registry>/incident-management-srv:<image-version> \
--path gen/srv \
--builder paketobuildpacks/builder-jammy-base \
--publish
更新版本号
<image-version>以反映 incident-management-hana-deployer 应用中的变更,然后构建数据库镜像。
pack build <your-container-registry>/incident-management-hana-deployer:<image-version> \
--path gen/db \
--builder paketobuildpacks/builder-jammy-base \
--publish
更新版本号
<image-version>以反映 incident-management-html5-deployer 应用中的变更,然后构建 HTML5 Deployer 镜像。
pack build <your-container-registry>/incident-management-html5-deployer:<image-version> \
--path ui-resources \
--builder paketobuildpacks/builder-jammy-base \
--publish
把容器镜像设置添加到
chart/values.yaml。
...
global:
imagePullSecret:
name: [<image pull secret name>]
...
srv:
image:
repository: <your-container-registry>/incident-management-srv
tag: <srv-image-version>
...
hana-deployer:
image:
repository: <your-container-registry>/incident-management-hana-deployer
tag: <db-deployer-image-version>
...
html5-apps-deployer:
image:
repository: <your-container-registry>/incident-management-html5-deployer
tag: <html5apps-deployer-image-version>
再次使用
cds build --production构建应用
将 CAP Helm Chart 部署到 Kyma
登录到你的 Kyma 集群。
创建一个命名空间。
kubectl create namespace incidents-namespace
kubectl label namespace incidents-namespace istio-injection=enabled
使用 Helm 命令部署:
helm upgrade --install incident-management --namespace incidents-namespace ./gen/chart \
--set-file xsuaa.jsonParameters=xs-security.json
该命令会从 chart 文件夹安装 Helm chart,发布名为 incident-management,命名空间为 incidents-namespace。
提示: 使用 helm upgrade --install 命令,既可以安装新的 chart,也可以升级已有的 chart。
安装结果大致如下:

要通过 URL 访问应用,你必须分配应用角色。
下一步,要在 launchpad 中访问应用,请继续阅读与 SAP Build Workzone 集成。
查看变更历史
为了测试变更跟踪功能的行为与流程,我们走一个简单的场景。在本节中,我们会修改示例数据集,用该功能跟踪这些修改,然后查看变更历史,观察它如何捕获并记录修改。 开始吧!
在本地打开 Incident Management 应用。

页面会显示事件列表。打开一个事件并修改其明细。

打开某个事件后,你可以看到一个额外的标签页 Change History。该标签页显示在实现阶段标记为变更跟踪的字段上所做修改的详细信息。要添加新对话,选择 Edit。

新建一个对话并选择 Save。

由于 conversation 实体的 message 字段已标记为变更跟踪,它应当显示在 Change History 中。要查看变更历史,选择 Show More,再选择搜索图标。这样会加载变更跟踪数据。

message 字段的旧值与更新后的值都会显示,同时还会显示变更类型、用户 ID 与修改时间戳。
在 Change History 中,你可以修改事件的标题、状态或客户,并查看相应的变更。


小结
恭喜,你已经成功在应用中实现并测试了变更跟踪功能。
下一步
实现并测试审计日志
实现变更跟踪
引言
前提条件
实现变更跟踪
方式 1 - 将 Incident Management 应用部署到 SAP BTP Cloud Foundry 运行时
方式 2 - 将 Incident Management 应用部署到 SAP BTP Kyma 运行时
查看变更历史
实现变更跟踪
引言
前提条件
实现变更跟踪
将 Incident Management 应用部署到 SAP BTP Cloud Foundry 运行时
查看变更历史
实现变更跟踪
引言
前提条件
实现变更跟踪
将 Incident Management 应用部署到 SAP BTP Kyma 运行时
查看变更历史
引言
变更跟踪(Change Tracking)功能用于帮助你监控和管理对数据与内容所做的修改,让你能够有效管理变更并做出有依据的决策。变更跟踪通过 @cap-js/change-tracking 包实现。@cap-js/change-tracking 是一个 CDS 插件,为建模实体的变更记录提供开箱即用的自动捕获、存储与查看支持。
后续步骤
实现变更跟踪
前提条件
按照分步教程 Develop a Full-Stack CAP Application 开发 Incident Management 应用。
把 Incident Management 应用部署到以下 SAP BTP 运行时之一:
方式 1:SAP BTP, Cloud Foundry 运行时:Deploy a Full-Stack CAP Application in SAP BTP, Cloud Foundry Runtime。
方式 2:SAP BTP, Kyma 运行时:Deploy a Full-Stack CAP Application in SAP BTP, Kyma Runtime。
运行以下命令取消部署应用:
对于 SAP BTP, Cloud Foundry 运行时:
cf undeploy <YOUR_MTA_ID> --delete-services对于 SAP BTP, Kyma 运行时:
helm uninstall <RELEASE_NAME> -n <YOUR_NAMESPACE>
前提条件
按照分步教程 Develop a Full-Stack CAP Application 开发 Incident Management 应用。
已将 Incident Management 应用部署到 SAP BTP, Cloud Foundry 运行时:Deploy a Full-Stack CAP Application in SAP BTP, Cloud Foundry Runtime。
运行以下命令取消部署应用:
cf undeploy <YOUR_MTA_ID> --delete-services
前提条件
按照分步教程 Develop a Full-Stack CAP Application 开发 Incident Management 应用。
已将 Incident Management 应用部署到 SAP BTP, Kyma 运行时:Deploy a Full-Stack CAP Application in SAP BTP, Kyma Runtime。
运行以下命令取消部署应用:
helm uninstall <RELEASE_NAME> -n <YOUR_NAMESPACE>
设置自定义日志收集
应用日志记录是在软件执行期间记录有价值信息与事件的实践。日志会被持久化保存,以便保留活动、错误与用户交互的历史记录。日志按不同级别分类,例如 DEBUG、INFO、WARN、ERROR 与 FATAL,用于表明其重要性与严重程度。
建议将日志的分析与持久化交给标准化、集中且托管的服务,例如 SAP Cloud Logging。
前提条件
你已搭好 Incident Management 应用。参见 Develop a Full-Stack CAP Application Following SAP BTP Developer's Guide 教程组。
为应用添加自定义日志
要在 Incident Management 应用中添加日志,可以利用 CAP 提供的极简日志门面(logging facade)。要为 Incident Management 应用添加日志功能:
打开
srv/processor-service.js。把以下代码行添加到 srv/services.js 文件的代码中。
const LOG = cds.log('processor-service');
要在自定义逻辑中定义日志,把以下代码行添加到 srv/services.js 文件的代码中。
if (status_code === 'C'){ LOG.info(`Incident ${req.data.ID} has already been closed`); return req.reject(`Can't modify a closed incident`) }
定义日志级别
通过 cds.env.log.levels 按模块配置初始日志级别,例如在 package.json 中这样写:
{
"cds": {
...
"log": {
"levels": {
"sqlite": "debug",
"cds": "info"
}
}
...
}
}
在本地运行并测试
应用具备所有必需的配置后,就可以在本地测试了。
在终端中用
cds watch命令运行应用。打开应用并创建一个事件。
要查看自定义日志,试着修改一个已关闭事件的紧急程度。你会在控制台中看到类似下面的内容:
[processor-service] - Incident 3b23bb4b-4ac7-4a24-ac02-aa10cabd842c has already been closed
后续步骤
设置跟踪收集
3-implement-traces
设置跟踪收集
跟踪(trace)让你可以分析请求、消息或任务在整个分布式系统中的处理过程。为此,@cap-js/telemetry 包装了 cds.Service 及其派生类的所有关键函数。对于 @cap-js 数据库(例如 @cap-js/sqlite),这包括 prepare() 及其后的 stmt.run()。
方式 1:配置 SAP BTP, Cloud Foundry 运行时部署
如果你要把应用部署到 SAP BTP, Cloud Foundry 运行时,请在应用根目录打开终端,用以下命令添加所需依赖:
cds add cloud-logging --with-telemetry
注意:CAP 通过 @cap-js/telemetry CDS 插件提供自定义指标与跟踪。
这会给你的应用添加以下依赖与配置:
在
package.json中:"dependencies": { "@cap-js/telemetry": ">=0", "@grpc/grpc-js": "^1", "@opentelemetry/exporter-metrics-otlp-grpc": "^0", "@opentelemetry/exporter-trace-otlp-grpc": "^0", "@opentelemetry/host-metrics": "^0", }
在
mta.yaml中:modules: - name: incident-management-srv type: nodejs path: gen/srv requires: - name: incident-management-auth - name: incident-management-db - name: incident-management-cloud-logging # Added resources: - name: incident-management-cloud-logging ## Cloud Logging Module Added type: org.cloudfoundry.managed-service parameters: service: cloud-logging service-plan: standard config: ingest_otlp: enabled: true
参见 Predefined Kinds。
注意:你执行上述命令时,这些依赖的版本可能有所不同,不必强求匹配这些依赖的版本号。
方式 2:配置 SAP BTP, Kyma 运行时部署
如果你要部署到 SAP BTP, Kyma 运行时,请按以下步骤操作:
在应用根目录打开终端并添加以下依赖:
npm add @cap-js/telemetry @opentelemetry/exporter-metrics-otlp-grpc @opentelemetry/exporter-trace-otlp-grpc @opentelemetry/host-metrics @grpc/grpc-js
注意:由于 @cap-js/telemetry 目前尚不支持 OpenTelemetry SDK 2.0,请把 @opentelemetry/exporter-metrics-otlp-grpc 与 @opentelemetry/exporter-trace-otlp-grpc 依赖的版本更新为
0.57.2。
...
"dependencies": {
...
"@opentelemetry/exporter-metrics-otlp-grpc": "0.57.2",
"@opentelemetry/exporter-trace-otlp-grpc": "0.57.2"
...
},
...
用 "telemetry": {"kind": "to-otlp"} 更新
package.json文件的代码,如下所示:
....
"cds": {
"requires": {
....
"[production]": {
"telemetry": {
"kind": "to-otlp"
},
}
....
如果
package.json中存在属性"telemetry":"to-cloud-logging",请将其删除。
在本地运行并测试
应用具备所有必需的配置后,就可以在本地测试了。
在终端中用
cds watch命令运行应用。打开应用并创建一个事件。
在终端中检查日志:
[telemetry] - elapsed times: 0.00 → 95.53 = 95.53 ms POST /odata/v4/processor/$batch 10.07 → 92.64 = 82.56 ms GET Incidents?$count=true&$filter=(IsActiveEntity%20eq%20false%20or%20SiblingEnt… 35.54 → 55.97 = 20.43 ms ProcessorService - READ ProcessorService.Incidents.drafts 38.75 → 55.82 = 17.07 ms db - READ ProcessorService.Incidents.drafts 53.87 → 54.76 = 0.88 ms @cap-js/sqlite - prepare SELECT json_insert('{}','$."HasActiveEntity"',CASE HasA… 55.24 → 55.60 = 0.35 ms @cap-js/sqlite - stmt.all SELECT json_insert('{}','$."HasActiveEntity"',CASE Has… 56.92 → 71.60 = 14.68 ms ProcessorService - READ ProcessorService.Incidents 57.75 → 71.40 = 13.65 ms db - READ ProcessorService.Incidents 69.26 → 70.03 = 0.76 ms @cap-js/sqlite - prepare SELECT json_insert('{}','$."ID"',ID,'$."title"',title,'… 70.16 → 70.78 = 0.61 ms @cap-js/sqlite - stmt.all SELECT json_insert('{}','$."ID"',ID,'$."title"',title,… 72.21 → 74.65 = 2.43 ms ProcessorService - READ ProcessorService.Incidents.drafts 72.75 → 74.59 = 1.84 ms db - READ ProcessorService.Incidents.drafts 73.83 → 74.22 = 0.39 ms @cap-js/sqlite - prepare SELECT json_insert('{}','$."ID"',ID) as _json_ FROM (SE… 74.31 → 74.54 = 0.22 ms @cap-js/sqlite - stmt.all SELECT json_insert('{}','$."ID"',ID) as _json_ FROM (S…
后续步骤
设置指标收集
在 SAP BTP, Cloud Foundry 运行时中启用可观测性
设置 SAP Cloud Logging 服务
要在 SAP BTP, Cloud Foundry 运行时中访问并分析可观测性遥测信号,请使用 SAP Cloud Logging 服务。要配置 SAP Cloud Logging 服务,在 resources 下添加 Cloud Logging 配置,并在 requires 部分把它绑定到 incident-management 服务。
- name: incident-management
type: nodejs
path: gen/srv
parameters:
buildpack: nodejs_buildpack
memory: 256MB
build-parameters:
builder: npm-ci
provides:
- name: srv-api # required by consumers of CAP services (e.g. approuter)
properties:
srv-url: ${default-url}
requires:
- name: incidents-auth
- name: incidents-db
- name: incidents-cloud-logging ## add cloud logging service instance
...
resources:
...
- name: incidents-cloud-logging
type: org.cloudfoundry.existing-service
在 SAP BTP, Cloud Foundry 运行时中部署 Incident Management 应用
用以下命令把所有内容组装成单个
mta.tar归档文件:mbt build
有关基于 MTA 的部署的更多信息,参见 Multitarget Applications in the Cloud Foundry Runtime。
确保已登录到你的子账户:
导航到
mta_archives文件夹,用以下命令把生成的归档文件部署到 SAP BTP, Cloud Foundry 运行时:cf deploy incident-management_1.0.0.mtar
这个过程可能需要几分钟,最终会输出类似下面的日志:
[…]
Application "incident-management-srv" started and available at
"[org]-[space]-incident-management.[landscape-domain].com"
小结
应用已部署到 SAP BTP, Cloud Foundry 运行时,其中包含自定义日志、指标与跟踪收集,并已集成到 SAP Build Work Zone。
可视化日志、指标与跟踪
访问自定义日志、指标与跟踪
在 SAP BTP, Cloud Foundry 运行时中启用可观测性
在 SAP BTP, Cloud Foundry 运行时中部署 Incident Management 应用
用以下命令把所有内容组装成单个
mta.tar归档文件:mbt build
有关基于 MTA 的部署的更多信息,参见 Multitarget Applications in the Cloud Foundry Runtime。
确保已登录到你的子账户:
cf api <API-ENDPOINT> cf login -u <USER-ID> -p <PASSWORD> cf target -o <ORG> -s <SPACE>
提示:
你可以在子账户的 Overview 部分找到 API 端点。
导航到
mta_archives文件夹,用以下命令把生成的归档文件部署到 SAP BTP, Cloud Foundry 运行时:cf deploy incident-management_1.0.0.mtar
这个过程可能需要几分钟,最终会输出类似下面的日志:
[…]
Application "incident-management-srv" started and available at
"[org]-[space]-incident-management.[landscape-domain].com"
要通过 URL 访问应用,你必须为应用分配特定角色。参见 Assign Application Roles。
下一步,要在 launchpad 中访问应用,请继续阅读与 SAP Build Workzone 集成。
小结
应用已部署到 SAP BTP, Cloud Foundry 运行时,其中包含自定义日志、指标与跟踪收集,并已集成到 SAP Build Work Zone。
可视化日志、指标与跟踪
访问自定义日志、指标与跟踪
在 SAP BTP, Kyma 运行时中启用可观测性
前提条件
添加 Kyma Telemetry 模块,并遵循 Add and Delete a Kyma Module Using Kyma Dashboard 中描述的步骤。
为你的子账户分配了服务
cloud-logging的权利。
设置 SAP Cloud Logging 并与 SAP BTP, Kyma 运行时集成
要创建 SAP Cloud Logging 实例,并把日志、指标与跟踪从 SAP BTP, Kyma 运行时流式传输到该实例,需要按以下步骤操作:
登录到 Kyma 集群。
[!TIP] 要登录 Kyma 集群,请遵循 Access a Kyma Instance Using kubectl。
用以下命令创建命名空间:
kubectl create namespace sap-cloud-logging-integration
创建新文件
cloud-logging-instance.yaml,并粘贴以下代码:apiVersion: services.cloud.sap.com/v1 kind: ServiceInstance metadata: name: sap-cloud-logging spec: serviceOfferingName: cloud-logging servicePlanName: standard externalName: cloud-logging-created-with-sap-btp-service-operators parameters: ingest_otlp: enabled: true
ingest_otlp会启用对基于 OpenTelemetry 的数据的支持,这是摄取分布式跟踪与指标所必需的。用以下命令应用配置:
kubectl apply -n sap-cloud-logging-integration -f cloud-logging-instance.yaml
这会触发 SAP Cloud Logging 实例的预配。
[!TIP] 在本指南中,你通过 SAP BTP service operator 创建 SAP Cloud Logging 实例,这是推荐的做法。它会负责创建并定期轮换所需的密钥。参见 Create an SAP Cloud Logging Instance through SAP BTP Service Operator。 不过,你也可以选择任何其他方式创建实例与密钥,只要实例中启用了 OTLP 摄取参数即可。详情参见 Configuration Parameters。
等待实例创建完成。可以用以下命令检查其状态:
kubectl get serviceinstances.services.cloud.sap.com -o yaml -n sap-cloud-logging-integration
实例创建完成后,创建一个绑定,它提供所需的 SAP Cloud Logging 服务密钥。创建文件
cloud-logging-binding.yaml,并粘贴以下代码:apiVersion: services.cloud.sap.com/v1 kind: ServiceBinding metadata: name: cls-binding spec: serviceInstanceName: sap-cloud-logging externalName: cloud-logging-created-with-sap-btp-service-operators secretName: sap-cloud-logging credentialsRotationPolicy: enabled: true rotationFrequency: 1440h
要应用配置,使用以下命令:
kubectl apply -n sap-cloud-logging-integration -f cloud-logging-binding.yaml
把日志发送到 SAP Cloud Logging 服务。参见 Ship Logs to SAP Cloud Logging。
把分布式跟踪发送到 SAP Cloud Logging 服务。参见 Ship Distributed Traces to SAP Cloud Logging。
把指标发送到 SAP Cloud Logging 服务。参见 Ship Metrics to SAP Cloud Logging。
配置应用后,可以在 Kyma dashboard 中检查所有遥测配置的状态。它们应当如下所示:

[!TIP] 了解如何访问 Kyma dashboard。
为方便访问,调整 Kyma dashboard 导航。参见 Kyma Dashboard Integration。
在 SAP BTP, Kyma 运行时中部署 Incident Management 应用
按照 Deploy a Full-Stack CAP Application in SAP BTP, Kyma Runtime 教程中的步骤操作。
可视化日志、指标与跟踪
验证设置,并在新预配的 SAP Cloud Logging 实例中访问已部署应用的自定义日志、指标与跟踪。
使用 SAP Cloud Logging 服务访问日志、指标与跟踪
要在 SAP BTP cockpit 中访问日志,导航到你的子账户,选择 Services > Instances and Subscriptions。
前提条件
已将 SAP Cloud Identity Services 的 Identity Authentication SAML 2.0 与 SAP Cloud Logging 集成。参见将 SAP Cloud Identity Services 的 Identity Authentication SAML 2.0 与 SAP Cloud Logging 集成。
[!TIP] 如果没有 SAP Cloud Identity Services,你可以在 Cloud Foundry 运行时中使用服务密钥登录。对于 Kyma,sap-cloud-logging-integration 命名空间下的 secrets 中会有用于登录的 dashboard URL、用户名与密码。
访问 SAP Cloud Logging 服务
在 SAP BTP cockpit 中导航到你的子账户,选择 Services > Instances and Subscriptions。然后选择 Instances 标签页。

选择 incidents-cloud-logging 打开 SAP Cloud Logging Dashboard。提供 SAP Identity and Authentication 租户的凭据。
根据应用部署所在的运行时,选择以下之一:
如果应用部署在 SAP BTP, Cloud Foundry 运行时,选择 CF,如下方截图高亮所示:
这一步会打开 Cloud Foundry 概览,展示许多关键的应用指标与统计信息。
如果应用部署在 SAP BTP, Kyma 运行时,选择 Kyma。
选择要显示指标的时间范围。例如选择 Last 30 minutes 或 Last 24 hours,然后选择 Apply。 将显示以下指标:
CAP 框架会生成请求、错误、信息日志,日志级别可以更改。参见 CAP 文档中的 Configuring Log Levels。
要显示应用日志,点击左侧的面包屑导航,选择 Discover。
通过将鼠标悬停在标签上并选择“+”来选择过滤器。选择
msg,app_name,loggger。
现在可以按如下方式可视化日志:
[!NOTE] 默认日志由 CAP 框架生成。在
logger中,框架日志可以通过cds或odata标签识别。 自定义日志可以通过用户在声明 cds 自定义日志时定义的标签识别。例如const LOG = cds.log('incident-customlog'),由自定义 logger 生成的日志会带有incident-customlog标签,如上方截图所示。
如果你使用的是 SAP BTP, Kyma 运行时,需要选择
logs-json-kyma-*。 日志将如下所示:
访问应用指标
在屏幕左侧点击面包屑导航,选择 Discover。
在 Discover Screen 中,默认选中
logs-cfsyslog-*。你可以看到应用日志。选择
logs-cfsyslog-*,会出现下拉菜单。选择metrics-otel-v1-*。这样会显示应用的指标。在屏幕左侧选择字段,以查看特定字段。输出应当如下所示:

为自定义指标创建可视化
在上一章中,你创建了一个自定义指标,用于统计“High”紧急程度的事件。你可以创建自定义可视化来展示该计数。
在左侧面包屑导航中选择 Visualize。
选择 Create visualization。
出现一个对话框。选择 Metric。
在屏幕右侧选择 Metric。
选择 Aggregation 下的下拉菜单,选择 Top Hit。
选择 Field 下拉菜单,选择 value。
在 Custom 标签下输入名称,例如 High Urgency Incidents。
在屏幕底部选择 Update。
可视化即创建完成。
你可以保存该可视化,以便快速访问。
访问跟踪
要查看跟踪,在左侧选择
logs-cfsyslog-*,会出现下拉菜单。选择otel-v1-apm-span-*。跟踪将如下所示:

[!WARNING] 跟踪最多需要 3 分钟才会出现在 Cloud Logging Dashboard 中。如果仍看不到跟踪,请重试。
可视化跟踪
你可以把跟踪可视化为时间线。为此:
在 Cloud Logging Dashboard 中,选择左侧菜单,然后选择 Observability。
选择 Trace Analytics > Traces。如果仍看不到跟踪,把持续时间增加到 15 分钟。

选择其中一条跟踪,它会显示各个跟踪的时间线。

遵循 SAP BTP Developer's Guide 在全栈 CAP 应用中实现可观测性
引言
设置自定义日志收集
设置跟踪收集
设置指标收集
引言
可观测性(Observability)帮助你基于运行时可观测性遥测数据(日志、指标、跟踪、事件等)做出数据驱动的明智决策,并提供对 SAP 与客户服务及系统的洞察,以理解并提升效率、可扩展性、韧性与可用性。
当你需要应用完整、详细的可观测性数据时,可以使用 SAP Cloud Logging。SAP Cloud Logging 允许你对日志、指标与跟踪进行切片和切块分析,以分析 BTP 工作负载在 Cloud Foundry 与 Kyma 上的功能与性能表现。
解决方案示意图
Cloud Foundry 运行时
Kyma 运行时
引入自定义指标、日志与跟踪跨度,以捕获服务特有的可观测性遥测
我们建议在 SAP Application Programming Model(CAP)框架发出的内置通用监控与可观测性信号之外,再添加服务特有的可观测性遥测信号。服务团队应当引入特定的指标、日志与跟踪跨度。在这些自定义信号之上构建自己的仪表盘、用户流乃至定义自己的告警模式,可以提升问题与事件处理场景中的效率。
在本教程中,你将学习如何为 Incident Management 应用创建服务特有的遥测信号(日志、指标与跟踪)。
实现
添加自定义日志、指标、跟踪
metrics
设置指标收集
指标是“在运行时捕获的测量值”,可帮助你了解应用的健康状况与性能。
开箱即用,@cap-js/telemetry 提供与应用数据库连接池相关的指标,即 generic-pool 的 pool info 统计信息。
在本地运行并测试
应用具备所有必需的配置后,就可以在本地测试了。
在终端中用
cds watch运行应用打开应用并创建一个事件。
在终端中检查日志
打印到控制台的数据库连接池指标示例:
[telemetry] - db.pool: size | available | pending 1/1 | 1/1 | 0
为应用添加自定义指标
业务用户可以通过自定义指标查看系统中当前正在处理多少个“High”事件。 可以按以下示例添加自定义指标:
在应用根目录创建一个新文件,命名为
server.js,并粘贴以下代码:const cds = require('@sap/cds') // Import necessary modules const { metrics } = require('@opentelemetry/api'); const meter = metrics.getMeter('@capire/incidents:incidents.urgency.high'); // Create a counter const counter = meter.createUpDownCounter('incidents.urgency.high'); cds.on('served', async () => { const { ProcessorService } = cds.services // Increase count when new incident with high urgency is created ProcessorService.after("CREATE", "Incidents", (results, req) => { if (results.urgency_code === "H" && results.status_code !== "C") { counter.add(1, { 'sap.tenancy.tenant_id': req.tenant }); } }); // Reduce count once incident is closed ProcessorService.after("UPDATE", "Incidents", (results, req) => { if (results.urgency_code === "H" && results?.status_code === "C") { counter.add(-1, { 'sap.tenancy.tenant_id': req.tenant }); } }); }); module.exports = cds.server
用 cds watch 命令监视应用。
2. 创建一个紧急程度为“High”、状态为“Open”的事件。
3. 等待 1 分钟,检查终端中的日志。你会看到类似下面的内容:
[telemetry] - incidents.urgency.high: 1
在 SAP Cloud ALM 中访问真实用户监控、健康监控数据以及集成与异常监控
应用部署完成、SAP Cloud ALM 租户配置了真实用户监控与健康监控之后,你就可以开始在 SAP Cloud ALM 中分析 Incident Management 应用了。
前提条件
为真实用户监控与健康监控配置 SAP Cloud ALM
测试应用
应用部署完成后,启动它并创建几个事件。
真实用户监控数据
从 SAP Cloud ALM 的 Operations 部分启动 Real User Monitoring Application。
打开 Select a Scope 对话框,搜索你的服务,然后选择 Apply。
会显示一张带有你服务的磁贴,展示 HTTP 与 SAPUI5 请求统计信息。选择 SAPUI5。
打开 Requests 屏幕,显示 Avg. Response Time、Users、Request Type 等请求统计信息。
从列表中选择一个请求,进一步查看该请求的详细信息。
[!TIP] 图表已从默认的(“Orientation: left to right”)切换为“Orientation: Top to Bottom”。
后端明细显示在 Back End 标签页中。明细会按你选择的时间范围显示每小时到达的请求数量。

在 Front End 标签页中,你会看到 Device Type、Operating System、Web Browser 等用于访问应用的数据。

你可以在真实用户监控应用的其他页面中查看更详细的信息。
健康监控数据
从 SAP Cloud ALM 的 Operations 部分启动 Health Monitoring Application。
打开 Select a Scope 对话框,搜索你的服务,然后选择 Apply。
选择显示的磁贴。它会打开 Monitoring Screen,显示一些基本的应用指标。

选择你的服务以查看更多细节。它会显示应用的详细指标。

选择磁贴以获取 http.client.duration 等指标。选择右侧的 Hstory 按钮,可显示应用有工作负载时客户端耗时的历史指标。
你可以根据需求探索更多选项,例如触发告警以及进一步深入到应用指标的细节。
[!NOTE] 健康指标数据需要一段时间才能在健康监控应用中可视化。如果暂时看不到数据,请稍等一段时间。
集成与异常监控
针对 Incident Management 的异常监控即将推出。
在 Real User Monitoring、Health Monitoring - Setup & Configuration 与 Integration & Exception Monitoring 中进一步了解真实用户监控、健康监控以及集成与异常监控应用的能力。
前提条件
按照分步教程 Develop a Full-Stack CAP Application 开发 Incident Management 应用。
把 Incident Management 应用部署到以下 SAP BTP 运行时之一:
方式 1:SAP BTP, Cloud Foundry 运行时:Deploy a Full-Stack CAP Application in SAP BTP, Cloud Foundry Runtime。
方式 2:SAP BTP, Kyma 运行时:Deploy a Full-Stack CAP Application in SAP BTP, Kyma Runtime。
运行以下命令取消部署应用:
对于 SAP BTP, Cloud Foundry 运行时:
cf undeploy <YOUR_MTA_ID> --delete-services对于 SAP BTP, Kyma 运行时:
helm uninstall <RELEASE_NAME> -n <YOUR_NAMESPACE>
所需权利
将 SAP Cloud Logging 服务与所开发的 CAP 应用集成,需要在 SAP BTP cockpit 中具备以下额外权利与配额:
服务 |
计划 |
实例数 |
|---|---|---|
SAP Cloud Logging |
Standard |
1 |