OpenTelemetry 接入炬鲸 OBSERVE：从采集到告警的完整链路

OpenTelemetry（OTel）已经是云原生场景下事实上的埋点与数据采集标准。它的价值不在于发明新协议，而在于把原本割裂的日志、指标、链路统一成一套数据模型，避免每换一个后端就重写一遍采集代码。本文以 Java 和 Python 两个典型技术栈为例，讲清楚如何把数据接进炬鲸 OBSERVE，并落地第一条告警。

部署 OpenTelemetry Collector

Collector 负责接收应用上报的数据并做转发、批处理。单机测试可以直接跑二进制，生产建议用容器或 systemd 部署。下面是一份最小可用的 config.yaml，把 OTLP 数据转发到 OBSERVE：

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: 512
exporters:
  otlphttp:
    endpoint: https://ob.jjhub.cn/otel/v1/traces
    headers:
      Authorization: "Bearer <your-token>"
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlphttp]

注意两点：导出端点按信号类型区分，traces 与 metrics 用不同的 path；生产环境务必把 Collector 与应用部署在同一网络区域，跨公网直连要评估延迟和丢包。

应用侧埋点

Java 应用优先用 opentelemetry-javaagent，不改业务代码即可采集：

java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.traces.exporter=otlp \
  -Dotel.metrics.exporter=otlp \
  -Dotel.logs.exporter=otlp \
  -Dotel.exporter.otlp.endpoint=http://collector:4317 \
  -jar app.jar

Python 用 opentelemetry-instrument 自动注入，配合 Flask、FastAPI、requests、psycopg2 等常见库：

opentelemetry-instrument \
  --traces_exporter otlp \
  --metrics_exporter otlp \
  --exporter_otlp_endpoint http://collector:4317 \
  gunicorn app:app

采样策略要提前想清楚：自动埋点默认全量采集，预发没问题，到了生产高流量路径会打爆 Collector，建议上线后用 parent-based 或 tail-based 采样收口。另一个容易踩的坑是 service.name 资源属性，别依赖默认值——它通常从进程或入口名推导，跨环境不一致，导致链路视图里服务名对不上。Java 用 -Dotel.resource.attributes=service.name=order-service，Python 用环境变量 OTEL_RESOURCE_ATTRIBUTES=service.name=order-service 显式指定。

把 trace_id 关联进日志

链路追踪和日志脱节，是排查时最耗时间的事。做法是让日志框架带上 trace_id 和 span_id。以 Logback 为例：

<pattern>%d{HH:mm:ss.SSS} [%X{trace_id:-}] [%X{span_id:-}] %-5level %logger{36} - %msg%n</pattern>

前提是启用 OTel 的日志 MDC 注入（otel.instrumentation.logback-mdc），运行期会把当前 span 上下文自动放进 MDC。之后在 OBSERVE 里点开一条链路，就能直接跳到关联的日志，不用再按时间戳人肉 grep。

落地第一条告警

数据进来后，先别急着配一堆规则。建议从两个高价值指标入手：服务错误率（5xx 占比超过 2% 持续 3 分钟）和 P99 延迟（超过 500ms 持续 5 分钟）。告警通道配置成企微或钉钉，避免半夜邮件没人看；再给告警加冷却时间，防止单个服务抖动把整组值班电话打爆。

最后提醒一句：埋点上线前先在预发环境跑一周，确认采样率、指标基线和 Collector 资源占用都符合预期，再放量到生产。