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
With a database
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"
Without a database
Configure this plugin on a Service by adding this section do your declarative configuration file:
plugins:
- name: kong-splunk-log
service: {service}
config:
splunk_access_token: aaaaaaaa-bbbb-cccc-dddd-ffffffffffff
method: POST
content_type: application/json
timeout: 10000
retry_count: 5
queue_size: 20
flush_timeout: 30
keepalive: 60000
In both cases, {service} is the id or name of the Service that this plugin configuration will target.
Enabling the plugin on a Route
With a database
Configure this plugin on a Route with:
$ curl -X POST http://kong:8001/routes/{route}/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"
Without a database
Configure this plugin on a Route by adding this section do your declarative configuration file:
plugins:
- name: kong-splunk-log
route: {route}
config:
splunk_access_token: aaaaaaaa-bbbb-cccc-dddd-ffffffffffff
method: POST
content_type: application/json
timeout: 10000
retry_count: 5
queue_size: 20
flush_timeout: 30
keepalive: 60000
In both cases, {route} is the id or name of the Route that this plugin configuration will target.
Global plugins
- Using a database, all plugins can be configured using the
http://kong:8001/plugins/endpoint. - Without a database, all plugins can be configured via the
plugins:entry on the declarative configuration file.
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 parameter | description |
|---|---|
name | The name of the plugin to use, in this case kong-splunk-log |
service_id | The id of the Service which this plugin will target. |
route_id | The id of the Route which this plugin will target. |
enableddefault value: true | Whether this plugin will be applied. |
config.splunk_access_token
|
Passes required Splunk header |
config.method
optional default value:
|
HTTP Method to send to Splunk |
config.content_type
optional default value:
|
Defines the Content-Type header to send to Splunk |
config.timeout
optional default value:
|
The amount of time to wait on a Splunk transaction before timing out |
config.retry_count
optional default value:
|
The number of attempts to retry logging an event on splunk connection errors |
config.queue_size
optional default value:
|
The max number of event logs the plugin may send in a single request |
config.flush_timeout
optional default value:
|
The time taken in seconds before flushing a queue of transactions to splunk that has not reached its max |
config.keepalive
optional default value:
|
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
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
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
Feel free to open issues, or refer to our Contribution Guidelines if you have any questions.