Use your own dashboard
Already have a web dashboard for your bot? You don’t have to send people to a second one. Everything the Shardlens
dashboard shows is an answer from the collector’s API, and @shardlens/client asks for the same answers from your own
backend. The collector keeps doing the collecting, storing and counting; you decide how it looks.
1. Get a read key
Section titled “1. Get a read key”Setting up from scratch, npx shardlens init … --dashboard own turns the Shardlens dashboard off and writes
dashboard.env with the two settings your dashboard’s server needs, SHARDLENS_URL and SHARDLENS_READ_KEY
(Choose your setup).
With a collector that is already running, use SHARDLENS_READ_KEY from its .env, or create another key in the
Shardlens dashboard under Settings → API keys → New read key (shown once). You can keep the Shardlens dashboard
on as well as your own.
A read key can run queries and nothing else: it can’t send events, change settings or see who ran a command.
2. Ask for what you want to show
Section titled “2. Ask for what you want to show”pnpm add @shardlens/clientnpm install @shardlens/clientyarn add @shardlens/clientbun add @shardlens/client@shardlens/client has no dependencies and uses fetch, so it runs in Node.js, Bun, Deno, Cloudflare Workers and
Next.js route handlers.
// Runs on your dashboard's server. A key must never reach a browser.import { createShardlensClient, lastDays } from '@shardlens/client';
const shardlens = createShardlensClient({ endpoint: process.env.SHARDLENS_URL!, // https://stats.example.com apiKey: process.env.SHARDLENS_READ_KEY!, // slk_read_…});
// A route on your own backend, for example GET /api/stats/commands. This is a Web-standard handler, so it works as a// Next.js route handler, in Hono, on Cloudflare Workers and in Bun.export async function GET(): Promise<Response> { const { rows } = await shardlens.commands({ range: lastDays(7) }); return Response.json(rows.slice(0, 10), { headers: { 'cache-control': 'private, max-age=60' } });}
// One server's most used commands, for a per-server page in your dashboard.export function topCommandsIn(guildId: string) { return shardlens.top({ metric: 'interactions', groupBy: 'command', filters: [{ field: 'guild', value: guildId }], range: lastDays(30), limit: 10, });}
// The commands that fail in one server: errors, missed 3-second deadlines and runs that got no response.export function failingCommandsIn(guildId: string) { return shardlens.top({ metric: 'interactions', groupBy: 'command', filters: [ { field: 'guild', value: guildId }, { field: 'outcome', op: 'in', value: ['error', 'timeout', 'no_response'] }, ], range: lastDays(30), limit: 10, });}
// One command in depth, for a per-command page: outcomes, how often it deferred, subcommands, options and the servers// that use it most. It reads single events, which are kept for 35 days unless Settings says otherwise (7 to 90).export function commandDetail(name: string) { return shardlens.command(name, { range: lastDays(30) });}
// Commands per day, ready for any chart library.export function commandsPerDay() { return shardlens.series({ metric: 'interactions', interval: 'day', range: lastDays(30) });}Your front end then calls your own route (/api/stats/commands above) and renders the rows with whatever components
and chart library you already use. Answers are typed, and a failed request throws a ShardlensClientError with the
HTTP status and the collector’s error code.
Not on JavaScript? The client is a thin layer over POST /v1/query with Authorization: Bearer <read key> and a JSON
body, which any language can send: { "kind": "commands", "range": { "from": "…", "to": "…" } }.
Who ran what
Section titled “Who ran what”In audit mode, your own pages can show the activity log too. That takes an activity key
(slk_activity_…) instead of a read key: it reads everything a read key does, and who ran what.
// Runs on your dashboard's server, behind your own sign-in: these answers name people.import { createShardlensClient } from '@shardlens/client';
const shardlens = createShardlensClient({ endpoint: process.env.SHARDLENS_URL!, apiKey: process.env.SHARDLENS_ACTIVITY_KEY!, // slk_activity_…: who ran what, and everything a read key reads});
// The latest failed runs in one server, with who ran each. Pass `nextBefore` back as `before` for the next page.export function failedRunsIn(guildId: string, before?: string | null) { return shardlens.activity.log({ guild: guildId, outcome: 'failed', limit: 50, before });}
// Everything one user ran, newest first: for a support ticket or an abuse report. Exact IDs only.export function runsBy(userId: string) { return shardlens.activity.log({ user: userId });}
// The most active users of the last 7 days, as counts.export function busiestUsers() { return shardlens.activity.topUsers('7d');}npx shardlens init … --dashboard own --identify-users creates one and puts it in dashboard.env; with the
Shardlens dashboard on, create one under Settings → API keys → New activity key. The
guardrails of audit mode apply to a key as they do to a person: every read is written
to the access log under the key’s label, a user is looked up by exact ID only, and nothing groups by user. Put these
routes behind your own sign-in, for your own staff.
What you can ask for
Section titled “What you can ask for”Every query has a kind, and the client has a method named after each (shardlens.overview(),
shardlens.eventProps({ … })), plus shardlens.query({ kind, … }) for any of them. Ranges are ISO timestamps, at
most 400 days apart; lastDays(30) makes one.
kind |
What comes back |
|---|---|
overview |
The app, runs and failures per day for the last 30 days, the server count, unique users this period, and the state of each bot process’s SDK |
commands |
Every command: runs, change on the previous period, failure rate, p95, servers, unique users, and the kinds it ran as (chat_input, message_command, menus) |
command |
One command in depth: runs by outcome (ok, error, missed deadline, no response), how often it deferred or took over 3 s, runs per kind, subcommands, options, channel types, member tiers, languages, top servers, latency |
series |
A metric over time (interval: minute, hour, day, week or month), optionally split with groupBy |
top |
The top values of one dimension: commands, servers, languages, outcomes |
heatmap |
Hour-by-weekday counts in your time zone |
servers, server |
The server list (search, sort, page) and one server’s profile |
growth, audience |
Joins and leaves, retention cohorts, daily and weekly unique users |
reliability |
Response-time percentiles, missed deadlines, errors by Discord code, REST health, shards, memory |
gauge |
One gauge over time: shard.ping_ms, shard.guilds, memory.rss_bytes, eventloop.p99_ms and the others in the metrics list. perShard: true gives a line per shard |
bursts |
Minutes in the last 14 days with several times the usual number of interactions |
premium, installs |
Entitlements by SKU, user installs |
events, eventProps |
Your custom events and their properties |
funnel, retention |
Conversion through steps, and cohort retention |
series and top take filters, so one server’s numbers are a filter on guild away, as in topCommandsIn above.
Add a filter on outcome for the commands that fail there (failingCommandsIn), and ask for command to build a
page per command (commandDetail). The full schema of every query is in the HTTP API reference and at /openapi.json on
your collector.
There is no groupBy: 'user' and no per-user query: that is by design, in every mode.
Linking to Shardlens for the rest
Section titled “Linking to Shardlens for the rest”The pages of the Shardlens dashboard have plain addresses, so yours can link to them instead of rebuilding them:
| Address | Opens |
|---|---|
/commands/<name> |
One command in depth |
/servers/<server ID> |
One server: runs, top and failing commands, install history |
/activity?guild=<server ID>&outcome=failed |
Who ran into a failure in that server (audit mode only) |
/activity?command=<name>&outcome=failed |
Who ran into a failure of that command (audit mode only) |
This needs the Shardlens dashboard on (SHARDLENS_DASHBOARD=on, the default), and the last two need a Discord
sign-in there. outcome is failed, error, timeout, no_response or ok. A user ID is never part of an
address.
What you can split a metric by
Section titled “What you can split a metric by”groupBy and filters take the dimensions the metric keeps. Asking for another one is answered with 400 and
{ "error": "invalid_query" }, with a message that lists the ones you can use.
metric |
Dimensions |
|---|---|
interactions |
kind, command, sub, outcome, context, install, locale, tier |
interactions, with guild in it anywhere |
guild, kind, command, outcome |
components |
kind, custom_id, source, outcome, guild |
interactions.autocomplete |
command, option |
modals.shown, modals.submitted |
command and custom_id; custom_id and outcome |
interactions.errors |
command, error_class |
rest.calls, rest.invalid, rest.ratelimits |
method, route, status; status; scope, route |
guild.joins, guild.leaves, guild.unavailable |
detected |
custom (with name) |
None: use eventProps for an event’s properties |
Rollups are kept in UTC: minutes for 14 days, hours for 13 months, then days. In a time zone that isn’t a whole number of hours from UTC (India, Newfoundland, Nepal, parts of Australia), hourly points start at half past (10:30) and the heatmap’s 10:00 column counts from 10:30 to 11:30. Days older than 13 months are UTC days.
Per-server numbers are kept for fewer dimensions on purpose, so the store doesn’t grow with commands × servers × everything else.
Reading the answers
Section titled “Reading the answers”- Times in a series look like
2026-11-12T14:00:00: the start of the bucket in thetimezoneyou asked for (UTC if you didn’t), with no offset. An hour or day in which nothing happened is left out, not sent as zero. - Intervals have limits.
minuteseries cover at most 2 days and only the last 14;hourseries at most 31 days. - Ranges are read in whole hours. A range that starts at 15:20 is read from 15:00, so “the last hour” always has something in it. Ranges that start more than 13 months back are read in whole days.
- Unique users are recounted every 5 minutes, per UTC day, and “this period” is the current salt period (a month by default). Everything else is at most a minute behind.
- Percentiles (
p50,p95,p99) come from a histogram with fixed buckets, so they read as the upper edge of the bucket they fall in: up to a third above the true value, never below it. - Missed deadlines count both a reply Discord refused as too late and an interaction that got no reply at all.
- HTTP-interaction bots (
@shardlens/http) have no gateway, soservers,growth, shard and REST numbers stay empty for them. Interactions, audience and custom events work the same.
Good manners
Section titled “Good manners”- Cache. Numbers are rolled up once a minute, so caching a response for 60 seconds loses nothing.
- Limits.
/v1/queryallows 600 requests a minute per address and answers429withRetry-Afterpast that./v1/livekeeps up to 10 streams open per address (100 in all) and answers503with{ "error": "busy" }past that: share onelive()between your visitors instead of opening one each. - Replace the key if it ever leaks: put a new one (
npx shardlens keys --scope read) in the collector’s.envasSHARDLENS_READ_KEYand restart the collector. The old one stops working then. With the Shardlens dashboard on, you can instead create a new key in Settings → API keys, deploy it, then revoke the old one, with no gap.
Other ways to get the numbers out
Section titled “Other ways to get the numbers out”- Into Discord: a scheduled report posts a daily or weekly summary to a channel, and alerts tell you when something breaks.
- Into Grafana: the Prometheus and OpenTelemetry exporters send bot-health metrics to the monitoring you already run, with or without a collector.
- Live:
shardlens.live()followsGET /v1/live, a Server-Sent Events stream of interactions per minute, p95 and shard state:for await (const update of shardlens.live({ signal })) { … }.