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/pglitenpm install @shardlens/discordjs @shardlens/collector @electric-sql/pgliteimport { 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.mjsfile). In CommonJS, put the same lines inside theasyncfunction that starts your bot, and keeplenson the client (client.lens = lens) so listeners registered earlier can reach it. - Starting can fail. The SDK never throws into your bot, but
startEmbeddedCollectordoes when it can’t do its job:appIdisn’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)urlandingestKeyon: 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.
What’s in the data folder
Section titled “What’s in the data folder”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.
Options
Section titled “Options”| 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
ShardingManageror 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.