# @coralogix/opentelemetry 中文文档

规范地址：https://npmcn.com/package/%40coralogix/opentelemetry/

版本：0\.5\.1
npm 元数据更新时间：2026-11-02T13:12:14.924Z
中文译文更新时间：2026-11-10T18:29:52.471Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：324 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@opentelemetry/api ^1\.7\.0，@opentelemetry/core ^2\.8\.0，@opentelemetry/sdk-trace-base ^2\.8\.0
- 首次发布：2023-11-22T11:32:54.969Z
- 最新版本发布：2026-11-02T13:12:14.519Z
- 近 30 天下载量：109113（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 7 个）

## 中文简介

OpenTelemotics Node SDK的 Corlogix 扩展,包括 Corlogix APM 的交易采样器.

## 安装

```sh
npm install @coralogix/opentelemetry
```

也可以使用：`pnpm add @coralogix/opentelemetry`、`yarn add @coralogix/opentelemetry`、`bun add @coralogix/opentelemetry`

## README

[![Coralogix](https://npmcn.com/package/%40coralogix/opentelemetry/.github/assets/coralogix-logo-light.svg)](https://coralogix.com/?utm_source=oss_platforms&utm_medium=referral&utm_campaign=oss_presence&utm_content=readme_badge)

# 打开遥测节点 SDK 扩展

[![CI](https://github.com/coralogix/coralogix-opentelemetry-js/actions/workflows/ci.yml/badge.svg)](https://github.com/coralogix/coralogix-opentelemetry-js/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/@coralogix/opentelemetry.svg)](https://www.npmjs.com/package/@coralogix/opentelemetry) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://npmcn.com/package/%40coralogix/opentelemetry/LICENSE)

* * *

缩略语 [打开遥测节点 SDK](https://github.com/open-telemetry/opentelemetry-js)。本套件在标准OpenTeleometry追踪设置之上添加了 Corlogix 特定行为——通过采样器和/或一个 `SpanProcessor`,包括处理器路径上独有的自持续时间.

```bash
npm install --save @coralogix/opentelemetry
```

## 所需资源

此软件包依赖于您应用程序现有的 OpenTelemeter 设置 。 以下是: `peerDependencies` 并且必须同时安装:

| 软件包 | 版本 |
| --- | --- |
| `@opentelemetry/api` | `^1.7.0` |
| `@opentelemetry/sdk-trace-base` | `^2.8.0` |

以下例子也使用了 `@opentelemetry/resources` 财务报告和审定财务报表 `@opentelemetry/semantic-conventions`,它们属于典型的OpenTelemory节点设置的一部分.

> **说明:** 此套件针对 OpenTeleometry JS SDK **2.x 数据**。如下所示的资源/提供者 API(`resourceFromAttributes`, (中文(简体) ), `ATTR_SERVICE_NAME`)是 2.x API;如果您仍在 SDK 1.x 上,则相应调整设置(`new Resource(...)`, (中文(简体) ), `SemanticResourceAttributes`) (中文(简体) ).

## Corlogix 变速器

`CoralogixTransactionSampler` 将现有的 OpenTeleometry 采样器包成定义、 报告并监视 Corlogix [交易](https://coralogix.com/docs/user-guides/apm/features/transactions/)。它将 Corlogix 交易属性设定在被采样的跨度上,并传播交易身份.

```js
import { CoralogixTransactionSampler } from "@coralogix/opentelemetry";
import { AlwaysOnSampler } from "@opentelemetry/sdk-trace-base";

// Wrap your existing sampler...
const sampler = new CoralogixTransactionSampler(new AlwaysOnSampler());

// ...or omit the argument to default to a ParentBased(AlwaysOn) sampler.
const defaultSampler = new CoralogixTransactionSampler();
```

将采样器像其它 OpenTelemetry 采样器一样传递给您的追踪器提供者 :

```js
import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
import { resourceFromAttributes } from "@opentelemetry/resources";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";

const tracerProvider = new BasicTracerProvider({
    resource: resourceFromAttributes({
        [ATTR_SERVICE_NAME]: "<your-service-name>",
    }),
    sampler: new CoralogixTransactionSampler(),
});
```

### 辅助仪器

和我们一起工作 [个人自动仪器](https://coralogix.com/docs/opentelemetry/instrumentation-options/nodejs-opentelemetry-instrumentation/#individual-auto-instrumentation) 财务报告和审定财务报表 [手动仪器](https://coralogix.com/docs/opentelemetry/instrumentation-options/nodejs-opentelemetry-instrumentation/#manual-instrumentation)。捆绑的自动仪器方法是 **没有** 已支持.

### 发送属性

当一个跨度开始交易时,采样器会添加以下属性:

| 属性 | 说明 |
| --- | --- |
| `cgx.transaction` | 交易名称( 如 . `GET /users/:id`) (中文(简体) ). |
| `cgx.transaction.distributed` | 分布式交易名称在各种服务中传播. |
| `cgx.transaction.root` | 此跨度是否是交易的根 . |

## 交易处理器

`TransactionSpanProcessor` 包裹一个 `SpanExporter` 标记 Corlogix 交易, 专用邮票自用时间(`cgx.transaction.self_duration`记录匹配的直方图(单位) `s`) (中文(简体) ). 它与任何样本.

### 命名如何运作

交易 **成员** (新继承,和 `cgx.transaction.root`)在起始时决定。 显示名称 `cgx.transaction` 只有在完成的本地追踪完成后,才使用 `overrideName ?? rootSpan.name`。这对快递很重要:HTTP跨度通常从 `GET` 后来改名为 `GET /myroute` 由中间软件来表示 —— 输出的交易名称是最后一个根跨度名称 .

每一个完成的本地跟踪立即被输出. 处理器缓冲 改为 `CORALOGIX_MAX_SPANS_PER_TRACE` 交易增益完成周期 (默认:256),最多 `CORALOGIX_MAX_TRANSACTION_TRACES` 一次保留在内存中的交易(默认:无限). 当正跨度被突破时,它立即导出追踪缓冲 和后来流的长度不变. `CORALOGIX_MAX_SPANS_PER_TRACE=0` 是无限的. 当微量极限达到时,以后的微量 流线不变。 微量限额只适用于保留内存的交易; `0` 是无限的,一旦一个缓冲交易完成,能力就会再次得到。 这些痕迹没有处理器交易标记, 自我延长,或称度量.

```js
import { BasicTracerProvider, ConsoleSpanExporter } from "@opentelemetry/sdk-trace-base";
import { TransactionSpanProcessor } from "@coralogix/opentelemetry";

const tracerProvider = new BasicTracerProvider({
    spanProcessors: [
        new TransactionSpanProcessor(new ConsoleSpanExporter(), {
            // Optional MeterProvider for the self-duration histogram; defaults to the global one.
        }),
    ],
});
```

### 选项

构造选项胜过环境变量 。 无效的内存值返回到默认值 .

| 选项 | 类型 | 默认 | 新闻 var | 含义 |
| --- | --- | --- | --- | --- |
| `completionHoldbackMillis` | `number` | `100` | `OTEL_CX_TRANSACTION_COMPLETION_HOLDBACK_MILLIS` | 在最后的寿命结束之后, 等待这么长的时间 才能最终确定 迟到的兄弟姐妹可以加入. `0` = 立即敲定. |
| `shutdownIdleWaitMillis` | `number` | `30000` | —— 说 | 多久的停机等待飞行时间. |
| `meterProvider` | `MeterProvider` | 全球 | —— 说 | 测量自长直方图. |

## 与快递的交易

解决快递线路的稳定,低心率交易名称(如. `GET /users/:id` 而不是每个请求路径),呼叫 `setExpressApp` 这样取样员就可以学习你的应用的路线和终点.

> **重要内容:** 打电话 `setExpressApp` **在所有路线和路由器注册后**。采样器在您调用时读取了Express路由器堆栈,所以之后添加的任何路线都不会解决.

```javascript
import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
import { resourceFromAttributes } from "@opentelemetry/resources";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
import { CoralogixTransactionSampler } from "@coralogix/opentelemetry";
import express from "express";
import router from "./router";

const sampler = new CoralogixTransactionSampler();

const tracerProvider = new BasicTracerProvider({
    resource: resourceFromAttributes({
        [ATTR_SERVICE_NAME]: "<your-service-name>",
    }),
    sampler,
});

const app = express();
app.use("/", router);

// Register routes first, then hand the app to the sampler.
sampler.setExpressApp(app);

app.listen(3000, () => {
    console.log("Server is running");
});
```

### 前缀和嵌入路由器

`setExpressApp` 决定 **满** 路由模板,包括挂载前缀和任意嵌入路由器. 例如:

```javascript
const orders = express.Router();
orders.get("/orders/:oid", handler);

const api = express.Router();
api.use("/deep", orders);

app.use("/api", api);
```

请求 `/api/deep/orders/9` 决定交易 `GET /api/deep/orders/:oid`。 。 。 .

### 表达式版本支持

两者 **捷运 4** 财务报告和审定财务报表 **运通5** 被支持.

参数在两个版本上均正确诱导,包括a _挂载前缀_ (单位:千美元)`app.use("/v/:ver", router)`: 请求 `/v/2/things/abc` 决定: `GET /v/:ver/things/:t`。 。 。 .

## 更改日志

见 [变动情况](https://npmcn.com/package/%40coralogix/opentelemetry/CHANGELOG.md) 用于发行笔记. 注意前缀和嵌入式路由器的路由调解是 **断开输出变化**: 受影响应用程序的交易名称更改, 因此更新前名上键入的任何仪表板, 提醒, 或保存视图 .

## 许可证

凭 [Apache 许可证 2.0](https://npmcn.com/package/%40coralogix/opentelemetry/LICENSE)。 。 。 .

## 常见问题

### @coralogix/opentelemetry 是什么？

OpenTelemotics Node SDK的 Corlogix 扩展,包括 Corlogix APM 的交易采样器\.

### 如何安装 @coralogix/opentelemetry？

在项目目录运行 npm install @coralogix/opentelemetry，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@opentelemetry/api（^1\.7\.0）、@opentelemetry/core（^2\.8\.0）、@opentelemetry/sdk-trace-base（^2\.8\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @coralogix/opentelemetry 支持 TypeScript 吗？

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

### @coralogix/opentelemetry 支持 ESM 还是 CommonJS？

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

### @coralogix/opentelemetry 可以商用吗？

@coralogix/opentelemetry 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @coralogix/opentelemetry 的下载量有多少？

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

### @coralogix/opentelemetry 还在维护吗？

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