Skip to content

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.

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.

pnpm 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.

lib/shardlens.ts
// 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": "…" } }.

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.

lib/shardlens-activity.ts
// 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.

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.

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.

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.

  • Times in a series look like 2026-11-12T14:00:00: the start of the bucket in the timezone you 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. minute series cover at most 2 days and only the last 14; hour series 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, so servers, growth, shard and REST numbers stay empty for them. Interactions, audience and custom events work the same.
  • Cache. Numbers are rolled up once a minute, so caching a response for 60 seconds loses nothing.
  • Limits. /v1/query allows 600 requests a minute per address and answers 429 with Retry-After past that. /v1/live keeps up to 10 streams open per address (100 in all) and answers 503 with { "error": "busy" } past that: share one live() 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 .env as SHARDLENS_READ_KEY and 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.
  • 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() follows GET /v1/live, a Server-Sent Events stream of interactions per minute, p95 and shard state: for await (const update of shardlens.live({ signal })) { … }.