Custom metrics and events

Counters, gauges and timings

A counter counts how often something happens: orders, commands, cache misses. The chart shows the total in each period. A gauge is a reading that goes up and down: a queue length, connected users, guilds. The chart shows the average, minimum, maximum or last reading. A timing is a duration in milliseconds, kept as a histogram, so the chart can show the median and the 95th and 99th percentiles as well as the average.

The SDK adds values up in memory and sends one point per series every ten seconds, so calling increment thousands of times a second costs nothing on the network.

Names and tags

Names are lowercase letters, digits, dots and underscores, start with a letter and are at most 100 characters: orders.created, cache.miss, payment.duration. Names starting process., runtime., http., discord., browser. and container. are the ones the SDKs and integrations use.

Tags are up to 8 pairs of short strings. Each distinct name and set of tags is a separate series, and every project has a limit on series, with new ones past it dropped. Tag by something with a handful of values (a plan, a command, a region), never by a user, guild, message or order id. The service and environment are added as tags automatically.

Charting them

On the Metrics tab, pick a metric, how to combine it (sum, average, minimum, maximum, last, or a percentile for timings), optionally a tag to split it by and a tag value to filter on, and a range from the last hour to the last year.

Events

An event is a record of one thing that happened, with a name and a small set of attributes (up to 4 KiB of JSON): a deploy, a sign-up, a server joined. Events are listed newest first on the Events tab, where you can filter by name. A deploy event also draws a marker on the Overview charts, so a change in errors or response times can be lined up with what was released.

monitoring.event("guild.joined", {"members": guild.member_count})

monitoring.event('guild.joined', { members: guild.memberCount });