Data collected
This page is generated from the wire format in @shardlens/schema. A test fails the build if a field can be sent
without being listed here, so the list is complete for the version these docs were built from.
Reading the tables
Section titled “Reading the tables”Each table is one object on the wire. envelope is the batch around every request, event holds the fields every
event has, and the other tables are event types (such as interaction or guild_join) or objects inside them
(actor, guild_info).
- Mode: “Both” fields are collected in privacy mode and audit mode. “Audit only” fields are sent only when both the SDK and the collector are in audit mode.
- Personal data: “Pseudonymous” means a salted hash that can’t be reversed once its salt is destroyed. It is still personal data under UK and EU GDPR while the salt exists. “Yes” means the field identifies a person.
- Kept: how long the collector’s database stores it. Fields marked “Not stored” are read while the batch is processed and then dropped. Raw retention is 35 days by default and configurable from 7 to 90; after raw rows expire, aggregate counts stay: minute counts for 14 days, hourly counts for 13 months and daily counts for good.
Erasure deletes every row that holds a person’s hash, and in audit mode their encrypted records, whatever the tables say about how long those would otherwise be kept.
Privacy mode
Section titled “Privacy mode”envelope
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
v | Wire-format major version. | Both | No | Not stored; used while processing the batch only |
mode | Data mode the SDK runs in (privacy or audit). | Both | No | Not stored; used while processing the batch only |
sdk | SDK package name and version, kept with the SDK health of the sending process. | Both | No | Latest value only |
app | Discord application ID, environment name and bot release. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
source | Shard IDs and an instance label (host name and process ID) for the sending process, kept with its SDK health and its gauges. The cluster ID (discord-hybrid-sharding) is sent but not stored. | Both | No | 30 days as sent (every 30 seconds for process gauges), then deleted |
sentAt | When the batch was sent; used to correct clock skew. | Both | No | Not stored; used while processing the batch only |
events | The events in the batch. | Both | No | Not stored; used while processing the batch only |
event
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
id | UUIDv7 event ID; makes retries idempotent. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
ts | When the event happened (epoch milliseconds). | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
weight | Inverse sample rate, so sampled counts stay accurate. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
type | Event type. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
interaction
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
kind | Slash command, context menu, entry point, button, select, modal submit or autocomplete. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
command | Command name. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
group | Subcommand group name. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
sub | Subcommand name. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
commandId | Registered command ID. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
commandScope | Whether the command is global or registered to one server. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
options | Names of the options used. Values are not collected. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
optionValues | Values of options the bot owner allow-listed with `captureOptionValues` only. Never user, channel, role, mentionable or attachment options, nor a value holding a Discord ID. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
customId | Component or modal custom ID (for a command that opened a modal, the modal's), with secrets removed and numbers and IDs replaced by `*`, or as the bot's `normaliseCustomId` rewrites it. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
componentType | Component type number. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
sourceCommand | Command that created the message a component is on. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
context | Where it ran: server, bot DM or private channel. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
install | Whether the app was server-installed, user-installed or both. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
guild | Server ID (not personal data). | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
channelType | Channel type number. Channel IDs and names are never collected. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
locale | The user's Discord app language (not their location). | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
guildLocale | The server's preferred language. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
memberTier | Admin, manager, member or DM, derived from the member’s permissions. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
user | Keyed hash of the user ID, computed inside the bot process. | Both | Pseudonymous | In unique-user counts until the salt for its period is destroyed (period end + 7 days); raw rows expire after 35 days (configurable 7–90) |
premium | Whether the user or server has an active entitlement. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
outcome | ok, error, timeout (missed 3-second deadline) or no response. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
errorCode | Discord API error code, if the response failed. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
errorClass | Error class name the handler threw. Never messages or stack traces. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
ackMs | Milliseconds from Discord creating the interaction to the first response. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
responseType | Interaction callback type (for example deferred or modal). | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
deferred | Whether the first response was a deferral. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
ephemeral | Whether the first response was ephemeral. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
handlerMs | Handler duration, when the handler is wrapped or reports when it finished. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
shard | Shard that received the interaction. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
message_command
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
command | Command name as the bot defines it, after aliases. Never the text the user typed. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
group | Subcommand group name, if the bot reports one. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
sub | Subcommand name, if the bot reports one. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
options | Names of the arguments the bot reports as used. Values are not collected. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
optionValues | Values of arguments the bot owner allow-listed with `captureOptionValues` only. Never a value holding a Discord ID. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
guild | Server ID (not personal data). | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
channelType | Channel type number. Channel IDs and names are never collected. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
guildLocale | The server's preferred language. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
memberTier | Admin, manager, member or DM, derived from the member’s permissions. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
user | Keyed hash of the message author’s ID, computed inside the bot process. | Both | Pseudonymous | In unique-user counts until the salt for its period is destroyed (period end + 7 days); raw rows expire after 35 days (configurable 7–90) |
outcome | ok or error, as the handler finished. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
errorClass | Error class name the handler threw. Never messages or stack traces. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
errorCode | Discord API error code, if the error came from Discord. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
handlerMs | Handler duration, when the bot reports it. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
shard | Shard that received the message. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
interaction_error
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
interaction | ID of the interaction event the error belongs to. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
command | Command name. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
errorClass | Error class name the handler threw. Never messages or stack traces. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
errorCode | Discord API error code, if the error came from Discord. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
handlerMs | Handler duration until it failed. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
command_permissions
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
guild | Server that changed command permissions. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
command | Command ID, or the application ID for app-wide changes. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
overwrites | Number of permission overwrites now set. Role and user IDs are not collected. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
guild_info
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
guild | Server ID. | Both | No | While the bot is installed, plus 90 days after it leaves |
name | Server name (rendered as plain text). | Both | No | While the bot is installed, plus 90 days after it leaves |
icon | Server icon hash. | Both | No | While the bot is installed, plus 90 days after it leaves |
memberCount | Member count when the profile was sent (on joining, after a restart and on server updates), or Discord's approximate count with `refreshGuildCounts`. | Both | No | While the bot is installed, plus 90 days after it leaves |
large | Discord's large-server flag. | Both | No | While the bot is installed, plus 90 days after it leaves |
preferredLocale | The server's preferred language. | Both | No | While the bot is installed, plus 90 days after it leaves |
features | Server feature flags such as COMMUNITY or PARTNERED. | Both | No | While the bot is installed, plus 90 days after it leaves |
premiumTier | Boost tier. | Both | No | While the bot is installed, plus 90 days after it leaves |
boosts | Number of boosts. | Both | No | While the bot is installed, plus 90 days after it leaves |
verificationLevel | Verification level. | Both | No | While the bot is installed, plus 90 days after it leaves |
nsfwLevel | NSFW level. | Both | No | While the bot is installed, plus 90 days after it leaves |
mfaLevel | Moderator MFA requirement. | Both | No | While the bot is installed, plus 90 days after it leaves |
createdAt | When the server was created. | Both | No | While the bot is installed, plus 90 days after it leaves |
joinedAt | When the bot joined. | Both | No | While the bot is installed, plus 90 days after it leaves |
shard | Shard the server is on. | Both | No | While the bot is installed, plus 90 days after it leaves |
channelCounts | Number of channels of each type. Never names. | Both | No | While the bot is installed, plus 90 days after it leaves |
roleCount | Number of roles. | Both | No | While the bot is installed, plus 90 days after it leaves |
emojiCount | Number of custom emojis. | Both | No | While the bot is installed, plus 90 days after it leaves |
stickerCount | Number of stickers. | Both | No | While the bot is installed, plus 90 days after it leaves |
botPermissions | The bot's permission bitfield in the server. | Both | No | While the bot is installed, plus 90 days after it leaves |
guild_join
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
info | Server profile at install. | Both | No | While the bot is installed, plus 90 days after it leaves |
detectedAtStartup | True when the join happened while the bot was offline. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
guild_update
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
info | Updated server profile. | Both | No | While the bot is installed, plus 90 days after it leaves |
guild_leave
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
guild | Server ID that removed the bot. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
detectedAtStartup | True when the removal happened while the bot was offline. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
guild_availability
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
guild | Server ID affected by a Discord outage. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
available | Whether the server became available or unavailable. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
shard | Shard the server is on. Not stored. | Both | No | Not stored; used while processing the batch only |
guild_snapshot
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
shards | Shards reporting the snapshot. | Both | No | Not stored; used while processing the batch only |
shardCount | Total shard count, to detect resharding. | Both | No | Not stored; used while processing the batch only |
guilds | Server IDs on those shards, diffed to find joins and removals while offline. Held for up to a day while a new shard layout is still reporting. | Both | No | Not stored; used while processing the batch only |
command_registry
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
commands | Registered commands (ID, name, type, scope, subcommands) to find unused ones. | Both | No | While the command stays registered |
shard_state
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
shard | Shard ID. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
state | Ready, resumed, reconnecting, disconnected, error or invalidated. discord.js 15 reports ready, resumed and disconnected. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
closeCode | Gateway close code. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
replayed | Events replayed on resume. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
unavailableGuilds | Servers still unavailable when the shard became ready (discord.js 14). Not stored. | Both | No | Not stored; used while processing the batch only |
rest_window
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
windowMs | Length of the aggregation window. Not stored. | Both | No | Not stored; used while processing the batch only |
rows | REST call counts, retries and latency histograms by method, route and status. Routes hold route words only: IDs, invite and template codes, tokens, query strings and any other value are replaced. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
invalid | 401, 403 and 429 counts toward the invalid-request ban threshold. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
rate_limit
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
scope | Scope of the rate limit a request was held back for: user, global or shared. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
global | Whether the limit was global. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
route | Route with route words only, as for REST calls (never the raw path, which can contain tokens). | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
method | HTTP method. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
limit | Request limit for the bucket. Not stored. | Both | No | Not stored; used while processing the batch only |
retryAfter | Milliseconds until the request may be retried. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
sublimitTimeout | Sub-limit timeout, if any. Not stored. | Both | No | Not stored; used while processing the batch only |
invalid_request_warning
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
count | Invalid requests counted by discord.js in the current window, kept as the `rest.invalid_warning_count` gauge. | Both | No | 30 days as sent (every 30 seconds for process gauges), then deleted |
remainingTime | Milliseconds left in the window. Not stored. | Both | No | Not stored; used while processing the batch only |
gauge_window
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
gauges | Process and gateway gauges: shard ping and servers, event-loop delay, memory, caches. | Both | No | 30 days as sent (every 30 seconds for process gauges), then deleted |
entitlement
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
action | Created, updated or deleted. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
sku | SKU ID. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
entitlementType | Entitlement type (purchase, test, subscription and so on). | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
owner | Whether a user or a server owns the entitlement. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
user | Keyed hash of the owning user. | Both | Pseudonymous | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
guild | Owning server ID. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
startsAt | Start time. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
endsAt | End time. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
subscription
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
action | Created, updated or deleted. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
status | Subscription status. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
skus | SKU IDs. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
user | Keyed hash of the subscriber. | Both | Pseudonymous | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
periodStart | Current period start. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
periodEnd | Current period end. | Both | No | No automatic expiry. A user hash in it can no longer be linked to anyone once its salt is destroyed |
custom
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
name | Custom event name passed to `track()`. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
props | Properties passed to `track()`, chosen by the bot owner. The SDK sends at most 2 KB. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
user | Keyed hash of the user, if the bot passes one. | Both | Pseudonymous | In unique-user counts until the salt for its period is destroyed (period end + 7 days); raw rows expire after 35 days (configurable 7–90) |
guild | Server ID, if the bot passes one. | Both | No | Raw rows 35 days (configurable 7–90), then aggregate counts only |
app_info
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
name | Application name. | Both | No | Latest value only |
approximateGuildCount | Discord's approximate server count. | Both | No | 30 days as sent (every 30 seconds for process gauges), then deleted |
approximateUserInstallCount | Discord's approximate user-install count. | Both | No | 30 days as sent (every 30 seconds for process gauges), then deleted |
approximateUserAuthorizationCount | Discord's approximate user-authorisation count. | Both | No | Latest value only |
dashboardUserIds | The app owner's or accepted team members' user IDs, kept as they are to check a Discord sign-in to the dashboard. Admin sessions and the admin activity log keep the ID of the team member who signed in. | Both | Yes | Latest value only |
eventWebhooksStatus | Whether Discord webhook events are enabled. | Both | No | Latest value only |
skus | SKU IDs, names and types. | Both | No | Latest value only |
sessionStartRemaining | Identify calls left in the current 24-hour window. | Both | No | 30 days as sent (every 30 seconds for process gauges), then deleted |
sessionStartTotal | Identify calls allowed per 24 hours. | Both | No | Latest value only |
nodeVersion | Node.js version of the bot process. | Both | No | Latest value only |
libVersion | discord.js version of the bot process. | Both | No | Latest value only |
sdk_health
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
queueDepth | Events waiting to be sent. | Both | No | Latest value only |
dropped | Events dropped, by priority lane and by reason. | Both | No | Latest value only |
failedFlushes | Batches that failed to send. | Both | No | Latest value only |
internalErrors | Errors caught inside the SDK, by name. | Both | No | Latest value only |
Audit mode only
Section titled “Audit mode only”interaction
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
actor | Who ran it (raw user ID, optional names). Audit mode only; encrypted at rest. | Audit only | Yes | Encrypted; 30 days by default, 90 days maximum |
message_command
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
actor | Who ran it (raw user ID, optional names). Audit mode only; encrypted at rest. | Audit only | Yes | Encrypted; 30 days by default, 90 days maximum |
actor
| Field | What it is | Mode | Personal data | Kept |
|---|---|---|---|---|
userId | Discord user ID of the person who ran the interaction or message command. | Audit only | Yes | Encrypted; 30 days by default, 90 days maximum |
username | Username. Left out with `auditIncludeProfile: false`. | Audit only | Yes | Encrypted; 30 days by default, 90 days maximum |
avatar | Avatar hash, to show the profile picture. Left out with `auditIncludeProfile: false`. | Audit only | Yes | Encrypted; 30 days by default, 90 days maximum |
Copies outside the collector’s database
Section titled “Copies outside the collector’s database”- Your own database. With an event sink, the collector copies every event it accepts, without the fields marked “Yes” under personal data, and deletes the copies after the sink’s own retention (35 days by default).
- ClickHouse (preview). With the ClickHouse store, interactions, message commands and custom events are copied there for 35 days, whatever the raw retention setting, and their minute counts for 400 days.
- Exporters. The Prometheus and OpenTelemetry exporters run inside your bot. They see events before users are hashed, with the user left out, and keep only counts and timings.