otel-fastapi-style

OTel FastAPI 风格

使用原生 FastAPI 插桩。不要仅为创建 span 而用手动中间件替代请求处理。

from fastapi import FastAPI
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor

def init_observability(app: FastAPI) -> bool:
    ...
    FastAPIInstrumentor.instrument_app(app)
    return True

将 FastAPIInstrumentor.instrument_app(app) 与其余可观测性设置放在一起，以便更容易理解引导过程。如果注册流程仍在进行，生成的令牌尚未被认领，也仍可初始化 providers；在浏览器流程完成之前，接收端可能会拒绝导出。

入口点

在开始处理用户流量之前完成初始化。

app = FastAPI(title="Mugline API")
init_observability(app)

有界工作

对于自动插桩的 HTTP span 无法覆盖的辅助函数，使用模块级 OTel 对象和装饰器。

tracer = trace.get_tracer("mugline.api")
meter = metrics.get_meter("mugline.api")

@tracer.start_as_current_span("mug.recommend")
async def recommend_mug(*, tenant_id: str, preference: str) -> dict[str, str]:
    span = trace.get_current_span()
    span.set_attribute("tenant.id", tenant_id)
    ...

日志

对于通过 OTLP 转发的标准库日志，请配置以下所有项目：

• LoggerProvider
• set_logger_provider(logger_provider)
• OTLPLogExporter
• LoggingHandler
• LoggingInstrumentor().instrument(...)

LLM 调用

LLM 路由需要覆盖令牌用量：

• llm.tokens.input
• llm.tokens.output

只有在 provider 插桩无法捕获令牌用量时，才为显式令牌计数添加租户、provider、模型、用例、调用位置和结果标签。不要在应用侧添加 LLM 成本指标或定价表；Superlog 会根据 provider、模型和令牌数据集中估算成本。