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 parameter | default | 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. | |
enabled | true | Whether this plugin will be applied. |
config.splunk_access_token
|
Passes required Splunk header |
|
config.method
optional |
|
HTTP Method to send to Splunk |
config.content_type
optional |
|
Defines the Content-Type header to send to Splunk |
config.timeout
optional |
|
The amount of time to wait on a Splunk transaction before timing out |
config.retry_count
optional |
|
The number of attempts to retry logging an event on splunk connection errors |
config.queue_size
optional |
|
The max number of event logs the plugin may send in a single request |
config.flush_timeout
optional |
|
The time taken in seconds before flushing a queue of transactions to splunk that has not reached its max |
config.keepalive
optional |
|
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.