Repository navigation
[Proposal] 提供原生 OpenTelemetry handler，按 GenAI 语义约定为 ChatModel / Tool / Retriever / Graph / ADK 上报 span #1028
Description
Is your feature request related to a problem? Please describe.
要给 eino 应用接入可观测性，目前必须自行实现 callbacks.Handler。社区生态里有 Langfuse / cozeloop 两个实现（位于 eino-ext），但它们都是面向各自后端的专有映射，无法直接对接通用的 OTel collector / APM。eino-ext#328 提出 OTel 上报，但范围只限 Indexer / Retriever。
OpenTelemetry 已经发布 GenAI Semantic Conventions（gen_ai.system、gen_ai.request.model、gen_ai.usage.input_tokens、gen_ai.operation.name 等），主流框架普遍原生支持（Google ADK、Pydantic AI + Logfire、Mastra、LlamaIndex）。eino 缺一个框架自带、与后端解耦的 OTel handler。这本质上是「切面扩展」能力的标准化输出。
Describe the solution you'd like
新增 callbacks/otel 包，提供一个标准 handler：
package otel
func NewHandler(tp trace.TracerProvider, mp metric.MeterProvider, opts ...Option) callbacks.Handler行为：
- 按
RunInfo.Component（model/tool/retriever/ ...）映射到gen_ai.operation.name（chat/execute_tool/embeddings/ ...）。 OnStart注入gen_ai.request.*，OnEnd注入gen_ai.response.*与gen_ai.usage.*。- 流式场景在
OnEndWithStreamOutput内累计 token，stream 关闭时一次性落 span。 - Graph / ADK 节点产生父 span，Component 调用作为子 span，形成完整调用树。
- Metrics：
gen_ai.client.token.usage、gen_ai.client.operation.duration直方图。
分期：
- 一期：ChatModel / Tool / Embedding / Retriever / Indexer 的 span + 标准 attribute
- 二期：Graph 节点与 ADK Agent 的父子 span 层级 + AgentEvent 拓扑
- 三期：AgenticMessage（Responses API）的 reasoning / tool 双 span 表示
Describe alternatives you've considered
- 继续用 Langfuse / cozeloop handler：绑定特定后端，无法对接已有的 OTel collector / Jaeger / Tempo / 各类 APM。
- 由用户各自实现 OTel handler：每个团队重复造轮子，且很难统一遵循 GenAI semconv，trace 不可跨项目复用。
- 只做 metrics 不做 trace：丢失调用树，无法定位多 Agent / 多节点链路。
Additional context
- OTel GenAI Semantic Conventions: https://opentelemetry.io/docs/specs/semconv/gen-ai/
- 现有实现可参考：eino-ext
callbacks/langfuse。 - 关联：eino-ext#328（仅 indexer/retriever，范围窄）。
- 放置位置（主仓库
callbacks/otelvs eino-ext）可讨论；倾向主仓库，因为 OTel 是行业标准、且不引入重后端依赖。
愿意在 maintainer 认可方向后承担实现。
Reacted by zhangnan, Zhichang Yu and Ryo
Activity
March-77 commentedon Jul 24, 2026
This needs a placement/dependency decision before implementation. My suggested first increment is an
eino-extcallback handler (to avoid adding OTel SDK dependencies to core) covering ChatModel/Tool/Retriever/Indexer spans first, pinned to one GenAI semconv version, with in-memory exporter tests for parentage, attributes, errors, and streaming completion. Graph/ADK topology and metrics can follow after the base span contract stabilizes. Please confirm core vs eino-ext and the intended semconv stability level.SilenceShine commentedon Aug 6, 2026
我也想要
Ethanz11-creat commentedon Aug 30, 2026
Implemented this as a backend-agnostic handler in eino-ext: cloudwego/eino-ext#980.
Placement rationale: I followed the suggestion to keep the OpenTelemetry SDK out of eino core (which currently has no observability dependencies) by putting the handler in eino-ext alongside
langfuseandcozeloop. The handler is a standardcallbacks.Handler, so it works anywhere core callbacks work, including ADK.What it covers today:
gen_ai.operation.namemapping:ChatModel/AgenticModel→chat,Embedding/Indexer→embeddings,Retriever→retrieve,Tool/tools nodes →execute_tool,Agent/Graph/Workflow/Chain→invoke_agentgen_ai.systemfrom the component implementation type (lowercased)gen_ai.request.modelfrom chat model / embedding callbacksgen_ai.usage.input_tokens/gen_ai.usage.output_tokensfrom chat model / embedding callbacksNot yet covered: metrics (token-usage counters / histograms) and
gen_ai.client.*event attributes. I left those out to keep this first increment reviewable — happy to add them as a follow-up if maintainers want the full surface.Would love maintainer feedback on whether this placement and scope matches the project direction.
feat(callbacks): add native OpenTelemetry callback handler