> ## Documentation Index
> Fetch the complete documentation index at: https://tyk.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Uptime Tests
> How to configure 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`:
```json theme={null}
{
"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](/docs/nightly/#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:
```json theme={null}
{
"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](/docs/nightly/#initial-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:
## 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](/docs/nightly/api-management/dashboard-analytics#what-data-is-captured) generated for API traffic.
Redis is not intended for long time storage so, as with traffic logs, [Tyk Pump](/docs/nightly/api-management/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](/docs/nightly/api-management/logs/external-data-sinks#combined-vs-distributed-deployments) 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](/docs/nightly/api-management/tyk-pump#common-pump-settings) such as `filters` or `timeout`: Tyk Pump writes every uptime test result it receives, unconditionally.
```json theme={null}
{
"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](/docs/nightly/api-management/dashboard-analytics/control-plane-pumps#standard-mongo-pump), storing every individual test result as a separate document in one collection.
It accepts the same [Common Mongo Meta](/docs/nightly/api-management/dashboard-analytics/control-plane-pumps#common-mongo-meta) as every other Mongo pump, plus these fields, identical to the Standard Mongo Pump's own:
```json theme={null}
{
"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](/docs/nightly/api-management/dashboard-analytics/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](/docs/nightly/api-management/dashboard-analytics/analytics-storage-management).
### 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](/docs/nightly/api-management/dashboard-analytics/analytics-storage-management#table-sharding)).
Set `uptime_type` to `sql` in `uptime_pump_config` to use the SQL Uptime Pump. It accepts the same [Common SQL Meta](/docs/nightly/api-management/dashboard-analytics/control-plane-pumps#common-sql-meta) as every other SQL pump.
```json theme={null}
{
"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:
```json theme={null}
{
"storage": {
"uptime": {
"type": "mongo",
"mongo_url": "mongodb://username:password@{hostname:port}/{db_name}"
}
}
}
```
For SQL:
```json theme={null}
{
"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](/docs/nightly/api-management/gateway-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:
```json theme={null}
{
"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`.