Kong Gateway logs

Logging in Kong Gateway allows you to see information, warnings, and errors about requests that are proxied by Kong Gateway.

The information in this reference doc helps you understand and modify Kong Gateway logs. You can also use logging plugins to extend these capabilities by logging additional information or sending logs to another application.

By default, you can view Kong Gateway logs at /usr/local/kong/logs/error.log. If you are running Kong Gateway on Docker, you can also view them from your Docker container.

By default, logs are set to the recommended notice level. If logs are too chatty, you can increase the level to something like warn.

You can change log levels dynamically, without restarting Kong Gateway, using the Admin API or the Konnect API. A dynamic log level change is never persisted to kong.conf. If a node restarts while an override is active, it reverts to the log level set in kong.conf, and the ttl doesn’t carry over.

Alternatively, you can configure log levels using the log_level parameter in the kong.conf file, which will persist. However, this requires you to restart Kong Gateway.

Dynamic log levels for control planes and traditional clusters

Use the following settings and endpoints for log levels in traditional mode and hybrid mode control planes:

Dynamic log levels for data plane nodes v3.16+

In hybrid mode, you can temporarily change the log level of data plane nodes from the control plane. This is a runtime-only, on-demand override for debugging. It doesn’t persist, and it isn’t a substitute for permanent configuration in kong.conf.

Note: Dynamic log levels are supported for data plane nodes running in hybrid mode. DB-less deployments are not supported.

When you create an operation, you specify a log_level, a target (all data plane nodes, or a list of node_ids), and an optional ttl in seconds. The data plane applies the new log level and automatically reverts to the previous level when the ttl expires.

Note: The ttl must be an integer between 10 and 3600 seconds. If you don’t set one, it defaults to 600 seconds (10 minutes). The 10 second minimum exists because data planes poll the control plane for updates every 5 seconds, so the ttl needs to cover at least two poll intervals for the node to reliably apply the change before it expires.

A dynamic log level operation reports one of the following statuses:

To see a data plane’s current effective log level, and the details of any active override, get its node information by sending the following request from a control plane:

curl -X GET "http://localhost:8001/clustering/data-planes" \
     --no-progress-meter --fail-with-body  \
     -H "Accept: application/json"\
     -H "Content-Type: application/json"

curl -X GET "https://us.api.konghq.com/v2/control-planes/$CONTROL_PLANE_ID/nodes" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"

Each node has a log_level field with its current effective level.

Reading the current log level is available to any Control Plane Viewer. You can also use the Debugger to do this directly from the Konnect UI. Creating or changing a dynamic log level operation is a privileged action and requires Control Plane Admin permissions or higher.

The X-Kong-Request-Id header contains a unique identifier for each client request. You can use this header to match specific requests to their corresponding error logs.

If Kong Gateway returns an error by calling the PDK kong.response.error, the request ID will also be included in the response body generated by Kong Gateway. In addition, any generated Kong Gateway error log contains the same request ID with the format request_id: xxx. This can help with debugging because you can search for the header when the debug output is too long to fit in the response header.

This feature can be customized for upstreams and downstreams using the headers and headers_upstream configuration options in kong.conf:

You may need to customize what Kong Gateway logs. For instance, you may want to:

• Protect private information
• Comply with GDPR or other data protection regulations
• Remove instances of a specific piece of data from your logs, such as an email address

These changes can be made to Kong Gateway’s Nginx template and only affect the output of the Nginx access logs. This doesn’t have any effect on Kong Gateway’s logging plugins.

Let’s look at an example where you want to remove any instances of an email address from your Kong Gateway logs. The email addresses may come through in different formats, for example /servicename/v2/verify/alice@example.com or /v3/verify?alice@example.com. To keep all of these formats from being added to the logs, you need to use a custom Nginx template.

Make a copy of Kong Gateway’s Nginx template, then edit it to add or remove the data you need. The following template shows an example configuration for removing email addresses from logs:

# ---------------------
# custom_nginx.template
# ---------------------

worker_processes $; # can be set by kong.conf
daemon $;                     # can be set by kong.conf

pid pids/nginx.pid;                      # this setting is mandatory
error_log stderr $; # can be set by kong.conf



events {
    use epoll; # custom setting
    multi_accept on;
}

http {


    map $request_uri $keeplog {
        ~.+\@.+\..+ 0;
        ~/v1/invitation/ 0;
        ~/reset/v1/customer/password/token 0;
        ~/v2/verify 0;

        default 1;
    }
    log_format show_everything '$remote_addr - $remote_user [$time_local] '
        '$request_uri $status $body_bytes_sent '
        '"$http_referer" "$http_user_agent"';

    include 'nginx-kong.conf';
}

For this example, we’re using the following:

• map $request_uri $keeplog: Maps a new variable called keeplog, which is dependent on values appearing in the $request_uri. Each line in the example starts with a ~ because this is what tells Nginx to use a regex when evaluating the line. This example looks for the following:
  • The first line uses a regex to look for any email address in the x@y.z format
  • The second line looks for any part of the URI that contains /servicename/v2/verify

  • The third line looks at any part of the URI that contains /v3/verify

    Because all of these patterns have a value of something other than 0, if a request has any of those elements, it will not be added to the log.

• log_format: Sets the log format for what Kong Gateway keeps in the logs. The contents of the log can be customized for your needs. For the purpose of this example, you can assign the new logs with the name show_everything and set everything to the Kong Gateway default standards. To see the full list of options, refer to the Nginx core module variables reference.

Once you’ve adjusted the Nginx template for your environment, you need to tell Kong Gateway to use the newly created log, show_everything.

To do this, alter the Kong Gateway variable proxy_access_log by either editing etc/kong/kong.conf or using the environmental variable KONG_PROXY_ACCESS_LOG adjust the default location:

proxy_access_log=logs/access.log show_everything if=$keeplog

Restart Kong Gateway to apply changes with the kong restart command.

Now, any request made with an email address in it will no longer be logged.

Kong Gateway collects logs for the AI Gateway plugins. This allows you to aggregate AI usage analytics across various providers.

Each log entry includes the following details: