OBI component configuration - Cloud Monitor - Alibaba Cloud Documentation Center

OpenTelemetry eBPF Instrumentation (OBI) captures application network and protocol traffic at the kernel layer without modifying business code or injecting SDKs. This topic explains each configuration module for OBI deployed in Alibaba Cloud Container Service for Kubernetes (ACK) environments, covering field semantics, values, and tuning suggestions. OBI produces metrics and traces that comply with OpenTelemetry semantic conventions.

Prerequisites

This configuration runs by default in an ACK environment. It deploys OBI as a DaemonSet on each node and uses eBPF to collect traffic from all pods on the node at the kernel layer. Before you begin, confirm the following prerequisites.

Item	Requirement	Description
Deployment mode	DaemonSet (node-level)	One OBI instance per node collects data from all workloads on that node.

Configuration modules

This configuration consists of six top-level modules that control what metrics to collect, which instances to collect from, what labels to attach to data, how to consolidate routes, which protocols to parse at the kernel layer, and how to export traces.

Module	Responsibility	Key effect
`metrics`	Metric capability toggles	Enables application, network, and TCP RTT metrics
`discovery`	Collection target discovery and exclusion	Excludes the OBI namespace and Application Real-Time Monitoring Service (ARMS) component namespaces
`attributes`	Attribute decoration and filtering	Associates Kubernetes metadata; retains GenAI attributes in traces
`routes`	HTTP route consolidation	Controls path cardinality to prevent metric dimension explosion
`ebpf`	Kernel-layer payload extraction	Parses GenAI and JSON-RPC application-layer protocols

Metrics capability

The metrics module uses the features list to specify the types of metrics that OBI collects. This example enables application, network, and TCP RTT metrics.

Configuration item	Description	Value	Notes and tuning recommendations
`features: application`	Application metrics	Enabled	Enables metric collection for the application dimension.
`features: network`	Network metrics	Enabled	Enables metric collection for the network dimension.
`features: stats_tcp_rtt`	TCP RTT metrics	Enabled	Enables TCP RTT statistics collection.

Namespace exclusion

discovery determines which processes or Pods OBI instruments. This example uses exclude_instrument to exclude namespaces, preventing OBI from collecting its own data and ARMS platform component data. This reduces unnecessary self-monitoring data and resource overhead.

Field	Purpose	Value	Notes
`exclude_instrument[].k8s_namespace: obi-system`	Excludes the namespace where OBI runs	Excluded	Prevents OBI from collecting its own data and avoids self-monitoring noise
`exclude_instrument[].k8s_namespace: ack-onepilot`	Excludes the ARMS Application Monitoring operator components	Excluded	ack-onepilot is the ARMS agent management component and does not require business-level collection
`exclude_instrument[].k8s_namespace: arms-prom`	Excludes ARMS Prometheus-related components	Excluded	Platform collection components; excluding them reduces self-collection overhead

You can extend the exclusion list based on your environment. For example, add kube-system or other platform namespaces.

Use exclude_instrument (blocklist) when most namespaces need collection and only a few should be excluded. To collect only specific business namespaces, use a discovery.instrument allowlist instead.

Attribute configuration

attributes controls which attributes to attach to collected metrics and traces, and which attributes to retain in traces. This example enables Kubernetes metadata association and explicitly retains all GenAI semantic attributes in traces.

Field	Purpose	Value	Notes
`kubernetes.enable`	Associates Kubernetes metadata (Pod, namespace, workload, node, and others) with data	`true`	(Recommended) Enable in ACK environments for Kubernetes dimension-based queries and drill-downs
`select.traces.include: gen_ai.*`	Attribute allowlist for traces. `gen_ai.*` matches all GenAI semantic convention attributes	Retains all `gen_ai.*` attributes	Ensures that LLM call attributes such as provider, model, token, operation, and tool are fully included in traces

gen_ai.* attributes follow OpenTelemetry GenAI semantic conventions and include attributes such as gen_ai.system (provider), gen_ai.request.model (model name), gen_ai.operation.name (operation type, such as chat or embeddings), and gen_ai.tool.name (tool calling name). Retaining these attributes is essential for LLM trace observability.

Route consolidation

routes consolidates HTTP request paths into route templates. This prevents unlimited growth of metric dimensions (cardinality) caused by variable segments such as IDs and UUIDs in paths. Uncontrolled cardinality significantly increases time-series database costs and slows down queries.

Field	Purpose	Value	Options	Notes
`routes.unmatched`	Processing strategy for paths that do not match any route template	`low-cardinality`	`low-cardinality` / `wildcard` / `path` / `heuristic`	`low-cardinality` consolidates unmatched paths into a low-cardinality form to prevent dimension explosion. You can temporarily use `path` during debugging to retain original paths.
`routes.max_path_segment_cardinality`	Maximum number of distinct values allowed for a single path segment. Segments exceeding this threshold are collapsed into a wildcard.	`500`	Positive integer	Higher values retain more detail but increase cardinality. (Recommended) Use a lower threshold for high-variability segments such as IDs.

Protocol parsing

ebpf.payload_extraction controls whether OBI extracts HTTP payloads at the kernel layer and parses application-layer protocol content. When enabled, OBI reconstructs semantic information such as LLM calls and MCP calls from plaintext HTTP messages. This is the foundation for non-intrusive GenAI observability.

Field	Purpose	Value	Options	Notes
`http.jsonrpc.enabled`	Parses HTTP-based JSON-RPC 2.0 protocols	`true`	`true` / `false`	MCP and similar protocols are based on JSON-RPC. Enable to reconstruct method names and call semantics.
`http.genai.*`	Parsing toggles for individual GenAI providers and call types	See the following table	Toggle per provider	Enable only the providers that you actually use to reduce unnecessary parsing overhead.
`buffer_sizes.http`	Kernel buffer size for HTTP payload extraction (bytes)	`262144` (256 KB)	Positive integer (bytes)	LLM request and response bodies can be large. Allocate enough buffer to avoid payload truncation. Larger values increase memory usage.

GenAI provider parsing toggles

The http.genai section provides individual toggles for payload parsing of different LLM providers and call types. The following items are enabled in this example. Enable only the providers that your workloads actually call.

Field	Parsing target	Value	Description
`genai.openai_compatible.enabled`	OpenAI-compatible interfaces	`true`	Covers vLLM, DashScope compatibility mode, local Ollama OpenAI-compatible endpoints, and similar services
`genai.openai.enabled`	OpenAI native API	`true`	Parses OpenAI official API calls
`genai.anthropic.enabled`	Anthropic Claude API	`true`	Parses Claude model calls
`genai.retrieval.enabled`	Retrieval calls (Retrieval / RAG)	`true`	Reconstructs vector retrieval and RAG retrieval stages
`genai.mcp.enabled`	MCP (Model Context Protocol) calls	`true`	Based on JSON-RPC; use together with `jsonrpc.enabled`
`genai.qwen.enabled`	Qwen DashScope native API	`true`	Parses Qwen model calls
`genai.embedding.enabled`	Text embedding calls	`true`	Reconstructs text embedding stages
`genai.gemini.enabled`	Google Gemini API	`true`	Parses Gemini model calls
`genai.rerank.enabled`	Reranking calls	`true`	Reconstructs retrieval result reranking stages

Custom gateways

If you route LLM calls through a self-hosted gateway (such as LiteLLM or vLLM), add a gateways list under openai_compatible to declare the hosts and ports of these gateways. OBI identifies traffic that matches the list and parses it as the corresponding gateway, producing correct GenAI semantic information even on non-official OpenAI-compatible endpoints.

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

Note

host is required. port and provider are optional.

Enabled instrumentation types

The instrumentations list under otel_traces_export determines which protocols and middleware OBI generates traces for. The following types are enabled in this example:

Instrumentation type	Target	Value
`http`	HTTP and HTTPS calls	Enabled
`grpc`	gRPC calls	Enabled
`sql`	SQL database access	Enabled
`redis`	Redis access	Enabled
`kafka`	Kafka messages	Enabled
`mqtt`	MQTT messages	Enabled
`mongo`	MongoDB access	Enabled
`couchbase`	Couchbase access	Enabled
`memcached`	Memcached access	Enabled
`genai`	LLM (GenAI) calls	Enabled

Complete configuration reference

The following is the complete OBI configuration described in this topic. You can copy and use it directly. Before you apply the configuration in production, adjust the exclusion list, GenAI toggles, and export parameters based on your namespaces, providers, and traffic volume.

Complete OBI configuration 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