# @carecard/telemetry 中文文档

规范地址：https://npmcn.com/package/%40carecard/telemetry/

版本：3\.45\.0
npm 元数据更新时间：2026-11-02T19:30:07.500Z
中文译文更新时间：2026-11-09T13:17:25.798Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40carecard/telemetry
原文对照：https://npmcn.com/package/%40carecard/telemetry/?lang=original
项目主页：https://github.com/CareCard-ca/pkg-telemetry#readme
源码仓库：https://github.com/CareCard-ca/pkg-telemetry

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：30 kB，13 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.21\.0 \<25
- 运行依赖：13 个
- 首次发布：2026-07-29T19:25:46.089Z
- 最新版本发布：2026-11-02T19:30:07.324Z
- 近 30 天下载量：2576（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

CareCard Node.js 服务的隐私安全开口遥测追踪

## 安装

```sh
npm install @carecard/telemetry
```

也可以使用：`pnpm add @carecard/telemetry`、`yarn add @carecard/telemetry`、`bun add @carecard/telemetry`

## README

# @ carecard/ 遥测

## 1.1.1版和生产数据

CareCard Release 1.1.1是生产基准. 种子为 `--seed-release-data` 已经完成。 生产集群数据、数据库行、, 并保存存储的用户文件。 没有 完成用户数据擦拭和再创建.

未来生产变化必须使用数据保存迁移。 不重播 完成初始化或运行重置、回滚或种子工作流程 常规生产部署.

这个 [已完成的种子库存和核查记录](https://github.com/CareCard-ca/plans/blob/main/cc-seed-data/production-seed-result.md) 记录所接受的释放基准和核查限制.

CareCard Node.js服务器进程隐私安全OpenTeleometry追踪.

强制性寄存器政策:装入 `$pkg-telemetry-coding-standards-and-best-practices` 在更改、审查、, 测试、记录或释放此软件包.

该套装为CareCard服务拥有一个明确的追踪靴。 用这个 W3C 追踪背景,向Grafana合金出口OTLP/HTTP和仪器 HTTP、PostgreSQL和Kafka不向追踪发送应用有效载荷 后端 .

不可转让类型脚本类型规则: 永远不要使用类型脚本类型 `any`永远 使用特定领域类型、通用项目类型、现有项目类型,或 `unknown` 与 在所有类型Script- family文件中明确缩小(`.ts`, (中文(简体) ), `.tsx`, (中文(简体) ), `.mts`, (中文(简体) ), `.cts`,以及 `.d.ts`) (中文(简体) ).

## 安装

```sh
npm install @carecard/telemetry@3.44.0 --save-exact
```

## 诱饵

初始化环境配置后和装入前的追踪 `http`, (中文(简体) ), `express`, (中文(简体) ), `pg`, (中文(简体) ), `kafkajs`,或 `undici`。节点仪器补丁模块 当它们装入时, 因此导入这些库可以先离开请求 无相相相.

```js
require('./src/config');

const packageJson = require('./package.json');
const { createTelemetryShutdown, initializeServiceTelemetry } = require('@carecard/telemetry');

const telemetry = initializeServiceTelemetry({
  serviceName: 'worker',
  serviceVersion: packageJson.version,
});

const serverRuntime = require('./src/serverRuntime');

const shutdown = createTelemetryShutdown({
  telemetryRuntime: telemetry,
  shutdownResources: serverRuntime.shutdown,
});
```

`installTelemetryShutdownHandlers(telemetry)` 可用于小程序 尚未拥有 `SIGINT` 财务报告和审定财务报表 `SIGTERM` 处理。 服务 应使用现有的优雅的下沉路径 `createTelemetryShutdown()` 这样 如果清理失败, 应用程序资源将先停止, 遥测仍然会冲出 .

Next.js仪表板只从它的Node.js调用相同的初始化器 `instrumentation.ts` 注册钩。 浏览器和边缘运行时间不能装入 这个包裹.

## 配置

| 变量 | 默认 | 含义 |
| --- | --- | --- |
| `OTEL_SDK_DISABLED` | `false` | 设定为 `true` 以禁用 SDK 。 默认时已禁用 `NODE_ENV=test` 除非明确设定为 `false`。 。 。 . |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | `http://127.0.0.1:4318/v1/traces` | 合金OTLP/HTTP跟踪接收器. 证书、查询参数和碎片均被拒绝. |
| `OTEL_TRACES_SAMPLER` | `parentbased_traceidratio` | `parentbased_traceidratio`, (中文(简体) ), `always_on`,或 `always_off`。 。 。 . |
| `OTEL_TRACES_SAMPLER_ARG` | `1` 发展; `0.1` 生产 | 根取样比 `0` 结束 `1`。 。 。 . |

使用比例 `1` 用于本地开发和多克桌面库伯内特. 生产默认值 `0.1`;自办制作简介也设置了它 当然 基于父母的抽样保留了整个服务部门的上游决定 边框.

## 宣传

自动仪器为:

-   进出的节点HTTP请求;
-   快速处理请求;
-   没有查询参数或增强数据库的 PostgreSQL 操作 报告;
-   KafkaJS 生产者和消费者利用现有 `traceparent` 消息 页眉;
-   服务器侧 `fetch` 请求通过Undici.

正常的健康、准备状态、衡量标准以及下一个.js的静态请求没有追踪. 仅限 W3C `traceparent` 被传播。 提供打电话者 `tracestate` 被忽略, 并故意不配置行李.

对于持久的队列,在创建记录时抓取活动上下文 后处理记录时恢复:

```js
const { captureActiveTraceparent, runWithTraceparent } = require('@carecard/telemetry');

const eventMetadata = {
  traceparent: captureActiveTraceparent(),
};

await runWithTraceparent(
  {
    spanName: 'outbox publish',
    traceparent: eventMetadata.traceparent,
  },
  () => publishOutboxEvent(),
);
```

传递到 `runWithTraceparent` 必须固定,小写可操作 名称。 永远不要从用户、路由、记录、电子邮件、信使或有效载荷数据中构建它们.

## 隐私边界

出口者在离开期间之前使用源边隐私边界 进程。 它保持了路由模板, HTTP 等有界限的操作域 方法和状态代码、数据库操作名称、数据库命名空间以及 卡夫卡主题名称.

它会删除 SQL 文本,查询参数,消息有效载荷,消息密钥, URL 值、信头、饼干、授权数据、请求和响应机构, 客户端地址、用户代理、例外消息、例外堆栈、状态 描述、动态跨事件名称和链接属性。 格拉法纳合金 重复删除防御属性后再转发到 Tempo .

不添加附加域名标识符、 电子邮件地址、 JWTs 、 文件的钩子 名称、格式数据或其他跨度应用值.

## 公共 API

-   `initializeServiceTelemetry({ serviceName, serviceVersion })` 接受 CareCard 证书 `app-*` 财务报告和审定财务报表 `ms-*` 运行时间身份,包括 `app-auth` 财务报告和审定财务报表 `app-dashboard`。 。 。 .
-   `createTelemetryShutdown({ telemetryRuntime, shutdownResources })`
-   `captureActiveTraceparent()`
-   `runWithTraceparent({ spanName, traceparent }, operation)`
-   `installTelemetryShutdownHandlers(runtime)`

该软件包披露了通用JS、无害环境管理和类型脚本申报.

## 验证

```sh
npm run test:All
npm run lint
npm run format:check
npm audit --audit-level=high
```

## 召客身份和排斥

服务名称是通用的受限业务识别符. 设定 `serviceNamespace` 明确在需要的时候。 没有内置的应用程序命名规则,命名空间, 健康路线列表,或框架路线排除. 供应 `ignoreIncomingRequest` 拥有服务或申请的布尔决定。 出口 继续排除以避免遥测复发。 隐私消毒和W3C 传播仍然是一揽子技术责任.

## 常见问题

### @carecard/telemetry 是什么？

CareCard Node\.js 服务的隐私安全开口遥测追踪

### 如何安装 @carecard/telemetry？

在项目目录运行 npm install @carecard/telemetry，或使用 pnpm add / yarn add / bun add。

### @carecard/telemetry 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @carecard/telemetry 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @carecard/telemetry 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.21\.0 \<25。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @carecard/telemetry 可以商用吗？

@carecard/telemetry 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @carecard/telemetry 的下载量有多少？

根据 npm 官方下载统计，@carecard/telemetry 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,576 次，日均约 86 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @carecard/telemetry 还在维护吗？

最新版本 3\.45\.0 发布于 2026/11/03（6 天前）；至今共发布 28 个版本，其中过去 12 个月发布了 28 个；首次发布于 2026/07/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。