欢迎使用 @ cap- js/ 遥测
关于此工程
@cap-js/telemetry 是 CDS 插件,提供可观察性特性,包括 自动打开遥测仪表。 。 。 .
文件可在下列地点找到: 顶点. cloud.sap 财务报告和审定财务报表 开远测量.io。 。 。 .
目录
所需资源
见 开始 如何在SAP Cloud应用编程模型中跳动启动您的开发并成长.
设置
简单添加 @cap-js/telemetry 通过 npm add @cap-js/telemetry 你会发现远程测量输出 写在控制台这样:
[odata] - GET /odata/v4/processor/Incidents
[telemetry] - elapsed times:
0.00 → 2.85 = 2.85 ms GET /odata/v4/processor/Incidents
0.47 → 1.24 = 0.76 ms ProcessorService - READ ProcessorService.Incidents
0.78 → 1.17 = 0.38 ms db - READ ProcessorService.Incidents
0.97 → 1.06 = 0.09 ms @cap-js/sqlite - prepare SELECT json_object('ID',ID,'createdAt',createdAt,'creat…
1.10 → 1.13 = 0.03 ms @cap-js/sqlite - stmt.all SELECT json_object('ID',ID,'createdAt',createdAt,'crea…
1.27 → 1.88 = 0.61 ms ProcessorService - READ ProcessorService.Incidents.drafts
1.54 → 1.86 = 0.32 ms db - READ ProcessorService.Incidents.drafts
1.74 → 1.78 = 0.04 ms @cap-js/sqlite - prepare SELECT json_object('ID',ID,'DraftAdministrativeData_Dra…
1.81 → 1.85 = 0.04 ms @cap-js/sqlite - stmt.all SELECT json_object('ID',ID,'DraftAdministrativeData_Dr…
见 预定义类型 对于额外的依赖,您需要带给自己以及一些额外的设置步骤,您在向 Dynatrace, SAP Cloud Looking, Jaeger 等输出时需要执行.
设置环境变量可禁用插件 NO_TELEMETRY 对某事的真相.
数据库追踪仅限于 @cap-js/cds-dbs (英语)- 基于数据库,例如: @ cap-js/ sqlite (英语) 财务报告和审定财务报表 @cap-js/hana (英语)。 。 。 .
遥测信号
遥测数据分为三类,又称: 信号。 。 。 .
以下简要叙述在下文中如何处理每个问题: @cap-js/telemetry。 。 。 .
关于一般信号的更多信息,请参见: https://openterometry.io/docs/概念/符号。 。 。 .
追踪
Tracks允许您分析一个请求,消息,任务等是如何在您分布的系统中处理的.
为了这个, @cap-js/telemetry 包罗全部基本函数 cds.Service 及其衍生物.
用于 @cap-js 数据库(例如, @cap-js/sqlite),这包括 prepare() 及随后 stmt.run() 和喜欢的.
Dynatrace 中的实例跟踪 :

打印到控制台的示例 telemetry-to-console。 。 。 .
要向 Dynatrace 导出痕迹, 请使用预定义的类型 telemetry-to-dynatrace如果 一号代理 目前,CDS跨度也可以由OneAgent在程序中捕获,而不使用OTLP的追踪出口商.
计量
度量衡是"运行时捕获的度量衡",帮助您了解应用的健康和性能.
这个 @cap-js/telemetry 允许在框外观察一些参数.
其中包括: @opentelemetry/instrumentation-host-metrics (如果软件包在应用程序的依赖性中找到),
关于该应用程序数据库库的参数,即: 池信息 统计数据 generic-pool, (中文(简体) ),
衡量标准 CAP 的持续队列。 。 。 .
主机计量
@ 开元/ 仪器 -- -- 主机测量 允许您通过配置选项选择将收藏限制在一个或多个度量组 metricGroups。 。 。 .
对于后向兼容, @cap-js/telemetry 限制收藏到 ['process.cpu', 'process.memory'] 如果没有手动配置( 通过) cds.requires.telemetry.instrumentations)或通过环境变量被禁用 HOST_METRICS_RETAIN_SYSTEM=true。 。 。 .
为了避免挤出控制台,只是 process.* 默认打印,无论 system.* 衡量标准是否被忽视.
打印 system.* 可以通过环境变量启用内置控制台导出器中的度量(如果没有被忽略) HOST_METRICS_LOG_SYSTEM=true。 。 。 .
示例 host metrics 产出:
[telemetry] - host metrics:
Process Cpu time in seconds: { user: 1691.832, system: 218.223 }
Process Cpu usage time 0-1: { user: 82.07801878654074, system: 10.586932682237526 }
Process Memory usage in bytes: 141049856
数据库库
收集资料 db.pool 参数,可以通过设置来禁用 cds.requires.telemetry.metrics._db_pool 改为 false。 。 。 .
请注意,应考虑这一备选方案的具体名称和结构 beta 并且很可能会在未来发生变化.
示例 db.pool 输出 :
[telemetry] - db.pool:
size | available | pending
1/1 | 1/1 | 0
队列
获取关于 CAP 持久队列、与相关数据库表格的互动和当前状况的测量数据 - cds.outbox.Messages - 被观察.
基于互动的衡量标准 incoming 财务报告和审定财务报表 outgoing 每个应用实例都观察到,而基于表格的计量标准 cold, (中文(简体) ), remaining 财务报告和审定财务报表 * storage times 每个数据库都观察到(但每个应用程序都观察到).
一旦针对特定队列服务的信件首次被排入队列,则开始对特定队列服务的观察.
所有关于存储时间的观测以秒计.
收集资料 queue 参数,可以通过设置来禁用 cds.requires.telemetry.metrics._queue 改为 false。 。 。 .
请注意,应考虑这一备选方案的具体名称和结构 beta 并且很可能会在未来发生变化.
此外, queue 仅在使用 @sap/cds >= 9。 。 。 .
示例 queue 输出 :
[telemetry] - queue:
cold | remaining | min storage time | med storage time | max storage time | incoming | outgoing
2 | 32 | 2 | 16 | 128 | 256 | 512
自定义计量
最后,可以添加自定义度量衡如下示例(tenant-aware required counting):
// server.js
const cds = require('@sap/cds')
let counter
cds.middlewares.add((req, _, next) => {
counter.add(1, { 'sap.tenancy.tenant_id': cds.context.tenant })
next()
})
cds.on('listening', () => {
const { metrics } = require('@opentelemetry/api')
const meter = metrics.getMeter('@capire/incidents:req.counter')
counter = meter.createCounter('req.counter')
})
module.exports = cds.server
日志
通过OpenTeleometry导出日志作为实验性选入功能得到支持.
通过添加区域启用 logging 改为 cds.requires.telemetry 如下(使用 grpc 例如:
"logging": {
"exporter": {
"module": "@opentelemetry/exporter-logs-otlp-grpc",
"class": "OTLPLogExporter"
}
}
cds.log()SAP Cloud 日志的自定义字段配置决定了添加到此选项的附加属性 LogRecord。 。 。 .
见 cds.log() - 自定义字段 详细情况.
请注意,为了通过OpenTeleometry输出日志, cds.log()JSON log formatter 必须是活性的, 这是生产中的默认, 但不是开发中的默认 .
预定义类型
有5个预定义类型如下:
telemetry-to-console
如先前所描述的那样,打印指向控制台的痕迹和度量标准(跟踪在 设置 和指标 遥测信号 - 度量衡) (中文(简体) ).
不需要额外的依赖. 这是开发与生产的默认类型.
telemetry-to-dynatrace
向Dynatrace出口痕迹和度量衡. 因此,需要Dynatrace实例,应用程序必须与Dynatrace实例挂钩.
通过 cds.requires.telemetry.kind = 'to-dynatrace'。 。 。 .
所需额外依赖:
@opentelemetry/exporter-trace-otlp-proto@opentelemetry/exporter-metrics-otlp-proto
出口痕迹的必要范围openTelemetryTrace.ingest)和指标(metrics.ingest)不是标准的一部分 apitoken 并且必须提出要求.
这可以通过将绑定到"管理服务实例"(即不是用户提供的服务实例)的参数化实现如下.
摘自实例 mta.yaml :
requires:
- name: my-dynatrace-instance
parameters:
config:
tokens:
- name: ingest_apitoken #> default lookup name, configurable via cds.requires.telemetry.token_name
scopes:
- openTelemetryTrace.ingest
- metrics.ingest
在用户提供的服务中,您需要在Dynatrace中生成一个具有必要范围的信使,将其添加到用户提供的服务的证书中,并配置 cds.requires.telemetry.token_name 如果证书对象中的密钥不是 ingest_apitoken。 。 。 .
Dynatrace本身中,您需要确保启用以下两个特性:
- OpenTeleometry Node.js 仪器代理支持 :
- 从 Dynatrace 菜单进入设置 > 首选项 > OneAgent 特性.
- 查找并打开 OpenTeleometry 节点.js 仪器代理支持.
- W3C 追踪背景 :
- 从 Dynatrace 菜单进入设置 > 服务器侧服务监测 > 深度监测 > 分布追踪.
- 打开发送 W3C Trace 背景 HTTP 头头 .
一号代理
若为 一号代理 例如,在SAP BTP CF中存在,OTLP追踪出口商是 没有 已安装, @cap-js/telemetry 不导出痕迹。 相反,它登记了一个没有出口商的录音追踪器提供者,并依靠OneAgent在进程中的OpenTeleometry捕捉来取取CDS跨度——没有OTLP输出,没有重复跨度.
安装 OTLP 跟踪导出器(@opentelemetry/exporter-trace-otlp-proto,参见 所需额外依赖 (见上文)优先: @cap-js/telemetry 然后导出跨度本身而不是依赖于进程内抓取,以及 openTelemetryTrace.ingest 必须给予范围.
telemetry-to-cloud-logging
向SAP云记录系统出口痕迹和度量衡. 因此,需要SAP云记录实例,该应用程序必须与SAP云记录实例挂钩.
通过 cds.requires.telemetry.kind = 'to-cloud-logging'。 。 。 .
所需额外依赖:
@grpc/grpc-js@opentelemetry/exporter-trace-otlp-grpc@opentelemetry/exporter-metrics-otlp-grpc
为了在SAP Cloud Digging 实例的绑定中接收 OpenTeleometry 证书,您需要在创建 SAP Cloud Digging 实例时包含以下配置(或者通过更新现有实例) :
{
"ingest_otlp": {
"enabled": true
}
}
如果您正在将您的应用程序绑定到 SAP 云记录 用户提供的服务实例,确保它有标记 Cloud Logging。 。 。 .
提示:要将所需的标记添加到现有的用户提供的服务中,您可以使用:
cf update-user-provided-service {service-name} -t "Cloud Logging"关于联合呼吁程序中具有约束力的决议的详细资料,请查阅
cds.connect()• 服务约束。 。 。 .
telemetry-to-jaeger
出口追踪到杰格.
通过 cds.requires.telemetry.kind = 'to-jaeger'。 。 。 .
所需的额外依赖性(由于Jaeger不支持衡量标准,只需要追踪出口商):
@opentelemetry/exporter-trace-otlp-proto
提供这样自定义的证书:
{
"cds": {
"requires": {
"telemetry": {
"kind": "to-jaeger",
"tracing": {
"exporter": {
"config": { //> this object is passed into constructor as is
// add credentials here as decribed in
// https://www.npmjs.com/package/@opentelemetry/exporter-trace-otlp-proto
}
}
}
}
}
}
}
通过本地运行 Jaeger 插头数字 :
- 运行
docker run -d --name jaeger -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 -e COLLECTOR_OTLP_ENABLED=true -p 6831:6831/udp -p 6832:6832/udp -p 5778:5778 -p 16686:16686 -p 4317:4317 -p 4318:4318 -p 14250:14250 -p 14268:14268 -p 14269:14269 -p 9411:9411 jaegertracing/all-in-one:latest- 这样,就不需要自定义的证书了
- 打开
localhost:16686看到痕迹
telemetry-to-otlp
向OTLP/gRPC或OTLP/HTTP端点出口痕量和度量 环境变量。 。 。 .
通过 cds.requires.telemetry.kind = 'to-otlp'。 。 。 .
所需额外依赖性* = grpc|proto|http:
@grpc/grpc-js(关于OTLP/gRPC)@opentelemetry/exporter-trace-otlp-*@opentelemetry/exporter-metrics-otlp-*
请注意: @cap-js/telemetry 不通过环境变量验证配置 !
运行 SAP 云 ALM (β)
当您的应用程序已经运行 SAP Cloud ALM 代理扩展名时( S)@sap/xotel-agent-ext-js),该代理拥有OpenTeleometry SDK. @cap-js/telemetry 检测,而不是建立自己的追踪提供者,而是将其CDS跨度贡献给代理人的追踪管道(作为代理人的跨度处理器上的代表)。 两者运行在一个共享的OpenTeleometry SDK实例上,因此CDS跨度与代理已经收集的数据同时出现——没有第二个SDK,没有重复设置.
这需要 @sap/xotel-agent-ext-js 2.0.4 或后论. 关于SAP Cloud ALM代理软件本身的启用和上载,请参考 SAP 云ALM 文档。 。 。 .
注意:这种并存状态目前为β. 不支持与 Dynatrace One Agent 一起运行 SAP Cloud ALM 代理 .
详细配置选项
配置通过
一般来说,您可以通过相应的模块来影响使用过的模块的配置 config 节点在 cds.env.requires.telemetry。 。 。 .
例如,可以指明: temporalityPreference 设置相应的指标出口商,例如:
{
"cds": {
"requires": {
"telemetry": {
"metrics": {
"exporter": {
"config": { //> this object is passed into constructor as is
"temporalityPreference": "DELTA"
}
}
}
}
}
}
}
资源属性
资源属性描述生成遥测的实体. 见 资源 财务报告和审定财务报表 资源语义公约 更多细节.
@cap-js/telemetry 自动从应用程序的信息中获取资源属性( n)package.json)以及该应用的环境 (.
您可以配置额外的属性, 也可以通过 cds.requires.telemetry.resource.attributes = { <key>: <value>, ... }
示例
{
"service.version": "1.2.3",
"my.custom.attribute": "foo"
}
仪器
通过 cds.requires.telemetry.instrumentations = { <name>: { module, class, config? } }
默认 :
{
"http": {
"module": "@opentelemetry/instrumentation-http",
"class": "HttpInstrumentation"
},
"undici": {
"module": "@opentelemetry/instrumentation-undici",
"class": "UndiciInstrumentation"
}
}
样本
通过 cds.requires.telemetry.tracing.sampler = { kind, root?, ratio?, ignoreIncomingPaths? }
默认 :
{
"kind": "ParentBasedSampler",
"root": "AlwaysOnSampler",
"ignoreIncomingPaths": [
"/health"
]
}
宣传者
通过 cds.requires.telemetry.tracing.propagators = [<name> | { module, class, config? }]
默认 :
["W3CTraceContextPropagator", "W3CBaggagePropagator"]
宽处理器
通过 cds.requires.telemetry.tracing.processor = { kind, config? }时 kind 这是其中之一 BatchSpanProcessor 或者说 SimpleSpanProcessor 财务报告和审定财务报表 config 传递到处理器的构造器.
默认 : BatchSpanProcessor时,除 [development] 配置文件,用于 SimpleSpanProcessor 因此立即导出跨度.
{
"kind": "BatchSpanProcessor"
}
[注] 这个
ConsoleSpanExporter(默认)telemetry-to-console仅对出口者进行了测试SimpleSpanProcessor将它与BatchSpanProcessor不建议.
出口商
通过 :
cds.requires.telemetry.tracing.exporter = { module, class, config? }cds.requires.telemetry.metrics.exporter = { module, class, config? }
默认 :
{
{
"kind": "telemetry-to-console",
"tracing": {
"module": "@cap-js/telemetry",
"class": "ConsoleSpanExporter"
},
"metrics": {
"module": "@cap-js/telemetry",
"class": "ConsoleMetricExporter"
}
},
{
"kind": "telemetry-to-dynatrace",
"tracing": {
"exporter": {
"module": "@opentelemetry/exporter-trace-otlp-proto",
"class": "OTLPTraceExporter"
}
},
"metrics": {
"exporter": {
"module": "@opentelemetry/exporter-metrics-otlp-proto",
"class": "OTLPMetricExporter"
}
}
},
{
"kind": "telemetry-to-cloud-logging",
"tracing": {
"exporter": {
"module": "@opentelemetry/exporter-trace-otlp-grpc",
"class": "OTLPTraceExporter"
}
},
"metrics": {
"exporter": {
"module": "@opentelemetry/exporter-metrics-otlp-grpc",
"class": "OTLPMetricExporter"
}
}
},
{
"kind": "telemetry-to-jaeger",
"tracing": {
"exporter": {
"module": "@opentelemetry/exporter-trace-otlp-proto",
"class": "OTLPTraceExporter"
}
}
}
}
一些替代出口国
- JSON 输出到控制台时, 使用 :
{ "tracing": { "exporter": { "module": "@opentelemetry/sdk-trace-base", "class": "ConsoleSpanExporter" } }, "metrics": { "exporter": { "module": "@opentelemetry/sdk-metrics", "class": "ConsoleMetricExporter" } } } - 对于HTTP,使用:
{ "tracing": { "exporter": { "module": "@opentelemetry/exporter-trace-otlp-http", "class": "OTLPTraceExporter" } }, "metrics": { "exporter": { "module": "@opentelemetry/exporter-metrics-otlp-http", "class": "OTLPMetricExporter" } } }
高分辨率时间戳(β)
默认情况下,从 Date.now() 因此,只有毫秒分辨率.
通过 cds.requires.telemetry.tracing.hrtime = true,可以指示插件指定跨度的起止时间,这与纳秒分辨率有关.
这可能造成轻微漂移,特别是由于其他仪器,例如: @opentelemetry/instrumentation-http。 。 。 .
因此 hrtime 模式在开发过程中默认使用,但在生产过程中则不使用.
SAP 业绩统计(β)
启用时, 输出的 HTTP 客户端跨度会被来自响应头的 SAP 性能统计所丰富 sap-statistics (SAP Gateway/ICM/Web调度员), sap-statistics-scc (云连接器)和 sap-statistics-hciodp (BTP上提供OData). 这些信头只有在请求时才返回,例如通过请求信头返回 sap-statistics: true统计记录 http编号 :https 客户电话(例如通过SAP Cloud SDK的电话) fetch编号 :undici 打电话.
它是选择通过 cds.requires.telemetry.tracing.sap_statistics数字 :
true- 通过默认模式启用(fields(中文(简体) ){ "mode": "fields" }– 每个字段一个数字属性,例如.sap.statistics.total = 42(默认){ "mode": "raw" }– 每个标题一个字符串属性,例如.sap.statistics = "total=42,gwtotal=40,..."{ "mode": "both" }- 原始和已解析的属性
{
"requires": {
"telemetry": {
"tracing": {
"sap_statistics": true
}
}
}
}
注:这取决于
@cap-js/telemetry安装 HTTP 仪器本身, 因此无法使用 使用 SAP 云 ALM 代理运行时,它拥有OpenTeleometry SDK及其仪器.
环境变量
NO_TELEMETRY: 禁用插件NO_LOCATE: 在跟踪中禁用函数位置SAP_PASSPORT: 启用向 SAP HANA 传播 W3C 微量上下文( 实验!)OTEL_LOG_LEVEL: 如果未指定, 则 cds 日志的日志级别telemetry用于OTEL_SERVICE_NAME: 如果未指定,则从 package.json (默认为“ CAP 应用程序”) 中确定名称OTEL_SERVICE_VERSION: 如果未指定,则该版本从 package.json(默认为"1.0.0")确定
关于OpenTeleometry所支持的环境变量完整列表,参见 环境可变规格。 。 。 .
请注意: process.env.VCAP_APPLICATION 财务报告和审定财务报表 process.env.CF_INSTANCE_GUID如果存在,则用于确定一些 属性。 。 。 .
自定义 Spans( β)
自定义跨度可以通过 tracer.startActiveSpan()。 。 。 .
为此,您需要通过 TraceAPI.get Tracer () (中文(简体) )。 。 。 .
支持、反馈、贡献
此项目可通过下列方式对特性请求/建议、错误报告等开放: GitHub 问题鼓励并始终欢迎各方作出贡献和反馈。 关于如何作出贡献的更多信息,项目结构以及额外贡献信息见我们 贡献准则。 。 。 .
行为守则
作为成员、贡献者和领导人,我们保证使参加我们的社区成为每个人不受骚扰的经历。 通过参与这个项目,你同意遵守 行为守则 在任何时间.
许可证发放
版权2023 SAP SE或SAP下属公司和贡献者。 请看我们的 自由主义 版权和许可证信息。 详细信息,包括第三方组成部分及其许可证/版权信息 通过REUSE工具。 。 。 .