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. Alternatively, you can configure log levels using the log_level parameter in the kong.conf file, but this requires you to restart Kong Gateway.

¹: You can’t change the log level of the Data Plane or DB-less nodes.

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: