Kong provides many great logging tools out of the box - this is a modified version of the Kong HTTP logging plugin that has been refactored and tailored to work with Splunk.


Terminology

  • plugin: a plugin executing actions inside Kong before or after a request has been proxied to the upstream API.
  • Service: the Kong entity representing an external upstream API or microservice.
  • Route: the Kong entity representing a way to map downstream requests to upstream services.
  • upstream service: this refers to your own API/service sitting behind Kong, to which client requests are forwarded.

Configuration

Enabling the plugin on a Service

Configure this plugin on a Service by making the following request:

$ curl -X POST http://kong:8001/services/{service}/plugins \
    --data "name=kong-splunk-log"  \
    --data "config.splunk_access_token=aaaaaaaa-bbbb-cccc-dddd-ffffffffffff" \
    --data "config.method=POST" \
    --data "config.content_type=application/json" \
    --data "config.timeout=10000" \
    --data "config.retry_count=5" \
    --data "config.queue_size=20" \
    --data "config.flush_timeout=30" \
    --data "config.keepalive=60000"

  • service: the id or name of the Service that this plugin configuration will target.

Enabling the plugin on a Route

Configure this plugin on a Route with:

$ curl -X POST http://kong:8001/routes/{route_id}/plugins \
    --data "name=kong-splunk-log"  \
    --data "config.splunk_access_token=aaaaaaaa-bbbb-cccc-dddd-ffffffffffff" \
    --data "config.method=POST" \
    --data "config.content_type=application/json" \
    --data "config.timeout=10000" \
    --data "config.retry_count=5" \
    --data "config.queue_size=20" \
    --data "config.flush_timeout=30" \
    --data "config.keepalive=60000"

  • route_id: the id of the Route that this plugin configuration will target.

Global plugins

All plugins can be configured using the http://kong:8001/plugins/ endpoint. A plugin which is not associated to any Service, Route or Consumer (or API, if you are using an older version of Kong) is considered "global", and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

form parameterdefaultdescription
nameThe name of the plugin to use, in this case kong-splunk-log
service_idThe id of the Service which this plugin will target.
route_idThe id of the Route which this plugin will target.
enabledtrueWhether this plugin will be applied.
config.splunk_access_token

Passes required Splunk header Authorization Splunk: aaaaaaaa-bbbb-cccc-dddd-ffffffffffff

config.method
optional

POST

HTTP Method to send to Splunk

config.content_type
optional

application/json

Defines the Content-Type header to send to Splunk

config.timeout
optional

10000

The amount of time to wait on a Splunk transaction before timing out

config.retry_count
optional

5

The number of attempts to retry logging an event on splunk connection errors

config.queue_size
optional

20

The max number of event logs the plugin may send in a single request

config.flush_timeout
optional

30

The time taken in seconds before flushing a queue of transactions to splunk that has not reached its max queue_size

config.keepalive
optional

60000

The amount of time to keep plugin connections with Splunk active

We recommend enabling the Splunk Logging plugin at a global level.

Example Log in Splunk UI

Splunk UI screen shot

Installation

Recommended:

$ luarocks install kong-splunk-log

Other:

$ git clone https://github.com/Optum/kong-splunk-log.git /path/to/kong/plugins/kong-splunk-log
$ cd /path/to/kong/plugins/kong-splunk-log
$ luarocks make *.rockspec

Configuration

The plugin requires an environment variable SPLUNK_HOST. This is how we define the host="" Splunk field in the example log picture embedded above in our README.

Example Plugin Configuration

Splunk Config

If not already set, it can be done so as follows:

$ export SPLUNK_HOST="gateway.company.com"

One last step is to make the environment variable accessible by an nginx worker. To do this, simply add this line to your nginx.conf

env SPLUNK_HOST;

Maintainers

jeremyjpj0916
rsbrisci

Feel free to open issues, or refer to our Contribution Guidelines if you have any questions.