Export logs over OTLP

Export agentgateway access logs as OTLP LogRecord objects to an OpenTelemetry Collector or any compatible backend.

Log export happens in addition to stdout output, so you can send logs to a collector without losing local visibility.

This guide walks through setting up an OpenTelemetry Collector to receive access logs from agentgateway.

Run the OTel Collector as a Docker container on the same host as agentgateway.

Create an otel-collector-config.yaml file that defines an OTLP receiver and a logs pipeline.

cat > otel-collector-config.yaml << 'EOF'
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch:

exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
EOF

Replace the debug exporter with the exporter for your logging backend (for example, Loki, Elasticsearch, or an OTLP-compatible storage system).

Start the OTel Collector container and mount your config file.

docker run -d --name otel-collector \
  -p 4317:4317 \
  -v $(pwd)/otel-collector-config.yaml:/etc/otelcol/config.yaml \
  otel/opentelemetry-collector:latest

Configure agentgateway to send access logs to the collector.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
frontendPolicies:
  accessLog:
    otlp:
      host: localhost:4317

Send a request through agentgateway, then check the collector output to verify that log records are arriving.
```
docker logs otel-collector
```
Each proxied request appears as a LogRecord entry in the collector output. Look for a block that starts with LogRecord # and includes attributes such as gateway, http.method, http.path, and http.status.
When you are done, remove the OTel Collector container.
```
docker rm -f otel-collector
```

Deploy the OTel Collector into your cluster by using the OpenTelemetry Helm chart and point agentgateway at its service.

Add the OpenTelemetry Helm repository.

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update

Create a values.yaml file that defines the collector pipeline.

mode: deployment
config:
  receivers:
    otlp:
      protocols:
        grpc:
          endpoint: 0.0.0.0:4317
  processors:
    batch:
  exporters:
    debug:
      verbosity: detailed
  service:
    pipelines:
      logs:
        receivers: [otlp]
        processors: [batch]
        exporters: [debug]

Replace the debug exporter with the exporter for your logging backend.

Install the OTel Collector chart.

helm install otel-collector open-telemetry/opentelemetry-collector \
  -n monitoring --create-namespace \
  -f values.yaml

Verify that the collector pod is running.
```
kubectl get pods -n monitoring
```
Update your agentgateway values.yaml to send access logs to the collector service. The chart takes the agentgateway configuration under the top-level config field.
```
config:
  frontendPolicies:
    accessLog:
      otlp:
        host: otel-collector.monitoring.svc.cluster.local:4317
```

Apply the change with a Helm upgrade.

helm upgrade -i agentgateway-standalone \
  oci://cr.agentgateway.dev/charts/agentgateway-standalone \
  --namespace agentgateway-system \
  --version 0.0.0-latest-dev \
  --reuse-values \
  -f values.yaml

Send a request through agentgateway, then check the collector logs to verify that log records are arriving.
```
kubectl logs -n monitoring deployment/otel-collector
```
Each proxied request appears as a LogRecord entry. Look for a block that starts with LogRecord # and includes attributes such as gateway, http.method, http.path, and http.status.

When you are done, remove the OTel Collector and the monitoring namespace.

helm uninstall otel-collector -n monitoring
kubectl delete namespace monitoring

Other configurations

Review other common configurations when exporting access logs to an OTLP-compatible backend.

Filter logs before export

You can filter which access logs are exported to your OTLP backend by setting the accessLog.otlp.filter field. When otlp.filter is not set, the top-level filter (frontendPolicies.accessLog.filter) is used as a fallback for OTLP export as well. When otlp.filter is set, it takes precedence over the top-level filter for OTLP export only, so you can send a different subset of logs to your OTLP backend than to stdout and the database.

The following example sends only error responses to the OTLP collector while logging all requests to stdout.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
frontendPolicies:
  accessLog:
    otlp:
      host: localhost:4317
      filter: 'response.code >= 400'

The following example logs only error responses to stdout, the database, and the OTLP collector. Because no otlp.filter is set, the top-level filter applies to all three backends.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
frontendPolicies:
  accessLog:
    filter: 'response.code >= 400'
    otlp:
      host: localhost:4317

The following example logs only error responses to stdout and the database, but sends all requests to the OTLP collector. To override the top-level filter for OTLP, set otlp.filter explicitly.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
frontendPolicies:
  accessLog:
    filter: 'response.code >= 400'
    otlp:
      host: localhost:4317
      filter: 'true'

Customize exported fields

You can add or remove fields to the log entry that you export to the OTLP endpoint.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
frontendPolicies:
  accessLog:
    otlp:
      host: localhost:4317
      fields:
        add:
          trace_id: 'request.headers["x-trace-id"]'
        remove:
          - http.host

View and customize logs Store logs in a database

Was this page helpful?

Export logs over OTLP

Other configurations

Filter logs before export

Customize exported fields

What could be improved?