OBI 組件配置說明 - Cloud Monitor

OBI（OpenTelemetry eBPF Instrumentation）基於 eBPF 在核心層自動捕獲應用的網路與協議流量，無需修改業務代碼或注入 SDK，即可產出符合 OpenTelemetry 語義約定的指標（Metrics）與鏈路（Traces）。本文逐欄位說明 OBI 樣本配置中各模組的含義、取值與調優建議，適用於在阿里雲 ACK（Kubernetes）環境中以無侵入方式實現可觀測採集的情境。

適用範圍

本配置預設運行在 Kubernetes（阿里雲 ACK）環境，以 DaemonSet 形式在每個節點部署 OBI，依賴 eBPF 在節點核心層採集全節點 Pod 的流量。使用前請確認下列前提。

前提項	要求	說明
部署形態	DaemonSet（節點級）	每節點一個 OBI 執行個體，採集本節點全部工作負載

配置總覽

本配置由六個頂層模組組成，分別控制"采什麼指標、采哪些執行個體、給資料打什麼標籤、如何歸併路由、在核心層解析哪些協議、以及如何匯出鏈路"。

頂層模組	職責	關鍵效果
`metrics`	指標能力開關	開啟應用、網路、TCP RTT 三類指標
`discovery`	採集對象發現與排除	排除 OBI 自身及 ARMS 組件所在命名空間
`attributes`	屬性裝飾與篩選	關聯 K8s 中繼資料，鏈路保留 GenAI 屬性
`routes`	HTTP 路由歸併	控制 path 基數，防止指標維度爆炸
`ebpf`	核心層負載提取	解析 GenAI 與 JSON-RPC 應用程式層協議

指標能力開關（metrics）

metrics 模組通過 features 列表控制 OBI 開啟哪些類型的指標採集。本樣本開啟了應用、網路、TCP RTT 三類指標。

配置項	含義與作用	本樣本取值	可選值 / 預設	說明與調優建議
`features: application`	應用指標	啟用	—	開啟應用維度指標採集
`features: network`	網路指標	啟用	—	開啟網路維度指標採集
`features: stats_tcp_rtt`	TCP RTT 指標	啟用	—	開啟 TCP RTT 統計採集

採集對象發現與排除（discovery）

discovery 決定 OBI 對哪些進程或 Pod 插樁。本樣本通過 exclude_instrument 按命名空間做排除，避免採集 OBI 自身及 ARMS 平台組件，減少無意義的自監控資料與資源開銷。

配置項	含義與作用	本樣本取值	可選值 / 預設	說明與調優建議
`exclude_instrument[].k8s_namespace: obi-system`	排除 OBI 自身所在命名空間	排除	—	防止 OBI 採集自己，避免自監控雜訊
`exclude_instrument[].k8s_namespace: ack-onepilot`	排除 ARMS 應用監控 Operator 組件	排除	—	ack-onepilot 為 ARMS 探針管理組件，無需業務採集
`exclude_instrument[].k8s_namespace: arms-prom`	排除 ARMS Prometheus 相關組件	排除	—	平台採集組件，排除以減少自採集

排除清單可按實際情況擴充，例如加入 kube-system 或其他平台命名空間。若需僅採集特定業務命名空間，也可改用正向的 discovery.instrument 白名單方式。

屬性裝飾與篩選（attributes）

attributes 控製為採集到的指標與鏈路附加哪些屬性，以及在鏈路中保留哪些屬性。本樣本開啟 Kubernetes 中繼資料關聯，並在鏈路中顯式保留全部 GenAI 語義屬性。

配置項	含義與作用	本樣本取值	可選值 / 預設	說明與調優建議
`kubernetes.enable`	是否為資料關聯 K8s 中繼資料（Pod、Namespace、工作負載、節點等）	`true`	—	ACK 環境建議開啟，便於按 K8s 維度檢索與下鑽
`select.traces.include: gen_ai.*`	鏈路中包含的屬性白名單，`gen_ai.*` 通配所有 GenAI 語義約定屬性	保留全部 `gen_ai.*`	—	保證大模型調用的 provider、model、token、operation、tool 等屬性完整落到鏈路

gen_ai.* 屬性遵循 OpenTelemetry GenAI 語義約定，包含如 gen_ai.system（供應商）、gen_ai.request.model（模型名）、gen_ai.operation.name（操作類型，如 chat / embeddings）、gen_ai.tool.name（工具調用名）等。保留這些屬性是實現大模型鏈路可觀測的關鍵。

路由歸併（routes）

routes 用於將 HTTP 要求 path 歸併為路由模板，避免因 path 中包含 ID、UUID 等可變片段造成指標維度（基數）無限膨脹。基數失控會顯著增加時序資料庫成本並拖慢查詢。

配置項	含義與作用	本樣本取值	可選值 / 預設	說明與調優建議
`routes.unmatched`	未匹配到路由模板的 path 的處理策略	`low-cardinality`	`low-cardinality` / `wildcard` / `path` / `heuristic`	`low-cardinality` 會將未匹配 path 歸併為低基數形式，防止維度爆炸；調試期可臨時用 `path` 保留原始路徑
`routes.max_path_segment_cardinality`	單個 path 片段允許的最大不同取值數，超過則該片段收斂為通配	`500`	正整數	值越大保留細節越多、基數越高；ID 類高變化片段建議維持較小閾值

協議解析（ebpf）

ebpf.payload_extraction 控制 OBI 是否在核心層提取 HTTP 負載並解析應用程式層協議內容。開啟後 OBI 可從明文 HTTP 報文中還原大模型調用、MCP 調用等語義資訊，這是 GenAI 無侵入可觀測的基礎。

配置項	含義與作用	本樣本取值	可選值 / 預設	說明與調優建議
`http.jsonrpc.enabled`	是否解析基於 HTTP 的 JSON-RPC 2.0 協議	`true`	`true` / `false`	MCP 等基於 JSON-RPC，開啟後可還原方法名與調用語義
`http.genai.*`	各 GenAI 供應商 / 調用類型的解析開關	見下表	按供應商逐項開關	僅需開啟實際使用的供應商，減少無關解析開銷
`buffer_sizes.http`	HTTP 負載提取的核心緩衝區大小（位元組）	`262144`（256 KB）	正整數（位元組）	大模型請求/響應體較大，需足夠緩衝以避免負載被截斷；過大則增加記憶體佔用

GenAI 供應商解析開關

http.genai 下逐項控制對不同大模型供應商與調用類型的負載解析。本樣本開啟的項如下，可僅保留實際鏈路中調用的供應商。

配置項	解析目標	本樣本取值	說明
`genai.openai_compatible.enabled`	OpenAI 相容介面	`true`	覆蓋 vLLM、DashScope 相容模式、本地 Ollama 的 OpenAI 相容端點等
`genai.openai.enabled`	OpenAI 原生 API	`true`	解析 OpenAI 官方介面調用
`genai.anthropic.enabled`	Anthropic Claude API	`true`	解析 Claude 系列模型調用
`genai.retrieval.enabled`	檢索類調用（Retrieval / RAG 檢索）	`true`	還原向量檢索 / RAG 檢索環節
`genai.mcp.enabled`	MCP（Model Context Protocol）調用	`true`	基於 JSON-RPC，配合 `jsonrpc.enabled` 使用
`genai.qwen.enabled`	通義千問 DashScope 原生 API	`true`	解析 Qwen 系列模型調用
`genai.embedding.enabled`	Embedding 向量化調用	`true`	還原文本向量化環節
`genai.gemini.enabled`	Google Gemini API	`true`	解析 Gemini 系列模型調用
`genai.rerank.enabled`	Rerank 重排序調用	`true`	還原檢索結果重排環節

自訂網關（gateways）

若通過自建網關（如 LiteLLM、vLLM 等）代理大模型調用，可在 openai_compatible 下增加 gateways 列表，聲明網關的主機與連接埠。OBI 會將命中列表的流量按對應網關識別並解析，從而在非官方網域名稱的 OpenAI 相容端點上也能正確產出 GenAI 語義資訊。

genai:
  openai_compatible:
    enabled: true
    gateways:
      - host: litellm.example.com
        provider: litellm
      - host: localhost
        port: 8080
        provider: vllm

host 為必要欄位，port 和 provider 可選。

啟用的插樁類型

instrumentations 列表決定 OBI 對哪些協議 / 中介軟體產生鏈路。本樣本啟用的類型如下。

插樁類型	覆蓋對象	本樣本取值
`http`	HTTP / HTTPS 調用	啟用
`grpc`	gRPC 調用	啟用
`sql`	SQL 資料庫訪問	啟用
`redis`	Redis 訪問	啟用
`kafka`	Kafka 訊息	啟用
`mqtt`	MQTT 訊息	啟用
`mongo`	MongoDB 訪問	啟用
`couchbase`	Couchbase 訪問	啟用
`memcached`	Memcached 訪問	啟用
`genai`	大模型（GenAI）調用	啟用

完整配置附錄

以下為本文說明的完整配置，可直接複製使用。請在正式啟用前，結合實際的命名空間、供應商與流量規模，對排除清單、GenAI 開關及匯出參數做相應裁剪。

完整配置 YAML

metrics:
  features:
    - application
    - network
    - stats_tcp_rtt
discovery:
  exclude_instrument:
    - k8s_namespace: obi-system
    - k8s_namespace: ack-onepilot
    - k8s_namespace: arms-prom
attributes:
  kubernetes:
    enable: true
  select:
    traces:
      include:
        - "gen_ai.*"
routes:
  unmatched: low-cardinality
  max_path_segment_cardinality: 500
ebpf:
  payload_extraction:
    http:
      jsonrpc:
        enabled: true
      genai:
        openai_compatible:
          enabled: true
        openai:
          enabled: true
        anthropic:
          enabled: true
        retrieval:
          enabled: true
        mcp:
          enabled: true
        qwen:
          enabled: true
        embedding:
          enabled: true
        gemini:
          enabled: true
        rerank:
          enabled: true
  buffer_sizes:
    http: 262144
otel_traces_export:
  batch_timeout: 10s
  batch_max_size: 512
  queue_size: 4096
  backoff_initial_interval: 5s
  backoff_max_interval: 15s
  backoff_max_elapsed_time: 2m
  instrumentations:
    - http
    - grpc
    - sql
    - redis
    - kafka
    - mqtt
    - mongo
    - couchbase
    - memcached
    - genai