Monitoring quota consumption
Last updated: 3 minutes read.
Tyk provides the ability to actively monitor both user and organisation quotas, using a dedicated webhook to notify your stakeholders, your system stack or the requesting API client when certain thresholds have been reached for a token.
Unlike API event webhooks the quota monitor is configured at the Gateway level.
Note
Advanced quota threshold monitoring is currently only supported by Tyk Classic APIs.
Configuring the quota consumption monitor
To enable advanced quota monitoring you will need to add a new monitor
section to your Tyk Gateway configuration file (tyk.conf
).
This has the following fields:
enable_trigger_monitors
: set totrue
to have the monitors start to measure quota thresholdsconfiguration
: a webhook configuration objectglobal_trigger_limit
: this is a percentage of the quota that the key must consume for the webhook to be firedmonitor_user_keys
: set totrue
to monitor individual tokens (this may result in a large number of triggers as it scales with the number of user tokens that are issued)monitor_org_keys
: set totrue
to monitor Organisation quotas
For example:
{
"monitor": {
"enable_trigger_monitors": true,
"configuration": {
"method": "POST",
"target_path": "http://posttestserver.com/post.php?dir=tyk-monitor-drop",
"template_path": "templates/monitor_template.json",
"header_map": {"x-tyk-monitor-secret": "12345"},
"event_timeout": 10
},
"global_trigger_limit": 80.0,
"monitor_user_keys": false,
"monitor_org_keys": true
}
}
With this configuration, a monitor is configured to issue a request to POST http://posttestserver.com/post.php?dir=tyk-monitor-drop
when 80% of the API-level quota has been consumed. This request will have the x-tyk-monitor-secret
header (set to a value of 12345
) and will provide the content of the template file found at templates/monitor_template.json
in the request body. A minimum of 10 seconds will elapse between successive monitor webhooks being fired.
Note
If you are using our Classic Developer Portal, developers registered in the portal will also receive emails about quota threshold limits being reached.
Setting advanced thresholds
The default quota consumption monitor will be triggered at the same level of quota usage for all users. Sometimes you might want to have a more granular approach with different triggering thresholds per user or organisation. Sometimes you might want to fire the event at multiple thresholds, for example when the user hits 50%, 75% and 90% of their allowed quota.
You can set user specific trigger levels for a user by additionally adding a monitor
section to the access key (Session Object). This has one field, which is an array of trigger_limits
(thresholds) that must be in descending order and represent the percentage of the quota that must be reached in order for the trigger to be fired, for example:
"monitor": {
"trigger_limits": [90.0, 75.0, 50.0]
}
If this is included in the session object, then the quota threshold event will be fired and the monitor webhook triggered when the user hits 50%, then 75%, and then again at 90% consumption.
You can configure advanced thresholds for all users in an Organisation by adding the monitor
section to the Organisation session object.
Webhook payload
When the quota consumption monitor is fired, the webhook request that is issued will have the following payload:
{
"event": "TriggerExceeded",
"message": "Quota trigger reached",
"org": "53ac07777cbb8c2d53000002",
"key": "",
"trigger_limit": "80",
}
trigger_limit
will indicate which threshold has been reached (as defined in the session object’smonitor
section).org
will contain the OrgID for the user or organisation that triggered the eventkey
will contain the raw API key used in the request only if the event was triggered by a user quota
Note: if the webhook was triggered by an organisation threshold, key
will be blank.
Warning
When the monitor is triggered by a user hitting their quota threshold, the raw API key is provided in the webhook payload. It is important to secure the webhook endpoint and to handle the payload securely on the receiving end.