可观测与链路追踪

KsADK 提供本地 spans、Langfuse 兼容路径和标准 OTLP HTTP traces exporter。tracing 是可选诊断能力，不应成为 quickstart 的前置条件。

从 0.6.2 开始，推荐把业务代码写成 OTel-first：应用只创建 OpenTelemetry spans、span events 和 attributes，后端通过 OTEL_EXPORTER_OTLP_* 环境变量路由到 Langfuse、OTel Collector 或其他兼容后端。

导出路径

通用 OTLP HTTP

只配置通用 endpoint 时，KsADK 会自动派生 /v1/traces：

export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-collector.example.com/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20demo-token"

agentengine run .

也可以显式配置 traces 专用 endpoint、protocol 和 headers。TRACES_* 优先于通用配置：

export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://otel-collector.example.com/otel/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer%20trace-token"

Langfuse 兼容

如果团队仍使用 Langfuse 环境变量，原配置继续可用：

export LANGFUSE_BASE_URL="https://langfuse.example.com"

agentengine run .

当 generic OTLP 和 Langfuse 环境变量同时存在时，setup_tracing(enable_langfuse=None) 优先使用 generic OTLP，不会再额外启用 Langfuse 直连 exporter。这样可以避免同一次运行在 Langfuse 中出现重复 traces。确实需要强制 Langfuse 兼容路径时，可显式调用 setup_tracing(enable_langfuse=True)。

如果把 Langfuse 当作 OTLP backend，也可以只配置标准 OTLP 变量：

export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://langfuse.example.com/api/public/otel/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Basic%20<base64-public-secret>,x-langfuse-ingestion-version=4"

Callback-only 模式

LangChain 或 LangGraph 项目有时更适合使用 Langfuse callback handler，而不是 direct OTLP。显式启用 callback-only：

export LANGFUSE_BASE_URL="https://langfuse.example.com"
export LANGFUSE_USE_CALLBACK="true"

agentengine run .

云监控双写 (0.6.7 新增)

setup_tracing() 在初始化时检查 CLOUD_MONITOR_* 变量：存在 CLOUD_MONITOR_OTLP_ENDPOINT 或 CLOUD_MONITOR_LANGFUSE_HOST 时，分别构建云监控 OTLP exporter 和 Langfuse SDK callback，与自建 Langfuse / 标准 OTEL_EXPORTER_OTLP_* 路径并行写入。三条路径各自独立探测、互不压制，单条 span 可以同时进入自建集群和云监控 trace 平台。

CloudMonitor OTLP exporter 使用 Ksc-Appkey header 注入 AppKey 鉴权，固定 http/protobuf protocol；trace token 会归集回填到 root span，便于在云监控平台按一次完整调用聚合。CloudMonitor Langfuse SDK callback handler 挂在独立 TracerProvider 上，避免与业务侧 TracerProvider 互相干扰。

涉及的环境变量（共 11 个，参考 ../reference/environment-variables.md 可观测小节）：

最小配置示例（占位值，请替换为自有 endpoint 与 AppKey）：

export CLOUD_MONITOR_OTLP_ENDPOINT="https://cloudmonitor.example.com"
export CLOUD_MONITOR_APP_KEY="cm-appkey-placeholder"

# 可选：CloudMonitor Langfuse callback
export LANGFUSE_USE_CALLBACK="true"
export CLOUD_MONITOR_LANGFUSE_PUBLIC_KEY="pk-cm"
export CLOUD_MONITOR_LANGFUSE_SECRET_KEY="cm-secret"
export CLOUD_MONITOR_LANGFUSE_HOST="https://cloudmonitor.example.com"

agentengine run .

Span event 与子 span

span event 是某个 span 内的时间点事件，适合记录：

• checkpoint.saved
• agent.run.started
• analysis.milestone
• 错误提示和恢复 hint

子 span 是 trace tree 中的独立步骤，适合记录：

• tool 调用
• checkpoint 持久化
• 外部 I/O
• 报告生成
• score 计算

Metadata 与 score

长周期、多用户、多实例场景建议在关键 span 上带稳定、非敏感 attributes：

• ksadk.agent_id
• ksadk.session_id
• ksadk.user_id
• ksadk.invocation_id
• ksadk.account_id
• ksadk.runtime.service
• ksadk.runtime.instance_id

评估分数建议先用后端无关的 attributes 表达：

span.set_attribute("score.name", "answer_quality")
span.set_attribute("score.value", 0.88)
span.set_attribute("score.source", "auto_evaluator")
span.set_attribute("score.comment", "Report covers evidence and next steps.")

如果后端是 Langfuse，平台服务或 OTel Collector 可以把 score.* attributes 转成 Langfuse native score。KsADK 业务代码不需要直接 import Langfuse SDK，这样后续替换后端时改动更小。

故障排查

公开文档规则