Kong Plugin for Treblle

treblle-kong

The official Treblle plugin for Kong.

The Kong plugin captures API requests and responses in real time through Kong Gateway and sends them to Treblle for monitoring, security, and analytics.

Terminologies

Plugin: Executes actions within Kong before or after a request is proxied to the upstream API.
Service: Represents an external upstream API or microservice within Kong.
Route: Maps downstream requests to upstream services in Kong.
Consumer: Represents a developer or machine using the API. Consumers interact with Kong, which proxies every call to the upstream API.
Credential: A unique string associated with a Consumer, commonly called an API key.
Upstream Service: Refers to your API or service behind Kong, receiving client requests via Kong.
API: Kong deprecated this entity, which represented upstream services, and replaced it with Services starting from CE 0.13.0 and EE 0.32.

Installation

1. Installing the Treblle Plugin

Clone the treblle-kong repository and copy the source code content to the correct location:

/usr/local/share/lua/5.1/kong/plugins/treblle

git clone https://github.com/Treblle/treblle-kong.git

2. Updating the Plugins List

In kong.conf, append treblle to the plugins field (or custom_plugins in older Kong versions) and ensure the field is not a comment.

plugins = bundled,treblle     # Comma-separated list of plugins this node should load.
                              # By default, only plugins bundled in official distributions
                              # are loaded via the `bundled` keyword.

If kong.conf is missing, create one from the default configuration:

cp /etc/kong/kong.conf.default /etc/kong/kong.conf

3. Starting Kong

Start the Kong server as usual.

Configuration

Enabling the Treblle Plugin Globally

To enable the Treblle plugin globally, create an API in Treblle and obtain the SDK token and API ID from the Treblle dashboard.

Check how to start with the Treblle Platform.

In Kong, a plugin not associated with any specific Service, Route, Consumer, or API (in older versions) is considered “global” and applies to every request.

For more details, refer to the Plugin Reference and Plugin Precedence sections.

curl -i -X POST --url http://localhost:8001/plugins/ \
    --data "name=treblle" \
    --data "config.api_key=<SDK Token>" \
    --data "config.project_id=<API_ID>"

Enabling the Plugin on a Service

To enable the plugin for a specific Service, send the following request to your Kong server:

To configure the plugin on a particular service:

config.api_key – Find your Treblle SDK Token in the Treblle Portal.
config.project_id – Find your Treblle API ID in the Treblle Portal.
service – Use the service ID or name to apply the plugin.

curl -X POST http://kong:8001/services/{service}/plugins \
    --data "name=treblle"  \
    --data "config.api_key=<SDK Token>" \
    --data "config.project_id=<API_ID>"

Enabling the Plugin on a Route

To configure the plugin for a specific route, use the following command.

route_id: The plugin applies to the route with this ID.

curl -X POST http://kong:8001/routes/{route_id}/plugins \
    --data "name=treblle"  \
    --data "config.api_key=<SDK Token>" \
    --data "config.project_id=<API_ID>"

Parameters

The following table outlines the available configuration parameters for the Treblle plugin, including their default values and descriptions:

Parameter	Default (Kong 1.x, 2.x)	Default (Kong 3.x+)	Description
`name`	-	-	The plugin’s name (`treblle`).
`service_id`	-	-	The ID of the service where the plugin is applied.
`route_id`	-	-	The ID of the route where the plugin is applied.
`enabled`	true	true	Specifies whether the plugin is active.
`config.api_key`	-	-	The Treblle SDK token.
`config.project_id`	-	-	The Treblle API ID.
`config.connect_timeout`	1000	1000	Connection timeout in milliseconds.
`config.send_timeout`	5000	5000	Timeout for sending data (in milliseconds).
`config.keepalive`	5000	5000	Duration (in milliseconds) to keep idle connections alive.
`config.request_max_body_size_limit`	100000	100000	Maximum request body size (in bytes).
`config.response_max_body_size_limit`	100000	100000	Maximum response body size (in bytes).
`config.debug`	false	false	Enables or disables debug logs.
`config.enable_compression`	false	false	Enables or disables request compression.
`config.max_retry_count`	1	1	Number of retries for API requests.
`config.retry_interval`	5	5	Interval (in seconds) between retries.
`config.mask_keywords`	-	-	List of keywords to mask in request/response logs.

Masking Sensitive Data

To enable masking of sensitive data, use the following cURL command:

curl -i -X POST http://localhost:8001/plugins/ \
    --data "name=treblle" \
    --data "config.api_key=<SDK Token>" \
    --data "config.project_id=<API_ID>" \
    --data "config.mask_keywords[]=Authorization" \
    --data "config.mask_keywords[]=API_Key"

For more details on masking fields in Treblle, refer to the Masking Fields documentation.

Troubleshooting

Enabling Debug Logs

To enable Treblle debug logs, set --data "config.debug=true" when configuring the plugin.

If you already have Treblle, update the existing plugin configuration instead of installing it again.

Kong does not support multiple instances of the same plugin.

Updating the Plugin with Debug Enabled

Sample Commands:

Create a Service:

curl -X POST http://localhost:8001/services \
--data "name=httpbin-service" \
--data "url=https://httpbin.org"

Create a Route:

curl --location 'http://localhost:8001/services/httpbin-service/routes' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'name=httpbin-route' \
--data-urlencode 'paths%5B%5D=/httpbin' \
--data-urlencode 'methods%5B%5D=POST'

Enable the Plugin with Masking:

curl -i -X POST http://localhost:8001/services/httpbin-service/plugins \
--data "name=treblle" \
--data "config.api_key=<SDK Token>" \
--data "config.project_id=<API_ID>" \
--data "config.mask_keywords[]=Authorization" \
--data "config.mask_keywords[]=API_Key"