多租户 SaaS 应用(CAP) · 3 · 进阶主题(2/2)
项目 |
内容 |
|---|---|
官方仓库 |
|
业务场景 |
把 CAP 应用改造成多租户 SaaS:租户订阅、隔离、按租户配置 |
技术栈 |
CAP(Node.js/Java)、mtxs、SaaS Registry、XSUAA、Cloud Foundry / Kyma |
对应课程 |
|
对应路径 |
第 2 条、第 7 条 |
为什么值得做:多租户是 SaaS 产品的分水岭。本案例实现了租户开通、隔离与升级机制, 用一个应用即可服务众多客户。
动手要点:
理解 SaaS Registry 与租户感知应用之间的关系。
研读
mta.yaml与租户部署描述文件——大部分复杂度都集中在这里。
本页内容抓取自官方仓库 SAP-samples/btp-cap-multitenant-saas,共收录 4 篇官方文档(README 与 docs)。原仓库内容版权归 SAP SE,遵循其许可证。
集成 SAP API Management
Kyma ✅
Cloud Foundry ❌
重要 - 本部分教程已弃用,稍后将更新!!❌
你的 SaaS 应用包含一套 API,供订阅方以编程方式访问其租户数据库容器,因此需要确保这些 API 端点得到妥善管理与监控。为此,你应当实现 Rate Limiting(限流)等特性来防范 DoS 攻击。此外,你还可以按所选服务计划设置 Quota(配额),在消费方之间实现资源的公平使用。高级订阅方每秒可发送的请求数可以多于标准消费方。对 API 进行恰当的监控,有助于你分析性能问题,并识别消费方一侧的故障。
在本部分教程中,你将学习如何确保每一个发往 SaaS API 的请求都先经过 SAP API Management。SAP API Management 属于 SAP Integration Suite,是 SAP 面向各类 API 相关需求提供的标准云软件产品。
集成 SAP API Management
架构
前提条件
集成设置
内部机制
API 策略深入解析
5.1. Decode JWT Token 策略
5.2. Spike Arrest 策略
5.3. API 配额策略
5.4. Kyma 认证策略
5.5. 统计收集策略
5.6. 更新 API Proxy 并部署变更
测试该设置
延伸阅读
重要 - 对于非流式的 HTTP 请求与响应,SAP API Management 将单个 HTTP 请求的负载大小限制为 10 MB(参见详情)。如需传输更大的文件,请考虑使用流式传输!
1. 架构
SAP API Management 是 Advanced Version 架构核心部分的一个新增组件。在基础版本中,API 调用直接访问 Kyma API Service 的工作负载;而现在所有请求都会经过这个额外组件,让你在处理入站与出站 API 流量时拥有极大的灵活性。下图展示了解决方案架构中的相关部分(点击可放大):
2. 前提条件
进行本设置前,请确保已有一个可用的 SAP API Management 租户。由于 SAP API Management 是 SAP Integration Suite 的一项能力,请先订阅 SAP Integration Suite,并激活相应的 API Management 功能。详细的分步指南见以下 SAP Help 文档(点击此处)。作为本教程的一部分,我们无法就 SAP Integration Suite 的设置过程提供更多细节。
3. 集成设置
Cloud Foundry 通过所谓的 Route Services 提供了非常便捷的集成方式(直接拦截发往你的 API 的流量),而在 Kyma 中我们需要自行设置必要的路由。正如 Kyma 入门章节中所述(见此处),任何发往 Kyma API Service 的请求都会先路由到 SAP API Management,在那里检查相关的 API 规则(限流、配额)。
只有通过这些规则的检查后,流量才会被送回 Kyma,并路由到实际的 API Service 工作负载。该路由所需的 SAP API Management 实例详情,必须维护在额外的 values-apim.yaml 文件中。
3.1. 下方是集成 API Management 所需的配置。本进阶特性提供的 ./files/values-apim.yaml 文件中有一个示例。请把该示例配置添加到 /deploy/kyma/charts/sustainable-saas/ 目录下 values-private.yaml 文件中已有的 api 小节。修改后,values-private.yaml 中的 api 小节应如下所示:
const { metrics } = require('@opentelemetry/api');
let counterRequestCountByTenant;
// Initialise 'Request Count by Tenant' Custom Counter
cds.on('listening', () => {
counterRequestCountByTenant = metrics.getMeter('susaas.metering').createCounter('req.count.per.tenant');
})
// Add Middleware to update the 'Request Count by Tenant' Custom Counter
cds.middlewares.add((req, _, next) => {
counterRequestCountByTenant.add(1, { 'susaas_tenant_id': cds.context.tenant })
next()
})
3.2. 根据你自己的环境信息更新上述配置后,请再次运行 helm upgrade,把变更应用到 Kyma 集群。
## Run in ./deploy/kyma ##
helm upgrade <ReleaseName> ./charts/sustainable-saas -f ./charts/sustainable-saas/values-private.yaml -n <Namespace>
# Example #
helm upgrade susaas ./charts/sustainable-saas -f ./charts/sustainable-saas/values-private.yaml -n default
3.3. 切换到 SAP API Management,配置尚缺的集成部分,并上传我们的示例 API Proxy。
3.4. 首先,你需要在 SAP API Management 中保存有效的 XSUAA 客户端凭据。为此,请打开 Configure 菜单并选择 APIs。切换到 Key Value Maps 标签页,然后点击 Create。
3.5. 新建一个名为 susaas-api 的 Key Value Map,其中包含 XSUAA 服务实例的 Client Id 与 Token Endpoint。
提示 - 所需的详细信息可在 <ReleaseName>-api-xsuaa-apim 这个 Kyma Secret 中找到,它是在 helm upgrade 期间创建的。你可以通过 Kyma Dashboard 获取该 Secret 的详情,也可以使用以下 kubectl 命令。
clientId:Kyma Secret 的 clientid 属性
示例 -> sb-susaas-api-default!b1234
tokenEndpoint:Kyma Secret 的 url 属性(不含 https://)
3.6. 再创建一个名为 susaas-api-key 的 Key Value Map,其中包含 XSUAA 服务实例的 Client Secret。保存之前,请为该 Key Value Map 启用加密。
3.7. 由于提供的示例 API Proxy 还包含额外的监控特性(例如跟踪客户端的 XSUAA Zone ID 以及所请求的 OData 实体),请在你的 SAP API Management 实例的 Monitoring 区域中添加这些额外的 Dimensions。为此,请切换到 Monitoring 菜单下的 APIs 部分,然后点击 + Add。
3.8. 创建以下三个 Dimensions,示例 API Proxy 会用到它们。点击 OK 保存变更。
ODataEntityList
ODataPrimaryEntity
Zone
3.9. 返回 Design 环境,上传本教程提供的示例 APIProxy.zip 文件;该文件位于本教程的 files 子文件夹中(点击此处)。
3.10. 上传完成后,请打开 susaas-api 的 API Proxy 定义,把 Target Endpoint 更新为你的 Kyma API Service URI(例如 susaas-api-default.a1b2c3.kyma.ondemand.com),如下方截图所示。
提示 - 如果你的 Kyma 环境使用了自定义域名,此处也应使用该域名(例如 susaas-api-default.sap-demo.com)。
3.11. 保存变更并部署 API Proxy,如下方截图所示。
就是这些——从现在开始,所有发往 Kyma API Service 工作负载的请求都会经由 SAP API Management 路由,以强制执行 Rate Limiting 或 Quotas 等策略。策略检查通过后,请求会返回 Kyma,并由我们的 API Service Target Endpoint 提供服务。下一章中,我们会带你抢先看看这套架构内部究竟发生了什么。
4. 内部机制
正如我们在模板详情章节中简要提到的,我们使用专用的 Istio 资源来实现这条集成路径。这里再总结一下相应的流程,让你了解内部发生了什么。由于除 SAP API Management 之外,这一方式也可用于任何其他类型的外部服务,请务必理解其基本概念。掌握之后,你就能以类似方式集成 SAP Integration Suite 的 iFlows。
总体目标现在应该很清楚了:我们要确保没有任何请求能在不经过 SAP API Management 中策略检查的情况下到达 Kyma API Service。如上图所示,相应的 Istio 资源确保每个传入请求都带有一个有效的 JWT 令牌(x-jwt-assertion 自定义标头)。这个 JWT 令牌标头是本次集成的核心组件,由 SAP API Management 基于某个 XSUAA 服务实例的专用客户端凭据生成并注入(详见「API 策略深入解析」)。
这段总结应该已经让你大致看出各部分如何咬合在一起了?很好!我们一步一步来!
一切始于通过 Istio Ingress Gateway 到达 Kyma 集群的 API 请求。虽然你也可以把 API Proxy 端点直接提供给租户,但在端到端路由场景中,我们决定利用 Istio 提供的额外灵活性。
重要 - 从 Kyma 到 SAP API Management 的这一跳会略微延长响应时间。因此,如果你的用例追求尽可能短的响应时间,可以考虑把 API Proxy 端点直接交给订阅方使用。如果你的场景对延迟极为敏感,并且要通过 API 端点传输巨大负载,也可以考虑在 API Service 实现中做 API Rule 检查,或者利用 Istio 的限流特性。
要把 SAP API Management 集成到我们的服务网格中,需使用专用的 Istio Virtual Service。该 Virtual Service 为所有通过 Istio Ingress Gateway 到达 API Service 的请求定义路由规则。路由规则依据自定义标头 x-jwt-assertion 是否存在来判定。若缺少该标头(即初始请求),流量会路由到 SAP API Management 的 API Proxy;若请求中已带有该自定义标头,流量则直接路由到 Kyma API Service。
重要 - 一旦请求成功通过所有流量策略(例如限流),SAP API Management 就会注入 x-jwt-assertion 自定义标头。
apiVersion: networking.istio.io/v1beta1 kind: VirtualService spec: # Matches all requests arriving on host exposed by SusaaS API Service gateways: - kyma-system/kyma-gateway hosts: - susaas-api-default.a1b2c3.kyma.ondemand.com http: - match: # Matches requests containing the x-jwt-assertion header - headers: x-jwt-assertion: {} # Routes requests to Cluster IP Service of our SaaS API route: - destination: host: susaas-api.default.svc.cluster.local port: number: 5000 # Matches requests without the x-jwt-assertion header - match: - withoutHeaders: x-jwt-assertion: {} # Rewrite URL path to add API Proxy path and authority details rewrite: uri: /susaas-api/ authority: sap-demo.prod.apimanagement.us20.hana.ondemand.com # Routes to SAP API Management defined in the Service Entry route: - destination: host: sap-demo.prod.apimanagement.us20.hana.ondemand.com port: number: 443
补充说明 - 所谓的 Service Entry 把 SAP API Management 声明为网格外部(mesh-external)服务。这样我们就能在 Virtual Service 的路由规则中把它用作目标。
请求成功通过 SAP API Management 中的所有策略后,API Proxy 会使用 XSUAA 客户端凭据申请一个新的 JWT 访问令牌;这些凭据安全地存放在相应的 Key Value Map 中,你已在本教程开头完成设置。只有 SAP API Management 持有这些客户端凭据,因此任何租户都无法自行生成有效的访问令牌。通过校验该 JWT 令牌(在 x-jwt-assertion 标头中传递)的有效性,你就能确保请求确实经过了 SAP API Management。随后,请求连同该自定义标头一起被送回 Kyma。
重要 - 你的 SaaS 订阅方以及任何其他人都绝不能拿到这些客户端凭据。同时请务必定期轮换它们。
作为敏锐又内行的安全爱好者,你大概会想到这样一个问题……「基于自定义标头的路由固然不错,但它能防止别人直接把相应的自定义标头手工加进请求吗?!」你说得完全对,那样确实会绕过到 SAP API Management 的路由……不过别担心,我们的 API Service 纹丝不动,因为伪造出有效 JWT 令牌的概率几乎为零。继续往下读,你会了解 Kyma 中是如何借助各种 Istio 组件实现令牌校验的。
首先,Istio 的 Request Authentication 会检查发往 API Service 的请求是否在 x-jwt-assertion 标头中提供了由可信颁发方签发的有效 JWT 令牌。若满足该条件,请求即被视为已认证,相应的身份信息可供后续 Authorization Policy 中的鉴权检查使用。
提示 - 单独的 Request Authentication 并不一定会限制对服务的访问。它只是让你能够认证请求,并确保 JWT 令牌由可信颁发方签发。提取出的身份信息(例如 requestPrincipals 属性)仍需在相应的 Authorization Policy 中校验。如果 JWT 颁发方不可信或令牌无效,请求仍会被转发,但会被视为「未认证」,于是通过 Authorization Policy 所需的身份信息就缺失了!
apiVersion: security.istio.io/v1beta1 kind: RequestAuthentication spec: # Any request targeting the Kyma API Service workload selector: matchLabels: app.kubernetes.io/name: api # Check if request contains a valid JWT token issued by XSUAA instance of the the Provider Subaccount jwtRules: - issuer: https://sap-demo.authentication.us20.hana.ondemand.com/oauth/token jwksUri: https://sap-demo.authentication.us20.hana.ondemand.com/token_keys # As the JWT token of the initial user request shall be retained a custom header is being used fromHeaders: - name: x-jwt-assertion
Istio 的 Authorization Policy 确保只有那些在已校验身份信息中带有特定 Issuer 与 Subject 声明的请求才能访问 API Service。在我们的示例场景中,我们检查 requestPrincipals 属性,其结构为 <JWTIssuer>/<JWTSubject>。请记住,如果 x-jwt-assertion 标头中的 JWT 令牌无效,或并非由可信的 XSUAA 租户签发,该属性将为空,请求会被拦截!
提示 - 对于 XSUAA,JWT 的颁发方等于提供方子账户 XSUAA 租户的 token endpoint(例如 https://sap-demo.authentication.us20.hana.ondemand.com/oauth/token),而 Subject claim 包含 API XSUAA 服务实例的 Client Id。默认的 Subject 结构为 sb-<ReleaseName>-api-<Namespace>,必须在 values.yaml 文件中提供(例如 sb-susaas-api-default)。此处故意使用星号,因为 XSUAA 生成的 Client Id 在感叹号之后总会带一段随机字符!
apiVersion: security.istio.io/v1beta1 kind: AuthorizationPolicy spec: action: ALLOW # Any request targeting the Kyma API Service workload selector: matchLabels: app.kubernetes.io/name: api # Only grant access if Issuer and Subject of the authenticated request match a defined pattern # The Issuer has to match the XSUAA token endpoint of the Provider Subaccount # The prefix of the Subject claim has to match the Client Id of the API XSUAA Service Instance rules: - from: - source: # Will only be available if Request Authentication was successful requestPrincipals: - https://sap-demo.authentication.us20.hana.ondemand.com/oauth/token/sb-susaas-api-default!*
Istio 的 Destination Rule 是本示例中用到的另一个资源,它让我们可以把出站到 SAP API Management 的流量改用简单的 TLS 通信。由于 Istio 在服务网格内默认强制使用双向 TLS,任何例外都必须显式定义。知会你一声 : )
# Source: susaas/charts/api/templates/apim-proxy/istio-dest-rule-apim.yaml apiVersion: networking.istio.io/v1alpha3 kind: DestinationRule metadata: name: susaas-apim labels: app.kubernetes.io/name: api spec: host: sap-demo.prod.apimanagement.us20.hana.ondemand.com trafficPolicy: portLevelSettings: - port: number: 443 tls: mode: SIMPLE
就是这些——现在你应该清楚我们的示例场景是如何搭建 SAP API Management 的安全集成了。警觉的读者此时可能还会追问一句:为什么要在自定义标头上费这么大劲?难道不能直接用 Authorization 标头来达到同样目的吗?问得好,要给出恰当的答案,我们再看一次那张示意图。
显然,Authorization 标头本应是存放这类 JWT 令牌的首选位置,但可惜它已被初始请求占用:其中包含订阅方子账户的 XSUAA 租户签发的 JWT 令牌,CAP 用它来在多租户上下文中识别租户。因此我们必须保留这个令牌,并让它在整个流程中一路传递下去。正因如此,我们决定把额外的 JWT 令牌(用于表明请求已被 API Management 成功处理)存放在自定义标头中。
理论概念你已经掌握,现在就去直面实战考验,下到 SAP API Management 的机房看看吧。该动手配置 API 策略了!
5. API 策略深入解析
示例 API Proxy 的 API 策略主要基于 SAP API Management 的标准特性。在接下来的部分,你将学习如何自行配置其中部分 API 策略,包括用于限流的 Spike Arrest 组件,以及根据订阅方所选计划(trial/standard/premium)应用的不同 Quota。
重要 - 以下步骤已在本教程开头你部署的示例 API Proxy(APIProxy.zip)中完成。如果你想重新走一遍下面的分步操作,可以删除现有的 API Proxy,并上传 APIProxyPolicies.zip。否则,只需跟着阅读,并在你现有的 API Proxy 中对照这些步骤与组件即可。
要查看和修改 API Proxy 的策略,点击 API Proxy 右上角的 Policies 即可。
在 Policy Editor 中点击 Edit,切换到编辑模式。
5.1. Decode JWT Token 策略
我们先从 API Proxy 的 PreFlow 开始,在这里放置 SaaS API 的限流器。要了解 SAP API Management 中各种 Flow 类型,请参阅以下 SAP Help 文档。
5.1.1. 在本用例中,我们通过唯一的 Client ID 区分 API 客户端,该 ID 可在每个请求的 JWT 令牌中找到(!注意这次是默认 Authorization 标头中的 JWT 令牌!)。因此,如果你决定从零重建这些 API 策略,请添加名为 DecodeJWT 的 API 特性,以便在后续步骤中使用解码后的 JWT 令牌。
5.1.2. 如果你从零重建 API 策略,请把流元素重命名为 decodeJwt。若你用了别的名字,请记住它,因为后续某一步会用到。
5.1.3. 如果你从零重建 API 策略,请从配置中删除 <Source>var.jwt</Source> 这一行。
5.2. Spike Arrest 策略
Spike Arrest 策略用于限制 API Proxy 处理的请求数量。它可以保护你免遭性能下降与宕机,是每个企业级 API Proxy 的必备组件。
5.2.1. 解码 JWT 令牌之后,我们就可以在策略工具箱中使用 Spike Arrest 特性。如果你从零重建 API 策略,请新增一个实例,并把流元素重命名为 spikeArrest。
5.2.2. Spike Arrest 实例需要一个客户端标识符,在本场景中即 Client Id。该 Client Id 来自上一个流元素(用于解码 JWT 令牌)。如果你从零重建 API 策略,且最初的流元素用了别的名字,就需要相应修改 decodeJwt 的值。
<Identifier ref="jwt.decodeJwt.claim.client_id"/>
5.2.3. 你可以按需调整每分钟(pm)或每秒(ps)允许的请求数。Spike Arrest 的配置选项非常丰富,详见其文档(点击此处)。
<Rate>1ps</Rate> instead of <Rate>30pm</Rate>
5.3. API 配额策略
除了 API 限流(保护 SaaS API 免受 DoS 攻击)之外,我们还通过引入基于计划的配额来增强 API Proxy。这样可以区分标准客户与高级客户,为 SaaS API 提供不同的服务水平(例如每日请求数)。
5.3.1. 为了区分不同的 API 服务计划,我们使用 Subflows(子流)。这些子流会在 PreFlow 执行完之后,按特定条件执行。如果你从零重建 API 策略,只需点击 + 图标为 Proxy Endpoint 创建一个新的子流。
5.3.2. 我们使用三个子流:standardPlanFlow、premiumPlanFlow 和 trialPlanFlow。它们会在通用的 PreFlow 之后,按你定义的条件执行。PreFlow 对所有请求都会执行。
5.3.3. 这里我们同样借助解码后的 JWT 令牌数据来区分请求。我们的 SaaS API Service Broker 确保把所选 service plan 作为 scope 注入所有签发的 JWT 令牌。这样你就能读取服务计划信息,并按如下方式把它写进 Flow Condition:
提示 - 如果你从零重建 API 策略,请在添加条件之前先选中 standardPlanFlow。
jwt.decodeJwt.claim.scope ~ "*plan_standard"
5.3.4. premiumPlanFlow 的条件如下。
jwt.decodeJwt.claim.scope ~ "*plan_premium"
5.3.5. trialPlanFlow 的条件如下。
jwt.decodeJwt.claim.scope ~ "*plan_trial"
提示 - 未来可能会用其他方式改进从 JWT 令牌 scope 中读取服务计划的做法。
5.3.6. 现在,请求会按消费方所选的服务计划交由不同的子流处理。在这些子流中,我们可以定义不同的 Quota 额度。要为 API 添加一个很简单的配额上限,我们使用策略工具箱中的 Quota 特性。如果你从零重建 API 策略,请把新的流元素分别命名为:standard 流中的 quotaStandard、premium 流中的 quotaPremium、trial 流中的 quotaTrial。
5.3.7. 在我们的示例应用中,standard 与 trial 的配额配置如下。该配置允许 API 客户每天正好向你的 API 发送 1200 个请求。Quota 策略的完整配置选项见相应文档(点击此处)。
重要 - 请确保 Quota 策略配置同样包含 Client Id 标识符,如下例所示。
<!-- 配额策略示例:标准计划与试用计划共用,按客户端标识符分别统计,
每个客户端每天最多 1200 次请求。配额按日历日计算,由 API Management
分布式、同步执行,多个网关节点共享同一计数;如需调整额度,请修改
Allow 元素的 count 值,或调整 TimeUnit 与 Interval 来改变统计周期。
不同租户之间配额互不影响。 -->
<Quota async="false" continueOnError="false" enabled="true" type="calendar" xmlns="http://www.sap.com/apimgmt">
<Identifier ref="jwt.decodeJwt.claim.client_id"/>
<Allow count="1200"/>
<Interval>1</Interval>
<Distributed>true</Distributed>
<StartTime>2015-2-11 12:00:00</StartTime>
<Synchronous>true</Synchronous>
<TimeUnit>day</TimeUnit>
</Quota>
提示 - 对于 premium 计划,我们把每日请求数翻倍到 2400,你也可以按需要改成自己的配置。
5.4. Kyma 认证策略
自定义标头 x-jwt-assertion(Kyma 用它判断请求是否已成功通过 API 策略)是在 TargetEndpoint - PreFlow 中注入的。不展开细节来说,PreFlow 中的相应元素会使用本教程开头创建的 Key Value Maps 中存储的 XSUAA token endpoint 来申请一个访问令牌。
认证时使用关联的 Client Id 与 Secret(同样存放在 Key Value Maps 中)。这个 JWT 访问令牌会依据其有效期在 SAP API Management 中缓存,并在适用时自动复用于后续请求。
5.5. 统计收集策略
在 TargetEndpoint - PostFlow 阶段,所申请(或已缓存)的 XSUAA JWT 访问令牌会以 x-jwt-assertion 自定义标头的形式加入 HTTP 请求。正如 API Proxy 设置中所定义的,Target Endpoint 最终仍指向我们 Kyma 集群的 API Service(例如 susaas-api-default.a1b2c3.kyma.ondemand.com)。
如果 API Service 工作负载返回成功响应,系统会先记录一些统计信息,然后再把响应返回给客户端。这些信息包括所请求的 OData 实体以及客户端的 XSUAA zone,之后可在自定义的监控仪表盘中可视化。
使用这些维度的简单监控仪表盘大致如下。
5.6. 更新 API Proxy 并部署变更
5.6.1. 如果你从零重建 API 策略,或修改了任何现有策略,请点击 Policy Editor 右上角的 Update。
5.6.2. 点击 Save 保存对 API Proxy 的修改。
5.6.3. 选择相应选项,确保部署最新版本的 API Proxy。
6. 测试该设置
就这样,你已成功把基于 Kyma 的 SaaS API 与 SAP API Management 集成,并配置了一些 API 策略。要测试这套设置,可以在订阅方子账户中新建一个服务密钥(或使用现有密钥),然后尝试调用 API 端点,例如使用示例 HTTP 文件。
你会发现,若每秒调用 API 超过一次(例如用 Postman 或 HTTP 文件),就会收到 SAP API Management 返回的错误消息,因为 Spike Arrest(限流)策略会介入。
7. 延伸阅读
关于上述主题的更多信息,请使用以下链接:
Cloud Foundry - 使用 Cloud Logging Service 实现可观测性
Kyma ❌
Cloud Foundry ✅
重要 - 本部分教程仅适用于 Cloud Foundry 部署!
本节中,你将学习如何创建 SAP Cloud Logging 服务的新实例,并将其绑定到 Cloud Foundry 应用。这样你就能使用 SAP Cloud Logging 服务监控应用的日志。
Cloud Foundry - 使用 Cloud Logging Service 实现可观测性
SAP Cloud Logging 服务简介
使用 Telemetry 插件添加可观测性
部署并绑定到 SAP Cloud Logging 服务
延伸阅读
1. SAP Cloud Logging 服务简介
SAP Cloud Logging 服务是一个基于实例的可观测性服务,构建在 OpenSearch 之上,用于存储、可视化和分析来自 SAP BTP Cloud Foundry、Kyma、Kubernetes 及其他运行时环境的应用程序日志、指标与跟踪数据。对于 Cloud Foundry 与 Kyma,它提供了预置内容,便于按请求调查所观测应用的负载、延迟和错误率,并与其他数据关联,从而实现轻松的集成。
SAP Cloud Logging 服务提供多种服务计划(例如 Standard、Large 和 Dev),以满足不同的用例与需求。这些计划提供不同的摄取与存储能力。例如:
Standard/Large 计划面向生产工作负载,支持更大的数据量和更长的保留期。
Dev 计划仅适用于非生产环境与评估用途,不具备云服务质量。
更多信息请参阅 SAP Cloud Logging 及其服务计划文档。你也可以查看服务创新指南,了解从 SAP Application Logging Service 演进到 SAP Cloud Logging Service 的创新历程及其优势。
2. 使用 Telemetry 插件添加可观测性
Telemetry(@cap-js/telemetry)插件 提供跟踪与指标等可观测性特性,其中包括自动的 OpenTelemetry 埋点。在项目中启用该插件后,各类遥测数据都会被自动收集。
下面把 Telemetry 插件加入项目,并通过少量配置定制来启用它。
切换到 code 目录并安装依赖
## Run in ./code ## npm i @cap-js/telemetry @grpc/grpc-js @opentelemetry/exporter-metrics-otlp-grpc @opentelemetry/exporter-trace-otlp-grpc @opentelemetry/host-metrics @opentelemetry/exporter-logs-otlp-grpc
在 code/srv/.cdsrc.json 与 code/api/.cdsrc.json 两个文件中,于 requires 键下添加以下配置。
"telemetry": { "[hybrid]": { "kind": "telemetry-to-cloud-logging" }, "[local-with-mtx]": { "kind": "telemetry-to-console" }, "[development]": { "kind": "telemetry-to-console" } }
按第 1 节中的步骤在本地测试应用,即可在控制台看到遥测数据。
如下所示,控制台中应显示跟踪与指标数据(也称为信号):
Traces(跟踪):
跟踪让你可以分析请求、消息、任务等是如何被应用处理的,它细粒度地展示请求的流转过程以及每个操作所耗费的时间。

Metrics(指标):
指标是在运行时采集的测量值,有助于了解应用的健康状况与性能。开箱即用,@cap-js/telemetry 提供 HTTP 指标 http.server.duration,它可度量最小/最大响应时间、跨请求的总耗时、请求耗时的分布等不同数值,有助于分析性能、定位瓶颈并优化响应时间。

此外,@cap-js/telemetry 还会实例化并提供主机指标,例如 CPU 使用率、内存使用率等(@opentelemetry/host-metrics)。

3. 部署并绑定到 SAP Cloud Logging 服务
准备部署
确保项目中已安装以下依赖(可在 code/package.json 中核对)。
## Run in ./code ## npm i @cap-js/telemetry @grpc/grpc-js @opentelemetry/exporter-metrics-otlp-grpc @opentelemetry/exporter-trace-otlp-grpc @opentelemetry/host-metrics
在 code/srv/srv/.cdsrc.json 与 code/api/srv/.cdsrc.json 两个文件中,于 requires 键下添加以下配置。
"telemetry": { "kind": "to-cloud-logging" }
在 mta.yaml 文件的 server(susaas-srv) 与 api(susaas-api-srv) 模块中添加以下属性,用于设置向 cloud logging 服务发送信号时使用的 OpenTelemetry 组件名称。
properties: OTEL_SERVICE_NAME: ${app-name}
创建服务实例 / 绑定
创建 SAP Cloud Logging 服务实例有多种方式,如下所示。也可以在部署应用时使用
mta.yaml文件创建该实例。由于同一个 SAP Cloud Logging 服务可以跨多个应用使用,建议单独创建实例,再把它绑定到各应用。如果你希望在部署期间创建实例,请替换 mta.yaml 文件中的以下代码片段。
# Before - name: susaas-logging type: org.cloudfoundry.managed-service parameters: service: application-logs service-name: ${space}-susaas-logging service-plan: lite # After - name: susaas-logging type: org.cloudfoundry.managed-service parameters: service: cloud-logging service-name: ${space}-susaas-cls-logging service-plan: standard config: ingest_otlp: enabled: true retention_period: 14 backend: max_data_nodes: 2 dashboards: custom_label: 'SusaaS' saml: enabled: false
如需进一步了解各个参数并调整初始化设置,请参阅配置参数文档。
注意:还可以在同一个 Cloud Foundry 组织内,在不同 space 之间共享同一个 SAP Cloud Logging 服务实例。这样就能汇聚多个 space 的可观测性数据,简化监控与分析。更多细节请参阅文档。
如果你已单独创建实例,可以在
mta.yaml文件中把它声明为现有资源。- name: susaas-logging type: org.cloudfoundry.existing-service
要把实例绑定到应用,只需在
mta.yaml文件中把它声明为必需服务:把susaas-logging加入 mta.yaml 文件中 server(susaas-srv) 与 api(susaas-api-srv) 模块的requires小节。requires: - name: susaas-logging
部署应用
构建并部署应用,然后从消费方子账户订阅它。最后测试应用,确保从消费方角度看功能符合预期。请按以下各节的步骤操作:3 - 构建并部署应用
4 - 订阅消费方子账户
5 - 向 SaaS API 推送数据
6 - 测试应用
访问 SAP Cloud Logging 服务并探索仪表盘
进入 SAP BTP Cockpit,打开 cloud logging 服务并创建一个服务密钥。然后在操作菜单中选择 View Dashboard 打开仪表盘。

使用服务密钥中提供的凭据(dashboards-username 与 dashboards-password)登录仪表盘。登录后应显示仪表盘的欢迎页。

你可以在 CF 标签页下探索仪表盘,查看应用的请求详情、日志、跟踪与指标数据(如下所示)。其中提供预置的可视化用于分析数据,例如 Four Golden Signals(即延迟、流量、错误与饱和度)、Performance and Quality、Requests and Logs。




在 OpenTelemetry/Metrics 标签页中,可以看到由 Telemetry 插件自动收集的跟踪与指标数据,如下所示:


如果想更细致地探索指标,可以进入 'Discover' 菜单项,并选择 'metrics-otel-v1-*' 数据源。

NOTE:也可以添加自定义指标并在仪表盘中可视化。要了解如何创建自定义指标,请参阅「创建自定义指标」一节。
4. 延伸阅读
关于上述主题的更多信息,请使用以下链接:
创建自定义指标
Kyma ✅
Cloud Foundry ✅
本部分教程将深入介绍如何创建自定义指标,并在 SAP Cloud Logging 服务中探索该指标。
步骤
按以下步骤创建一个自定义指标,用于统计每个租户对该服务的请求数量,然后在 SAP Cloud Logging 服务中展示该指标。
在 server.js 文件中添加以下代码,以创建自定义指标,并在每次请求时更新该指标值。
const { metrics } = require('@opentelemetry/api'); let counterRequestCountByTenant; // Initialise 'Request Count by Tenant' Custom Counter cds.on('listening', () => { counterRequestCountByTenant = metrics.getMeter('susaas.metering').createCounter('req.count.per.tenant'); }) // Add Middleware to update the 'Request Count by Tenant' Custom Counter cds.middlewares.add((req, _, next) => { counterRequestCountByTenant.add(1, { 'susaas_tenant_id': cds.context.tenant }) next() })
说明:上面的代码中,服务器就绪并开始监听传入请求后,首先以 req.count.per.tenant 为名初始化一个自定义计数器。然后向应用添加一个中间件,在每次请求时更新该计数器的值。每次请求都会把计数值加 1,并用租户 ID 作为标签,以区分来自不同租户的请求。
代码添加完成后,构建并部署应用。之后就可以在 SAP Cloud Logging 服务中探索这个自定义指标。
自定义指标会自动出现在 SAP Cloud Logging 服务的 OpenTelemetry explorer 仪表盘中。

-
注意:如果在仪表盘中看不到指标的属性(例如 susaas_tenant_id),这是索引造成的;可依次进入 Stack Management --> Index Patterns,打开索引模式 metrics-otel-v1-*,然后点击 Refresh field list 按钮刷新。

延伸阅读
关于上述主题的更多信息,请使用以下链接:
Kyma - 使用 Cloud Logging Service 实现可观测性
Kyma ✅
Cloud Foundry ❌
重要 - 本部分教程仅适用于 Kyma 部署!
本教程中,你还将学习如何借助 Telemetry 插件,把 SaaS 应用的日志、跟踪与指标发送到 SAP Cloud Logging 服务。
Kyma - 使用 Cloud Logging Service 实现可观测性
SAP Cloud Logging 服务简介
在 Kyma 中启用 Telemetry 模块
使用 Telemetry 插件添加可观测性
延伸阅读
1. SAP Cloud Logging 服务简介
SAP Cloud Logging 服务是一个基于实例的可观测性服务,构建在 OpenSearch 之上,用于存储、可视化和分析来自 SAP BTP Cloud Foundry、Kyma、Kubernetes 及其他运行时环境的应用程序日志、指标与跟踪数据。对于 Cloud Foundry 与 Kyma,它提供了预置内容,便于按请求调查所观测应用的负载、延迟和错误率,并与其他数据关联,从而实现轻松的集成。
SAP Cloud Logging 服务提供多种服务计划(例如 Standard、Large 和 Dev),以满足不同的用例与需求。这些计划提供不同的摄取与存储能力。例如:
Standard/Large 计划面向生产工作负载,支持更大的数据量和更长的保留期。
Dev 计划仅适用于非生产环境与评估用途,不具备云服务质量。
更多信息请参阅 SAP Cloud Logging 及其服务计划文档。你也可以查看服务创新指南,了解从 SAP Application Logging Service 演进到 SAP Cloud Logging Service 的创新历程及其优势。
2. 在 Kyma 中启用 Telemetry 模块
在 Kyma 集群中启用 telemetry 模块。详情见添加与删除 Kyma 模块。

Telemetry 模块只关注应用日志、分布式跟踪与指标这几类信号,不考虑其他类型的信号。此外,审计日志不在其范围内。
telemetry 模块以 Kubernetes Operator Telemetry Manager 作为核心组件。Telemetry Manager 管理该模块中所有其他组件的整个生命周期,监听模块配置的变化并同步模块状态。它还会监听用户创建的 Kubernetes 资源:LogPipeline、TracePipeline 与 MetricPipeline。在这些资源中,你可以指定要收集某类信号的哪些数据,以及把数据发往何处。更多细节见模块生命周期。
一旦检测到配置,Telemetry Manager 会相应部署相关的网关组件与代理组件,并使它们与所请求的管道定义保持同步。更多细节见 telemetry 模块的架构。
3. 使用 Telemetry 插件添加可观测性
Telemetry(@cap-js/telemetry)插件 提供跟踪与指标等可观测性特性,其中包括自动的 OpenTelemetry 埋点。在项目中启用该插件后,各类遥测数据都会被自动收集。
下面把 Telemetry 插件加入项目,并通过少量配置定制来启用它。
切换到 code 目录并安装依赖
## Run in ./code ## npm i @cap-js/telemetry @grpc/grpc-js @opentelemetry/exporter-metrics-otlp-grpc@0.57.2 @opentelemetry/exporter-trace-otlp-grpc@0.57.2 @opentelemetry/host-metrics @opentelemetry/exporter-logs-otlp-grpc@0.57.2
在 code/srv/.cdsrc.json 与 code/api/.cdsrc.json 两个文件中,于 requires 键下添加以下配置。
"telemetry": { "[hybrid]": { "kind": "telemetry-to-cloud-logging" }, "[local-with-mtx]": { "kind": "telemetry-to-console" }, "[development]": { "kind": "telemetry-to-console" } }
按第 1 节中的步骤在本地测试应用,即可在控制台看到遥测数据。
如下所示,控制台中应显示跟踪与指标数据(也称为信号):
Traces(跟踪):
跟踪让你可以分析请求、消息、任务等是如何被应用处理的,它细粒度地展示请求的流转过程以及每个操作所耗费的时间。

Metrics(指标):
指标是在运行时采集的测量值,有助于了解应用的健康状况与性能。开箱即用,@cap-js/telemetry 提供 HTTP 指标 http.server.duration,它可度量最小/最大响应时间、跨请求的总耗时、请求耗时的分布等不同数值,有助于分析性能、定位瓶颈并优化响应时间。

此外,@cap-js/telemetry 还会实例化并提供主机指标,例如 CPU 使用率、内存使用率等(@opentelemetry/host-metrics)。

4. 部署并集成到 Cloud Logging
准备部署
确保项目中已安装以下依赖(可在 code/package.json 中核对)。
## Run in ./code ## npm i @cap-js/telemetry @grpc/grpc-js @opentelemetry/exporter-metrics-otlp-grpc@0.57.2 @opentelemetry/exporter-trace-otlp-grpc@0.57.2 @opentelemetry/host-metrics @opentelemetry/exporter-logs-otlp-grpc@0.57.2
在 code/srv/srv/.cdsrc.json 与 code/api/srv/.cdsrc.json 两个文件中,于 requires 键下添加以下配置。
"telemetry": { "kind": "to-otlp" }
在 helm chart 中为后端应用启用 otlp 配置,如下面的 yaml 所示
### Backend Service
srv:
...
otlp:
traces:
enabled: true
endpoint: http://telemetry-otlp-traces.kyma-system.svc.cluster.local:4317
metrics:
enabled: true
endpoint: http://telemetry-otlp-metrics.kyma-system.svc.cluster.local:4317
构建并部署你的应用。
创建服务实例 / 绑定
创建 SAP Cloud Logging 服务实例有多种方式,如下所示。在 Kyma 环境中,首选方式是使用 BTP Service Operator。它有助于创建所需的 Secret,telemetry 模块也会智能地轮换并切换到新凭据,无需开发者做任何操作。
-
## Run in ./code ## kubectl apply -f ../docu/3-advanced/5-kyma-add-cls/cls/
在 Kyma 中启用配置,并把日志、跟踪与指标发送到 SAP Cloud Logging
发送应用日志:
运行在 Kyma 运行时中的应用会把日志写到 stdout 或 stderr。要把这些日志发送到 SAP Cloud Logging,需要创建一个 LogPipeline(自定义资源)。Telemetry 模块会依据 LogPipeline 中的信息捕获日志并发送到 SAP Cloud Logging。## Run in ./code ## kubectl apply -f ../docu/3-advanced/5-kyma-add-cls/cls/logpipeline-app-logs.yaml
## logpipeline-app-logs.yaml ## apiVersion: telemetry.kyma-project.io/v1alpha1 kind: LogPipeline metadata: name: susaas-app-logs spec: input: application: containers: exclude: - istio-proxy namespaces: include: - mtenant output: http: dedot: true host: valueFrom: secretKeyRef: name: susaas-logging namespace: mtenant key: ingest-mtls-endpoint tls: cert: valueFrom: secretKeyRef: name: susaas-logging namespace: mtenant key: ingest-mtls-cert key: valueFrom: secretKeyRef: name: susaas-logging namespace: mtenant key: ingest-mtls-key uri: /customindex/kyma
这样会把 susaas 命名空间内的所有应用日志推送到 logs-json-kyma-* 索引模式。注意日志会自动填入租户 ID。此外,在上述配置中,你可以通过输入部分的细节控制从哪些应用、容器和命名空间发送日志。

发送 Istio 访问日志
Istio 访问日志提供访问工作负载时流量的细粒度信息,其中包含与 4 个黄金信号(延迟、流量、错误与饱和度)相关的有用信息,也能用于排查各类异常。## Run in ./code ## kubectl apply -f ../docu/3-advanced/5-kyma-add-cls/cls/istio-trace-default.yaml kubectl apply -f ../docu/3-advanced/5-kyma-add-cls/cls/logpipeline-istio-logs.yaml
## istio-trace-default.yaml ## apiVersion: telemetry.istio.io/v1alpha1 kind: Telemetry metadata: name: istio-trace-default namespace: mtenant spec: accessLogging: - providers: - name: stdout-json
Istio 模块自带的 Istio 配置提供了一个预配置的访问日志扩展提供方,它让 Istio 代理以 JSON 格式把访问日志打印到 stdout。上述配置为 susaas 命名空间启用 Istio 访问日志。不过,也可以进行更细粒度的配置。参见配置 Istio 访问日志
要把访问日志发送到 SAP Cloud Logging,需要创建以下 LogPipeline。
## logpipeline-istio-logs.yaml ## apiVersion: telemetry.kyma-project.io/v1alpha1 kind: LogPipeline metadata: name: susaas-istio-logs spec: input: application: keepAnnotations: true containers: include: - istio-proxy namespaces: include: - mtenant output: http: dedot: true host: valueFrom: secretKeyRef: name: susaas-logging namespace: mtenant key: ingest-mtls-endpoint tls: cert: valueFrom: secretKeyRef: name: susaas-logging namespace: mtenant key: ingest-mtls-cert key: valueFrom: secretKeyRef: name: susaas-logging namespace: mtenant key: ingest-mtls-key uri: /customindex/istio-envoy-kyma
发送跟踪详情
## istio-trace-default.yaml ## apiVersion: telemetry.istio.io/v1alpha1 kind: Telemetry metadata: name: istio-trace-default namespace: mtenant spec: accessLogging: - providers: - name: stdout-json tracing: - providers: - name: "kyma-traces" randomSamplingPercentage: 10.0
通过该配置,你将对经由 Istio 服务网格进入 susaas 命名空间 Kyma 工作负载的所有请求中的 10% 启用跟踪。为优化资源与网络使用,务必把采样百分比设置为合理的默认值。
要把跟踪数据发送到 SAP Cloud Logging,需要创建以下 TracePipeline。
## Run in ./code ## kubectl apply -f ../docu/3-advanced/5-kyma-add-cls/cls/tracepipeline-app-traces.yaml
## tracepipeline-app-traces.yaml ## apiVersion: telemetry.kyma-project.io/v1alpha1 kind: TracePipeline metadata: name: susaas-traces spec: output: otlp: endpoint: valueFrom: secretKeyRef: name: susaas-logging namespace: mtenant key: ingest-otlp-endpoint tls: cert: valueFrom: secretKeyRef: name: susaas-logging namespace: mtenant key: ingest-otlp-cert key: valueFrom: secretKeyRef: name: susaas-logging namespace: mtenant key: ingest-otlp-key
Telemetry Manager 会依据 TracePipeline 资源(包括跟踪网关的目标后端)配置网关。跟踪网关会把数据发送到 TracePipeline 资源中指定的可观测性系统。 按以下步骤可在 SAP Cloud Logging 中找到某个请求的跟踪:
发送指标详情
要把指标发送到 SAP Cloud Logging,需要创建以下 MetricPipeline。## Run in ./deploy/kyma ## kubectl apply -f ../docu/3-advanced/5-kyma-add-cls/cls/metricpipeline-app-metrics.yaml
## metricpipeline-app-metrics.yaml ## apiVersion: telemetry.kyma-project.io/v1alpha1 kind: MetricPipeline metadata: name: susaas-metrices spec: input: prometheus: enabled: false istio: enabled: false runtime: enabled: false otlp: namespaces: include: - mtenant output: otlp: endpoint: valueFrom: secretKeyRef: name: susaas-logging namespace: mtenant key: ingest-otlp-endpoint tls: cert: valueFrom: secretKeyRef: name: susaas-logging namespace: mtenant key: ingest-otlp-cert key: valueFrom: secretKeyRef: name: susaas-logging namespace: mtenant key: ingest-otlp-key
该配置会从 susaas 命名空间收集指标并发送到 SAP Cloud Logging。Telemetry Manager 会依据 MetricPipeline 资源规格(包括指标网关的目标后端)配置代理与网关。指标网关会把数据发送到 MetricPipeline 资源中指定的可观测性系统。你可以修改资源规格来为 Istio 启用指标,详见设置 MetricPipeline
在 OpenTelemetry/Metrics 标签页中,可以看到由 Telemetry 插件自动收集的指标数据,如下所示

访问 SAP Cloud Logging 服务并探索仪表盘
NOTE:也可以添加自定义指标并在仪表盘中可视化。要了解如何创建自定义指标,请参阅「创建自定义指标」一节。
4. 延伸阅读
关于上述主题的更多信息,请使用以下链接:




















































