Skip to content

feat(callbacks): add native OpenTelemetry callback handler - #1270

Open
JopenChen wants to merge 1 commit into
cloudwego:mainfrom
JopenChen:feat/otel-callback-handler
Open

feat(callbacks): add native OpenTelemetry callback handler#1270
JopenChen wants to merge 1 commit into
cloudwego:mainfrom
JopenChen:feat/otel-callback-handler

Conversation

@JopenChen

@JopenChen JopenChen commented Sep 9, 2026

Copy link
Copy Markdown

What type of PR is this?

feat

Check the PR title.

  • This PR title match the format: (optional scope):
  • The description of this PR title is user-oriented and clear enough for others to understand.
  • Attach the PR updating the user documentation if the current PR requires user awareness at the usage level.

(Optional) Translate the PR title into Chinese.

feat(callbacks): 新增原生 OpenTelemetry callback handler

(Optional) More detailed description for this PR(en: English/zh: Chinese).

en:
Add a new callbacks/otel package that implements callbacks.Handler with OpenTelemetry tracing following the GenAI semantic conventions.

Addresses community request #1028 for native OTel support. Currently users must implement callbacks manually to get distributed tracing for LLM applications built with eino.

Features:

  • Span creation for ChatModel, Tool, Retriever, Embedding, Graph, Chain, and Workflow components
  • GenAI standard attributes: gen_ai.system, gen_ai.operation.name, gen_ai.request.model, gen_ai.response.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, gen_ai.usage.total_tokens, gen_ai.tool.name
  • Token usage extraction from model.CallbackOutput
  • Query and document count attributes for Retriever components
  • Nested span propagation (child spans automatically link to parent via context)
  • Error recording with OpenTelemetry span status codes
  • TimingChecker implementation - skips stream callbacks to avoid unnecessary stream copying overhead
  • Configurable via WithTracerProvider and WithTracer options
  • Uses OTel v1.21.0 to maintain Go 1.18 compatibility

Usage:

import (
    "github.com/cloudwego/eino/callbacks"
    "github.com/cloudwego/eino/callbacks/otel"
)

// Global registration
callbacks.AppendGlobalHandlers(otel.NewHandler())

// Or with custom TracerProvider
handler := otel.NewHandler(otel.WithTracerProvider(tp))

zh(optional):
新增 callbacks/otel 包,实现遵循 GenAI 语义约定的 OpenTelemetry callback handler。

响应社区需求 #1028,提供原生 OTel 支持。目前用户必须手动实现 callbacks 才能获得分布式追踪。

特性:

  • 为 ChatModel、Tool、Retriever、Embedding、Graph、Chain、Workflow 组件创建 Span
  • GenAI 标准属性:gen_ai.system、gen_ai.operation.name、gen_ai.request.model、gen_ai.response.model、gen_ai.usage.*、gen_ai.tool.name
  • 从 model.CallbackOutput 提取 Token 使用量
  • Retriever 组件的查询和文档数量属性
  • 嵌套 Span 自动传播(子 Span 通过 context 自动关联父 Span)
  • 错误记录与 OpenTelemetry Span 状态码
  • 实现 TimingChecker——跳过 stream 回调以减少不必要的流拷贝开销
  • 通过 WithTracerProvider 和 WithTracer 选项配置
  • 使用 OTel v1.21.0 以保持 Go 1.18 兼容性

(Optional) Which issue(s) this PR fixes:

Fixes #1028

(optional) The PR that updates user documentation:

Will follow up with a docs PR if this feature is accepted.

@CLAassistant

CLAassistant commented Sep 9, 2026

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

Add a new callbacks/otel package that implements the callbacks.Handler
interface with OpenTelemetry tracing following the GenAI semantic conventions.

This addresses the community request for native OTel support (Issue cloudwego#1028),
eliminating the need for users to implement callbacks manually.

Features:
- Span creation for ChatModel, Tool, Retriever, Embedding, Graph, Chain,
  Workflow, and other component types
- GenAI standard attributes: gen_ai.system, gen_ai.operation.name,
  gen_ai.request.model, gen_ai.response.model, gen_ai.usage.*, gen_ai.tool.name
- Token usage extraction from model.CallbackOutput (input/output/total tokens)
- Query and document count attributes for Retriever components
- Nested span propagation (child spans automatically link to parent)
- Error recording with span status codes
- TimingChecker implementation to skip stream callbacks and reduce overhead
- Configurable via WithTracerProvider and WithTracer options

Usage:
  callbacks.AppendGlobalHandlers(otel.NewHandler())
  // or
  handler := otel.NewHandler(otel.WithTracerProvider(tp))

Note: This upgrades the minimum Go version to 1.25.0 as required by
go.opentelemetry.io/otel v1.46.0.

Refs cloudwego#1028
@JopenChen
JopenChen force-pushed the feat/otel-callback-handler branch from 3e4c38c to 90f03d0 Compare September 9, 2026 09:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

[Proposal] 提供原生 OpenTelemetry handler,按 GenAI 语义约定为 ChatModel / Tool / Retriever / Graph / ADK 上报 span

2 participants