# @backendkit-labs/agent-otel 中文文档

规范地址：https://npmcn.com/package/%40backendkit-labs/agent-otel/

版本：0\.1\.10
npm 元数据更新时间：2026-10-27T10:49:11.392Z
中文译文更新时间：2026-11-07T22:59:18.818Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40backendkit-labs/agent-otel
原文对照：https://npmcn.com/package/%40backendkit-labs/agent-otel/?lang=original
项目主页：https://github.com/BackendKit-labs/backendkit-agent-framework#readme
源码仓库：https://github.com/BackendKit-labs/backendkit-agent-framework

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

- 包体积（解压后）：42.8 kB，18 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：0 个
- peer 依赖：@opentelemetry/api \>=1\.4\.0 \<2，@backendkit-labs/agent-core \>=0\.27\.0 \<0\.38\.0
- 首次发布：2026-10-22T13:02:02.338Z
- 最新版本发布：2026-10-27T10:49:11.201Z
- 近 30 天下载量：2113（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

为 @ backendkit-labs/ agent-core 的 OpenTeleometry 导出: OTLP/ HTTP 出口国(不需要SDK) 和 OpenTeleometry API 的适配器, 带有 GenAI 语义规范

## 安装

```sh
npm install @backendkit-labs/agent-otel
```

也可以使用：`pnpm add @backendkit-labs/agent-otel`、`yarn add @backendkit-labs/agent-otel`、`bun add @backendkit-labs/agent-otel`

## README

# @ backendkit-labs/ 代理服务器

用于跟踪的 OpenTeleometry 导出 [`@backendkit-labs/agent-core`](https://npmcn.com/package/%40backendkit-labs/core)选择符合下列条件的出口商: 如何运行遥测:

| 你有过 | 使用 |
| --- | --- |
| 一个能说OTLP/HTTP的收藏器或后端(Jaeger, Tempo, Langfuse, Datadog, OpenTeleometry Collector...)和 **没有** 打开遥测 SDK | `otlpHttpSpanExporter` |
| 已在此过程中注册的 OpenTeleometry SDK( 自动仪器、 自己的处理器/ 出口器) | `otelApiSpanExporter` |

```ts
import { createBaseEngine } from '@backendkit-labs/agent-core';
import { otlpHttpSpanExporter } from '@backendkit-labs/agent-otel';

const exporter = otlpHttpSpanExporter({ endpoint: 'http://localhost:4318', serviceName: 'support-agent' });

const engine = createBaseEngine({
  // ...
  observability: { tracing: { exporter } },
});

// on shutdown
await exporter.shutdown();
```

```ts
import { otelApiSpanExporter } from '@backendkit-labs/agent-otel';   // needs @opentelemetry/api
observability: { tracing: { exporter: otelApiSpanExporter() } }
```

## 你得到的东西

每张一张 `engine.run()`数字 :

```
agent.run
└─ invoke_agent Main
   ├─ chat deepseek-chat          (tokens, model, provider, cost, cache tokens)
   ├─ execute_tool read_file      (success, duration — parallel tools overlap in time)
   └─ chat deepseek-chat
```

属性遵循 OpenTeleometry **GenAI 语义公约**数字 : `gen_ai.operation.name` (单位:千美元)`invoke_agent` 编号 : `chat` 编号 : `execute_tool`, (中文(简体) ), `gen_ai.request.model`, (中文(简体) ), `gen_ai.provider.name`, (中文(简体) ), `gen_ai.usage.input_tokens`, (中文(简体) ), `gen_ai.usage.output_tokens`, (中文(简体) ), `gen_ai.usage.cache_read.input_tokens`, (中文(简体) ), `gen_ai.usage.cache_creation.input_tokens`, (中文(简体) ), `gen_ai.agent.id/name`, (中文(简体) ), `gen_ai.tool.name`。任何与 代理核心(成本以美元计,原始跟踪识别码、护卫行动、为什么额外发出LLM呼叫) `bk.*`,比如说. `bk.cost_usd`, (中文(简体) ), `bk.llm.purpose` (单位:千美元)`context_summary`, (中文(简体) ), `structured_output`, (中文(简体) ), `bk.guardrail.<name>.<action>`。 。 。 .

**对话内容从不导出 .** Spans只携带姓名、期限、记号和身份证:否 提示、答案、工具参数或工具结果.

要求数 `@backendkit-labs/agent-core` 与 `llm_call` 编号 : `tool_call` 宽度(0.28+)。 你只有0.27岁 `agent.run` 财务报告和审定财务报表 `invoke_agent`。 。 。 .

## `otlpHttpSpanExporter(options)`

将OTLP/JSON发送给 `<endpoint>/v1/traces`没有SDK 没有依附关系.

| 选项 | 默认 |  |
| --- | --- | --- |
| `endpoint` | `OTEL_EXPORTER_OTLP_ENDPOINT` 或者说 `http://localhost:4318` | `/v1/traces` 除非已经附上 |
| `headers` | – 说吧 – | 譬如说. `{ Authorization: 'Basic …' }` |
| `serviceName` | `agent` | `service.name` 资源属性 |
| `resourceAttributes` | – 说吧 – | `deployment.environment`, (中文(简体) ), `service.version`. |
| `batchSize` | 64国道 | 发送前缓冲跨度 |
| `flushIntervalMs` | 联合国 | 此长后发送部分批次( 时间为 `unref`(d) 国家 |
| `timeoutMs` | 1万个 | 每个请求 |
| `onError` | – 说吧 – | 在此报告一个失败的发送 **那批货被丢掉**无法到达代理 |
| `fetch` | 全球 `fetch` | 测试或海关运输 |

返回函数为 `flush()` 财务报告和审定财务报表 `shutdown()`。发送是序列化的,从不重叠. ID从代理-core的ID中衍生出决定性的ID,所以父母/孩子的联系被保留了下来.

## `otelApiSpanExporter(options)`

重建跨度 `@opentelemetry/api` (单位:千美元)`options.tracer`默认值 `trace.getTracer('@backendkit-labs/agent-core')`),所以他们到达任何你的SDK出口.

OpenTeleometry API 无法选择一个跨度的代号,孩子必须从其父母的真实跨度创建. 代理核心出口在结束时(先是孩子),所以这个适配器在根上保持一个跟踪的间隔 `agent.run` 结尾,然后创建树父母- 首先是原始的起始/结束时间。 后果:

-   当运行完成时,而不是运行时,运行的Spans出现在后端.
-   从未结束( 崩溃) 的跑步会缓冲: 呼叫 `exporter.flush()` 关闭(按 父 从未到达 . `maxBufferedSpans` (默认 5000) 范围内存 .
-   `@opentelemetry/api` 是一个可选的对等依赖;没有它,出口商就会在创建时投出一个明显的错误.

## 已验证

单位测试外加一个真正的引擎运行 通过两个出口商。 API 适配器也被检查为真实 `@opentelemetry/sdk-trace-base` 提供者:一个跟踪,正确的等级,平行工具在时间上重叠.

## 常见问题

### @backendkit-labs/agent-otel 是什么？

为 @ backendkit-labs/ agent-core 的 OpenTeleometry 导出: OTLP/ HTTP 出口国\(不需要SDK\) 和 OpenTeleometry API 的适配器, 带有 GenAI 语义规范

### 如何安装 @backendkit-labs/agent-otel？

在项目目录运行 npm install @backendkit-labs/agent-otel，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@backendkit-labs/agent-core（\>=0\.27\.0 \<0\.38\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @backendkit-labs/agent-otel 支持 TypeScript 吗？

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

### @backendkit-labs/agent-otel 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @backendkit-labs/agent-otel 需要什么版本的 Node\.js？

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

### @backendkit-labs/agent-otel 可以商用吗？

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

### @backendkit-labs/agent-otel 的下载量有多少？

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

### @backendkit-labs/agent-otel 还在维护吗？

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