OpenTelemetry 入门实战:从链路追踪到指标与日志统一采集
一、为什么需要统一标准
一个请求打进来,网关记一份日志、应用打一条 trace、Prometheus 抓一组指标,三套 SDK、三套标签命名,出故障时很难对齐到同一个请求。换一次监控后端,埋点代码就得重写。
OpenTelemetry(OTel)把采集层标准化:一套 API/SDK 生成 trace、metrics、logs,统一用 OTLP 发给 Collector,再由 Collector 导出到 Jaeger、Prometheus、Loki 或云厂商。业务代码只依赖 OTel,不绑定后端。
二、三类信号与核心概念
信号:回答的问题:关键对象
Trace:请求慢在哪一步:Span、TraceID、SpanContext
Metrics:整体趋势与速率:Counter、Histogram、Gauge
Logs:具体发生了什么:结构化日志 + TraceID 关联
Span 通过 parent 串成树;跨进程传递靠 W3C TraceContext 的 traceparent 请求头。Resource 描述服务本身(service.name),Attribute 描述单次操作(http.method)。这些键名要遵守语义约定,别自己造。
三、五分钟跑通(Python + Flask)
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-grpc \
opentelemetry-instrumentation-flask
from flask import Flask
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.flask import FlaskInstrumentor
resource = Resource.create({"service.name": "order-api", "service.version": "1.2.0"})
provider = TracerProvider(resource=resource)
provider.add_span_processor(BatchSpanProcessor(
OTLPSpanExporter(endpoint="http://localhost:4317", insecure=True)))
trace.set_tracer_provider(provider)
app = Flask(__name__)
FlaskInstrumentor().instrument_app(app) # 自动为每个请求建 span
tracer = trace.get_tracer(__name__)
@app.get("/order/<oid>")
def get_order(oid):
with tracer.start_as_current_span("load_order") as span:
span.set_attribute("order.id", oid)
span.add_event("cache_miss")
return {"id": oid}
异常时用 span.record_exception(e) 并设置 ERROR 状态。自动埋点打底 + 手动埋点补关键路径是性价比最高的组合。
四、Collector:真正的中枢
别把 exporter 直连后端,统一先发 Collector:receiver 接数据、processor 加工、exporter 落地。
receivers:
otlp:
protocols: { grpc: { endpoint: 0.0.0.0:4317 }, http: { endpoint: 0.0.0.0:4318 } }
processors:
batch: { timeout: 5s, send_batch_size: 512 }
memory_limiter: { check_interval: 1s, limit_mib: 400, spike_limit_mib: 100 }
attributes/clean:
actions:
· key: http.request.header.authorization
action: delete # 脱敏
exporters:
otlp/jaeger: { endpoint: jaeger:4317, tls: { insecure: true } }
prometheus: { endpoint: 0.0.0.0:8889 }
service:
pipelines:
traces: { receivers: [otlp], processors: [memory_limiter, attributes/clean, batch], exporters: [otlp/jaeger] }
metrics: { receivers: [otlp], processors: [memory_limiter, batch], exporters: [prometheus] }
memory_limiter 必须放在 processor 链首位,否则高流量下 Collector 先被自己压垮;batch 一定要开,逐条导出会打满网络。生产建议 Gateway 模式:每节点 Agent Collector → 集中 Gateway,便于统一采样、脱敏和多后端扇出。
五、采样与成本
· 头部采样:ParentBased(TraceIdRatioBased(0.1)),入口即决定,省资源但会漏掉偶发错误。
· 尾部采样:Collector 收齐整条 trace 再决定,可按"含 ERROR 或延迟 > 1s 必留"配置,排障体验最好、内存开销最大。
processors:
tail_sampling:
decision_wait: 10s
policies:
· { name: keep-errors, type: status_code, status_code: { status_codes: [ERROR] } }
· { name: keep-slow, type: latency, latency: { threshold_ms: 1000 } }
· { name: baseline, type: probabilistic, probabilistic: { sampling_percentage: 5 } }
六、五个常见坑
· 跨服务 trace 断链:异步队列、线程池、手动 HTTP 调用没传 traceparent,需用 inject/extract 显式传播 context。
· 高基数属性:把 user_id、order_id 塞进 metrics label 会让时序爆炸,这类维度只放 span attribute。
· 没设 service.name:后端看到一堆 unknown_service,等于白采。
· 同步导出:SimpleSpanProcessor 会在请求链路里同步发网络请求,拖慢接口;生产一律 BatchSpanProcessor。
· 日志没关联 trace:日志格式需输出 trace_id/span_id,否则三类信号仍对不上。
七、小结
落地顺序:自动埋点打通 trace → 部署 Collector 收口并加脱敏 → 配置尾部采样控成本 → 日志注入 TraceID 完成三信号关联。Schema 稳定后,换后端只是改 Collector 的 exporter 配置,业务代码一行不动。
- 点赞
- 收藏
- 关注作者
评论(0)