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-clientnpm install @shardlens/discordjs @shardlens/exporter-prometheus prom-clientimport { 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:
scrape_configs: - job_name: discord-bot static_configs: - targets: ['127.0.0.1:9464']serve()listens on127.0.0.1. When Prometheus runs in another container or on another machine, passhost: '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
ShardingManagerthe snippet gives each shard process its own port (9464, 9465…); with discord-hybrid-sharding use9464 + 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:
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 });pnpm add @shardlens/discordjs @shardlens/exporter-otel @opentelemetry/apinpm install @shardlens/discordjs @shardlens/exporter-otel @opentelemetry/apiimport { createShardlens } from '@shardlens/discordjs';import { openTelemetryExporter } from '@shardlens/exporter-otel';import { Client, GatewayIntentBits } from 'discord.js';
const client = new Client({ intents: [GatewayIntentBits.Guilds] });
// Records through the global MeterProvider your OpenTelemetry SDK registers (OTLP, Prometheus, a vendor…).createShardlens(client, { endpoint: process.env.SHARDLENS_URL, // optional: keep sending to a collector too apiKey: process.env.SHARDLENS_INGEST_KEY, exporters: [openTelemetryExporter()],});
await client.login(process.env.DISCORD_TOKEN);The exporter only uses the OpenTelemetry API. It records through the global MeterProvider (also one your SDK
registers after the exporter was created), or through the meter you pass. If you don’t have an SDK set up yet,
this sends the metrics over OTLP to the address in OTEL_EXPORTER_OTLP_ENDPOINT (default http://localhost:4318):
npm install @opentelemetry/sdk-metrics @opentelemetry/exporter-metrics-otlp-httpimport { metrics } from '@opentelemetry/api';import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';import { MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
const reader = new PeriodicExportingMetricReader({ exporter: new OTLPMetricExporter(), exportIntervalMillis: 15_000 });metrics.setGlobalMeterProvider(new MeterProvider({ readers: [reader] }));An OpenTelemetry Collector that receives it and exposes it to Prometheus:
receivers: otlp: protocols: http: endpoint: 0.0.0.0:4318exporters: prometheus: endpoint: 0.0.0.0:8889service: pipelines: metrics: receivers: [otlp] exporters: [prometheus]Prometheus then scrapes the collector on port 8889. Prometheus 3 can also receive OTLP itself: start it with
--web.enable-otlp-receiver and set OTEL_EXPORTER_OTLP_METRICS_ENDPOINT to
http://prometheus:9090/api/v1/otlp/v1/metrics; the job label is then your service name. Either way the names are
the ones in the table below, so the Grafana dashboard works with either exporter.
What is exported
Section titled “What is exported”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.
| Prometheus | OpenTelemetry | Type | Labels | Description |
|---|---|---|---|---|
shardlens_interactions_total | shardlens.interactions | counter | kind, command, outcome | Interactions handled (commands, context menus, components, modals, autocomplete) and message (prefix) commands, by outcome. |
shardlens_interaction_response_seconds | shardlens.interaction_response | histogram | kind, command | Time from Discord's interaction timestamp to the first response. Discord's deadline is 3 seconds. |
shardlens_interaction_handler_seconds | shardlens.interaction_handler | histogram | kind, command | Time spent in a handler wrapped with lens.wrap(), or reported for a message command. |
shardlens_interaction_errors_total | shardlens.interaction_errors | counter | command, error_class | Errors thrown by wrapped handlers, by error class (never the message). |
shardlens_rest_requests_total | shardlens.rest_requests | counter | method, route, status | REST requests to Discord, by method, bucketed route and status. |
shardlens_rest_invalid_requests_total | shardlens.rest_invalid_requests | counter | status | Responses that count towards Discord's invalid-request limit (10,000 per 10 minutes per IP). |
shardlens_ratelimits_total | shardlens.ratelimits | counter | scope | Requests held back for a rate limit, by scope (user, global or shared). |
shardlens_shard_events_total | shardlens.shard_events | counter | shard, state | Shard state changes (ready, resumed, reconnecting, disconnected, error, invalidated). |
shardlens_guild_events_total | shardlens.guild_events | counter | event | Servers joined and left, and outages (unavailable, available). |
shardlens_custom_events_total | shardlens.custom_events | counter | name | Custom events recorded with track(), by name. |
shardlens_entitlements_total | shardlens.entitlements | counter | action | Entitlement changes (create, update, delete). |
shardlens_shard_ping_seconds | shardlens.shard_ping | gauge | shard | Gateway heartbeat latency per shard. |
shardlens_guilds | shardlens.guilds | gauge | shard | Servers per shard. |
shardlens_eventloop_delay_p99_seconds | shardlens.eventloop_delay_p99 | gauge | — | Event loop delay, 99th percentile over the last 30 seconds. |
shardlens_memory_bytes | shardlens.memory | gauge | type | Process memory (rss, heap_used). |
shardlens_cache_size | shardlens.cache_size | gauge | cache | discord.js cache sizes (users, channels). |
shardlens_identify_remaining | shardlens.identify_remaining | gauge | — | 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.
Privacy and cardinality
Section titled “Privacy and cardinality”- 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
sampleRatesampling.
What you don’t get without a collector
Section titled “What you don’t get without a collector”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.