# @cap-js/telemetry 中文文档 规范地址：https://npmcn.com/package/%40cap-js/telemetry/ 版本：2\.2\.0 npm 元数据更新时间：2026-10-29T15:06:14.583Z 中文译文更新时间：2026-11-09T03:01:43.840Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40cap-js/telemetry 原文对照：https://npmcn.com/package/%40cap-js/telemetry/?lang=original 项目主页：https://cap.cloud.sap/ 源码仓库：https://github.com/cap-js/telemetry ## 关键信息（来自 npm 元数据） - 包体积（解压后）：150 kB，26 个文件 - 模块格式：CommonJS - TypeScript 类型：未声明 - 运行依赖：10 个 - peer 依赖：@sap/cds ^10 \|\| ^9 - 首次发布：2023-12-18T09:39:30.899Z - 最新版本发布：2026-10-29T15:06:13.124Z - 近 30 天下载量：61615（2026-10-09 至 2026-11-07，npm 官方下载统计） - 已发布版本数：38（近 12 个月 6 个） ## 中文简介 CDS插件提供可观察性特性,包括自动的OpenTeleometry仪器. ## 安装 ```sh npm install @cap-js/telemetry ``` 也可以使用：`pnpm add @cap-js/telemetry`、`yarn add @cap-js/telemetry`、`bun add @cap-js/telemetry` ## README # 欢迎使用 @ cap- js/ 遥测 [![REUSE status](https://api.reuse.software/badge/github.com/cap-js/telemetry)](https://api.reuse.software/info/github.com/cap-js/telemetry) ## 关于此工程 `@cap-js/telemetry` 是 CDS 插件,提供可观察性特性,包括 [自动打开遥测仪表](https://opentelemetry.io/docs/concepts/instrumentation/automatic)。 。 。 . 文件可在下列地点找到: [顶点. cloud.sap](https://cap.cloud.sap/docs) 财务报告和审定财务报表 [开远测量.io](https://opentelemetry.io/docs)。 。 。 . ## 目录 - [关于此工程](https://npmcn.com/package/%40cap-js/telemetry/#readme-about-this-project) - [所需资源](https://npmcn.com/package/%40cap-js/telemetry/#readme-requirements) - [设置](https://npmcn.com/package/%40cap-js/telemetry/#readme-setup) - [遥测信号](https://npmcn.com/package/%40cap-js/telemetry/#readme-telemetry-signals) - [追踪](https://npmcn.com/package/%40cap-js/telemetry/#readme-traces) - [计量](https://npmcn.com/package/%40cap-js/telemetry/#readme-metrics) - [日志](https://npmcn.com/package/%40cap-js/telemetry/#readme-logs) - [预定义类型](https://npmcn.com/package/%40cap-js/telemetry/#readme-predefined-kinds) - [`telemetry-to-console`](https://npmcn.com/package/%40cap-js/telemetry/#readme-telemetry-to-console) - [`telemetry-to-dynatrace`](https://npmcn.com/package/%40cap-js/telemetry/#readme-telemetry-to-dynatrace) - [`telemetry-to-cloud-logging`](https://npmcn.com/package/%40cap-js/telemetry/#readme-telemetry-to-cloud-logging) - [`telemetry-to-jaeger`](https://npmcn.com/package/%40cap-js/telemetry/#readme-telemetry-to-jaeger) - [`telemetry-to-otlp`](https://npmcn.com/package/%40cap-js/telemetry/#readme-telemetry-to-otlp) - [运行 SAP 云 ALM (β)](https://npmcn.com/package/%40cap-js/telemetry/#readme-running-with-sap-cloud-alm-beta) - [详细配置选项](https://npmcn.com/package/%40cap-js/telemetry/#readme-detailed-configuration-options) - [配置通过](https://npmcn.com/package/%40cap-js/telemetry/#readme-configuration-pass-through) - [资源属性](https://npmcn.com/package/%40cap-js/telemetry/#readme-resource-attributes) - [仪器](https://npmcn.com/package/%40cap-js/telemetry/#readme-instrumentations) - [样本](https://npmcn.com/package/%40cap-js/telemetry/#readme-sampler) - [宣传者](https://npmcn.com/package/%40cap-js/telemetry/#readme-propagators) - [宽处理器](https://npmcn.com/package/%40cap-js/telemetry/#readme-span-processor) - [出口商](https://npmcn.com/package/%40cap-js/telemetry/#readme-exporters) - [高分辨率时间戳(β)](https://npmcn.com/package/%40cap-js/telemetry/#readme-high-resolution-timestamps-beta) - [SAP 业绩统计(β)](https://npmcn.com/package/%40cap-js/telemetry/#readme-sap-performance-statistics-beta) - [环境变量](https://npmcn.com/package/%40cap-js/telemetry/#readme-environment-variables) - [自定义 Spans( β)](https://npmcn.com/package/%40cap-js/telemetry/#readme-custom-spans-beta) - [支持、反馈、贡献](https://npmcn.com/package/%40cap-js/telemetry/#readme-support-feedback-contributing) - [行为守则](https://npmcn.com/package/%40cap-js/telemetry/#readme-code-of-conduct) - [许可证发放](https://npmcn.com/package/%40cap-js/telemetry/#readme-licensing) ## 所需资源 见 [开始](https://cap.cloud.sap/docs/get-started) 如何在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… ``` 见 [预定义类型](https://npmcn.com/package/%40cap-js/telemetry/#readme-predefined-kinds) 对于额外的依赖,您需要带给自己以及一些额外的设置步骤,您在向 Dynatrace, SAP Cloud Looking, Jaeger 等输出时需要执行. 设置环境变量可禁用插件 `NO_TELEMETRY` 对某事的真相. 数据库追踪仅限于 [@cap-js/cds-dbs (英语)](https://github.com/cap-js/cds-dbs)\- 基于数据库,例如: [@ cap-js/ sqlite (英语)](https://www.npmjs.com/package/@cap-js/sqlite) 财务报告和审定财务报表 [@cap-js/hana (英语)](https://www.npmjs.com/package/@cap-js/hana)。 。 。 . ## 遥测信号 遥测数据分为三类,又称: _信号_。 。 。 . 以下简要叙述在下文中如何处理每个问题: `@cap-js/telemetry`。 。 。 . 关于一般信号的更多信息,请参见: [https://openterometry.io/docs/概念/符号](https://opentelemetry.io/docs/concepts/signals)。 。 。 . ### 追踪 Tracks允许您分析一个请求,消息,任务等是如何在您分布的系统中处理的. 为了这个, `@cap-js/telemetry` 包罗全部基本函数 `cds.Service` 及其衍生物. 用于 @cap-js 数据库(例如, `@cap-js/sqlite`),这包括 `prepare()` 及随后 `stmt.run()` 和喜欢的. Dynatrace 中的实例跟踪 : ![Example trace in Dynatrace](https://npmcn.com/package/%40cap-js/telemetry/docs/dynatrace.png) 打印到控制台的示例 [`telemetry-to-console`](https://npmcn.com/package/%40cap-js/telemetry/#readme-telemetry-to-console)。 。 。 . 要向 Dynatrace 导出痕迹, 请使用预定义的类型 [`telemetry-to-dynatrace`](https://npmcn.com/package/%40cap-js/telemetry/#readme-telemetry-to-dynatrace)如果 [一号代理](https://npmcn.com/package/%40cap-js/telemetry/#readme-dynatrace-oneagent) 目前,CDS跨度也可以由OneAgent在程序中捕获,而不使用OTLP的追踪出口商. ### 计量 度量衡是"运行时捕获的度量衡",帮助您了解应用的健康和性能. 这个 `@cap-js/telemetry` 允许在框外观察一些参数. 其中包括: [`@opentelemetry/instrumentation-host-metrics`](https://www.npmjs.com/package/@opentelemetry/instrumentation-host-metrics) (如果软件包在应用程序的依赖性中找到), 关于该应用程序数据库库的参数,即: [池信息](https://www.npmjs.com/package/generic-pool#pool-info) 统计数据 `generic-pool`, (中文(简体) ), 衡量标准 [CAP 的持续队列](https://cap.cloud.sap/docs/node.js/queue#persistent-queue)。 。 。 . #### 主机计量 [@ 开元/ 仪器 -- -- 主机测量](https://www.npmjs.com/package/@opentelemetry/instrumentation-host-metrics) 允许您通过配置选项选择将收藏限制在一个或多个度量组 `metricGroups`。 。 。 . 对于后向兼容, `@cap-js/telemetry` 限制收藏到 `['process.cpu', 'process.memory']` 如果没有手动配置( 通过) [`cds.requires.telemetry.instrumentations`](https://npmcn.com/package/%40cap-js/telemetry/#readme-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): ```js // 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` 例如: ```json "logging": { "exporter": { "module": "@opentelemetry/exporter-logs-otlp-grpc", "class": "OTLPLogExporter" } } ``` `cds.log()`SAP Cloud 日志的自定义字段配置决定了添加到此选项的附加属性 `LogRecord`。 。 。 . 见 [`cds.log()` - 自定义字段](https://cap.cloud.sap/docs/node.js/cds-log#custom-fields) 详细情况. 请注意,为了通过OpenTeleometry输出日志, `cds.log()`JSON log formatter 必须是活性的, 这是生产中的默认, 但不是开发中的默认 . ## 预定义类型 有5个预定义类型如下: ### `telemetry-to-console` 如先前所描述的那样,打印指向控制台的痕迹和度量标准(跟踪在 [设置](https://npmcn.com/package/%40cap-js/telemetry/#readme-setup) 和指标 [遥测信号 - 度量衡](https://npmcn.com/package/%40cap-js/telemetry/#readme-metrics)) (中文(简体) ). 不需要额外的依赖. 这是开发与生产的默认类型. ### `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 : ```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本身中,您需要确保启用以下两个特性: 1. OpenTeleometry Node.js 仪器代理支持 : - 从 Dynatrace 菜单进入设置 > 首选项 > OneAgent 特性. - 查找并打开 OpenTeleometry 节点.js 仪器代理支持. 2. W3C 追踪背景 : - 从 Dynatrace 菜单进入设置 > 服务器侧服务监测 > 深度监测 > 分布追踪. - 打开发送 W3C Trace 背景 HTTP 头头 . #### 一号代理 若为 [一号代理](https://www.dynatrace.com/platform/oneagent) 例如,在SAP BTP CF中存在,OTLP追踪出口商是 _没有_ 已安装, `@cap-js/telemetry` 不导出痕迹。 相反,它登记了一个没有出口商的录音追踪器提供者,并依靠OneAgent在进程中的OpenTeleometry捕捉来取取CDS跨度——没有OTLP输出,没有重复跨度. 安装 OTLP 跟踪导出器(`@opentelemetry/exporter-trace-otlp-proto`,参见 [所需额外依赖](https://npmcn.com/package/%40cap-js/telemetry/#readme-telemetry-to-dynatrace) (见上文)优先: `@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 实例时包含以下配置(或者通过更新现有实例) : ```json { "ingest_otlp": { "enabled": true } } ``` 如果您正在将您的应用程序绑定到 SAP 云记录 [用户提供的服务实例](https://docs.cloudfoundry.org/devguide/services/user-provided.html),确保它有标记 `Cloud Logging`。 。 。 . > 提示:要将所需的标记添加到现有的用户提供的服务中,您可以使用: > > ``` > cf update-user-provided-service {service-name} -t "Cloud Logging" > ``` > > 关于联合呼吁程序中具有约束力的决议的详细资料,请查阅 [`cds.connect()` • 服务约束](https://cap.cloud.sap/docs/node.js/cds-connect#service-bindings)。 。 。 . ### `telemetry-to-jaeger` 出口追踪到杰格. 通过 `cds.requires.telemetry.kind = 'to-jaeger'`。 。 。 . 所需的额外依赖性(由于Jaeger不支持衡量标准,只需要追踪出口商): - `@opentelemetry/exporter-trace-otlp-proto` 提供这样自定义的证书: ```jsonc { "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 [插头](https://www.docker.com/)数字 : - 运行 `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端点出口痕量和度量 [环境变量](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter)。 。 。 . 通过 `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 文档](https://support.sap.com/en/alm/sap-cloud-alm/operations/expert-portal/data-collection-infrastructure.html)。 。 。 . > 注意:这种并存状态目前为β. 不支持与 Dynatrace One Agent 一起运行 SAP Cloud ALM 代理 . ## 详细配置选项 ### 配置通过 一般来说,您可以通过相应的模块来影响使用过的模块的配置 `config` 节点在 `cds.env.requires.telemetry`。 。 。 . 例如,可以指明: `temporalityPreference` 设置相应的指标出口商,例如: ```jsonc { "cds": { "requires": { "telemetry": { "metrics": { "exporter": { "config": { //> this object is passed into constructor as is "temporalityPreference": "DELTA" } } } } } } } ``` ### 资源属性 资源属性描述生成遥测的实体. 见 [资源](https://opentelemetry.io/docs/concepts/resources) 财务报告和审定财务报表 [资源语义公约](https://opentelemetry.io/docs/specs/semconv/resource) 更多细节. `@cap-js/telemetry` 自动从应用程序的信息中获取资源属性( n)`package.json`)以及该应用的环境 (. 您可以配置额外的属性, 也可以通过 `cds.requires.telemetry.resource.attributes = { : , ... }` 示例 ```json { "service.version": "1.2.3", "my.custom.attribute": "foo" } ``` ### 仪器 通过 `cds.requires.telemetry.instrumentations = { : { module, class, config? } }` 默认 : ```json { "http": { "module": "@opentelemetry/instrumentation-http", "class": "HttpInstrumentation" }, "undici": { "module": "@opentelemetry/instrumentation-undici", "class": "UndiciInstrumentation" } } ``` ### 样本 通过 `cds.requires.telemetry.tracing.sampler = { kind, root?, ratio?, ignoreIncomingPaths? }` 默认 : ```json { "kind": "ParentBasedSampler", "root": "AlwaysOnSampler", "ignoreIncomingPaths": [ "/health" ] } ``` ### 宣传者 通过 `cds.requires.telemetry.tracing.propagators = [ | { module, class, config? }]` 默认 : ```json ["W3CTraceContextPropagator", "W3CBaggagePropagator"] ``` ### 宽处理器 通过 `cds.requires.telemetry.tracing.processor = { kind, config? }`时 `kind` 这是其中之一 `BatchSpanProcessor` 或者说 `SimpleSpanProcessor` 财务报告和审定财务报表 `config` 传递到处理器的构造器. 默认 : `BatchSpanProcessor`时,除 `[development]` 配置文件,用于 `SimpleSpanProcessor` 因此立即导出跨度. ```json { "kind": "BatchSpanProcessor" } ``` > \[注\] 这个 `ConsoleSpanExporter` (默认) `telemetry-to-console` 仅对出口者进行了测试 `SimpleSpanProcessor`将它与 `BatchSpanProcessor` 不建议. ### 出口商 通过 : - `cds.requires.telemetry.tracing.exporter = { module, class, config? }` - `cds.requires.telemetry.metrics.exporter = { module, class, config? }` 默认 : ```json { { "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" } } } } ``` #### 一些替代出口国 1. JSON 输出到控制台时, 使用 : ```json { "tracing": { "exporter": { "module": "@opentelemetry/sdk-trace-base", "class": "ConsoleSpanExporter" } }, "metrics": { "exporter": { "module": "@opentelemetry/sdk-metrics", "class": "ConsoleMetricExporter" } } } ``` 2. 对于HTTP,使用: ```json { "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" }` - 原始和已解析的属性 ```json { "requires": { "telemetry": { "tracing": { "sap_statistics": true } } } } ``` > 注:这取决于 `@cap-js/telemetry` 安装 HTTP 仪器本身, 因此无法使用 [使用 SAP 云 ALM 代理运行时](https://npmcn.com/package/%40cap-js/telemetry/#readme-running-with-sap-cloud-alm-beta),它拥有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所支持的环境变量完整列表,参见 [环境可变规格](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables)。 。 。 . 请注意: `process.env.VCAP_APPLICATION` 财务报告和审定财务报表 `process.env.CF_INSTANCE_GUID`如果存在,则用于确定一些 [属性](https://opentelemetry.io/docs/specs/otel/common/#attribute)。 。 。 . ## 自定义 Spans( β) 自定义跨度可以通过 [`tracer.startActiveSpan()`](https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api._opentelemetry_api.Tracer.html#startactivespan)。 。 。 . 为此,您需要通过 [TraceAPI.get Tracer () (中文(简体) )](https://open-telemetry.github.io/opentelemetry-js/classes/_opentelemetry_api._opentelemetry_api.TraceAPI.html#gettracer)。 。 。 . ## 支持、反馈、贡献 此项目可通过下列方式对特性请求/建议、错误报告等开放: [GitHub 问题](https://github.com/cap-js/telemetry/issues)鼓励并始终欢迎各方作出贡献和反馈。 关于如何作出贡献的更多信息,项目结构以及额外贡献信息见我们 [贡献准则](https://npmcn.com/package/%40cap-js/telemetry/CONTRIBUTING.md)。 。 。 . ## 行为守则 作为成员、贡献者和领导人,我们保证使参加我们的社区成为每个人不受骚扰的经历。 通过参与这个项目,你同意遵守 [行为守则](https://github.com/cap-js/.github/blob/main/CODE_OF_CONDUCT.md) 在任何时间. ## 许可证发放 版权2023 SAP SE或SAP下属公司和贡献者。 请看我们的 [自由主义](https://npmcn.com/package/%40cap-js/telemetry/LICENSE) 版权和许可证信息。 详细信息,包括第三方组成部分及其许可证/版权信息 [通过REUSE工具](https://api.reuse.software/info/github.com/cap-js/telemetry)。 。 。 . ## 常见问题 ### @cap-js/telemetry 是什么？ CDS插件提供可观察性特性,包括自动的OpenTeleometry仪器\. ### 如何安装 @cap-js/telemetry？ 在项目目录运行 npm install @cap-js/telemetry，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@sap/cds（^10 \|\| ^9）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @cap-js/telemetry 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cap-js\_\_telemetry 是否存在。 ### @cap-js/telemetry 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @cap-js/telemetry 可以商用吗？ @cap-js/telemetry 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @cap-js/telemetry 的下载量有多少？ 根据 npm 官方下载统计，@cap-js/telemetry 在 2026/10/09 – 2026/11/07 这 30 天内被下载 61,615 次，日均约 2,054 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @cap-js/telemetry 还在维护吗？ 最新版本 2\.2\.0 发布于 2026/10/29（10 天前）；至今共发布 38 个版本，其中过去 12 个月发布了 6 个；首次发布于 2023/12/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。