Skip to content

Exporter only

If you already run Prometheus or an OpenTelemetry pipeline, Shardlens can send its bot-health metrics there. You can use an exporter instead of a collector (leave out endpoint and apiKey) or as well as one.

pnpm add @shardlens/discordjs @shardlens/exporter-prometheus prom-client
bot.ts
import { createShardlens } from '@shardlens/discordjs';
import { prometheusExporter } from '@shardlens/exporter-prometheus';
import { Client, GatewayIntentBits } from 'discord.js';
const client = new Client({ intents: [GatewayIntentBits.Guilds] });
const prometheus = prometheusExporter();
createShardlens(client, { exporters: [prometheus] }); // no endpoint or apiKey: exporter only
// GET http://127.0.0.1:9464/metrics. Under a ShardingManager, shard 1's process serves on 9465, and so on.
await prometheus.serve({ port: 9464 + (client.shard?.ids[0] ?? 0) });
await client.login(process.env.DISCORD_TOKEN);

Then add the bot as a scrape target:

prometheus.yml
scrape_configs:
- job_name: discord-bot
static_configs:
- targets: ['127.0.0.1:9464']
  • serve() listens on 127.0.0.1. When Prometheus runs in another container or on another machine, pass host: '0.0.0.0' and keep the port off the public internet (a firewall, or a private Docker network).
  • serve() never throws into your bot. If the port is taken, it logs a warning and tries again every 10 seconds, so a restart that overlaps with the old process still ends up serving.
  • Each process has its own metrics. With discord.js’s ShardingManager the snippet gives each shard process its own port (9464, 9465…); with discord-hybrid-sharding use 9464 + ClusterClient.getInfo().CLUSTER. Scrape every port: the dashboard adds them up.

If your bot already serves /metrics, register Shardlens’s metrics on your own registry instead:

metrics.ts
import { prometheusExporter } from '@shardlens/exporter-prometheus';
import { collectDefaultMetrics, Registry } from 'prom-client';
// Already serving your own /metrics? Put Shardlens's metrics on your registry instead of starting a server.
export const registry = new Registry();
collectDefaultMetrics({ register: registry });
export const prometheus = prometheusExporter({ registry });

Both exporters register the same instruments, from one shared definition in @shardlens/core. OpenTelemetry instruments have UCUM units (s, By, and {interaction}, {server} and so on for counts), which Prometheus translators turn into the Prometheus names.

PrometheusOpenTelemetryTypeLabelsDescription
shardlens_interactions_totalshardlens.interactionscounterkind, command, outcomeInteractions handled (commands, context menus, components, modals, autocomplete) and message (prefix) commands, by outcome.
shardlens_interaction_response_secondsshardlens.interaction_responsehistogramkind, commandTime from Discord's interaction timestamp to the first response. Discord's deadline is 3 seconds.
shardlens_interaction_handler_secondsshardlens.interaction_handlerhistogramkind, commandTime spent in a handler wrapped with lens.wrap(), or reported for a message command.
shardlens_interaction_errors_totalshardlens.interaction_errorscountercommand, error_classErrors thrown by wrapped handlers, by error class (never the message).
shardlens_rest_requests_totalshardlens.rest_requestscountermethod, route, statusREST requests to Discord, by method, bucketed route and status.
shardlens_rest_invalid_requests_totalshardlens.rest_invalid_requestscounterstatusResponses that count towards Discord's invalid-request limit (10,000 per 10 minutes per IP).
shardlens_ratelimits_totalshardlens.ratelimitscounterscopeRequests held back for a rate limit, by scope (user, global or shared).
shardlens_shard_events_totalshardlens.shard_eventscountershard, stateShard state changes (ready, resumed, reconnecting, disconnected, error, invalidated).
shardlens_guild_events_totalshardlens.guild_eventscountereventServers joined and left, and outages (unavailable, available).
shardlens_custom_events_totalshardlens.custom_eventscounternameCustom events recorded with track(), by name.
shardlens_entitlements_totalshardlens.entitlementscounteractionEntitlement changes (create, update, delete).
shardlens_shard_ping_secondsshardlens.shard_pinggaugeshardGateway heartbeat latency per shard.
shardlens_guildsshardlens.guildsgaugeshardServers per shard.
shardlens_eventloop_delay_p99_secondsshardlens.eventloop_delay_p99gauge—Event loop delay, 99th percentile over the last 30 seconds.
shardlens_memory_bytesshardlens.memorygaugetypeProcess memory (rss, heap_used).
shardlens_cache_sizeshardlens.cache_sizegaugecachediscord.js cache sizes (users, channels).
shardlens_identify_remainingshardlens.identify_remaininggauge—Gateway sessions left in Discord's daily identify budget.

Gauges appear once they have a value: process gauges after 30 seconds, ping once a shard has had a heartbeat, the identify budget on the process that runs shard 0.

  • No user or server labels. Exporters see events before hashing, with user fields blanked and audit-mode identities removed, and no metric is labelled by user or server ID. That keeps your metrics anonymous and their cardinality bounded.
  • Labels are command names, bucketed REST routes (/channels/:id/messages), statuses, shard numbers and the custom event names you chose. Custom IDs of buttons, menus and modals are never a label: components count under the command that sent their message.
  • A label that would take more than 1,000 values in one metric, such as custom event names built from IDs, counts the rest as (other) in the Prometheus exporter. OpenTelemetry SDKs have their own limit (2,000 attribute sets per metric by default).
  • Counts are exact: exporters see every event before any sampleRate sampling.

Exporters cover bot health. Product analytics (unique users, retention, servers, growth, audience) need the collector, because they depend on salted user hashes and long-term storage.