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 v1.5.0 \
  --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. This filter is independent of the top-level filter (frontendPolicies.accessLog.filter), which controls what access logs are written to stdout and stored in the database. Because the two filters are evaluated separately, you can send a different subset of logs to stdout or your database, and to your OTLP backend.

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 and the database, but sends all requests to the OTLP collector.

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

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?