DBTrail Documentation

What official DBTrail binaries report, what they never report, and how to turn it off from the CLI, an environment variable or the web console.

Official release binaries send metadata-only usage statistics: which command ran, whether it worked, a coarse error class, version and platform. On by default in official builds. One step turns it off.

Turn it off

Console: This daemon page → Usage telemetry → toggle. It stops the daemon's beacons immediately and records the same machine-wide choice as bintrail telemetry off. A flag or variable on the daemon overrides the toggle, and the card says which.

bintrail telemetry off      # this account, permanently
DO_NOT_TRACK=1              # every tool that honours the convention
BINTRAIL_TELEMETRY=off      # this environment (systemd unit, compose .env)
bintrail --telemetry=off …  # one command

Five ways the telemetry decision is made, in order, the first that applies wins: DO_NOT_TRACK=1, the --telemetry=off flag, BINTRAIL_TELEMETRY=off, bintrail telemetry off or the console toggle, and finally the default, on in official builds. bintrail telemetry status names which one decided.

What is sent

Sent, a closed list of 13 fields: schema_version, event_type, command, outcome, error_class, duration_bucket, version, is_release, os, arch, is_ci, is_interactive, run_id. Never sent: DSNs, credentials, hostnames, IP addresses, server UUIDs, schema, table and column names, row data, query text, file paths, binlog positions, GTIDs, flag values, error messages, row counts. No install ID, machine fingerprint or account link.

error_class is one of db_connection, db_permission, binlog_not_found, schema_mismatch, config_invalid, storage_io, not_found, internal. Never the message.
run_id is created in memory for one command run so ingestion can drop a re-sent batch. Beacons and console events carry none. Nothing identifies the install.
See the exact bytes first; neither sends anything:

bintrail telemetry show     # a sample event, byte for byte
bintrail telemetry status   # on or off, and what decided that

Console: Usage telemetry → Show a sample event.

How it is sent

A command appends one line to a local spool file under ~/.config/bintrail with mode 0600 and sends nothing; a later run delivers it with a 2-second deadline and drops it on failure; delivery goes to telemetry.dbtrail.com with no auth header and no cookie. Unsent lines are discarded after 7 days.

Spool: ~/.config/bintrail/telemetry-spool/<date>.ndjson, capped at 5 MB a day. A failed delivery is dropped, never retried.
Endpoint: https://telemetry.dbtrail.com, separate from the authenticated API, no Authorization header, no cookie.
Operational commitments, not checkable in code: source IPs are dropped or truncated at the edge before anything is stored, and raw events are kept at most 90 days.

Who reports

Official release builds report: one event per CLI command, one beacon per UTC day per daemon, and five fixed console action kinds; beacons and console actions carry no run_id. Never reports: source builds, DBTrail EE builds, the MCP server, the demo image, CI environments, and processes with no home directory, because the ingestion address is compiled in only for official core releases.

Daemons (stream, agent, up, watch, bintrail-console serve, bintrail shim, bintrail-pg stream, bintrail-pg flashback): at most one beacon per UTC day, the first after an hour of running. They log one WARN line at startup when telemetry is on.
Console actions, under watch only: console-recover, console-recover-cascade, console-reconstruct, console-verify, console-baseline. Browsing records nothing. No JavaScript beacon.
Cloned images carry the setting. Put BINTRAIL_TELEMETRY=off or DO_NOT_TRACK=1 in the base image.

Not a sales channel: requests carry no account identifier. Full specification and the tests that enforce it: TELEMETRY.md.

Telemetry

What is sent

How it is sent

Who reports

On this page