Monitoring Kong API Gateway

After you install the Instana host agent, the Kong API Gateway sensor is automatically installed. You can view the metrics that are related to Kong API Gateway in the Instana UI after you configure the sensor as outlined in the Configuring section.

Supported information
Configuring
Viewing metrics

Supported information

Supported operating systems

The supported operating systems of the Kong API Gateway sensor are consistent with host agents requirements, which can be checked in the Supported operating systems section of each host agent, such as Supported operating systems for Unix.

Supported versions

Instana agent supports the following Kong API Gateway versions:

Kong Gateway (OSS) 2.6 or later
Kong Gateway 2.6 or later (in Free or Enterprise mode)

Prerequisites

Review the prerequisites before you configure the Kong API Gateway sensor.

Standalone mode

Make sure that the Kong Admin API is accessible from the host where the agent is installed. In the kong.conf file, update the admin_listen parameter as shown in the following example:

admin_listen = 0.0.0.0:8001 reuseport backlog=16384, 0.0.0.0:8444 http2 ssl reuseport backlog=16384

In interface binding, the IP address 127.0.0.1 indicates that the server listens only to the loopback interface. Binding the server to the IP address 0.0.0.0 enables the server to accept traffic from all the available interfaces.

Hybrid mode

Instana supports the hybrid mode architecture of Kong. Hybrid monitoring of the Kong API Gateway is achieved by automatically discovering the Kong process. No entry is necessary in the configuration.yaml file. By default, the control plane port is set to 8001 and the data plane port is set to 8100.

Basic authentication

The Kong Instana sensor supports basic authentication. To configure Kong basic authentication, see the instructions. If the Kong admin API does not require basic authentication, then you can skip this step.

The following configuration is applicable only if the basic authentication is enabled. Otherwise, do not update the configuration and keep it commented.

username: '' # Optional. Only for basic authentication otherwise keep it commented.
password: '' # Optional. Only for basic authentication otherwise keep it commented.
admin_api_route_path: '' # Optional.Only for basic authentication otherwise keep it commented.

Kong-Admin-Token based authentication

Kong-Admin-Token based authentication assumes that Kong is secured with Role-Based Access Control (RBAC) and you created your Kong-Admin-Token. You must create Kong-Admin-Token before you issue admin API calls. To create and update your token in the Kong Enterprise Edition web console, click Profile > Reset Token. Token abc123 is created in the following example: If the Kong admin API does not require Kong-Admin-Token based authentication, then you can skip this step.

The following configuration is applicable only if the Kong-Admin-Token based authentication is enabled. Otherwise, do not update the configuration, and keep it commented.

admin_token: 'abc123' # Optional. Only for Kong-Admin-Token based authentication otherwise keep it commented.

Configuring

The Kong API Gateway sensor supports both local and remote monitoring of Kong.

Local monitoring

Local monitoring of the Kong API Gateway is achieved by automatically discovering the Kong process. You must enable the sensor to start the local monitoring. To enable the sensor, set the enabled parameter to true in the configuration.yaml file. For more information about accessing the admin API in hybrid mode, see Hybrid Mode.

Remote monitoring

To connect to Kong API Gateway, configure the following parameters in the <agent_install_dir>/etc/instana/configuration.yaml agent configuration file:

#Kong API Gateway
com.instana.plugin.kong:
  enabled: false # To enable the sensor, set its value to ‘true’.
  dataset_size: 10 # Maximum number of rows to be fetched as part of the metrics collection related to services or routes.
  disabled_metrics: 'TOTAL_HTTP_REQUESTS,BANDWIDTH_UTILISATION,KONG_LATENCY,UPSTREAM_LATENCY,REQUEST_LATENCY' # Comma-separated list of metrics to be disabled. Remove these metrics to re-enable monitoring. To get the complete list, see Metric Names List.
  status_code_group: '2xx,3xx,4xx,5xx' # Comma-separated list of status codes to be monitored.
  remote: # Multiple remote configurations can be specified.
    - host: '' # Kong Server Host or IP address.
      port: '' # Admin api port (default is 8444). In case of basic authentication, it is a proxy port.
      availabilityZone: '' # default is 'KongAZ'.
      poll_rate: 30 # Poll rate in seconds (minimum 30 seconds).
      protocol: 'https' # Protocol to access Kong Admin API.  Valid values: [‘https’ or ‘http’]. Default: ‘https’.
      username: '' # Optional. Only for basic authentication otherwise leave it commented.
      password: '' # Optional. Only for basic authentication otherwise leave it commented.
      admin_api_route_path: '' # Optional. Only for basic authentication otherwise leave it commented.
      admin_token: '' # Optional. Only for Token based authentication otherwise leave it commented.

To stop monitoring metrics, add metric names as values for the disabled_metrics parameter. Use commas to separate the values. To start monitoring these metrics, remove the metric names from the list. To get the complete list, see Metric Names List.

By default, the maximum number of rows displayed in tables that are related to services or routes is set to 10. You can change this default value by adding the value to the dataset_size parameter.

The following example shows the configuration without basic authentication:

#Kong API Gateway
com.instana.plugin.kong:
  enabled: false # To enable the sensor, set its value to ‘true’.
  dataset_size: 10 # Maximum number of rows to be fetched as part of the metrics collection related to services or routes.
  disabled_metrics: 'TOTAL_HTTP_REQUESTS,BANDWIDTH_UTILISATION,KONG_LATENCY,UPSTREAM_LATENCY,REQUEST_LATENCY' # Comma-separated list of metrics to be disabled. Remove these metrics to re-enable monitoring. To get the complete list, see Metric Names List.
  status_code_group: '2xx,3xx,4xx,5xx' # Comma-separated list of status codes to be monitored.
  remote: # Multiple configurations can be specified
    - host: 'host-1' # Kong Server Host or IP address.
      port: '8444' # Admin api port(default is 8444). In case of basic authentication, it is a proxy port.
      availabilityZone: 'KongAZ-DC1' # default is 'KongAZ'
      poll_rate: 30 # Poll rate in seconds. It can not be less than 30 seconds.
      protocol: 'https' # ['https' or 'http']. Default is 'https'. Protocol to access Kong Admin API.
    - host: 'host-2' # Kong Server Host or IP address.
      port: '8444' # Admin api port(default is 8444). In case of basic authentication, it is a proxy port.
      availabilityZone: 'KongAZ-DC2' # default is 'KongAZ'
      poll_rate: 30 # Poll rate in seconds. It can not be less than 30 seconds.
      protocol: 'https' # ['https' or 'http']. Default is 'https'. Protocol to access Kong Admin API.

The following example shows the configuration with basic authentication enabled:

#Kong API Gateway
com.instana.plugin.kong:
  enabled: false # To enable the sensor, set its value to ‘true’.
  dataset_size: 10 # Maximum number of rows to be fetched as part of the metrics collection related to services or routes.
  disabled_metrics: 'TOTAL_HTTP_REQUESTS,BANDWIDTH_UTILISATION,KONG_LATENCY,UPSTREAM_LATENCY,REQUEST_LATENCY' # Comma-separated list of metrics to be disabled. Remove these metrics to re-enable monitoring. To get the complete list, see Metric Names List.
  status_code_group: '2xx,3xx,4xx,5xx' # Comma-separated list of status codes to be monitored.
  remote: # Multiple configurations can be specified
    - host: 'host-1' # Kong Server Host or IP address.
      port: '8444' # Admin api port(default is 8444). In case of basic authentication, it is a proxy port.
      availabilityZone: 'KongAZ-DC1' # default is 'KongAZ'
      poll_rate: 30 # Poll rate in seconds. It can not be less than 30 seconds.
      protocol: 'https' # ['https' or 'http']. Default is 'https'. Protocol to access Kong Admin API.
      username: 'user-1' # Optional. Only for basic authentication otherwise keep it commented.
      password: 'password-1' # Optional. Only for basic authentication otherwise keep it commented.
      admin_api_route_path: 'admin-api-1' # Optional.Only for basic authentication otherwise keep it commented.
    - host: 'host-2' # Kong Server Host or IP address.
      port: '8444' # Admin api port(default is 8444). In case of basic authentication, it is a proxy port.
      availabilityZone: 'KongAZ-DC2' # default is 'KongAZ'
      poll_rate: 30 # Poll rate in seconds. It can not be less than 30 seconds.
      protocol: 'https' # ['https' or 'http']. Default is 'https'. Protocol to access Kong Admin API.
      username: 'user-2' # Optional. Only for basic authentication otherwise keep it commented.
      password: 'password-2' # Optional. Only for basic authentication otherwise keep it commented.
      admin_api_route_path: 'admin-api-2' # Optional.Only for basic authentication otherwise keep it commented.

Metric names list

Custom provider name	UI table names that are disabled
TOTAL_HTTP_REQUESTS	Top Services by HTTP Requests
BANDWIDTH_UTILISATION	Top Services by Bandwidth Utilization, Bandwidth Across all Services
SHARED_DICTIONARY	Shared Dictionary Allocated Slabs
KONG_LATENCY	Top Services by Kong Latency, Top Routes by Kong Latency, Kong Latency across all Services, Kong Latency across all Routes
UPSTREAM_LATENCY	Top Services by Upstream Latency, Top Routes by Upstream Latency, Upstream Latency across all Services, Upstream Latency across all Routes
REQUEST_LATENCY	Top Services by Request Latency, Top Routes by Request Latency, Request Latency across all Services, Request Latency across all Routes
ALLOCATED_BYTES_WORKER_LUA	Allocated Bytes in Worker Lua VM
NGINX_TOTAL_REQUESTS	Kong NGINX Total Requests
NGINX_CURRENT_CONNECTIONS	Total Connections

Viewing metrics

To view the metrics, complete the following steps:

In the sidebar of the Instana UI, select Infrastructure.
Click a specific monitored host.

You can see a host dashboard with all the collected metrics and monitored processes.

The following metrics are available for each Kong API Gateway server:

Metric	Description	Granularity
Kong Datastore Reachable	Displays the Kong data store connection status. Returns "No" if Kong is unable to connect to the data store, otherwise returns "Yes".	30 seconds
Prometheus Enabled	Displays the Prometheus plugin status. Returns "No" if the plugin is not enabled in Kong, otherwise returns "Yes".	30 seconds
Kong Database	Displays the name of the database that Kong is connected to.	30 seconds
Total Number of Database Entities	Shows the total number of entities in the Kong database.	30 seconds
Kong DB Entity Count Errors	Measures the number of errors that are encountered during the measurement of total number of entities in the Kong database.	30 seconds
Errors in License Information Collection	Displays the total number of errors that are encountered during the collection of license information.	30 seconds
Kong Nginx Metric Errors	Increments the metric errors that are encountered on using the `nginx-lua-prometheus` library. This Lua library is used with Nginx to track metrics and display them on a separate web page to be pulled by Prometheus.	30 seconds
Worker Consistency	Defines whether this node must rebuild its state synchronously or asynchronously. Accepted values are strict and eventual.	30 seconds
Worker State Update Frequency	Defines how often the worker state changes are checked with a background job. The default value is 5 seconds.	30 seconds
Kong Nginx Timers	Presents the total number of NGINX timers in running and pending state.	30 seconds
Total Traffic	Shows the count of all status codes that are grouped by status code class (for example, 2xx, 3xx, 4xx, and 5xx)	30 seconds
Shared Dictionary Allocated Slabs	Presents allocated slabs in bytes in a shared-memory dictionary to store large amounts of data.	30 seconds
Shared Dictionary Memory Utilisation	Presents the total memory consumed by shared dictionaries	30 seconds
Allocated Bytes in Worker Lua VM	Shows the allocated memory in bytes in Worker Lua virtual machine.	30 seconds
Kong Nginx Total Requests	Displays the total number of requests by subsystem like HTTP or stream.	30 seconds
Bandwidth Across all Services	Displays the total Bandwidth (egress or ingress) flowing through Kong in bytes across all Services	30 seconds
Shared Dictionary Allocated Slabs	Presents allocated slabs in bytes in a shared-memory dictionary to store large amounts of data.	30 seconds
Total HTTP Requests	Displays the total number HTTP requests per service per route and per HTTP status code.	30 seconds
Kong Latency per Service and per Route	Displays the latency that is added by Kong and enabled plug-ins for each service and each route.	30 seconds
Request Latency per Service and per Route	Displays the total time taken by Kong to receive a request for a service or route and respond to the client.	30 seconds
Upstream Latency per Service and per Route	Displays the time taken by the upstream service to process a request and send the response back to Kong for a service or route.	30 seconds
Kong Latency across all Services and Routes	Displays the total Kong latency across all services and routes	30 seconds
Request Latency across all Services and Routes	Displays the total Request latency across all services and routes	30 seconds
Upstream Latency across all Services and Routes	Displays the total Upstream latency across all services and routes	30 seconds