OpenTelemetry 入门与 Kubernetes 部署指南

版本：2026.10
适用：OpenTelemetry Operator v0.158.0+ · Collector Contrib · Java Agent 3.0 预览
标签：OpenTelemetry Kubernetes 可观测性 分布式追踪 OTLP

📖 目录

一、为什么需要分布式追踪？
二、OpenTelemetry 是什么？
三、检测（埋点）方式
四、传播器
五、采样
六、OpenTelemetry 协议（OTLP）
七、OpenTelemetry Collector
八、Collector 部署模式
九、在 Kubernetes 上使用 OpenTelemetry
十、关键变更速查表
十一、总结

一、为什么需要分布式追踪？

在微服务架构中，一个请求可能经过几十甚至上百次网络调用。仅靠日志和指标，很难追踪请求的完整路径。分布式追踪以 Span 的形式记录请求在整个服务链路中的交互过程，包含延迟、错误等元数据，帮助快速定位瓶颈和故障。

二、OpenTelemetry 是什么？

OpenTelemetry 是一组开源、与供应商无关的工具、API 和 SDK 的集合，用于检测、生成、收集和导出遥测数据。它是 CNCF 的毕业项目，涵盖可观测性三大支柱：

支柱	说明
追踪（Traces）	服务请求在分布式系统中的完整路径
指标（Metrics）	对一段时间内活动的测量
日志（Logs）	系统或应用在特定时间点发生的事件的记录

核心优势：检测与后端解耦。开发者无需绑定特定商业供应商，可自由选择编程语言和存储后端。

三、检测（埋点）方式

自动检测：无需大量代码更改，Operator 通过注入 init 容器和配置实现零代码埋点。
手动检测：编写特定的埋点代码，可精确控制 Span 的属性和事件。

两者可混合使用：自动检测负责框架层埋点，手动检测补充业务级 Span。

四、传播器

传播器用于跨进程边界传递上下文数据。当前推荐使用 W3C Trace Context、Baggage 和 B3：

传播器	用途
Trace Context	在 HTTP headers 中编码 trace 数据
Baggage	在 span 之间传递键值对数据
B3	Zipkin 兼容的 trace 传递格式

五、采样

采样用于控制收集和发送到后端的追踪数据量，降低开销。常见方式包括：

头采样：在追踪开始时决定是否采样。
尾采样：根据完整追踪结果决定是否采样。

Collector 支持通过 tailsamplingprocessor 实现尾采样策略。

六、OpenTelemetry 协议（OTLP）

OTLP 是遥测数据在 SDK、Collector 和后端之间的标准传输协议。支持 gRPC 和 HTTP 两种传输方式，默认端口分别为：

传输方式	默认端口
gRPC	4317
HTTP	4318

七、OpenTelemetry Collector

Collector 是 OpenTelemetry 的核心组件，负责接收、处理和导出遥测数据。其架构包含以下部分：

7.1 Receivers（接收器）

接收器支持推送和拉取模式，标准配置同时在 gRPC 和 HTTP 端口上接受 OTLP 数据：

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: "0.0.0.0:4317"
      http:
        endpoint: "0.0.0.0:4318"

7.2 Processors（处理器）

处理器在接收和导出之间处理数据。强烈推荐将 memory_limiter 放在每个 pipeline 的第一个处理器位置，batch 紧随其后。

Memory Limiter 参数语义（2026 修正）

memory_limiter 的参数含义在官方文档中已明确：

参数	含义	建议值
`limit_mib`	硬性内存上限（hard heap target）	可用内存的 80–90%
`spike_limit_mib`	允许的瞬时内存增长缓冲区	`limit_mib` 的 20–25%
`check_interval`	内存检查频率	生产环境 1–5 秒

当内存使用超过 limit_mib - spike_limit_mib（软限制）时，Collector 开始拒绝新数据；超过 limit_mib 时，强制触发 GC 并拒绝数据。

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 1800      # 硬限制
    spike_limit_mib: 400  # 软限制 = 1800 - 400 = 1400 MiB
  batch:
    send_batch_size: 10000
    timeout: 10s

示例：容器内存限制为 2GB 时，limit_mib: 1800（90%），spike_limit_mib: 400（约 22%），软限制为 1400 MiB。当内存超过 1400 MiB 时 Collector 开始拒绝数据，为 GC 和恢复争取时间。

7.3 Exporters（导出器）

OTLP 导出器键名变更（重要）

OTLP 导出器的配置键名已更新：

传输方式	新键名	旧键名（已弃用）
gRPC	`otlp_grpc`	`otlp`
HTTP	`otlp_http`	`otlphttp`

exporters:
  debug:
    verbosity: detailed
  otlp_grpc:
    endpoint: "central-collector-collector.observability.svc:4317"
    tls:
      insecure: true
  otlp_http:
    endpoint: "http://central-collector-collector.observability.svc:4318"

注意：otlp_grpc 默认使用 gzip 压缩，可配置为 snappy 以降低 CPU 占用。
兼容性：若你的 Collector 版本较旧，请将 otlp_grpc 替换为 otlp，将 otlp_http 替换为 otlphttp。

Jaeger 导出器已移除

专用的 jaeger 导出器在 Collector contrib v0.86.0（2023 年 9 月） 中已被完全移除。如需将追踪数据发送到 Jaeger，应使用 otlp_grpc/jaeger（旧版为 otlp/jaeger）导出器，指向 Jaeger 的 OTLP gRPC 端口 4317（而非旧的 14250 端口）。

exporters:
  otlp_grpc/jaeger:
    endpoint: "jaeger.example.com:4317"
    tls:
      insecure: true

logging 导出器已弃用

logging 导出器已被 debug 导出器取代，loglevel 字段替换为 verbosity。

exporters:
  debug:
    verbosity: detailed

7.4 Extensions（扩展）

扩展用于健康监控、服务发现等非遥测数据处理任务，是可选的：

extensions:
  health_check:
  pprof:
  zpages:

八、Collector 部署模式

8.1 Agent 模式

Agent 模式将 Collector 部署为 sidecar 或 DaemonSet，与应用一起运行。应用通过 localhost 将数据发送到 Agent Collector，再由其转发到中心 Collector 或后端。

优点	缺点
启动简单，应用与 Collector 一对一映射清晰	对于团队和基础设施资源扩展性有限

8.2 Gateway 模式

Gateway 模式将数据发送到中心 Collector，再由其统一导出到后端。

优点：

消除对团队配置的依赖
集中执行批处理、重试、加密、压缩策略
统一身份验证和采样决策
通过 HPA 自动扩展

8.3 Kubernetes 部署模式对比

模式	说明
Sidecar	Collector 作为 sidecar 容器注入应用 Pod，数据经 localhost 转发
DaemonSet	每个节点部署一个 Agent Pod
Deployment	中心 Collector 以 Deployment 方式部署，支持 HPA 自动扩展

九、在 Kubernetes 上使用 OpenTelemetry

9.1 部署 OpenTelemetry Operator

当前 Operator 最新版本为 v0.158.0（2026 年 8 月发布）。推荐使用 Helm Chart 部署：

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update

helm upgrade --install --set admissionWebhooks.certManager.enabled=false \
  --set admissionWebhooks.certManager.autoGenerateCert=true \
  opentelemetry-operator open-telemetry/opentelemetry-operator \
  --namespace observability --create-namespace

9.2 创建中心 Collector（Gateway 模式）

apiVersion: opentelemetry.io/v1alpha1
kind: OpenTelemetryCollector
metadata:
  name: central-collector
  namespace: observability
spec:
  config: |
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: "0.0.0.0:4317"
          http:
            endpoint: "0.0.0.0:4318"
    processors:
      memory_limiter:
        check_interval: 1s
        limit_mib: 1800
        spike_limit_mib: 400
      batch:
        send_batch_size: 10000
        timeout: 10s
    exporters:
      debug:
        verbosity: detailed
      otlp_grpc/jaeger:
        endpoint: "jaeger.example.com:4317"
        tls:
          insecure: true
    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: [memory_limiter, batch]
          exporters: [debug, otlp_grpc/jaeger]

Operator 会创建名为 central-collector-collector 的 Service，暴露 4317/4318 端口。

9.3 创建 Sidecar Agent

Sidecar 模式的 Collector 配置需精简，批处理使用更小的批量和更短的超时以降低延迟：

apiVersion: opentelemetry.io/v1alpha1
kind: OpenTelemetryCollector
metadata:
  name: otel-sidecar
  namespace: observability
spec:
  mode: sidecar
  resources:
    limits:
      cpu: 100m
      memory: 128Mi
    requests:
      cpu: 50m
      memory: 64Mi
  config: |
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: "0.0.0.0:4317"
          http:
            endpoint: "0.0.0.0:4318"
    processors:
      memory_limiter:
        check_interval: 1s
        limit_mib: 100
        spike_limit_mib: 30
      batch:
        timeout: 2s
        send_batch_size: 500
    exporters:
      otlp_grpc:
        endpoint: "central-collector-collector.observability.svc:4317"
        tls:
          insecure: true
    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: [memory_limiter, batch]
          exporters: [otlp_grpc]

Sidecar 容器与中心 Collector 在同一集群内通信，可使用 tls.insecure: true 简化配置。

9.4 Sidecar 注入注解

在应用 Pod 的 metadata 中添加以下注解，触发 Sidecar 注入。注解值需匹配 OpenTelemetryCollector CR 的命名空间和名称：

annotations:
  sidecar.opentelemetry.io/inject: "observability/otel-sidecar"

该注解可应用于 Pod 级别或命名空间级别。

9.5 自动检测配置（Instrumentation CRD）

创建 Instrumentation 资源以启用自动埋点注入：

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: otel-instrumentation
  namespace: observability
spec:
  propagators:
    - tracecontext
    - baggage
    - b3
  sampler:
    type: parentbased_traceidratio
    argument: "0.25"
  exporter:
    endpoint: "http://localhost:4318"
  java:
    image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:latest

Java Agent 3.0 即将发布：当前 2.32.0 是 3.0 的候选版本，3.0 计划于 2026 年 10 月发布。3.0 将更改遥测数据、配置和埋点默认行为，包括数据库、代码和消息传递的语义约定变更。建议在生产环境中先使用预览标志验证兼容性：

# 预览 3.0 的遥测默认行为
OTEL_INSTRUMENTATION_COMMON_V3_PREVIEW=true
OTEL_SEMCONV_STABILITY_OPT_IN=database/dup,code/dup
OTEL_SEMCONV_STABILITY_PREVIEW=messaging/dup

9.6 为应用启用自动检测

在应用 Deployment 的 Pod 模板中添加注解：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
      annotations:
        instrumentation.opentelemetry.io/inject-java: "observability/otel-instrumentation"
        sidecar.opentelemetry.io/inject: "observability/otel-sidecar"
    spec:
      containers:
        - name: app
          image: my-app:latest
          env:
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: "http://localhost:4318"
            - name: OTEL_EXPORTER_OTLP_PROTOCOL
              value: "http/protobuf"

inject-java 注解触发 Java Agent 的 init 容器注入；sidecar.opentelemetry.io/inject 注解触发 Collector Sidecar 注入。应用通过 localhost:4318 将遥测数据发送到同一 Pod 内的 Sidecar Collector。

9.7 验证追踪数据

查看 Sidecar Collector 日志，确认数据已接收并导出：

kubectl logs -f deploy/my-app -c otc-container -n default

预期输出示例：

TracesExporter {"kind": "exporter", "data_type": "traces", "name": "otlp_grpc", "resource spans": 1, "spans": 76}

查看中心 Collector 日志，确认数据已到达：

kubectl logs -f deploy/central-collector-collector -n observability

预期输出示例：

Everything is ready. Begin running and processing data.
TracesExporter {"kind": "exporter", "data_type": "traces", "name": "debug", "resource spans": 1, "spans": 76}

十、关键变更速查表

变更项	旧方式（已弃用/移除）	新方式（2026 最新）
OTLP 导出器键名	`otlp` / `otlphttp`	`otlp_grpc` / `otlp_http`
Jaeger 导出器	`jaeger`（v0.86.0 移除）	`otlp_grpc/jaeger` 指向端口 4317
调试导出器	`logging` + `loglevel`	`debug` + `verbosity`
`limit_mib` 语义	模糊（曾被理解为软限制）	硬性堆上限（hard heap target）
软限制计算	不明确	`limit_mib - spike_limit_mib`
Java Agent	2.x 系列	3.0（2026 年 10 月发布）
Operator 版本	旧版	v0.158.0

十一、总结

本文演示了基于 2026 年最新标准，使用 OpenTelemetry Operator 在 Kubernetes 上实现零代码追踪的完整流程：

使用 Helm 部署 OpenTelemetry Operator（v0.158.0）
创建中心 Collector（Gateway 模式），配置 memory_limiter + batch 处理器和 otlp_grpc 导出器
以 Sidecar 模式部署 Agent Collector，将数据转发到中心 Collector
创建 Instrumentation 资源，通过注解实现自动检测注入
部署业务应用，追踪数据自动生成并发送到后端

核心要点：使用新键名 otlp_grpc / otlp_http；用 otlp_grpc/jaeger 替代已移除的 jaeger 导出器；正确理解 memory_limiter 的硬限制与软限制语义；关注 Java Agent 3.0 的发布与迁移。

posted @ 2026-10-10 21:48 wanghongwei-dev 阅读(10) 评论(0) 收藏举报

刷新页面返回顶部

https://www.cnblogs.com/wanghongwei-dev

欢迎来到本博客，本博客多为部署和配置文档用于查询使用，并用于记录故障处理。

OpenTelemetry 入门与 Kubernetes 部署指南

OpenTelemetry 入门与 Kubernetes 部署指南

📖 目录

一、为什么需要分布式追踪？

二、OpenTelemetry 是什么？

三、检测（埋点）方式

四、传播器

五、采样

六、OpenTelemetry 协议（OTLP）

七、OpenTelemetry Collector

7.1 Receivers（接收器）

7.2 Processors（处理器）

Memory Limiter 参数语义（2026 修正）

7.3 Exporters（导出器）

OTLP 导出器键名变更（重要）

Jaeger 导出器已移除

logging 导出器已弃用

7.4 Extensions（扩展）

八、Collector 部署模式

8.1 Agent 模式

8.2 Gateway 模式

8.3 Kubernetes 部署模式对比

九、在 Kubernetes 上使用 OpenTelemetry

9.1 部署 OpenTelemetry Operator

9.2 创建中心 Collector（Gateway 模式）

9.3 创建 Sidecar Agent

9.4 Sidecar 注入注解

9.5 自动检测配置（Instrumentation CRD）

9.6 为应用启用自动检测

9.7 验证追踪数据

十、关键变更速查表

十一、总结

公告