otel-flask-style

OTel Flask 风格

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

from flask import Flask
from opentelemetry.instrumentation.flask import FlaskInstrumentor

def init_observability(app: Flask) -> bool:
    ...
    FlaskInstrumentor().instrument_app(app)
    return True

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

入口点

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

app = Flask(__name__)
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")
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、模型和令牌数据集中估算成本。