Kafka Log Policy

Overview Configuration reference

Log format

Every request is logged separately as a JSON object, separated by a new line \n.

When a request is proxied to an LLM service through an AI Model, the log entry also includes an ai.proxy object with the provider, model, token usage, cost, and latency for that request.

Expand this block to see a sample log object for a proxied LLM request

{
    "workspace": "b4a1e9a2-6b4a-4e91-9c2e-3b6a9d8f1c72",
    "workspace_name": "default",
    "source": "upstream",
    "upstream_uri": "/v1/chat/completions",
    "upstream_status": 200,
    "client_ip": "192.168.65.1",
    "started_at": 1787113201719,
    "tries": [
        {
            "ip": "162.159.140.245",
            "port": 443,
            "hostname": "api.openai.com",
            "balancer_latency": 0,
            "balancer_start": 1787113201722,
            "keepalive": true
        }
    ],
    "request": {
        "id": "9ec9264afbbbad5fe5c64877d92eeb04",
        "uri": "/v1/chat/completions",
        "url": "http://localhost:8000/v1/chat/completions",
        "method": "POST",
        "size": 323,
        "querystring": {},
        "headers": {
            "host": "localhost:8000",
            "user-agent": "curl/8.7.1",
            "content-type": "application/json",
            "content-length": "94",
            "authorization": "REDACTED"
        }
    },
    "response": {
        "status": 200,
        "size": 1845,
        "headers": {
            "content-type": "application/json",
            "content-length": "847",
            "date": "Wed, 19 Aug 2026 04:20:02 GMT",
            "server": "cloudflare",
            "via": "1.1 kong/2.0.2-ai-gateway",
            "x-kong-request-id": "9ec9264afbbbad5fe5c64877d92eeb04",
            "x-kong-proxy-latency": "3",
            "x-kong-upstream-latency": "970",
            "x-kong-llm-model": "openai/gpt-4o",
            "x-ratelimit-remaining-requests": "4999",
            "x-ratelimit-remaining-tokens": "799993",
            "openai-organization": "org-example123456",
            "openai-project": "proj_example7890abcd"
        }
    },
    "latencies": {
        "kong": 3,
        "proxy": 970,
        "request": 976,
        "receive": 3
    },
    "service": {
        "id": "947a4e23-b483-5a65-8165-da9aed24565b",
        "name": "ai-gateway",
        "host": "ai-gateway.upstream.local",
        "port": 80,
        "protocol": "http"
    },
    "route": {
        "id": "8ae36805-da7a-55b9-b056-72bde6bb937d",
        "name": "openai-chat",
        "paths": ["/v1/chat/completions"],
        "methods": ["POST"]
    },
    "ai": {
        "proxy": {
            "tried_targets": [
                {
                    "route_type": "llm/v1/chat",
                    "provider": "openai",
                    "host": "api.openai.com",
                    "port": 443,
                    "upstream_scheme": "https",
                    "upstream_uri": "/v1/chat/completions",
                    "model": "gpt-4o"
                }
            ],
            "meta": {
                "request_mode": "oneshot",
                "provider_name": "openai",
                "request_model": "gpt-4o",
                "response_model": "gpt-4o-2024-08-06",
                "operation_name": "chat",
                "llm_latency": 972,
                "plugin_id": "f3adc007-171c-5519-8763-3a0eef79bde3"
            },
            "usage": {
                "prompt_tokens": 13,
                "completion_tokens": 12,
                "total_tokens": 25,
                "cost": 0,
                "time_per_token": 81,
                "time_to_first_token": 971
            }
        }
    }
}

The following table describes the core objects in the log. For a full breakdown of the ai.* fields shown in the previous example, see AI Gateway logs.

Log item	Description
`service`	Properties of the AI Gateway Service associated with the requested Route.
`route`	Properties of the specific Route requested.
`request`	Properties of the request sent by the client.
`response`	Properties of the response sent to the client.
`latencies`	Latency data for the request.
`tries`	A list of iterations made by the load balancer for this request, including each upstream target that was tried.
`client_ip`	The original client IP address.
`upstream_uri`	The URI, including query parameters, for the configured upstream service.
`consumer`	The authenticated AI Consumer. Only present if authentication is enabled.
`started_at`	The Unix timestamp of when the request started to be processed.
`source`	Indicates whether the response is generated by `kong` or `upstream`.
`upstream_status`	The status code received from the upstream service in the response.
`ai`	Present only for requests proxied to an LLM. Contains provider, model, usage, cost, and cache metrics, keyed by Policy name (for example, `ai.proxy`).

Custom fields by Lua

Use config.custom_fields_by_lua to dynamically modify log fields with Lua code. The field accepts a map of log field names to Lua expressions. Set a field to nil to remove it from the log entry.

Schema registry support

You can integrate the Kafka Log Policy with Confluent Schema Registry for AVRO and JSON schemas.

Schema registries provide a centralized repository for managing and validating schemas for data formats like AVRO and JSON. Integrating with a schema registry allows the Policy to validate and serialize/deserialize messages in a standardized format.

Using a schema registry with AI Gateway provides several benefits:

Data validation: Ensures messages conform to a predefined schema before being processed.
Schema evolution: Manages schema changes and versioning.
Interoperability: Enables seamless communication between different services using standardized data formats.
Reduced overhead: Minimizes the need for custom validation logic in your applications.

To learn more about Kong’s supported schema registry, see:

How schema registry validation works

When a producer Policy is configured with a schema registry, the following workflow occurs:

 
sequenceDiagram
autonumber
    participant Client
    participant Kong as Kafka Log Policy
    participant Registry as Schema Registry
    participant Kafka

    activate Client
    activate Kong
    Client->>Kong: Send request
    deactivate Client
    activate Registry
    Kong->>Registry: Fetch schema from registry
    Registry-->>Kong: Return schema
    deactivate Registry
    Kong->>Kong: Validate message against schema
    Kong->>Kong: Serialize using schema
    activate Kafka
    Kong->>Kafka: Forward to Kafka
    deactivate Kong
    deactivate Kafka

If validation fails, the request is rejected with an error message.

Configure schema registry

To configure Schema Registry with the Kafka Log Policy, use the config.schema_registry parameter for a Policy-wide registry, or config.topics[].schema_registry to override it for an individual topic.

Authentication

The Kafka Log Policy supports the following SASL authentication mechanisms for broker connections through config.authentication.mechanism:

Mechanism	Description
`PLAIN`	Authenticates using a username and password. Set `authentication.strategy` to `sasl` and provide `authentication.user` and `authentication.password`.
`SCRAM-SHA-256`	Authenticates using a username and password with SCRAM-SHA-256 hashing. Set `authentication.strategy` to `sasl` and provide `authentication.user` and `authentication.password`.
`SCRAM-SHA-512`	Authenticates using a username and password with SCRAM-SHA-512 hashing. Set `authentication.strategy` to `sasl` and provide `authentication.user` and `authentication.password`.

Configure TLS for broker connections with config.security.

Example

The following example creates a global Kafka Log Policy that publishes logs for all AI Gateway traffic to the kong-log topic, authenticating to the brokers with SASL/PLAIN:

policy.yaml

Copied!

ai_gateway_policies:
  - ref: kafka-log
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Kafka Log
    name: kafka-log
    type: kafka-log
    enabled: true
    global: true
    config:
      bootstrap_servers:
      - host: broker.internal
        port: 9092
      topic: kong-log
      authentication:
        strategy: sasl
        mechanism: PLAIN
        user: kafka-user
        password: kafka-password
      security:
        ssl: true

Make sure to replace the following placeholders with your own values:

AI_GATEWAY_ID: The id of your AI Gateway.