Skip to content
2023 API Summit Hackathon: Experiment with AI for APIs (August 28 - September 27) Learn More →
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Kong Gateway Operator
      Manage your Kong deployments on Kubernetes using YAML Manifests
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
  • API Specs
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Gateway
3.2.x
  • Home icon
  • Kong Gateway
  • Production Deployment
  • Logging
  • How to Customize Gateway Logs
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Kong Gateway Operator
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.4.x (latest)
  • 3.3.x
  • 3.2.x
  • 3.1.x
  • 3.0.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • Archive (pre-2.6)
enterprise-switcher-icon Switch to OSS
You are browsing documentation for an outdated version. See the latest documentation here.

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:

# ---------------------
# 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 logs/error.log $; # can be set by kong.conf

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

http {
    # include default Kong Nginx config
    include 'nginx-kong.conf';

    # custom server
    server {
        listen 8888;
        server_name custom_server;

        location / {
          ... # etc
        }
    }
}

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:


map $parameter_to_look_at $variable_name {
    pattern_to_look_for 0;
    second_pattern_to_look_for 0;

    default 1;
}

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';:

map $request_uri $keeplog {
    ~.+\@.+\..+ 0;
    ~/servicename/v2/verify 0;
    ~/v3/verify 0;

    default 1;
}

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.

log_format show_everything '$remote_addr - $remote_user [$time_local] '
    '$request_uri $status $body_bytes_sent '
    '"$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:

# ---------------------
# 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';
}

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:

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.

Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023