入門OpenTelemetry——部署OpenTelemetry

OpenTelemetry 部署模式

OpenTelemetry Collector 按部署方式分為 Agent 和Gateway 模式。

Agent 模式

在 Agent 模式下，OpenTelemetry 檢測的應用程序將數據發送到與應用程序一起駐留的（收集器）代理。然後，該代理程序將接管並處理所有來自應用程序的追蹤數據。

收集器可以通過 sidecar 方式部署為代理，sidecar 可以配置為直接將數據發送到存儲後端。

Gateway 模式

Gateway 模式則是將數據發送到另一個 OpenTelemetry 收集器，然後從（中心）收集器進一步將數據發送到存儲後端。在這種配置中，我們有一個中心的 OpenTelemetry 收集器，它使用 deployment/statefulset/daemonset 模式部署，具有許多優勢，如自動擴展。

發送遙測數據最佳實踐是將數據發送到OpenTelemetry Collector而不是直接發送到後端。Collector可以幫助簡化密鑰管理，將數據導出與應用程序解耦，並允許您在遙測數據中添加其他數據。

部署 OpenTelemetry

建議使用 OpenTelemetry Operator 來部署，因為它可以幫助我們輕鬆部署和管理 OpenTelemetry 收集器，還可以自動檢測應用程序。具體可參考文檔https://opentelemetry.io/docs/platforms/Kubernetes/operator/

部署cert-manager

因為 Operator 使用了 Admission Webhook 通過 HTTP 回調機制對資源進行校驗/修改。Kubernetes 要求 Webhook 服務必須使用 tls，因此 Operator 需要為其 webhook server 簽發證書，所以需要先安裝cert-manager。

# wget https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml
# kubectl apply -f cert-manager.yaml
# kubectl get pod -n cert-manager
NAME                                       READY   STATUS    RESTARTS   AGE
cert-manager-5577849d6c-kwg7f              1/1     Running   0          3m18s
cert-manager-cainjector-5755f77bbb-knlm2   1/1     Running   0          3m18s
cert-manager-webhook-b78d65b96-vpvrn       1/1     Running   0          3m18s

部署Operator

在 Kubernetes 上使用 OpenTelemetry，主要就是部署 OpenTelemetry 收集器。

# wget https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml
# kubectl apply -f opentelemetry-operator.yaml
# kubectl get pod -n opentelemetry-operator-system 
NAME                                                         READY   STATUS    RESTARTS   AGE
opentelemetry-operator-controller-manager-6d94c5db75-cz957   2/2     Running   0          74s
# kubectl get crd |grep opentelemetry
instrumentations.opentelemetry.io           2025-04-21T09:48:53Z
opampbridges.opentelemetry.io               2025-04-21T09:48:54Z
opentelemetrycollectors.opentelemetry.io    2025-04-21T09:48:54Z
targetallocators.opentelemetry.io           2025-04-21T09:48:54Z

部署Collector(中心)

接下來我們部署一個精簡版的 OpenTelemetry Collector，用於接收 OTLP 格式的 trace 數據，通過 gRPC 或 HTTP 協議接入，經過內存控制與批處理後，打印到日誌中以供調試使用。

# cat center-collector.yaml              
apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
# 元數據定義部分
metadata:
  name: center        # Collector 的名稱為 center
  namespace: opentelemetry
# 具體的配置內容
spec:
  replicas: 1           # 設置副本數量為1
  config:               # 定義 Collector 配置
    receivers:          # 接收器，用於接收遙測數據（如 trace、metrics、logs）
      otlp:             # 配置 OTLP（OpenTelemetry Protocol）接收器
        protocols:      # 啟用哪些協議來接收數據
          grpc: 
            endpoint: 0.0.0.0:4317      # 啟用 gRPC 協議
          http: 
            endpoint: 0.0.0.0:4318      # 啟用 HTTP 協議

    processors:         # 處理器，用於處理收集到的數據
      batch: {}         # 批處理器，用於將數據分批發送，提高效率

    exporters:          # 導出器，用於將處理後的數據發送到後端系統
      debug: {}         # 使用 debug 導出器，將數據打印到終端（通常用於測試或調試）

    service:            # 服務配置部分
      pipelines:        # 定義處理管道
        traces:         # 定義 trace 類型的管道
          receivers: [otlp]                      # 接收器為 OTLP
          processors: [batch]                    # 使用批處理器
          exporters: [debug]                     # 將數據打印到終端

# kubectl apply -f center-collector.yaml 
opentelemetrycollector.opentelemetry.io/center created
# kubectl get pod -n opentelemetry
NAME                                READY   STATUS    RESTARTS      AGE
center-collector-5c5987f4ff-zwqbk   1/1     Running   0             9s
# kubectl get svc -n opentelemetry  
NAME                          TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                       AGE
center-collector              ClusterIP   10.109.226.90    <none>        4317/TCP,4318/TCP             22s
center-collector-headless     ClusterIP   None             <none>        4317/TCP,4318/TCP             22s
center-collector-monitoring   ClusterIP   10.110.106.116   <none>        8888/TCP                      22s

部署Collector(代理)

我們使用 Sidecar 模式部署 OpenTelemetry 代理。該代理會將應用程序的追蹤發送到我們剛剛部署的中心OpenTelemetry 收集器。

# cat sidecar-collector.yaml 
apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector          # 定義資源類型為 OpenTelemetryCollector
metadata:
  name: sidecar                       # Collector 的名稱
  namespace: opentelemetry
spec:
  mode: sidecar                       # 以 sidecar 模式運行（與應用容器同 Pod）
  config:                             # Collector 配置部分（結構化 YAML）
    receivers:
      otlp:                           # 使用 OTLP 協議作為接收器
        protocols:
          grpc: 
            endpoint: 0.0.0.0:4317      # 啟用 gRPC 協議
          http: 
            endpoint: 0.0.0.0:4318      # 啟用 HTTP 協議
    processors:
      batch: {}                       # 使用 batch 處理器將數據批量發送，提高性能

    exporters:
      debug: {}                       # 將數據輸出到 stdout 日誌（用於調試）
      otlp:                           # 添加一個 OTLP 類型導出器，發送到 central collector
        endpoint: "center-collector.opentelemetry.svc:4317"  # 替換為 central collector 的地址
        tls:
          insecure: true              # 不使用 TLS

    service:
      telemetry:
        logs:
          level: "debug"              # 設置 Collector 自身日誌等級為 debug（方便觀察日誌）

      pipelines:
        traces:                       # 定義 trace 數據處理流水線
          receivers: [otlp]           # 從 otlp 接收 trace 數據
          processors: [batch]         # 使用批處理器
          exporters: [debug, otlp]    # 同時導出到 debug（日誌）和 otlp（中心 Collector）
# kubectl apply -f sidecar-collector.yaml                
opentelemetrycollector.opentelemetry.io/sidecar created
# kubectl get opentelemetrycollectors -n opentelemetry   
NAME      MODE         VERSION   READY   AGE   IMAGE                                                                                     MANAGEMENT
center    deployment   0.123.1   1/1     10m   ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector:0.123.1   managed
sidecar   sidecar      0.123.1           11s                                                                                             managed
# kubectl get pod -n opentelemetry                    
NAME                                READY   STATUS    RESTARTS      AGE
center-collector-5c5987f4ff-zwqbk   1/1     Running   0             10m

sidecar 代理依賴於應用程序啟動，因此現在創建後並不會立即啟動，需要我們創建一個應用程序並使用這個 sidecar 模式的 collector。