Skip to content

Hashed or identified users

You choose whether Shardlens hashes user IDs or records them.

Hashed (privacy mode, the default) Identified (audit mode)
What leaves your bot A salted hash that can’t be turned back into an ID The user ID, username and avatar, and nothing else
What you can see How many people, never which people Who ran each interaction, in the Activity log
How long it is kept Hashes become unlinkable when their salt is destroyed 30 days by default, 90 at most, encrypted

Identified mode exists so moderators and support staff can answer “who used /ban in this server yesterday?” or investigate abuse. Everything else in Shardlens (command usage, servers, growth, response times) works the same in both modes, and is always counts.

Exactly three things about the person who ran an interaction: their user ID, their username and their avatar (so the Activity log can show a profile picture). No email address, display name, roles, connections or message content, in any mode. Set auditIncludeProfile: false in the SDK to record the ID alone.

Use audit mode when you have a support or abuse-handling need that counts can’t meet, and you can explain it to your users. Don’t turn it on for curiosity or marketing.

Turning it on changes what you collect, so update your privacy policy first. npx shardlens privacy --audit prints a paragraph that matches.

Audit mode has to be switched on in both places. One side alone does nothing.

  1. Give the collector an audit key

    Setting up from scratch? npx shardlens init --identify-users … creates it for you. Otherwise:

    Terminal window
    openssl rand -base64 32

    Put the result in .env as SHARDLENS_AUDIT_KEY and restart the collector. Keep a copy somewhere safe: audit data can’t be read without it.

  2. Choose “Identified” on the collector

    In the dashboard, Settings → User identity → Mode: Identified. Only a Discord sign-in (owner or team) can change it.

    Running the collector without the Shardlens dashboard? Set SHARDLENS_MODE=audit in its .env instead (mode: 'audit' for an embedded collector) and restart it. npx shardlens init … --dashboard own --identify-users writes both lines for you.

  3. Switch the SDK to audit mode

    bot.ts
    import { createShardlens } from '@shardlens/discordjs';
    import { Client, GatewayIntentBits } from 'discord.js';
    const client = new Client({ intents: [GatewayIntentBits.Guilds] });
    createShardlens(client, {
    endpoint: process.env.SHARDLENS_URL!,
    apiKey: process.env.SHARDLENS_INGEST_KEY!,
    mode: 'audit', // only takes effect when the collector is in audit mode too
    auditIncludeProfile: true, // the default: username and avatar with each user ID. false records IDs only
    });

When someone reports that a command “did nothing”, open the server’s page or the command’s page and follow View failed runs: the Activity log opens already narrowed to the runs that errored, missed the 3-second deadline or got no response. The same filters are in the log itself (command, server ID, outcome, exact user ID), and its address can be linked to from your own tools: /activity?guild=<server ID>&outcome=failed. A user ID is never part of the address.

Shardlens records and shows; it doesn’t act on users. Blocking someone is your bot’s job: copy the user ID from the log into your bot’s own block command or admin panel, or read the log from that panel as below.

The activity log isn’t tied to the Shardlens dashboard. An activity key (slk_activity_…) reads it from the server side of a dashboard of your own, through @shardlens/client:

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');
}

Create one in Settings → API keys → New activity key, with npx shardlens init … --dashboard own --identify-users, or with npx shardlens keys --scope activity and SHARDLENS_ACTIVITY_KEY in the collector’s .env. An activity key reads the log and the top users, and everything a read key reads. It can’t export the log, change settings or sign in to the Shardlens dashboard, and it is answered with 404 audit_mode_off while users are hashed.

Treat it like a password to personal data: keep it on a server, behind a sign-in of your own for your own staff, and revoke it in Settings → API keys when it is no longer needed. Without the dashboard, put a new key in SHARDLENS_ACTIVITY_KEY and restart the collector: the old one stops working. To stop reading the log altogether, switch audit mode off (SHARDLENS_MODE=privacy).

  • Encrypted at rest with AES-256-GCM, using a key that lives outside the database.
  • Kept for 30 days by default. You can choose up to 90; longer is rejected.
  • Every access is logged: viewing the activity log, looking up a user, viewing top users and exporting, by a person or by an activity key (under the key’s label; the same read repeated by a key within a minute, as a page that refreshes does, is one entry). The log is visible under Settings → Privacy; with the dashboard off it is still written, and turning the dashboard on shows it.
  • Exact lookups only: you can search for a known user ID, but there is no browsing of user profiles and the query API can’t group by user.
  • Exports need confirmation, and spreadsheet formulas in the CSV are neutralised.
  • Three fields, no more: user ID, username and avatar. auditIncludeProfile: false keeps the ID only.

A complete bot is in examples/audit-mode.

Switch the collector back to Hashed in Settings. New interactions are stored without identities straight away; existing audit rows expire on their normal schedule, or you can erase individual users.