opentelemetry

OpenTelemetry 实施指南

概述

OpenTelemetry（OTel）是一个与供应商无关的可观测性框架，用于检测、生成、收集和导出遥测数据（跟踪、指标、日志）。本指南介绍如何在 Kubernetes 环境中实施 OTEL。

快速入门

在 Kubernetes 上部署 OTEL Collector

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

# Install with basic config
helm install otel-collector open-telemetry/opentelemetry-collector \
  --namespace monitoring --create-namespace \
  --set mode=daemonset

通过 OTLP 发送测试数据

# gRPC endpoint: 4317, HTTP endpoint: 4318
curl -X POST http://otel-collector:4318/v1/traces \
  -H "Content-Type: application/json" \
  -d '{"resourceSpans":[]}'

核心概念

信号：三种遥测数据：

• 跟踪：跨服务的分布式请求流
• 指标：数值测量（计数器、仪表、直方图）
• 日志：包含结构化或非结构化数据的事件记录

Collector 组件：

• 接收器：接收数据（OTLP、Prometheus、Jaeger、Zipkin）
• 处理器：转换数据（batch、memory_limiter、k8sattributes）
• 导出器：发送数据（prometheusremotewrite、loki、otlp）
• 扩展：添加功能（health_check、pprof、zpages）

Collector 配置

基本管道结构

config:
  receivers:
    otlp:
      protocols:
        grpc:
          endpoint: ${env:MY_POD_IP}:4317
        http:
          endpoint: ${env:MY_POD_IP}:4318

  processors:
    batch:
      timeout: 10s
      send_batch_size: 1024
    memory_limiter:
      check_interval: 5s
      limit_percentage: 80
      spike_limit_percentage: 25

  exporters:
    prometheusremotewrite:
      endpoint: "http://prometheus:9090/api/v1/write"
    loki:
      endpoint: "http://loki:3100/loki/api/v1/push"

  service:
    pipelines:
      metrics:
        receivers: [otlp]
        processors: [memory_limiter, batch]
        exporters: [prometheusremotewrite]
      logs:
        receivers: [otlp]
        processors: [memory_limiter, batch]
        exporters: [loki]
      traces:
        receivers: [otlp]
        processors: [memory_limiter, batch]
        exporters: [otlp/tempo]

Kubernetes 属性增强

processors:
  k8sattributes:
    auth_type: "serviceAccount"
    passthrough: false
    filter:
      node_from_env_var: ${env:K8S_NODE_NAME}
    extract:
      metadata:
        - k8s.pod.name
        - k8s.namespace.name
        - k8s.deployment.name
        - k8s.node.name

部署模式

模式	用例	优点	缺点
DaemonSet	节点级收集	覆盖全面，包含主机指标	资源使用较高
Deployment	集中式网关	可扩展，易于管理	单点故障
Sidecar	每个 Pod 单独收集	隔离性好，粒度精细	每个 Pod 都有资源开销

常见模式

开发环境

• 启用 debug exporter，以便查看数据
• 降低资源限制（250m CPU、512Mi 内存）
• 添加 spot 实例容忍度以节省成本

生产环境

• 实施采样（跟踪采样率为 10-50%）
• 提高批次大小（2048-4096）
• 启用自动扩缩容和 PodDisruptionBudget
• 所有端点均使用 TLS

详细参考

如需深入了解，请参阅：

• Collector 配置：COLLECTOR.md
• Kubernetes 部署：KUBERNETES.md
• 故障排查：TROUBLESHOOTING.md
• 检测：INSTRUMENTATION.md

验证命令

# Check collector pods
kubectl get pods -n monitoring -l app.kubernetes.io/name=otel-collector

# View collector logs
kubectl logs -n monitoring -l app.kubernetes.io/name=otel-collector --tail=100

# Test OTLP endpoint
kubectl run test-otlp --image=curlimages/curl:latest --rm -it -- \
  curl -v http://otel-collector.monitoring:4318/v1/traces

# Validate config syntax
otelcol validate --config=config.yaml

Helm Chart 关键值

mode: "daemonset"  # or "deployment"
presets:
  logsCollection:
    enabled: true
  hostMetrics:
    enabled: true
  kubernetesAttributes:
    enabled: true
  kubeletMetrics:
    enabled: true
useGOMEMLIMIT: true
resources:
  limits:
    cpu: 500m
    memory: 1Gi
  requests:
    cpu: 100m
    memory: 256Mi

---

注意事项

• Collector 的 tail_sampling 放在管道末尾时，不会释放正在处理的缓冲区——延迟做出的丢弃决策仍会占用内存；负载较高时可能发生 OOM。
• 自动检测与手动检测可能导致跟踪重复计数——每个服务选择一种策略，或通过采样器显式去重。
• 上下文传播：HTTP B3 与 W3C traceparent 标头不会自动转换；混合环境会在无提示的情况下中断跟踪连续性。
• OTel SDK 与 Collector 的协议版本：次要版本不匹配可能导致属性被静默丢弃（尤其是语义约定属性）。
• 资源检测会添加平台属性（cloud.account.id、host.id），使跟踪数据膨胀；若不用于路由，请禁用。
• 批处理器与内存限制器的顺序：限制器必须在管道中位于 batch 之前，否则内存压力会导致批次被丢弃，且没有背压机制。