FAQ

Frequently asked questions about the Dicolytics SDK and dashboard.

SDK

I lost my API key

Revoke the existing key in Dashboard > Settings > API Keys and issue a new one. After revocation, the SDK will stop sending events within about 60 seconds and the transport will be permanently disabled (HTTP 401). Update your environment variable with the new key and restart the bot.

Can the SDK slow down my bot?

No. The SDK provides an absolute no-throw guarantee. Every public method, every listener, and every timer callback is wrapped in a try-catch guard. SDK failures are silently ignored and never propagate to your bot code.

Event delivery is fully asynchronous and batched. Network failures, timeouts, and server errors are handled internally with retries and backoff. The SDK never blocks the event loop or delays interaction responses.

Note

The SDK's overhead is negligible: a few microseconds per event to serialize and enqueue, plus one HTTP request every 5 seconds. All timers use unref() so the SDK never keeps your process alive.

What data is collected?

The SDK collects three categories of data:

Category	What Is Collected	What Is NOT Collected
Interactions	Command names, response latency, success/failure, interaction IDs	Interaction content, option values, user input
Actions	REST route and HTTP method (e.g., "message sent")	Message content, payload data, response bodies
Events	Occurrence count per 60-second window	Event content, message text, user data

Additionally:

• Heartbeats: guild count, WebSocket ping, memory, CPU, event loop delay
• Guild snapshots: member count, online count, server name, locale
• Errors: error name, message (2 KiB max), stack trace (8 KiB max)

Privacy guarantees

• Message content is never collected. Only outbound send counts are recorded via action_message_send.
• Inbound message events (messageCreate) are counted but their content is never read or stored.
• User input from slash command options, modal fields, and select menu choices is never captured.
• Error stacks are size-capped to prevent accidental PII leakage.

See Collection Overview for the full data flow and Event Types for the complete list.

Can I disable specific event types?

Yes. Add event type strings to the disabledEvents array in the SDK options:

discord.js

createDicolytics(client, {
  apiKey: '...',
  disabledEvents: [
    'event_typing_start',
    'action_react',
    'guild_snapshot',
  ],
});

discord.py

create_dicolytics(bot,
    api_key="...",
    disabled_events=[
        "event_typing_start",
        "action_react",
        "guild_snapshot",
    ],
)

When an event type is disabled, its listener or patch is never registered, so there is zero overhead. The custom type cannot be disabled via this option -- simply stop calling track() instead.

See Event Types for the full list of disableable names.

How do I set up sharding?

For ShardingManager setups, create one SDK instance per shard process. Each shard process gets its own discord.js Client, so each gets its own createDicolytics call. The SDK automatically detects shardId from client.shard.ids.

discord.js

// bot.ts -- executed per shard
const analytics = createDicolytics(client, {
  apiKey: process.env.DICOLYTICS_KEY!,
});

discord.py

# bot.py -- executed per shard
analytics = create_dicolytics(bot, api_key=os.environ["DICOLYTICS_KEY"])

For multi-cluster deployments, additionally set clusterId. See Multi-cluster.

The SDK logs "buffer full: dropped N oldest events"

This means events are being generated faster than they can be delivered. Possible causes:

1. Network issues: the Dicolytics API is unreachable or slow.
2. High event volume: your bot generates more than 5,000 events between flush cycles.
3. 429 rate limiting: the server is rate-limiting requests, causing events to accumulate.

Solutions:

• Check network connectivity to the Dicolytics API
• Reduce flushIntervalMs to flush more frequently
• Disable high-volume event types you don't need (e.g., event_typing_start)
• Check for 429 responses with debug: true

The SDK logs "API key rejected (401); transport disabled"

The API key is invalid or has been revoked. The SDK permanently disables the transport to avoid repeated failed requests. Check:

1. The API key is correct (starts with dk_live_)
2. The key has not been revoked in dashboard settings
3. The environment variable is loaded correctly

After fixing the key, restart the bot process.

How does server-side deduplication work?

Each event is assigned a UUIDv7 identifier at enqueue time. This ID never changes across retries. If a request succeeds on the server but the client receives a network error, the retry sends the same event IDs. The server deduplicates by event ID, providing effectively exactly-once delivery.

Dashboard

No data is showing

Follow this checklist:

1. Verify SDK connection: ensure createDicolytics is called before client.login(). See Getting Started.
2. Enable debug mode: set debug: true and check the console for SDK diagnostic logs.
3. Verify API key: look for "API key rejected" or "invalid API key" in the console.
4. Check the period selector: make sure you are viewing a time range that includes when the bot was running.

INFO

The first heartbeat takes up to 60 seconds after bot startup. If you just started the bot, wait at least one minute before checking the dashboard.

Custom event props are not showing in Explore

Check that property values are the correct type:

• Recommended: string, number, boolean -- these are filterable and groupable.
• Not recommended: nested objects, arrays -- these are stored but not directly filterable.

Also verify that the custom event name matches exactly (it is case-sensitive).

Changing the period shows the same data

Try a hard refresh (Ctrl+Shift+R or Cmd+Shift+R) to clear the browser cache, then select the period again.

The dashboard shows "SDK version outdated"

The dashboard detected an older SDK version in the sdk.version field of incoming events. Update the SDK:

npm

npm update @dicolytics/discord.js

pnpm

pnpm update @dicolytics/discord.js

yarn

yarn upgrade @dicolytics/discord.js

pip

pip install --upgrade dicolytics

What is the difference between "events" and "discord_events" metrics?

• events = COUNT(*) -- the number of rows in the events table. For gateway events, each row represents one 60-second aggregation window per event type per shard.
• discord_events = SUM(data.count) -- the total number of gateway event occurrences.

For example, if messageCreate fires 500 times in 60 seconds on shard 0, that produces 1 row with data.count = 500. events increases by 1, discord_events increases by 500.

See Events -- Aggregation for details.