FastAPI手动埋点OTEL Span未在Grafana显示及名称缺失问题

一、针对「buddy Span在Grafana中缺失」的排查方向 #

1. 检查OTEL Collector的采样规则
   查看Collector配置文件（如otel-collector-config.yaml）中的采样策略，是否存在针对buddy名称的Span过滤规则。比如是否在tail_sampling或sampler处理器中设置了排除buddy的规则：

   processors:
     tail_sampling:
       policies:
         - name: exclude_buddy
           type: string_attribute
           string_attribute:
             key: name
             value: "buddy"
             match_type: exact
             excluded: true
   

   若存在类似配置，删除或调整规则即可。

2. 确认buddy Span的上下文关联
   确保buddy Span是在FastAPI请求的父Span上下文内创建的，孤立的Span可能被Collector丢弃或在Grafana链路视图中无法关联显示。示例正确写法：

   from opentelemetry import trace
   
   tracer = trace.get_tracer(__name__)
   
   @app.get("/your-endpoint")
   async def your_endpoint():
       # 确保在请求Span的上下文内创建buddy Span
       with tracer.start_as_current_span("buddy") as span:
           span.set_attribute("biz_attr", "value")
           # 业务逻辑代码
       return {"status": "ok"}
   

3. 验证buddy Span的结束状态
   未正确结束的Span不会被导出到Collector。如果是手动创建Span而非使用with语句，需确保调用span.end()；使用with块时，要避免块内抛出未捕获的异常导致Span未正常结束。控制台打印仅代表本地生成了Span，但未完成的Span不会被发送到Collector。

二、针对「create_embeddings Span名称未在Grafana表格显示」的排查方向 #

1. 检查Span名称是否被覆盖
   确认代码中未在创建Span后修改名称，比如是否误调用span.update_name()覆盖了原名称：

   # 错误示例：覆盖了原名称
   with tracer.start_as_current_span("create_embeddings") as span:
       span.update_name("unexpected-name")
   

   确保start_as_current_span的参数是最终要显示的名称，且后续无修改操作。

2. 核对Grafana的字段映射配置
   Grafana表格可能未正确关联OTEL Span的name字段。进入Grafana面板配置，检查数据源（如Jaeger、Prometheus）是否正确提取了Span名称字段，表格的列设置是否选择了name字段作为显示项。

3. 验证Collector导出的Span数据
   先通过Jaeger UI或Collector的日志输出，确认create_embeddings Span是否带着正确名称被导出。如果Jaeger中能看到正确名称，说明问题出在Grafana的面板配置；如果Jaeger中也看不到正确名称，回到代码排查Span创建逻辑。

内容的提问来源于stack exchange，提问作者niranjan pb