Atatus is a powerful observability and performance monitoring platform that seamlessly integrates with Kong Gateway to provide deep API analytics, performance insights, and real-time monitoring.

  • Kong Gateway simplifies API traffic management, security, and scalability, providing a robust framework to handle and route API requests across microservices efficiently.
  • Atatus delivers deep API analytics, offering detailed insights into the performance, health, and reliability of APIs and micro services managed by Kong..

Additionally, it is available as a package on LuaRocks, making it easy to install and integrate directly into your Kong environment.

Note: Before starting the installation, ensure you have a running instance of Kong.

Installation Steps for the Atatus Kong Plugin

If luarocks is installed (typically included in official installation packages), you can add the package to your LuaRocks tree, where Lua modules are stored.

1. Install the Atatus Plugin

copy
icon/buttons/copy 
luarocks install --server=http://luarocks.org/manifests/atatus kong-plugin-atatus

Ensure that the unzip package is installed on your system. If you are using the apt package manager, run:

copy
icon/buttons/copy 
## Optional
apt-get update; apt-get install curl vim unzip

Additionally, ensure that the lua-zlib library dependencies (including git, zlib1g-dev, and gcc) are installed. If using apt, you can install them with:

copy
icon/buttons/copy 
## Optional
apt-get update; apt-get install git zlib1g-dev gcc

2. Update Your Loaded Plugins List

In your kong.conf, append atatus to the plugins field (or custom_plugins if using an older version of Kong). Ensure the field is not commented out.

copy
icon/buttons/copy 
plugins = bundled,atatus

If you don’t have a kong.conf, you can create one from the default configuration by running:

copy
icon/buttons/copy 
cp /etc/kong/kong.conf.default /etc/kong/kong.conf

3. Restart Kong to Apply Changes

After installing the LuaRock package, restart Kong to apply the changes:

copy
icon/buttons/copy 
kong restart

4. Enable the Atatus Plugin

To activate the Atatus plugin, run the following command, replacing YOUR_LICENSE_KEY with your actual Atatus license key:

copy
icon/buttons/copy 
curl -i -X POST --url http://your_kong_domain/plugins/  \
        --data "name=atatus"  \
        --data "config.x_atatus_license_key=YOUR_LICENSE_KEY"

5. Restart Kong Again

If you don't see any analytics data in Atatus after enabling the plugin, try restarting Kong again:

copy
icon/buttons/copy 
kong restart

After this, you should begin seeing logs and analytics for your API traffic in Atatus.

User and Company Identification in Atatus

Atatus automatically identifies API users to help associate API traffic with web traffic, providing insights into user interactions and customer journeys.

To enable user and company tracking, modify the Atatus plugin configuration as follows:

copy
icon/buttons/copy 
curl -i -X POST --url http://your_kong_domain/plugins/ \
  --data "name=atatus" \
  --data "config.x_atatus_license_key=YOUR_LICENSE_KEY" \
  --data "config.user_id_header=X-User-ID" \
  --data "config.company_id_header=X-Company-ID"

Replace YOUR_LICENSE_KEY with your actual Atatus license key. This configuration ensures that Atatus can track users and associate API requests with companies.

Identifying Users

By default, Atatus determines users through various methods:

1. If config.user_id_header is set, Atatus extracts the value from the specified HTTP header.

2. Otherwise, Atatus looks for user identifiers in the following order:

  • x-consumer-custom-id
  • x-consumer-username
  • X-consumer-id

3. If an authorization token is present in config.authorization_header_name, Atatus extracts the user ID as follows:

  • If the header contains Bearer, it decodes the base64 string and retrieves the value specified by config.authorization_user_id_field (default: sub).
  • If the header contains Basic, it decodes the base64 string and extracts the username (before the : character).

For advanced configurations, you can define a custom header for the user ID via config.user_id_header or override config.authorization_header_name and config.authorization_user_id_field.

Identifying Companies

Atatus can track API usage at an account level by associating API users with companies:

1. If config.company_id_header is defined, Atatus will use the value from that header.

2. You can also update user details using the Atatus API to assign a company_id to a user, enabling automatic association of API calls with the corresponding company.

3. If an authorization token is present in config.authorization_header_name, Atatus extracts the company ID as follows:

  • If the header contains Bearer, it decodes the base64 string and retrieves the value specified by config.authorization_company_id_field.