Configuration

All options accepted by createDicolytics(client, options) for fine-tuning SDK behavior.

Options Reference

Option	Type	Default	Description
apiKey	string	(required)	Project API key (dk_live_...). Sent as Authorization: Bearer on every request. Throws synchronously if missing or empty.
endpoint	string	https://api.dicolytics.com	API base URL. Must be a valid http:// or https:// URL.
disabledEvents	string[]	[]	Array of event type strings to skip. See Disabling Events below. The custom type cannot be disabled.
debug	boolean	false	When true, SDK diagnostics are logged via console.warn with the [dicolytics] prefix.
snapshotIntervalMs	number	60000	Heartbeat and guild-snapshot loop cadence in milliseconds. Minimum 10000 (10 seconds).
flushIntervalMs	number	5000	Queue flush interval in milliseconds. Minimum 250. The queue also flushes when 50 events are pending.
requestTimeoutMs	number	10000	Per-request HTTP timeout in milliseconds. Minimum 1000.
clusterId	number	undefined	Cluster identifier for multi-cluster deployments. Integer between 0 and 32767. Stamped into every event's data.clusterId.
autoCapturePromiseRejections	boolean	false	When true, listens for unhandledRejection and reports each as an error event.

Python SDK (discord.py)

The Python SDK (dicolytics) uses create_dicolytics(bot, **options) with snake_case option names: api_key, disabled_events, snapshot_interval_ms, flush_interval_ms, request_timeout_ms, cluster_id, auto_capture_exceptions, debug, endpoint.

Validation behavior

Invalid optional values fall back to defaults silently (logged with debug: true). Only a missing or empty apiKey throws a synchronous TypeError.

Detailed Option Descriptions

apiKey

The project API key is the only required option. It authenticates every request to the Dicolytics API. Keys follow the format dk_live_... and are issued from the Dicolytics dashboard.

discord.js

createDicolytics(client, {
  apiKey: process.env.DICOLYTICS_KEY!,
});

discord.py

create_dicolytics(bot, api_key=os.environ["DICOLYTICS_KEY"])

Note

Always load the API key from an environment variable or secrets manager. Never commit it to source control.

endpoint

Override the API base URL. The SDK strips trailing slashes and validates the URL format. Most users do not need to change this.

discord.js

createDicolytics(client, {
  apiKey: '...',
  endpoint: 'https://analytics.example.com',
});

discord.py

create_dicolytics(bot, api_key="...", endpoint="https://analytics.example.com")

disabledEvents

Selectively disable auto-captured event types. Useful when you want to reduce data volume or exclude irrelevant metrics.

discord.js

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

discord.py

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

See Event Types for the full list of disableable event names.

INFO

The custom type cannot be disabled via this option. To stop sending custom events, simply stop calling track().

debug

Enable diagnostic logging to see exactly what the SDK is doing. Useful during initial setup and troubleshooting.

discord.js

createDicolytics(client, {
  apiKey: '...',
  debug: true,
});

discord.py

create_dicolytics(bot, api_key="...", debug=True)

Example output:

[dicolytics] gateway events: 12 listeners registered (intents=0x609)
[dicolytics] transport start
[dicolytics] snapshot tick
[dicolytics] buffer full: dropped 3 oldest event(s)

snapshotIntervalMs

Controls how often heartbeat and guild-snapshot events are emitted. The default of 60 seconds aligns with the server-side 10-minute aggregation buckets.

discord.js

createDicolytics(client, {
  apiKey: '...',
  snapshotIntervalMs: 30000, // every 30 seconds
});

discord.py

create_dicolytics(bot, api_key="...", snapshot_interval_ms=30000)  # every 30 seconds

INFO

The snapshot loop is wall-clock aligned: timers snap to multiples of the interval so that server-side buckets fill evenly.

flushIntervalMs

The SDK queues events and flushes them in batches. This option controls the time-based flush interval. The queue also flushes immediately when 50 events are pending.

discord.js

createDicolytics(client, {
  apiKey: '...',
  flushIntervalMs: 2000, // flush every 2 seconds
});

discord.py

create_dicolytics(bot, api_key="...", flush_interval_ms=2000)  # flush every 2 seconds

requestTimeoutMs

Per-request HTTP timeout for calls to the Dicolytics API. If a request takes longer than this, it is aborted and retried.

discord.js

createDicolytics(client, {
  apiKey: '...',
  requestTimeoutMs: 15000, // 15 second timeout
});

discord.py

create_dicolytics(bot, api_key="...", request_timeout_ms=15000)  # 15 second timeout

clusterId

Required for multi-cluster deployments. Assigns a cluster identifier that is stamped into every event, enabling the dashboard to group shards by cluster. See Multi-cluster for details.

discord.js

createDicolytics(client, {
  apiKey: '...',
  clusterId: 0,
});

discord.py

create_dicolytics(bot, api_key="...", cluster_id=0)

autoCapturePromiseRejections

Opt-in to capture unhandled promise rejections as error events. This registers a process-level unhandledRejection listener.

discord.js

createDicolytics(client, {
  apiKey: '...',
  autoCapturePromiseRejections: true,
});

discord.py

create_dicolytics(bot, api_key="...", auto_capture_exceptions=True)

INFO

If your bot already has its own unhandledRejection handler, both will fire -- the SDK never removes existing listeners.

Complete Example

discord.js

import { Client, GatewayIntentBits } from 'discord.js';
import { createDicolytics } from '@dicolytics/discord.js';

const client = new Client({
  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages],
});

const analytics = createDicolytics(client, {
  apiKey: process.env.DICOLYTICS_KEY!,
  debug: process.env.NODE_ENV !== 'production',
  disabledEvents: ['event_typing_start'],
  snapshotIntervalMs: 30000,
  flushIntervalMs: 3000,
  requestTimeoutMs: 15000,
  clusterId: Number(process.env.CLUSTER_ID),
  autoCapturePromiseRejections: true,
});

client.login(process.env.DISCORD_TOKEN);

discord.py

import os
import discord
from dicolytics import create_dicolytics

bot = discord.Bot()

analytics = create_dicolytics(bot,
    api_key=os.environ["DICOLYTICS_KEY"],
    debug=os.environ.get("ENV") != "production",
    disabled_events=["event_typing_start"],
    snapshot_interval_ms=30000,
    flush_interval_ms=3000,
    request_timeout_ms=15000,
    cluster_id=int(os.environ.get("CLUSTER_ID", 0)),
    auto_capture_exceptions=True,
)

bot.run(os.environ["DISCORD_TOKEN"])