opentelemetry

用途

OpenTelemetry（OTel）是一个厂商中立的可观测性框架，用于对遥测数据进行埋点、生成、采集和导出。本技能提供在 Kubernetes 环境中实施 OTEL 的指导，帮助搭建 Collector、配置追踪/指标/日志管道，并完成 Kubernetes 部署与埋点。

主要能力

支持三类遥测信号：追踪（Traces，跨服务的分布式请求流）、指标（Metrics，计数器、仪表、直方图等数值测量）、日志（Logs，结构化或非结构化的事件记录）。
Collector 组件包括：接收器（Receivers，接受 OTLP、Prometheus、Jaeger、Zipkin 等数据）、处理器（Processors，转换数据，如 batch、memory_limiter、k8sattributes）、导出器（Exporters，发送数据，如 prometheusremotewrite、loki、otlp）、扩展（Extensions，增加能力，如 health_check、pprof、zpages）。
支持 Kubernetes 属性增强，通过 k8sattributes 处理器提取 k8s.pod.name、k8s.namespace.name、k8s.deployment.name、k8s.node.name 等元数据。
提供三种部署模式：DaemonSet（节点级采集，覆盖全面、含主机指标，但资源占用较高）、Deployment（集中式网关，可扩展、易管理，但存在单点故障）、Sidecar（每 Pod 采集，隔离、细粒度，但每 Pod 有资源开销）。

使用方式

快速开始：通过 Helm 部署 OTEL Collector。

# 添加 Helm 仓库
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update

# 使用基础配置安装
helm install otel-collector open-telemetry/opentelemetry-collector \
  --namespace monitoring --create-namespace \
  --set mode=daemonset

通过 OTLP 发送测试数据（gRPC 端点 4317，HTTP 端点 4318）：

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

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

验证命令：

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

# 查看 collector 日志
kubectl logs -n monitoring -l app.kubernetes.io/name=otel-collector --tail=100

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

# 验证配置语法
otelcol validate --config=config.yaml

关键 Helm Chart 值示例：

mode: "daemonset"  # 或 "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

适用场景

开发环境：启用 debug 导出器以便观察；降低资源限制（250m CPU、512Mi 内存）；加入 spot 实例容忍以节省成本。
生产环境：实施采样（追踪 10-50%）；提高批处理大小（2048-4096）；启用自动扩缩容和 PodDisruptionBudget；所有端点使用 TLS。

限制与注意事项

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

更多深入指导可参考：Collector 配置（COLLECTOR.md）、Kubernetes 部署（KUBERNETES.md）、故障排查（TROUBLESHOOTING.md）、埋点（INSTRUMENTATION.md）。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项