Logging Reference

Log Levels

Log levels are set in Kong’s configuration. Following are the log levels in increasing order of their severity: debug, info, notice, warn, error and crit.

  • debug: It provides debug information about the plugin’s run loop and each individual plugin or other components. This should only be used during debugging, the debug option, if left on for extended periods of time, can result in excess disk space consumption.
  • info/notice: Kong does not make a big difference between both these levels. Provides information about normal behavior most of which can be ignored.
  • warn: To log any abnormal behavior that doesn’t result in dropped transactions but requires further investigation, warn level should be used.
  • error: Used for logging errors that result in a request being dropped (for example getting an HTTP 500 error). The rate of such logs need to be monitored.
  • crit: This level is used when Kong is working under critical conditions and not working properly thereby affecting several clients. Nginx also provides alert and emerg levels but currently Kong doesn’t make use of these levels making crit the highest severity log level.

notice is the default and recommended log level. However if the logs turn out to be too chatty, they can be bumped up to a higher level like warn.

Log the client request identifier

The X-Kong-Request-Id header contains a unique identifier for each client request. This is enabled by default both upstream and downstream. This unique ID helps in matching specific requests to their corresponding error logs, which is useful for debugging. 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 Kong Gateway error log generated will contain the same request ID, with the format: request_id: xxx.

The log line produced by the debug header as well as the debug response header contains the request ID. You can use this to search for the debug header output using a log viewer UI. This is especially useful 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.

More Information