需启用分布式追踪定位性能瓶颈，支持五种集成方式：一、OpenTelemetry SDK标准方案；二、Jaeger轻量调试；三、Zipkin遗留适配；四、Envoy边车注入；五、自定义Span标注。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用Hermes Agent时需要定位跨服务调用中的性能瓶颈或异常路径，则需启用分布式追踪能力。以下是实现Hermes Agent分布式追踪的多种集成方式：
一、集成OpenTelemetry SDK（推荐标准方案）
OpenTelemetry是云原生可观测性标准，Hermes Agent通过其Python SDK注入trace上下文，自动为HTTP、gRPC、Kafka及数据库调用生成span，并支持向后端导出。
1、在项目根目录执行pip install opentelemetry-api opentelemetry-sdk opentelemetry-instrumentation-all
2、创建tracing_setup.py，配置全局tracer provider与exporter：
3、在hermes_cli/入口文件顶部添加from tracing_setup import setup_tracing; setup_tracing()
4、启动Agent时添加环境变量OTEL_SERVICE_NAME=hermes-agent和OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317
二、对接Jaeger后端（轻量级调试方案）
Jaeger提供直观的UI与低开销的采样策略，适用于开发与预发布环境，Hermes Agent可通过OTLP或Thrift协议直连。
1、部署Jaeger All-in-One容器：docker run -d --name jaeger -p 6831:6831/udp -p 16686:16686 -p 4317:4317 jaegertracing/all-in-one:1.55
2、修改~/.hermes/config.yaml，在observability节下添加：
3、确保gateway/delivery.py与tools/terminal_tool.py中所有异步任务均被@trace.wrap装饰
4、访问http://localhost:16686搜索service.name=hermes-agent查看调用链
三、嵌入Zipkin兼容埋点（遗留系统适配方案）
针对已部署Zipkin集群的组织，Hermes Agent可通过opentelemetry-exporter-zipkin-json实现无缝对接，无需改造现有收集链路。
1、安装专用导出器：pip install opentelemetry-exporter-zipkin-json
2、在tracing_setup.py中替换exporter为ZipkinExporter(endpoint="http://zipkin:9411/api/v2/spans")
3、将OTEL_EXPORTER_ZIPKIN_ENDPOINT环境变量设为Zipkin服务地址
4、确认hermes status --service tracing返回active且last_export_time非空
四、基于Envoy代理的边车追踪注入（Kubernetes部署方案）
在K8s环境中，Hermes Agent Pod可复用Istio或独立Envoy作为边车，由代理完成HTTP头注入与span上报，Agent本体无需修改代码。
1、为Hermes Agent Deployment添加sidecar.istio.io/inject: "true"标签
2、在envoy-filter.yaml中启用x-b3-traceid等B3头透传
3、确保Pod内应用监听127.0.0.1:8080，流量经Envoy:15001转发
4、验证请求Header中存在x-request-id与x-b3-spanid字段
五、自定义Span标注与业务上下文注入
除自动埋点外，Hermes Agent支持手动创建span以标记关键业务逻辑节点，例如技能执行、证书签发、模型推理等高价值环节。
1、在domain_intel.py的verify_certificate函数开头添加with tracer.start_as_current_span("cert-verify") as span:
2、向span添加属性：span.set_attribute("cert.issuer", issuer_name)
3、捕获异常并标记error：span.set_status(Status(StatusCode.ERROR))
4、注入当前用户ID至span：span.set_attribute("user.id", context.get_user_id())
