For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

OpenTelemetry

Integrate agentgateway with OpenTelemetry for distributed tracing and observability

Agentgateway natively supports OpenTelemetry (OTLP) for distributed tracing. You can also enable structured logging for request details. For metrics, agentgateway exposes a Prometheus-compatible /metrics endpoint. For more information, see Prometheus metrics.

Configuration

Enable OpenTelemetry tracing in your agentgateway configuration.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
frontendPolicies:
  tracing:
    otlpEndpoint: http://localhost:4317
    randomSampling: true

Configuration options

Sampling strategies

In development, set randomSampling: true to capture every trace. In production, sampling every request adds overhead, so sample a percentage of requests instead by setting randomSampling to a ratio between 0 and 1. For example, the following configuration samples 10% of requests.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
frontendPolicies:
  tracing:
    otlpEndpoint: http://localhost:4317
    randomSampling: "0.1"

With Jaeger

Run Jaeger with OTLP support.

docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:latest

Configure agentgateway.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
frontendPolicies:
  tracing:
    otlpEndpoint: http://localhost:4317
    randomSampling: true

binds:
- port: 3000
  listeners:
  - routes:
    - backends:
      - mcp:
          targets:
          - name: my-server
            stdio:
              cmd: npx
              args: ["@modelcontextprotocol/server-everything"]

View traces at http://localhost:16686.

With OpenTelemetry Collector

For production deployments, use the OpenTelemetry Collector:

The following example exports traces to Jaeger via OTLP. Replace the otlp/jaeger endpoint with any OTLP-compatible backend.

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch:

exporters:
  otlp/jaeger:
    endpoint: jaeger:4317
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/jaeger]

Trace attributes

Agentgateway includes the following attributes in traces. The list below is representative; attributes might vary by deployment mode and request type.

Core attributes

• gateway - Gateway name
• listener - Listener name
• route - Route name
• endpoint - Backend endpoint
• src.addr - Source address
• http.method - HTTP request method
• http.host - Request host
• http.path - Request path
• http.status - Response status code (integer)
• http.version - HTTP version (e.g., HTTP/1.1)
• trace.id - Trace ID
• span.id - Span ID
• protocol - Protocol type (e.g., http, mcp)
• duration - Request duration
• url.scheme - URL scheme
• network.protocol.version - Network protocol version

For MCP-specific attributes such as mcp.method.name and mcp.session.id, see MCP Observability.

For LLM-specific attributes such as gen_ai.operation.name and gen_ai.request.model, see LLM Observability.

Learn more