How to Customize Gateway Logs

With regulations for protecting private data like GDPR, you may need to customize what Kong Gateway is logging. If you use Kong as your API gateway, this can be done in a single location to take effect on all of your services. This guide walks you through one approach to accomplishing this, but there are always different approaches for different needs.

These changes affect the output of the NGINX access logs. This doesn’t have any effect on Kong’s logging plugins.

For this example, let’s say you want to remove any instances of an email address from your Kong logs. The email addresses may come through in different ways, 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.

First, make a copy of Kong Gateway’s NGINX template. This template can be found in the Nginx directives reference or copied from below:

  1. # ---------------------
  2. # custom_nginx.template
  3. # ---------------------
  5. worker_processes $; # can be set by kong.conf
  6. daemon $;                     # can be set by kong.conf
  8. pid pids/nginx.pid;                      # this setting is mandatory
  9. error_log logs/error.log $; # can be set by kong.conf
  11. events {
  12.     use epoll; # custom setting
  13.     multi_accept on;
  14. }
  16. http {
  17.     # include default Kong Nginx config
  18.     include 'nginx-kong.conf';
  20.     # custom server
  21.     server {
  22.         listen 8888;
  23.         server_name custom_server;
  25.         location / {
  26.           ... # etc
  27.         }
  28.     }
  29. }

To control what is placed in the logs, you can use the NGINX map module in the template. This creates a new variable whose value depends on values of one or more of the source variables specified in the first parameter. The format is:

  2. map $parameter_to_look_at $variable_name {
  3.     pattern_to_look_for 0;
  4.     second_pattern_to_look_for 0;
  6.     default 1;
  7. }

For this example, map a new variable called keeplog, which is dependent on values appearing in the $request_uri. Place the map directive at the start of the http block, before include 'nginx-kong.conf';:

  1. map $request_uri $keeplog {
  2.     ~.+\@.+\..+ 0;
  3.     ~/servicename/v2/verify 0;
  4.     ~/v3/verify 0;
  6.     default 1;
  7. }

Notice that each of the lines in the example start with a tilde. This is what tells NGINX to use RegEx when evaluating the line. There are three things to look for in this example:

  • The first line uses 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.

Now, use the log_format module to set 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 simply set everything to the Kong default standards. To see the full list of options, refer to the NGINX core module variables reference.

  1. log_format show_everything '$remote_addr - $remote_user [$time_local] '
  2.     '$request_uri $status $body_bytes_sent '
  3.     '"$http_referer" "$http_user_agent"';

Now, the custom NGINX template is ready to be used. If you have been following along, your file should look like this:

  1. # ---------------------
  2. # custom_nginx.template
  3. # ---------------------
  5. worker_processes $; # can be set by kong.conf
  6. daemon $;                     # can be set by kong.conf
  8. pid pids/nginx.pid;                      # this setting is mandatory
  9. error_log stderr $; # can be set by kong.conf
  13. events {
  14.     use epoll; # custom setting
  15.     multi_accept on;
  16. }
  18. http {
  21.     map $request_uri $keeplog {
  22.         ~.+\@.+\..+ 0;
  23.         ~/v1/invitation/ 0;
  24.         ~/reset/v1/customer/password/token 0;
  25.         ~/v2/verify 0;
  27.         default 1;
  28.     }
  29.     log_format show_everything '$remote_addr - $remote_user [$time_local] '
  30.         '$request_uri $status $body_bytes_sent '
  31.         '"$http_referer" "$http_user_agent"';
  33.     include 'nginx-kong.conf';
  34. }

The last thing you need to do is tell Kong Gateway to use the newly created log, show_everything. To do this, alter the Kong variable proxy_access_log by either editing etc/kong/kong.conf or using the environmental variable KONG_PROXY_ACCESS_LOG. Adjust the default location to the following:

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

Restart Kong Gateway to make all the changes take effect. You can use the kong restart command.

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

You can use this logic to remove anything you want from the logs in a conditional manner.