校对:soup

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

安装

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

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 特性,您可能需要:

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两种版本.

注:您可能遇到已知的 打开远程浏览器错误 与 @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操作产生的噪音
• 支持自定义过滤逻辑
• 通过选项或环境变量配置

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,因此两个系统的横跨出现在同一个微量树上
• 分布式追踪: 使用不同追踪系统的服务的适当背景传播

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的跨度的孩子创造出跨度.

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()) (中文(简体) ).

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 上下文以进行传播时 .

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的子孙.

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(中文(简体) )

文档

• 大脑信任文件
• 打开远程文档
• 人才信托 OTEL指南