@arizeai/凤凰-otel

用于节点.js应用的 OpenTeleometry 周围的轻量级包装器,简化了向它发送痕迹 阿里兹·凤凰。 。 。 . @arizeai/phoenix-otel 处理供应商登记和OTLP出口,然后全部再出口 @arizeai/openinference-core 帮助者从同一软件包路径上表面,这样您就可以从一个导入开始注册追踪和作者手册跨度 .

说明: 此软件包正在积极开发中, API可能会有变化 .

特征

• 简单设置 - 有合理默认的一行配置
• 环境变量 - 从环境变量自动配置
• 批处理 - 用于生产的内置分批加工
• 包含的 Open 推论帮助 - 再出口 withSpan,横跨型包装(traceChain, (中文(简体) ), traceAgent, (中文(简体) ), traceTool, (中文(简体) ), traceLLM, (中文(简体) ), traceRetriever, (中文(简体) ), traceReranker, (中文(简体) ), traceEmbedding, (中文(简体) ), traceGuardrail, (中文(简体) ), traceEvaluator, (中文(简体) ), tracePrompt, (中文(简体) ), observe,上下文设置器,属性构建器, OITracer和工具助手
• 安全包装器 - 再导出 OpenInference 的帮助者在被包裹的函数执行时解决默认的跟踪器,因此,模块-扫描包会随着全球提供者的改变而继续
• 友好本地医生 - 船舶的文献和来源 node_modules/@arizeai/phoenix-otel/

安装

npm install @arizeai/phoenix-otel

要求节点.js 18或更新. 提供了无害环境管理和共同JS的切入点.

快速启动

基本用途

最简单的开始方式是使用 register() 与内在的追踪帮助者:

import { register, traceChain } from "@arizeai/phoenix-otel";

const provider = register({
  projectName: "my-app",
});

const answerQuestion = traceChain(
  async (question: string) => `Handled: ${question}`,
  { name: "answer-question" }
);

await answerQuestion("What is Phoenix?");
await provider.shutdown();

register() 设立"凤凰"出口商. 追踪帮助者来自 @arizeai/openinference-core,通过 @arizeai/phoenix-otel。 。 。 .

生产设置

用于远程凤凰城生产:

import { register } from "@arizeai/phoenix-otel";

register({
  projectName: "my-app",
  url: "https://your-phoenix-instance.com",
  apiKey: process.env.PHOENIX_API_KEY,
});

配置

环境变量

这个 register 函数自动从环境变量读取:

# For local Phoenix server (default)
export PHOENIX_COLLECTOR_ENDPOINT="http://localhost:6006"

# For a remote Phoenix instance
export PHOENIX_COLLECTOR_ENDPOINT="https://your-phoenix-instance.com"
export PHOENIX_API_KEY="your-api-key"

如果一个设置不是由参数或环境变量提供的, register 也寻找一个 .env.phoenix 当前工作目录中的文件——行走 上到文件系统根并停留在第一次对接时——读取 PHOENIX_- 其前置密钥( dotenv格式) 。 环境变量总是 优先于文件; 设置 PHOENIX_DISCOVER_CONFIG=false 无法禁用 完全发现.

PHOENIX_API_KEY 财务报告和审定财务报表 PHOENIX_CLIENT_HEADERS 作为证书解决 组合。 明确 Authorization 头被保留了大小写不敏感。 如果一个 明确或进程证书与 PHOENIX_COLLECTOR_ENDPOINT 从 文件, 出口商警告一次, 并继续不记录证书 数值.

配置选项

这个 register 函数接受以下参数:

自定义块处理器

register() 还接受 spanProcessors,它取代默认凤凰 出口商设置。 对于这些设置, 包根再导出 OTLPTraceExporter,而仅限无害环境管理 @arizeai/phoenix-otel/vercel 子路径 再出口 @arizeai/openinference-vercel (单位:千美元)OpenInferenceSimpleSpanProcessor, (中文(简体) ), OpenInferenceBatchSpanProcessor, (中文(简体) ), isOpenInferenceSpan类型)——不需要 安装基本软件包:

import {
  ensureCollectorEndpoint,
  OTLPTraceExporter,
  register,
} from "@arizeai/phoenix-otel";
import {
  isOpenInferenceSpan,
  OpenInferenceSimpleSpanProcessor,
} from "@arizeai/phoenix-otel/vercel";

register({
  projectName: "my-agent",
  spanProcessors: [
    new OpenInferenceSimpleSpanProcessor({
      exporter: new OTLPTraceExporter({
        url: ensureCollectorEndpoint("http://localhost:6006"),
      }),
      // Export only AI spans, re-rooting any left orphaned by the filter
      spanFilter: isOpenInferenceSpan,
      reparentOrphanedSpans: true,
    }),
  ],
});

用法实例

使用Vercel AI SDK(v7+)

AI SDK v7 遥测注册是全过程的,所以应用程序配置 很明显。 安装 ai 财务报告和审定财务报表 @ai-sdk/otel,然后注册合并 和凤凰城的供应商一起 请求头抓取在下面已禁用 因为信头可以包含授权符和饼干.

// instrumentation.ts
import { OpenTelemetry } from "@ai-sdk/otel";
import { registerTelemetry } from "ai";
import { register } from "@arizeai/phoenix-otel";

const provider = register({
  projectName: "my-ai-app",
});

registerTelemetry(
  new OpenTelemetry({
    tracer: provider.getTracer("@arizeai/phoenix-otel/ai-sdk"),
    headers: false,
  })
);

// main.ts
import "./instrumentation.ts";
import { openai } from "@ai-sdk/openai";
import { generateText } from "ai";

const result = await generateText({
  model: openai("gpt-4o-mini"),
  prompt: "Write a short story about a cat.",
});

说明: AI SDK v6 和 older 发出不同的跨度形状,而非 由捆绑的跨度处理器支持。 使用 @arizeai/phoenix-otel 1.x 运算 (与 @arizeai/openinference-vercel 2.x),用于AI SDK v6.

自动设备

自动设备通用库( 与 commonJS 合作最好):

import { register } from "@arizeai/phoenix-otel";
import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";

register({
  projectName: "my-express-app",
  instrumentations: [new HttpInstrumentation(), new ExpressInstrumentation()],
});

说明: 通过 instrumentations 参数最好与 CommunityJS 项目相配合. 无害环境管理项目需要人工仪器.

带有 OpenAI (ESM) 的

关于无害环境管理项目,手动仪器库:

// instrumentation.ts
import { register, registerInstrumentations } from "@arizeai/phoenix-otel";
import OpenAI from "openai";
import { OpenAIInstrumentation } from "@arizeai/openinference-instrumentation-openai";

register({
  projectName: "openai-app",
});

// Manual instrumentation for ESM
const instrumentation = new OpenAIInstrumentation();
instrumentation.manuallyInstrument(OpenAI);

registerInstrumentations({
  instrumentations: [instrumentation],
});

// main.ts
import "./instrumentation.ts";
import OpenAI from "openai";

const openai = new OpenAI();

const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});

追踪帮助者

软件包包括 withSpan 加上跨度的简指 traceChain, (中文(简体) ), traceAgent,以及 traceTool 用于以 OpenInference 跨度来包装函数。 每个帮助者会自动记录输入,输出,出错和跨度类型.

import {
  register,
  traceAgent,
  traceChain,
  traceTool,
  withSpan,
} from "@arizeai/phoenix-otel";

register({ projectName: "my-app" });

// traceTool — for tool calls and API lookups
const searchDocs = traceTool(
  async (query: string) => {
    const response = await fetch(`/api/search?q=${query}`);
    return response.json();
  },
  { name: "search-docs" }
);

// traceChain — for pipeline steps and orchestration
const summarize = traceChain(
  async (text: string) => `Summary of ${text.length} chars`,
  { name: "summarize" }
);

// traceAgent — for autonomous agent entry points
const supportAgent = traceAgent(
  async (question: string) => {
    const docs = await searchDocs(question);
    return summarize(JSON.stringify(docs));
  },
  { name: "support-agent" }
);

// withSpan — general purpose, specify kind explicitly
const retrieveDocs = withSpan(
  async (query: string) =>
    fetch(`/api/search?q=${query}`).then((r) => r.json()),
  { name: "retrieve-docs", kind: "RETRIEVER" }
);

这些帮助者在被包裹的函数运行时解决了默认的追踪器,因此模块范围所定义的追踪函数一直跟踪全球提供者的变化.

额外的 Span-Kind 包装器

全套的 OpenInform 跨度类型由相匹配的包装包覆盖,每个包包都有一个缩写 withSpan(fn, { ...options, kind })。他们接受与 traceChain编号 :traceAgent编号 :traceTool (除此之外,其他一切) kind,这是预设的). 这些包装是标记的 @experimental 内 @arizeai/openinference-core。 。 。 .

import {
  traceEmbedding,
  traceEvaluator,
  traceGuardrail,
  traceLLM,
  tracePrompt,
  traceReranker,
  traceRetriever,
} from "@arizeai/phoenix-otel";

const retrieveDocuments = traceRetriever(
  async (query: string) => vectorStore.similaritySearch(query, 5),
  { name: "vector-search" }
);

const evaluateAnswer = traceEvaluator(
  async (question: string, answer: string) => judge.score({ question, answer }),
  { name: "answer-evaluation" }
);

自定义输入和输出处理

使用 processInput 财务报告和审定财务报表 processOutput 当你想要比默认的 JSON 序列化更丰富的 OpenInference 属性时 input.value 财务报告和审定财务报表 output.value。 。 。 .

import {
  OpenInferenceSpanKind,
  getInputAttributes,
  getRetrieverAttributes,
  withSpan,
} from "@arizeai/phoenix-otel";

const retrieveDocs = withSpan(
  async (query: string) => [`Doc A for ${query}`, `Doc B for ${query}`],
  {
    name: "retrieve-docs",
    kind: OpenInferenceSpanKind.RETRIEVER,
    processInput: (query) => getInputAttributes(query),
    processOutput: (documents) =>
      getRetrieverAttributes({
        documents: documents.map((content, index) => ({
          id: `doc-${index}`,
          content,
        })),
      }),
  }
);

背景属性

使用上下文设置器将会话ID、用户ID、元数据以及标签传播到所有子进程 :

import {
  context,
  register,
  setMetadata,
  setSession,
  setUser,
  traceChain,
} from "@arizeai/phoenix-otel";

register({ projectName: "my-app" });

const handleQuery = traceChain(async (query: string) => `Handled: ${query}`, {
  name: "handle-query",
});

// All spans inside context.with() inherit session, user, and metadata
await context.with(
  setMetadata(
    setUser(setSession(context.active(), { sessionId: "sess-123" }), {
      userId: "user-456",
    }),
    { environment: "production" }
  ),
  () => handleQuery("Hello")
);

可用的设置 : setSession, (中文(简体) ), setUser, (中文(简体) ), setMetadata, (中文(简体) ), setTags, (中文(简体) ), setAttributes, (中文(简体) ), setPromptTemplate。 。 。 .

如果您手动创建了带平版 OpenTelemetry 跟踪器的跨度, 请将所传播的上下文属性复制到跨度上 :

import {
  context,
  getAttributesFromContext,
  register,
  trace,
} from "@arizeai/phoenix-otel";

register({ projectName: "my-app" });

const tracer = trace.getTracer("manual-tracer");
const span = tracer.startSpan("manual-span");
span.setAttributes(getAttributesFromContext(context.active()));
span.end();

装饰者

observe 在保存方法的同时将分类方法与跟踪相包裹 this 上下文。 使用TypeScript 5+标准装饰.

import { OpenInferenceSpanKind, observe } from "@arizeai/phoenix-otel";

class ChatService {
  @observe({ kind: OpenInferenceSpanKind.CHAIN })
  async runWorkflow(message: string) {
    return `processed: ${message}`;
  }

  @observe({ name: "llm-call", kind: OpenInferenceSpanKind.LLM })
  async callModel(prompt: string) {
    return `model output for: ${prompt}`;
  }
}

属性助手 API

直接构建 OpenInference-相容跨度属性时使用属性助手 :

import { getLLMAttributes, trace } from "@arizeai/phoenix-otel";

const tracer = trace.getTracer("llm-service");

tracer.startActiveSpan("llm-inference", (span) => {
  span.setAttributes(
    getLLMAttributes({
      provider: "openai",
      modelName: "gpt-4o-mini",
      inputMessages: [{ role: "user", content: "What is Phoenix?" }],
      outputMessages: [{ role: "assistant", content: "Phoenix is..." }],
      tokenCount: { prompt: 12, completion: 44, total: 56 },
      invocationParameters: { temperature: 0.2 },
    })
  );
  span.end();
});

可用的帮助包括:

• getLLMAttributes
• getEmbeddingAttributes
• getRetrieverAttributes
• getToolAttributes
• getMetadataAttributes
• getInputAttributes 编号 : getOutputAttributes
• defaultProcessInput 编号 : defaultProcessOutput

跟踪配置和编辑

OITracer 覆盖一个 OpenTeleometry 跟踪器, 并可以在写出跨度前编辑或删除敏感的 Open Inference 属性 :

import {
  OITracer,
  OpenInferenceSpanKind,
  trace,
  withSpan,
} from "@arizeai/phoenix-otel";

const tracer = new OITracer({
  tracer: trace.getTracer("my-service"),
  traceConfig: {
    hideInputs: true,
    hideOutputText: true,
    hideEmbeddingVectors: true,
    hideLLMTools: true,
    base64ImageMaxLength: 8_000,
  },
});

const safeLLMCall = withSpan(
  async (prompt: string) => `model response for ${prompt}`,
  {
    tracer,
    kind: OpenInferenceSpanKind.LLM,
    name: "safe-llm-call",
  }
);

支持的环境变量包括:

• OPENINFERENCE_HIDE_INPUTS
• OPENINFERENCE_HIDE_OUTPUTS
• OPENINFERENCE_HIDE_INPUT_MESSAGES
• OPENINFERENCE_HIDE_OUTPUT_MESSAGES
• OPENINFERENCE_HIDE_INPUT_IMAGES
• OPENINFERENCE_HIDE_INPUT_TEXT
• OPENINFERENCE_HIDE_OUTPUT_TEXT
• OPENINFERENCE_HIDE_EMBEDDING_VECTORS
• OPENINFERENCE_BASE64_IMAGE_MAX_LENGTH
• OPENINFERENCE_HIDE_PROMPTS
• OPENINFERENCE_HIDE_LLM_TOOLS

(原始内容存档于2013-10-12) (英语). Raw OpenTeleometry Spans

要全面控制属性和时间,请直接使用 OpenTeleometry API :

import { register, trace, SpanStatusCode } from "@arizeai/phoenix-otel";

register({ projectName: "my-app" });

const tracer = trace.getTracer("my-service");

async function processOrder(orderId: string) {
  return tracer.startActiveSpan("process-order", async (span) => {
    try {
      span.setAttribute("order.id", orderId);
      const result = await fetchOrderDetails(orderId);
      span.setAttribute("order.status", result.status);
      return result;
    } catch (error) {
      span.recordException(error as Error);
      span.setStatus({ code: SpanStatusCode.ERROR });
      throw error;
    } finally {
      span.end();
    }
  });
}

辅助工具

该套装还从下列地点再出口小型公用事业: @arizeai/openinference-core数字 :

• withSafety({ fn, onError? }) 包裹一个函数并返回 null 错误
• safelyJSONStringify(value) 财务报告和审定财务报表 safelyJSONParse(value) jSON行动

开发与生产

发展 (带有调试记录) :

import { DiagLogLevel, register } from "@arizeai/phoenix-otel";

register({
  projectName: "my-app-dev",
  url: "http://localhost:6006",
  batch: false, // Immediate span delivery for faster feedback
  diagLogLevel: DiagLogLevel.DEBUG,
});

生产 (业绩优化):

import { register } from "@arizeai/phoenix-otel";

register({
  projectName: "my-app-prod",
  url: "https://your-phoenix-instance.com",
  apiKey: process.env.PHOENIX_API_KEY,
  batch: true, // Batch processing for better performance
});

自定义信头

在 OTLP 请求中添加自定义信头 :

import { register } from "@arizeai/phoenix-otel";

register({
  projectName: "my-app",
  url: "https://your-phoenix-instance.com",
  headers: {
    "X-Custom-Header": "custom-value",
    "X-Environment": process.env.NODE_ENV || "development",
  },
});

非全球提供者

明确使用供应商而不在全球登记:

import { register } from "@arizeai/phoenix-otel";

const provider = register({
  projectName: "my-app",
  global: false,
});

// Use the provider explicitly
const tracer = provider.getTracer("my-tracer");

文档和源代码 node_modules

安装后,一个编码代理可以检查与软件包一起运出的确切版本道克和执行:

node_modules/@arizeai/phoenix-otel/docs/
node_modules/@arizeai/phoenix-otel/src/

因为 @arizeai/phoenix-otel 再出口 @arizeai/openinference-core,依赖文件也是有用的本地参考文献:

node_modules/@arizeai/openinference-core/docs/
node_modules/@arizeai/openinference-core/src/

编码代理技能

凤凰城的回购包括 凤凰追踪技能 用于教学编码代理(Claude Code, Cursor等) 如何用 OpenInference tracking 来规范 LLM 应用程序。 安装于 :

npx skills add Arize-ai/phoenix --skill phoenix-tracing

追踪帮助者 :

import {
  observe,
  traceAgent,
  traceChain,
  traceEmbedding,
  traceEvaluator,
  traceGuardrail,
  traceLLM,
  tracePrompt,
  traceReranker,
  traceRetriever,
  traceTool,
  withSpan,
} from "@arizeai/phoenix-otel";

上下文属性设置 :

import {
  setAttributes,
  setMetadata,
  setPromptTemplate,
  setSession,
  setTags,
  setUser,
} from "@arizeai/phoenix-otel";

丰富跨度数据属性构建器 :

import {
  defaultProcessInput,
  defaultProcessOutput,
  getEmbeddingAttributes,
  getLLMAttributes,
  getRetrieverAttributes,
  getToolAttributes,
} from "@arizeai/phoenix-otel";

编辑和工具助手:

import {
  OITracer,
  safelyJSONParse,
  safelyJSONStringify,
  withSafety,
} from "@arizeai/phoenix-otel";

追踪帮助包会解决运行时的默认跟踪. 在实验中和在流程寿命期间互换供应商的任何工作流程中,这都保持与当前供应商相接的跨度.

文档

• 凤凰网文档 - 完成凤凰城文件
• @ arizeai/ 凤凰邮包 - 这个软件包的破译网站文件
• @ arizeai/ openinference- core 包文件 - 上游帮助者和属性构建者参考
• OpenTeleometry 联合来文 - JavaScript 的开口遥测
• 打开推论 - 开放式语义公约

社区

加入我们的社区,与成千上万的人工智能建设者建立联系:

• 加入我们的行列 黑社会
• * 提问并提供反馈 #凤凰支持 # 频道
• 留下一颗星星在我们身上 GitHub 图像
• 报告错误 GitHub 问题
• X 跟着我们 页:1
• 跟着我们 链接
• 看看我们 路线图