Skip to content

Embedded mode

Embedded mode is for small bots on one host that don’t want to run anything else. The collector, its background jobs and the dashboard run inside your bot process, on an in-process PostgreSQL (PGlite) stored in one folder. It is the same code as the standalone collector, so the dashboard, privacy model and features are the same.

If your bot already has a database (MongoDB, MySQL, MariaDB, PostgreSQL or SQLite), embedded mode can also copy every event into it.

pnpm add @shardlens/discordjs @shardlens/collector @electric-sql/pglite
bot.ts
import { startEmbeddedCollector } from '@shardlens/collector/embedded';
import { createShardlens } from '@shardlens/discordjs';
import { Client, GatewayIntentBits } from 'discord.js';
const client = new Client({ intents: [GatewayIntentBits.Guilds] });
// The collector, its jobs and the dashboard, inside this process. Data lives in ./shardlens-data.
const collector = await startEmbeddedCollector({
dataDir: './shardlens-data',
appId: process.env.DISCORD_APP_ID!,
port: 8080, // dashboard on http://127.0.0.1:8080
});
const lens = createShardlens(client, { endpoint: collector.url, apiKey: collector.ingestKey });
console.log(`Shardlens: ${collector.dashboardUrl} (read key in ./shardlens-data/secrets.json)`);
await client.login(process.env.DISCORD_TOKEN);
for (const signal of ['SIGINT', 'SIGTERM'] as const) {
process.once(signal, async () => {
await lens.shutdown(); // send what is queued while the collector is still there
await client.destroy();
await collector.close();
process.exit(0);
});
}

Open http://127.0.0.1:8080 and sign in with the read key from secrets.json, or set up Discord sign-in by passing discord: { clientId, clientSecret } and publicUrl.

Three things to know before you paste it:

  • Node.js 24.11 or newer. That is the collector’s requirement; the SDK on its own runs on 22.12.
  • It uses top-level await, which needs an ES module ("type": "module", or a .mjs file). In CommonJS, put the same lines inside the async function that starts your bot, and keep lens on the client (client.lens = lens) so listeners registered earlier can reach it.
  • Starting can fail. The SDK never throws into your bot, but startEmbeddedCollector does when it can’t do its job: appId isn’t an application ID, the port is already in use, or the data folder can’t be written. Above, that stops the bot. To start without analytics instead, add .catch() to the call and pass the (then missing) url and ingestKey on: without them the SDK records nothing and says so once.

On shutdown, call lens.shutdown() first, so queued events reach the collector, and collector.close() last.

  • Directoryshardlens-data/
    • Directorydb/ the database (PGlite)
      • …
    • secrets.json session secret, settings key, ingest, read and activity keys; generated on first start

Back the folder up while the bot is stopped, and keep it private: secrets.json holds your keys. To replace a key that leaked, delete its line from secrets.json and restart the bot: a new one is generated, and the old one stops working. On Linux and macOS the folder and the file are created readable by your bot’s user only. Windows has no such file mode, so there the folder inherits the permissions of the folder it is in: put it somewhere other users can’t read.

Option Default What it does
dataDir (required) Where the database and secrets live.
appId (required) Your Discord application ID.
dashboard true false serves the API only: for a dashboard of your own or none, read with @shardlens/client and collector.readKey.
mode chosen in Settings 'privacy' or 'audit', decided here instead of in the dashboard’s Settings. The way to choose audit mode with dashboard: false; 'audit' needs auditKey.
port 8080 Dashboard and API port.
host 127.0.0.1 Address to listen on. The default keeps the dashboard private to this machine.
publicUrl http://localhost:<port> The URL people open the dashboard at (sign-in redirects, alert links).
discord none { clientId, clientSecret } for “Sign in with Discord”.
discordPublicKey none Receive webhook events; needs a public HTTPS URL.
auditKey none Allows audit mode. Keep it outside dataDir.
extraAdmins none Discord user IDs allowed into the dashboard besides the app owner and team.
trustProxy false Behind a reverse proxy, the number of proxies in front (1 for one), so rate limits see each visitor’s address.
sink none Also copy every event into your own database.
logLevel warn Collector log level, kept quiet so your bot’s logs stay readable.

startEmbeddedCollector resolves to the collector’s url and ingestKey (for the SDK), dashboardUrl, readKey and activityKey (for the dashboard, and for @shardlens/client), and close().

When to use the standalone collector instead

Section titled “When to use the standalone collector instead”
  • Bigger bots. Embedded mode shares your bot’s CPU, and the database has one connection. Beyond a few hundred servers, or if the dashboard feels slow, use Docker Compose.
  • Small machines. PGlite runs PostgreSQL in WebAssembly inside your process: a small bot with an embedded collector used 350 to 550 MB of memory in our tests.
  • Several processes. With ShardingManager or clusters, run one standalone collector and point every process at it. An embedded collector belongs to one process.
  • Public dashboards and webhook events need HTTPS in front, which a reverse proxy gives you more easily with the standalone setup.