Skip to content
Latest (currently 2026.10.2) has the newest features, bug fixes, and CVE patches of Solo Enterprise for agentgateway.

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

View and customize access logs

Page as Markdown

Configure per-request structured access logs with CEL-based filtering and field enrichment.

Agentgateway writes a structured access log line to stdout for every request it processes. Access logs are separate from debug/system logs, which control agentgateway’s own operational output.

Access log format

By default, access logs are written in a structured key=value format as shown in the following example.

2025-12-12T21:56:02.809082Z	info	request gateway=agentgateway listener=http route=openai endpoint=api.openai.com:443
src.addr=127.0.0.1:60862 http.method=POST http.host=localhost http.path=/openai http.version=HTTP/1.1
http.status=200 protocol=llm gen_ai.operation.name=chat gen_ai.provider.name=openai
gen_ai.request.model=gpt-4o gen_ai.response.model=gpt-4o-2024-08-06
gen_ai.usage.input_tokens=68 gen_ai.usage.output_tokens=298 duration=2488ms

For LLM traffic, the log line automatically includes gen_ai.* fields. For MCP traffic, it includes mcp.* fields.

View access logs

Access logs are written to stdout automatically for every request that passes through the gateway proxy. No policy configuration is required to enable them.

  1. Send a request to the httpbin app on the www.example.com domain.

    curl -i http://$INGRESS_GW_ADDRESS:80/get -H "host: www.example.com"
    curl -i localhost:8080/get -H "host: www.example.com"
  2. Check the gateway logs to see the access log entry for the request.

    kubectl -n agentgateway-system logs deployments/agentgateway-proxy | tail -1

    Example output:

    info	request gateway=agentgateway-system/agentgateway-proxy
    listener=http route=httpbin/httpbin endpoint=10.244.0.4:8080
    src.addr=127.0.0.1:46886 http.method=GET http.host=www.example.com
    http.path=/get http.version=HTTP/1.1 http.status=200
    protocol=http duration=0ms
    

To filter which requests are logged or customize log fields, see Filter access logs and Add and remove log fields.

Tip

The enterprise observability stack can also export access logs to ClickHouse, where you can query them directly. For setup instructions and customization options such as filtering and adding custom fields to exported records, see Export access logs.

Filter requests

Use the filter field in your EnterpriseAgentgatewayPolicy to write a CEL expression that controls which requests are logged. Only requests where the expression evaluates to true are logged.

  1. Update the EnterpriseAgentgatewayPolicy resource with your access log policy. The following example logs only requests with a response code of 400 or greater.

    kubectl apply -f- <<EOF
    apiVersion: enterpriseagentgateway.solo.io/v1alpha1
    kind: EnterpriseAgentgatewayPolicy
    metadata:
      name: access-logs
      namespace: agentgateway-system
    spec:
      targetRefs:
      - group: gateway.networking.k8s.io
        kind: Gateway
        name: agentgateway-proxy
      frontend:
        accessLog:
          filter: 'response.code >= 400'
    EOF
  2. Send a request that returns a 400 response code.

    curl -i http://$INGRESS_GW_ADDRESS:80/status/400 -H "host: www.example.com"
    curl -i localhost:8080/status/400 -H "host: www.example.com"
  3. Check the gateway logs and verify that an access log entry was written for the 400 request.

    kubectl -n agentgateway-system logs deployments/agentgateway-proxy | tail -1

    Example output:

    info	request gateway=agentgateway-system/agentgateway-proxy
    listener=http route=httpbin/httpbin endpoint=10.244.0.4:8080
    src.addr=127.0.0.1:46886 http.method=GET http.host=www.example.com
    http.path=/status/400 http.version=HTTP/1.1 http.status=400
    protocol=http duration=0ms
    
  4. Send a successful request.

    curl -i http://$INGRESS_GW_ADDRESS:80/get -H "host: www.example.com"
    curl -i localhost:8080/get -H "host: www.example.com"
  5. Check the logs again and verify that no new entry appears. Because the response code was 200, the filter expression response.code >= 400 does not match and no log is written.

    kubectl -n agentgateway-system logs deployments/agentgateway-proxy | tail -1

    Example output (the last entry is still the 400 request from step 2):

    info	request gateway=agentgateway-system/agentgateway-proxy
    listener=http route=httpbin/httpbin endpoint=10.244.0.4:8080
    src.addr=127.0.0.1:46886 http.method=GET http.host=www.example.com
    http.path=/status/400 http.version=HTTP/1.1 http.status=400
    protocol=http duration=0ms
    

Add or remove log fields

You can add custom fields to every access log line by using CEL expressions that are evaluated against the request and response context. You can also remove default fields that you do not need.

  1. Create an EnterpriseAgentgatewayPolicy resource that adds custom attributes and removes a default field. The following example adds 2 fields to every access log entry:

    • user_id: Extracts the value of the x-user-id request header.
    • env: Adds a static string of production.

    The example also removes the http.host default field.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    
    kubectl apply -f- <<EOF
    apiVersion: enterpriseagentgateway.solo.io/v1alpha1
    kind: EnterpriseAgentgatewayPolicy
    metadata:
      name: access-logs
      namespace: agentgateway-system
    spec:
      targetRefs:
      - group: gateway.networking.k8s.io
        kind: Gateway
        name: agentgateway-proxy
      frontend:
        accessLog:
          attributes:
            add:
            - name: user_id
              expression: 'request.headers["x-user-id"]'
            - name: env
              expression: '"production"'
            remove:
            - http.host
    EOF
  2. Send a request with an x-user-id header.

    curl -i http://$INGRESS_GW_ADDRESS:80/get -H "host: www.example.com" -H "x-user-id: user-123"
    curl -i localhost:8080/get -H "host: www.example.com" -H "x-user-id: user-123"
  3. Check the gateway logs and verify you can see the custom fields in your log entry, and that the http.host field is absent.

    kubectl -n agentgateway-system logs deployments/agentgateway-proxy | tail -1

    Example output:

    info	request gateway=agentgateway-system/agentgateway-proxy
    listener=http route=httpbin/httpbin endpoint=10.244.0.4:8080
    src.addr=127.0.0.1:46886 http.method=GET http.path=/get
    http.version=HTTP/1.1 http.status=200 protocol=http duration=0ms
    user_id="user-123" env="production"