Choose your setup
The SDK in your bot is the same in every setup: it sends events to a collector, which stores and counts them. What you choose is where you look at the numbers. You can change your mind later without losing anything.
| You want | Set it up with | You read the numbers |
|---|---|---|
| The Shardlens dashboard | npx shardlens init … |
At your collector’s address, in a browser |
| A dashboard you already have | npx shardlens init … --dashboard own |
In your own pages, through @shardlens/client |
| No dashboard | npx shardlens init … --dashboard none |
From scripts, in Discord, in your own database or in Grafana |
| No collector at all | Nothing to run | In Prometheus or OpenTelemetry only (exporter only) |
… stands for --domain stats.example.com --app-id 123456789012345678, as in the quick start.
The Shardlens dashboard
Section titled “The Shardlens dashboard”The default. The collector serves the dashboard at its own address: follow the quick start.
A dashboard you already have
Section titled “A dashboard you already have”The collector runs as an API only, and your dashboard’s server asks it for what your pages show.
npx shardlens init --domain stats.example.com --app-id 123456789012345678 --dashboard ownBesides the collector’s files, this writes dashboard.env: the collector’s address and a read key, for your
dashboard’s server. There, install @shardlens/client and ask for any number the Shardlens dashboard would show:
Use your own dashboard has the code.
To show who ran what in your own pages, add --identify-users. It turns on
audit mode in the collector and adds an activity key to dashboard.env, which reads the
activity log the way a Discord sign-in does in the Shardlens dashboard. Audit mode is two-sided: give your bot’s
createShardlens mode: 'audit' as well, or it keeps sending hashed users and the log stays empty.
No dashboard
Section titled “No dashboard”The collector still stores and counts everything; there is no page to open.
npx shardlens init --domain stats.example.com --app-id 123456789012345678 --dashboard noneYou can still get at every number:
-
From a script, with
@shardlens/client, the read key in.envand the collector’s address (SHARDLENS_PUBLIC_URLin.env) asSHARDLENS_URL:this-week.ts // Run by hand or on a schedule: this week's commands, without a dashboard.import { createShardlensClient, lastDays } from '@shardlens/client';const shardlens = createShardlensClient({endpoint: process.env.SHARDLENS_URL!, // https://stats.example.comapiKey: process.env.SHARDLENS_READ_KEY!, // slk_read_…});const { rows } = await shardlens.commands({ range: lastDays(7) });for (const row of rows.slice(0, 10)) {console.log(`${row.command}: ${row.runs} runs, p95 ${row.p95Ms === null ? '?' : Math.round(row.p95Ms)} ms`);} -
In your own database: set
SHARDLENS_SINK_URLand every event is copied there as it arrives. -
In Grafana: the Prometheus and OpenTelemetry exporters send bot health to the monitoring you already run.
-
In Discord: scheduled reports and alerts post to a channel. They are set up in the Shardlens dashboard, so turn it on for that (below); once set up they keep running with it off.
Inside your bot (embedded mode)
Section titled “Inside your bot (embedded mode)”Embedded mode makes the same choice with one option: dashboard: false starts the
collector without its pages, and collector.readKey is the key @shardlens/client needs.
What the package can read
Section titled “What the package can read”Everything the Shardlens dashboard shows is an answer from the collector’s API, and @shardlens/client asks for the
same answers. Nothing is kept for the dashboard alone.
| Data | Key it needs | In @shardlens/client |
|---|---|---|
| Every chart and table: commands, servers, growth, audience, reliability, premium, custom events, funnels, retention | Read key | One method per query, such as commands(), command(), servers(), reliability() |
| The live tiles (runs per minute, response time, shards) | Read key | live() |
| Who ran what, in audit mode | Activity key | activity.log() and activity.topUsers() |
What stays in the Shardlens dashboard is changing things, which needs a person signed in with Discord: settings, alerts, reports, API keys, erasing a user and the CSV export of the activity log.
Changing your mind
Section titled “Changing your mind”The choice is one line in the collector’s .env:
SHARDLENS_DASHBOARD=on # or offChange it and restart the collector (docker compose up -d), or run init again with --force and the choice you
want: npx shardlens init … --force --dashboard shardlens. Your data, keys and settings stay as they are, and so does
SHARDLENS_MODE if --identify-users wrote it: while it is set, Settings shows the mode but can’t change it, so
remove the line to choose the mode there again.