Uptime Tests

Introduction

Tyk Gateway has built-in “uptime awareness” of the upstream services it proxies to, by actively polling user-defined endpoints at set intervals. This isn’t meant to replace traditional uptime monitoring tools; it’s designed to supplement them, letting Tyk Gateway bypass unhealthy upstream hosts as part of its own request routing.

Compatibility

Uptime tests are only available for Tyk Self-Managed users. It is not available on Tyk Cloud.

How Uptime Tests Work

When uptime tests are configured in a Tyk Gateway cluster, a single Gateway elects itself as primary, using a key held in Redis as a dead man’s switch: the primary keeps that key alive, and if it stops or fails, another Gateway detects the gap and elects itself instead. Only the primary Gateway actually runs the uptime tests for the cluster (or shard group, if you’re using poller_group). The primary Gateway runs tests from a worker pool, executing them simultaneously on a configurable interval. Depending on how many uptime tests you’re running, increase or decrease the pool size as needed.

Initial Configuration

Add an uptime_tests section to tyk.conf:

{
  "uptime_tests": {
    "disable": false,
    "poller_group": "",
    "config": {
      "enable_uptime_analytics": true,
      "failure_trigger_sample_size": 3,
      "time_wait": 300,
      "checker_pool_size": 50
    }
  }
}

Field	Description
`disable`	If `true`, disables uptime tests on this Gateway node entirely. Useful if you want to run uptime tests only on a dedicated group of Gateway instances.
`poller_group`	Groups Gateways that share the same set of uptime tests. All Gateways with the same `poller_group` are candidates to become the primary for that group; useful if you’re running uptime tests across a sharded or segmented cluster.
`config.enable_uptime_analytics`	If `true`, records the results of uptime tests so they can be viewed in Tyk Dashboard. Since uptime tests run continuously, this can generate a lot of data; disable it if you don’t need to review results, or see Monitoring Uptime Tests in Tyk Dashboard to manage the volume instead.
`config.failure_trigger_sample_size`	Number of consecutive passes or failures required before Tyk Gateway fires a `HostDown` or `HostUp` event. Higher values protect against false positives, at the cost of a slower reaction time.
`config.time_wait`	Seconds between test runs.
`config.checker_pool_size`	Number of idle workers kept in memory to run tests concurrently.

Configure with the API Definition

Uptime tests are defined per API, so add an uptime_tests section to that API’s definition:

{
  "uptime_tests": {
    "check_list": [
      {
        "url": "http://internal-service.local/"
      },
      {
        "url": "http://internal-service.local/health",
        "method": "POST",
        "headers": {
          "X-Custom-Header": "value"
        },
        "body": "eyJmb28iOiAiYmFyIn0=",
        "timeout": 1000
      }
    ]
  }
}

Uptime tests are not versioned. Each entry in check_list accepts:

Field	Description
`url`	The endpoint to poll. With no other fields set, this is a quick-form GET request.
`method`	HTTP method to use, for a full-form check.
`headers`	Headers to send with the request.
`body`	Request body, base64-encoded.
`timeout`	Request timeout, in milliseconds.

Configure with the Dashboard

To add an uptime test using the Dashboard, make sure you’ve completed the Gateway configuration first, then: Step 1: Select the Uptime Tests tab From the API Designer, select the Uptime Tests tab:

Step 2: Click Add Click Add to add a test:

Step 3: Enter Path Details From the Path Details pop-up, complete the details and click Add to add the test:

Test details form and add button location

Monitoring Uptime Tests in Tyk Dashboard

Everything above already works on its own: Tyk Gateway detects unhealthy upstream hosts, bypasses them, and fires HostUp/HostDown events. But none of that is visible in Tyk Dashboard by default. What this section adds is exactly that visibility: a way to see and review uptime test results yourself, rather than relying solely on those events. To get that visibility, Tyk Dashboard needs the results somewhere it can query them. If config.enable_uptime_analytics is set to true then each time Tyk Gateway runs an uptime test, it generates a log containing: the tested URL, the response time, and either the HTTP status code returned or a flag marking a TCP-level or server-level failure, timestamped and tagged with the API and Organisation it belongs to. This result is written to Redis, under its own key, separate from the regular traffic logs generated for API traffic. Redis is not intended for long time storage so, as with traffic logs, Tyk Pump should be configured to transfer the logs to the persistent storage in the Control Plane, from which they can be accessed by Tyk Dashboard. Which persistent storage you are using, MongoDB or SQL, determines what is stored:

for MongoDB, the Uptime Pump stores each test log as a separate document in the collection
for SQL, the Uptime Pump aggregates the test results per hour, broken down by URL and response code (hit counts, successes, error counts, average response time), prior to storage in the table

Combined vs Distributed Deployments

In a combined control and data plane, this works as described above: Tyk Pump reads from the shared Redis and writes directly to persistent storage. In a distributed deployment, with separate control and data planes connected via Tyk MDCB, uptime test results are handled differently from regular traffic logs and aggregated analytics: they never flow through the Hybrid Pump or Tyk MDCB. Each data plane elects its own primary Gateway and runs its own uptime tests against its own upstream hosts, and results are written only to that data plane’s local Redis. To get this data into Tyk Dashboard, run a Tyk Pump instance directly on each data plane, with an Uptime Pump collecting from that data plane’s local Redis, configured to write to a MongoDB or SQL store that Tyk Dashboard, on the control plane, can also reach. This is the same pattern used for External Data Sink Pumps running on a data plane.

Common Configuration

The Uptime Pump is configured through its own uptime_pump_config object, at the top level of pump.conf, entirely separate from the pumps map used for every other pump type. Unlike those pumps, it doesn’t accept the common pump settings such as filters or timeout: Tyk Pump writes every uptime test result it receives, unconditionally.

{
  "uptime_pump_config": {
    "uptime_type": "mongo"
  },
  "dont_purge_uptime_data": false,
  ...
}

Field	Default	Description
`uptime_type`	`mongo`	`mongo` or `sql`. Determines which of the two sections below applies.
`dont_purge_uptime_data`	`false`	Set to true if no uptime pump is configured.

If dont_purge_uptime_data: false, Tyk Pump tries to start an Uptime Pump on startup regardless of whether you’ve configured a real uptime_pump_config target. It attempts to connect to a persistent store using whatever connection string is present in the uptime_pump_config, empty or otherwise.If that connection fails, Tyk Pump exits immediately, taking down every other pump in that instance too, not just the uptime one.Set dont_purge_uptime_data: true if you’re not using the Uptime Pump.

MongoDB

By default, the Uptime Pump uses the same implementation as the Standard Mongo Pump, storing every individual test result as a separate document in one collection. It accepts the same Common Mongo Meta as every other Mongo pump, plus these fields, identical to the Standard Mongo Pump’s own:

{
  "uptime_pump_config": {
    "collection_name": "tyk_uptime_analytics",
    "mongo_url": "mongodb://tyk-mongo:27017/tyk_analytics",
    "max_insert_batch_size_bytes": 10485760,
    "max_document_size_bytes": 10485760,
    "collection_cap_enable": false,
    "collection_cap_max_size_bytes": 5368709120,
    ...
  }
}

Field	Default	Description
`collection_name`	`tyk_uptime_analytics`	The MongoDB collection uptime results are written to.
`mongo_url`	-	MongoDB connection URL. Required.
`max_insert_batch_size_bytes`	10MB	Maximum size of a single insert batch (in bytes); larger batches are split into multiple inserts.
`max_document_size_bytes`	10MB	Maximum document size (in bytes); documents that would exceed this are skipped rather than written.
`collection_cap_enable`	`false`	If `true`, caps the collection at `collection_cap_max_size_bytes`, turning it into a FIFO buffer. See Analytics Storage Management.
`collection_cap_max_size_bytes`	5GB	Maximum collection size, in bytes, when `collection_cap_enable` is `true`.

Because this collection grows with every uptime test, it should be capped.

SQL

The SQL Uptime Pump generates aggregated data from the uptime test logs, storing them in a table called tyk_uptime_analytics, or one table per day if table_sharding is enabled (see Table Sharding). Set uptime_type to sql in uptime_pump_config to use the SQL Uptime Pump. It accepts the same Common SQL Meta as every other SQL pump.

{
  "uptime_pump_config": {
    "uptime_type": "sql",
    "type": "postgres",
    "connection_string": "host=sql_host port=sql_port user=sql_usr dbname=dbname password=sql_pw",
    "table_sharding": false,
    ...
  }
}

Field	Default	Description
`uptime_type`	`mongo`	Set to `sql` to use the SQL Uptime Pump.
`type`	-	`postgres` or `mysql`.
`connection_string`	-	Database connection string. Required.
`table_sharding`	`false`	If `true`, stores records in one table per day instead of a single table. Must match `storage.uptime.table_sharding` in the Tyk Dashboard configuration below.

Tyk Dashboard Configuration

In the Tyk Dashboard configuration, set storage.uptime to match wherever you’ve configured the Uptime Pump to write, so that results can be viewed under Monitoring > Service Uptime and Monitoring > Uptime Targets in Tyk Dashboard. For MongoDB:

{
  "storage": {
    "uptime": {
      "type": "mongo",
      "mongo_url": "mongodb://username:password@{hostname:port}/{db_name}"
    }
  }
}

For SQL:

{
  "storage": {
    "uptime": {
      "type": "postgres",
      "connection_string": "user=postgres password=topsecretpassword host=tyk-postgres port=5432 database=tyk_analytics",
      "table_sharding": false
    }
  }
}

If you’ve enabled table_sharding on the SQL Uptime Pump, set the matching storage.uptime.table_sharding here too.

Events

When Tyk Gateway detects downtime on a test, it fires a HostDown event; when the host recovers, it fires HostUp. These are ordinary Tyk Events, so you can attach any supported action to them, such as a logger, a webhook, or a custom JavaScript plugin. Since tests run per URL, a single host with multiple endpoints under test can fire several HostDown events at once.

Load Balancing and Service Discovery

If you’re using round-robin load balancing, you can have Tyk Gateway check the outbound request’s host against the uptime test results before routing to it, skipping to the next host in the list if it’s marked down:

{
  "proxy": {
    "check_host_against_uptime_tests": true
  }
}

The host, including port, must exactly match between the uptime test configuration and the load-balanced target list for Tyk Gateway to link the two, for example www.myapi.com:3000.

Getting Started

Deploy Tyk

Design & Create APIs

Secure APIs

Control Traffic

Routing Traffic

Transform Traffic

Observe APIs

Maintain APIs

Platform Administration

Guides

Reference

Developer Support

Introduction

Compatibility

How Uptime Tests Work

Initial Configuration

Configure with the API Definition

Configure with the Dashboard

Monitoring Uptime Tests in Tyk Dashboard

Combined vs Distributed Deployments

Common Configuration

MongoDB

SQL

Tyk Dashboard Configuration

Events

Load Balancing and Service Discovery

​Introduction

​Compatibility

​How Uptime Tests Work

​Initial Configuration

​Configure with the API Definition

​Configure with the Dashboard

​Monitoring Uptime Tests in Tyk Dashboard

​Combined vs Distributed Deployments

​Common Configuration

​MongoDB

​SQL

​Tyk Dashboard Configuration

​Events

​Load Balancing and Service Discovery

Introduction

Compatibility

How Uptime Tests Work

Initial Configuration

Configure with the API Definition

Configure with the Dashboard

Monitoring Uptime Tests in Tyk Dashboard

Combined vs Distributed Deployments

Common Configuration

MongoDB

SQL

Tyk Dashboard Configuration

Events

Load Balancing and Service Discovery