Vitals with InfluxDB

    For information about using Kong Vitals with a database as the backend (for example, PostgreSQL, Cassandra), refer to .

    If you already have a Kong Gateway instance, skip to deploying a license.

    If you have not installed Kong Gateway, a Docker installation will work for the purposes of this guide.

    Pull the Kong Gateway Docker image

    1. Pull the following Docker image.

      You should now have your Kong Gateway image locally.

    2. Tag the image.

    1. Create a custom network to allow the containers to discover and communicate with each other.

      1.  docker network create kong-ee-net

    2. Start a PostgreSQL container:

      1.  docker run -d --name kong-ee-database \
      2.    --network=kong-ee-net \
      3.    -p 5432:5432 \
      4.    -e "POSTGRES_USER=kong" \
      5.    -e "POSTGRES_DB=kong" \
      6.    -e "POSTGRES_PASSWORD=kong" \
      7.    postgres:9.6

    3. Prepare the Kong database:

      1. docker run --rm --network=kong-ee-net \
      2.    -e "KONG_DATABASE=postgres" \
      3.    -e "KONG_PG_HOST=kong-ee-database" \
      4.    -e "KONG_PG_PASSWORD=kong" \
      5.    -e "KONG_PASSWORD={PASSWORD}" \
      6.    kong-ee kong migrations bootstrap

    4. Start the gateway with Kong Manager:

      1. docker run -d --name kong-ee --network=kong-ee-net \
      2.    -e "KONG_DATABASE=postgres" \
      3.    -e "KONG_PG_PASSWORD=kong" \
      4.    -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
      5.    -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
      6.    -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
      7.    -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
      8.    -e "KONG_ADMIN_LISTEN=0.0.0.0:8001" \
      9.    -e "KONG_ADMIN_GUI_URL=http://{DNSorIP}:8002" \
      10.    -e "KONG_VITALS_STRATEGY=influxdb" \
      11.    -e "KONG_VITALS_TSDB_ADDRESS=influxdb:8086" \
      12.    -p 8000:8000 \
      13.    -p 8443:8443 \
      14.    -p 8001:8001 \
      15.    -p 8444:8444 \
      16.    -p 8002:8002 \
      17.    -p 8445:8445 \
      18.    -p 8003:8003 \
      19.    -p 8004:8004 \
      20.    kong-ee

    Deploy a Kong Gateway license

    If you already have a Kong Gateway license attached to your Kong Gateway instance, skip to .

    You will not be able to access the Kong Vitals functionality without a valid Kong Gateway license attached to your Kong Gateway instance.

    You can deploy a license file in one of the following ways:

    The recommended method is using the Admin API.

    Prerequisites

    • You have received a license.json file from Kong.
    • Kong Gateway is installed.

    Deploy the license

    Admin API

    Filesystem

    Environment variable (JSON)

    Environment variable (file path)

    You can use the Kong Admin API to distribute the license in any database-backed or hybrid mode deployment. We recommend using this method in most deployments.

    The license data must contain straight quotes to be considered valid JSON (' and ", not ’ or “).

    POST the contents of the provided license.json license to your Kong Gateway instance:

    Note: The following license is only an example. You must use the following format, but provide your own content.

    cURL

    HTTPie

    1. $ curl -i -X POST http://<hostname>:8001/licenses \
    2.   -d payload='{"license":{"payload":{"admin_seats":"1","customer":"Example Company, Inc","dataplanes":"1","license_creation_date":"2017-07-20","license_expiration_date":"2017-07-20","license_key":"00141000017ODj3AAG_a1V41000004wT0OEAU","product_subscription":"Konnect Enterprise","support_plan":"None"},"signature":"6985968131533a967fcc721244a979948b1066967f1e9cd65dbd8eeabe060fc32d894a2945f5e4a03c1cd2198c74e058ac63d28b045c2f1fcec95877bd790e1b","version":"1"}}'

    Result:

    1. {
    2.   "created_at": 1500508800,
    3.   "id": "30b4edb7-0847-4f65-af90-efbed8b0161f",
    4.   "payload": "{\"license\":{\"payload\":{\"admin_seats\":\"1\",\"customer\":\"Example Company, Inc\",\"dataplanes\":\"1\",\"license_creation_date\":\"2017-07-20\",\"license_expiration_date\":\"2017-07-20\",\"license_key\":\"00141000017ODj3AAG_a1V41000004wT0OEAU\",\"product_subscription\":\"Konnect Enterprise\",\"support_plan\":\"None\"},\"signature\":\"6985968131533a967fcc721244a979948b1066967f1e9cd65dbd8eeabe060fc32d894a2945f5e4a03c1cd2198c74e058ac63d28b045c2f1fcec95877bd790e1b\",\"version\":\"1\"}}",
    5.   "updated_at": 1500508800
    6. }

    For more detail and options, see the Admin API licenses endpoint reference.

    You can provide a license file to Kong Gateway in any database-backed or DB-less deployment. This method is not recommended for use in hybrid mode, as you have to maintain the license on each node manually.

    The license data must contain straight quotes to be considered valid JSON (' and ", not ’ or “).

    1. Securely copy the license.json file to your home directory on the filesystem where you have installed Kong Gateway.

      1.  $ scp license.json <system_username>@<server>:~

    2. Then, copy the license file again, this time to the /etc/kong directory:

      1.  $ scp license.json /etc/kong/license.json

      Kong Gateway will look for a valid license in this location.

    You can use the KONG_LICENSE_DATA environment variable to apply a license to Kong Gateway in any database-backed or DB-less deployment. This method is not recommended for use in hybrid mode, as you have to maintain the license on each node manually.

    The license data must contain straight quotes to be considered valid JSON (' and ", not ’ or “).

    1. Export the license key to a variable by running the following command, substituting your own license key.

      Note: The following license is only an example. You must use the following format, but provide your own content.

      1.  $ export KONG_LICENSE_DATA='{"license":{"signature":"LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tClZlcnNpb246IEdudVBHIHYyCgpvd0did012TXdDSFdzMTVuUWw3dHhLK01wOTJTR0tLWVc3UU16WTBTVTVNc2toSVREWk1OTFEzVExJek1MY3dTCjA0ek1UVk1OREEwc2pRM04wOHpNalZKVHpOTE1EWk9TVTFLTXpRMVRVNHpTRXMzTjA0d056VXdUTytKWUdNUTQKR05oWW1VQ21NWEJ4Q3NDc3lMQmorTVBmOFhyWmZkNkNqVnJidmkyLzZ6THhzcitBclZtcFZWdnN1K1NiKzFhbgozcjNCeUxCZzdZOVdFL2FYQXJ0NG5lcmVpa2tZS1ozMlNlbGQvMm5iYkRzcmdlWFQzek1BQUE9PQo9b1VnSgotLS0tLUVORCBQR1AgTUVTU0FHRS0tLS0tCg=","payload":{"customer":"Test Company Inc","license_creation_date":"2017-11-08","product_subscription":"Kong Enterprise","admin_seats":"5","support_plan":"None","license_expiration_date":"2017-11-10","license_key":"00141000017ODj3AAG_a1V41000004wT0OEAU"},"version":1}}'

    2. Include the license as part of the docker run command when starting a Kong Gateway container:

      1.  docker run -d --name kong-gateway \
      2.   ...
      3.   -e KONG_LICENSE_DATA \

    You can use the KONG_LICENSE_PATH environment variable to apply a license to Kong Gateway in any database-backed or DB-less deployment. This method is not recommended for use in hybrid mode, as you have to maintain the license on each node manually.

    Include the license as part of the docker run command when starting a Kong Gateway container. Mount the path to the file on your local filesystem to a directory in the Docker container, making the file visible from the container:

    1. docker run -d --name kong-gateway \
    2.  --network=kong-net \
    3.  ...
    4.  -v "$(pwd)/kong-license/:/kong-license/" \
    5.  -e "KONG_LICENSE_PATH=/kong-license/license.json" \
    6.  kong/kong-gateway:2.6.0.4-alpine

    Production-ready InfluxDB installations should be deployed as a separate effort, but for proof-of-concept testing, running a local InfluxDB instance is possible with Docker:

    You must use InfluxDB 1.8.4-alpine because InfluxDB 2.0 will not work.

    Writing Vitals data to InfluxDB requires that the kong database is created, this is done using the INFLUXDB_DB variable.

    Configure Kong Gateway

    In addition to enabling Kong Vitals, Kong Gateway must be configured to use InfluxDB as the backing strategy for Vitals. The InfluxDB host and port must also be defined:

    1. $ echo "KONG_VITALS_STRATEGY=influxdb KONG_VITALS_TSDB_ADDRESS=influxdb:8086 kong reload exit" \
    2. | docker exec -i kong-ee /bin/sh

    Note: In Hybrid Mode, configure vitals_strategy and on both the control plane and all data planes.

    Kong Vitals records metrics in two InfluxDB measurements:

    1. kong_request: Contains field values for request latencies and HTTP, and tags for various Kong entities associated with the requests (for example, the Route and Service in question).
    2. kong_datastore_cache: Contains points about cache hits and misses.

    To display the measurement schemas on your InfluxDB instance running in Docker:

    1. Open command line in your InfluxDB Docker container.

      1.  $ docker exec -it influxdb /bin/sh

    2. Log in to the InfluxDB CLI.

      1.  $ influx -precision rfc3339

    3. Enter the InfluxQL query for returning a list of tag keys associated with the specified database.

      1.  > SHOW TAG KEYS ON kong

      Example result:

      1.  name: kong_request
      2.  tagKey
      3.  ------
      4.  consumer
      5.  hostname
      6.  route
      7.  service
      8.  status_f
      9.  wid
      10.  workspace
      12.  name: kong_datastore_cache
      13.  tagKey
      14.  ------
      15.  hostname
      16.  wid

    4. Enter the InfluxQL query for returning the field keys and the data type of their field values.

        Example result:

      The tag wid is used to differentiate the unique worker ID per host, to avoid duplicate metrics shipped at the same point in time.

      As demonstrated above, the series cardinality of the kong_request measurement varies based on the cardinality of the Kong cluster configuration - a greater number of Service/Route/Consumer/Workspace combinations handled by Kong results in a greater series cardinality as written by Vitals.

      Consult the InfluxDB sizing guidelines for reference on appropriately sizing an InfluxDB node/cluster.

      Note: The query behavior when reading Vitals data falls under the “moderate” load category as defined by the InfluxDB sizing guidelines. Several GROUP BY statements and functions are used to generate the Vitals API responses, which can require significant CPU resources to execute when hundreds of thousands or millions of data points are present.

      Kong buffers Vitals metrics and writes InfluxDB points in batches to improve throughput in InfluxDB and reduce overhead in the Kong proxy path. Each Kong worker process flushes its buffer of metrics every 5 seconds or 5000 data points, whichever comes first.

      Metrics points are written with microsecond (u) precision. To comply with the , measurement values are read back grouped by second.

      Vitals InfluxDB data points are not downsampled or managed by a retention policy through Kong. InfluxDB operators are encouraged to manually manage the retention policy of the database to reduce the disk space and memory needed to manage Vitals data points.