# @braintrust/otel 中文文档

规范地址：https://npmcn.com/package/%40braintrust/otel/

版本：1\.1\.0
npm 元数据更新时间：2026-10-19T18:45:01.123Z
中文译文更新时间：2026-11-08T13:45:58.778Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40braintrust/otel
原文对照：https://npmcn.com/package/%40braintrust/otel/?lang=original
项目主页：https://www.braintrust.dev/docs
源码仓库：https://github.com/braintrustdata/braintrust-sdk-javascript

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

- 包体积（解压后）：637 kB，47 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：braintrust \>=1\.0\.0-0，@opentelemetry/api \>=1\.9\.0，@opentelemetry/core \>=1\.9\.0，@opentelemetry/sdk-trace-base \>=1\.9\.0，@opentelemetry/exporter-trace-otlp-http \>=0\.35\.0
- 首次发布：2025-12-02T00:03:21.458Z
- 最新版本发布：2026-10-19T18:45:00.697Z
- 近 30 天下载量：799423（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

SDK 用于将 Braintust 与 OpenTeleometry 整合

## 安装

```sh
npm install @braintrust/otel
```

也可以使用：`pnpm add @braintrust/otel`、`yarn add @braintrust/otel`、`bun add @braintrust/otel`

## README

# 校对:soup

[![npm version](https://img.shields.io/npm/v/%40braintrust%2Fotel.svg)](https://www.npmjs.com/package/@braintrust/otel)

用于整合的 SDK [大脑信任](https://braintrust.dev/) 与 [打开几何](https://opentelemetry.io/)。这个软件包允许您将 OpenTeleometry 跨度发送到 BrainTrust 用于记录和可观察性,并提供 BrainTrust 和 OpenTeleometry 跟踪背景之间的无缝互通性.

## 安装

此软件包有同伴依赖性, 您必须同时安装 :

```bash
npm install @braintrust/otel braintrust @opentelemetry/api @opentelemetry/core @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http
# or
yarn add @braintrust/otel braintrust @opentelemetry/api @opentelemetry/core @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http
# or
pnpm add @braintrust/otel braintrust @opentelemetry/api @opentelemetry/core @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http
```

如果您正在使用诸如上下文管理器等额外的 OpenTeleometry 特性,您可能需要:

```bash
npm install @opentelemetry/context-async-hooks
```

## 所需资源

-   节点.js 16
-   OpenTeleometry API 1.9.0 (英语)
-   开口遥测 SDK 1.9.0
-   大脑信任 0.5.0

这个软件包支持OpenTeleomet 1.x和 2.x两种版本.

注:您可能遇到已知的 [打开远程浏览器错误](https://github.com/open-telemetry/opentelemetry-js/issues/3545) 与 `@opentelemetry/exporter-trace-otlp-http` < 0.205.0. 如果遇到这一问题,请升级 `@opentelemetry/exporter-trace-otlp-http` 和相关包至少:

-   `@opentelemetry/exporter-trace-otlp-http` 页:1
-   `@opentelemetry/sdk-trace-base` 2.1.0
-   `@opentelemetry/api` 2.1.0
-   `@opentelemetry/core` 2.1.0

这是 **重要事项** 那个 `@opentelemetry/core` 和相关软件包均使用同一种主要版本(1.x或2.x).

## 能力

这种整合提供了两个主要能力:

1.  **导出 OpenTelection 跨度到大脑信任**: 使用 `BraintrustSpanProcessor` 将您的 OpenTeleometry 追踪发送给 Brain Trust 用于记录、监测和分析.
    
2.  **Braintust和OpenTeleometry之间的双向互操作性**: 使用 `setupOtelCompat()` 使Braintust跨度和OpenTelemetry跨度能够在相同的统一跟踪中共同工作。 这允许:
    
    -   OpenTelection 跨到大脑信任的跨度
    -   大脑信任的长度是开放遥测的孩子的长度
    -   两个系统共享相同的痕量/扩展ID(使用OpenTeleometry's格式)
    -   跨越服务界限的无缝上下文传播,无论每项服务使用哪种追踪系统

## 核心组成部分

### `BraintrustSpanProcessor`

一个向Braintrust的遥测端点发送OpenTeleometry的跨度处理器.

**什么时候用**: 将此处理器添加到您的 OpenTelemeth 中 `TracerProvider` 当您想要导出 OpenTeleometry 时, 时间跨度为 Brain Trust 。 这在您已经使用 OpenTeleomet 仪器时是有用的, 并且想要利用 BrainTrust 的伐木和可观察性特征.

**主要特点**数字 :

-   使用 OTLP 协议自动向 Braintust 发送跨度
-   可选的AI跨度过滤以减少非AI操作产生的噪音
-   支持自定义过滤逻辑
-   通过选项或环境变量配置

```typescript
import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
import { trace } from "@opentelemetry/api";
import { BraintrustSpanProcessor } from "@braintrust/otel";

const provider = new BasicTracerProvider();
provider.addSpanProcessor(
  new BraintrustSpanProcessor({
    apiKey: "your-api-key", // or set BRAINTRUST_API_KEY env var
    parent: "project_name:my_project", // or set BRAINTRUST_PARENT env var
    filterAISpans: true, // optional: filter out non-AI spans
  }),
);

trace.setGlobalTracerProvider(provider);
```

**配置选项**数字 :

-   `apiKey` (字符串,可选): Braintrust API 键. 掉回原点 `BRAINTRUST_API_KEY` 环境变量,然后是最近的 `.env.braintrust` file in Node.js. 页面存档备份,存于互联网档案馆.
-   `apiUrl` (字符串,可选): Braintrust API URL. 倒计时 `BRAINTRUST_API_URL` 环境变量。 默认为 `https://api.braintrust.dev`。 。 。 .
-   `parent` (弦,可选): 格式的父项目标识符 `project_name:my_project` 或者说 `project_id:uuid`后退至 `BRAINTRUST_PARENT` 环境变量.
-   `filterAISpans` (布尔,可选): 当属实时,过滤出非AI跨度. 只有前缀的相间 `gen_ai.*`, (中文(简体) ), `llm.*`, (中文(简体) ), `ai.*`, (中文(简体) ), `braintrust.*`,或 `traceloop.*` 将发送。 默认为假.
-   `customFilter` (职能,可选): 自定义高级跨度过滤逻辑的过滤功能 .
-   `headers` (对象,可选): 附加 HTTP 信头可以随遥测数据发送.

### `setupOtelCompat()`

配置 Braintrust 使用 OpenTeleometry 的上下文管理和ID生成,实现双向互通.

**什么时候用**: 调用此函数 **在应用程序启动时, 在创建 Braintust 日志或 OpenTelemeter 跨度之前**此配置将大脑信任与 OpenTeleometry 跟踪环境相融合,并能够:

-   **大脑信任跨度作为开阔遥测的子宫显示**: 当您在 OpenTeleometry 上下文内创建大脑托管时, 它会自动变成一个孩子
-   **OpenTelection 跨度作为大脑托拉斯的孩子跨度出现**: 当你在大脑信任的上下文内创建一个 OpenTeleometry 时, 它会自动变成一个孩子
-   **统一跟踪结构**:两个系统都使用OpenTeleomet-compatible track并横跨ID,因此两个系统的横跨出现在同一个微量树上
-   **分布式追踪**: 使用不同追踪系统的服务的适当背景传播

```typescript
import { setupOtelCompat } from "@braintrust/otel";
import { initLogger } from "braintrust";

// IMPORTANT: Call setupOtelCompat() before creating any Braintrust loggers or OpenTelemetry spans
setupOtelCompat();

// Now Braintrust will use OpenTelemetry context management
const logger = initLogger({ projectName: "my_project" });
```

**它会做什么**数字 :

-   设定 Braintust 用于在父子关系中使用 OpenTeleometry 上下文管理器
-   配置 Braintust 以使用 OpenTeleometry 兼容跨度并跟踪ID
-   允许将 Braintrust 和 OpenTeleometry 的相接无缝混合在同一跟踪中

## 分布式跟踪助手

这些公用设施使使用不同追踪系统的服务(人才信托和OpenTeleometry)能够进行分布式追踪.

### `contextFromSpanExport(exportStr: string)`

从 Brain Trust 从导出字符串中创建 OpenTelemetry 上下文 .

**什么时候用**:当服务A使用Braintrust并发送跨度导出到使用OpenTeleometry的服务B时. 这使得服务B能够作为服务A的跨度的孩子创造出跨度.

```typescript
import { contextFromSpanExport } from "@braintrust/otel";
import { context } from "@opentelemetry/api";

// Service A (Braintrust) exports span
const exportedSpan = await spanA.export();

// Service B (OpenTelemetry) imports context
const ctx = contextFromSpanExport(exportedSpan);
await context.with(ctx, async () => {
  // OpenTelemetry spans created here will be children of Service A's span
  await tracer.startActiveSpan("service_b_operation", async (span) => {
    // ...
    span.end();
  });
});
```

### `addSpanParentToBaggage(span: Span, ctx?: Context)`

副本 `braintrust.parent` 属性从 OpenTeleometry 跨度到 OpenTeleometry 行李.

**什么时候用**: 当您需要使用 OpenTeleometry 的传播机制(通常在调用之前) 跨服务范围传播 Braintust 母信息时 `propagation.inject()`) (中文(简体) ).

```typescript
import { addSpanParentToBaggage } from "@braintrust/otel";
import { propagation, context } from "@opentelemetry/api";

tracer.startActiveSpan("service_a", async (span) => {
  // Copy braintrust.parent to baggage so it propagates
  const ctx = addSpanParentToBaggage(span);

  // Export headers for downstream service
  const headers = {};
  propagation.inject(ctx, headers);

  // Send headers to Service B
  await fetch("https://service-b/api", { headers });

  span.end();
});
```

### `addParentToBaggage(parent: string, ctx?: Context)`

直接在 OpenTeletter 行李上添加 Braintrust 父标识符.

**什么时候用**: 当您拥有大脑信任母字符串并想要将其添加到 OpenTeleometry 上下文以进行传播时 .

```typescript
import { addParentToBaggage } from "@braintrust/otel";

const parent = "project_name:my_project";
const ctx = addParentToBaggage(parent);
// Now ctx contains braintrust.parent in baggage
```

### `parentFromHeaders(headers: Record<string, string>)`

从 HTTP 头部中提取包含 OpenTeleometry 跟踪上下文的 Braintrust 父信息 .

**什么时候用**:当服务A使用OpenTeleometry时,会向使用Braintrust的服务B发送跟踪头. 这使服务B能够创建脑力托管(Braintust),作为服务A的子孙.

```typescript
import { parentFromHeaders } from "@braintrust/otel";
import { initLogger } from "braintrust";

// Service B receives headers from Service A (OpenTelemetry)
const parent = parentFromHeaders(incomingHeaders);

// Create Braintrust span as child of Service A's span
const logger = initLogger({ projectName: "my_project" });
await logger.traced(
  async (span) => {
    // This span will be a child of Service A's span
    span.log({ message: "Processing in Service B" });
  },
  { name: "service_b_operation", parent },
);
```

## 环境变量

下列环境变量可用于配置集成:

-   `BRAINTRUST_API_KEY`: 您的大脑信任 API 密钥( 需要 `BraintrustSpanProcessor`;在节点.js中,这也可以设置在最接近的 `.env.braintrust` 文件)
-   `BRAINTRUST_PARENT`: 父项目标识符(例如, `project_name:my_project`(中文(简体) )
-   `BRAINTRUST_API_URL`: Braintrust API 端点(默认为 `https://api.braintrust.dev`(中文(简体) )

## 文档

-   [大脑信任文件](https://www.braintrust.dev/docs)
-   [打开远程文档](https://opentelemetry.io/docs/)
-   [人才信托 OTEL指南](https://www.braintrust.dev/docs/integrations/sdk-integrations/opentelemetry)

## 常见问题

### @braintrust/otel 是什么？

SDK 用于将 Braintust 与 OpenTeleometry 整合

### 如何安装 @braintrust/otel？

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

### @braintrust/otel 支持 TypeScript 吗？

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

### @braintrust/otel 支持 ESM 还是 CommonJS？

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

### @braintrust/otel 可以商用吗？

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

### @braintrust/otel 的下载量有多少？

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

### @braintrust/otel 还在维护吗？

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