Skip to content

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 default. The collector serves the dashboard at its own address: follow the quick start.

The collector runs as an API only, and your dashboard’s server asks it for what your pages show.

Terminal window
npx shardlens init --domain stats.example.com --app-id 123456789012345678 --dashboard own

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

The collector still stores and counts everything; there is no page to open.

Terminal window
npx shardlens init --domain stats.example.com --app-id 123456789012345678 --dashboard none

You can still get at every number:

  • From a script, with @shardlens/client, the read key in .env and the collector’s address (SHARDLENS_PUBLIC_URL in .env) as SHARDLENS_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.com
    apiKey: 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_URL and 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.

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.

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.

The choice is one line in the collector’s .env:

Terminal window
SHARDLENS_DASHBOARD=on # or off

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