Skip to main content
Version: Next

Telemetry reporting

FerretDB collects basic anonymous usage data and sends them to our telemetry service (FerretDB Beacon), which helps us understand its usage, and how we can further increase compatibility and enhance our product. It also enables us to provide you information about available updates.

Your privacy is important to us, and we understand how sensitive data collection can be, which is why we are not collecting any personally-identifying information or share any of the data with third parties.

The following data is collected:

  • FerretDB version
  • Random instance UUID
  • Autonomous system number, cloud provider region, or country derived from IP address (but not the IP address itself)
  • Uptime
  • Backend (PostgreSQL or SQLite) version
  • Installation type (Docker, package, cloud provider marketplace, self-built)
  • Build configuration (Go version, build flags and tags)
  • Command statistics:
    • protocol operation codes (e.g. OP_MSG, OP_QUERY);
    • command names (e.g. find, aggregate);
    • arguments (e.g. sort, $count (stage));
    • error codes (e.g. NotImplemented, InternalError; or ok).
info

Argument values, data field names, successful responses, or error messages are never collected.

Version notification​

When a FerretDB update is available, the telemetry service sends periodic notifications containing information about the latest FerretDB version. This information is logged in the server logs and startupWarnings command output.

While you may not upgrade to the latest release immediately, ensure that you update early to take advantage of recent bug fixes, new features, and performance improvements.

Configure telemetry​

The telemetry reporter has three state settings: enabled, disabled, and undecided (default). The latter acts as if it is enabled with two differences:

  • When enabled, the first report is sent right after FerretDB starts. If undecided, the first report is delayed by one hour. That should give you enough time to disable it if you decide to do so.
  • Similarly, when enabled, the last report is sent right before FerretDB shuts down. That does not happen when undecided.
info

undecided state does not automatically change into enabled or disabled after the first or any other report. Explicit user action is required (see below) to change an undecided state to enabled or disabled.

Telemetry reporting is always disabled for embedded FerretDB and can't be configured.

info

Despite the autogenerated message by mongosh regarding MongoDB's free cloud-based monitoring service, please note that no data will ever be shared with MongoDB Inc.

Disable telemetry​

We urge you not to disable telemetry reporter, as its insights will help us enhance our software.

While we are grateful for these usage insights, we understand that not everyone is comfortable with sending them.

caution

If you disable telemetry, automated version checks and information on updates will not be available.

Telemetry can be disabled using any of the following options:

  1. Pass the command-line flag --telemetry to the FerretDB executable with value: 0, f, false, n, no, off, disable, disabled, optout, opt-out, disallow, forbid.

    --telemetry=disable

  2. Set the environment variable FERRETDB_TELEMETRY.

    export FERRETDB_TELEMETRY=disable

  3. Set the DO_NOT_TRACK environment variable with any of the following values: 1, t, true, y, yes, on, enable, enabled.

    export DO_NOT_TRACK=true

  4. Rename FerretDB executable to include a donottrack string.

    caution

    If telemetry is disabled using this option, you cannot use the --telemetry flag or environment variables until the donottrack string is removed.

  5. Use the db.disableFreeMonitoring() command on runtime.

    db.disableFreeMonitoring()
    caution

    If the telemetry is set via a command-line flag, an environment variable or a filename, it's not possible to modify its state via command.

Enable telemetry​

Telemetry can be explicitly enabled (see above) with the command-line flag --telemetry by setting one of the values: 1, t, true, y, yes, on, enable, enabled, optin, opt-in, allow.

--telemetry=enable

You can also use FERRETDB_TELEMETRY environment variable with same values or on runtime via db.enableFreeMonitoring() command.

export FERRETDB_TELEMETRY=enable
db.enableFreeMonitoring()

One case when explicitly enabling telemetry is useful is if you want to help us improve compatibility with your application by running its integration tests or just by testing it manually. If you leave the telemetry state undecided and your test lasts less than an hour, we will not have data about unimplemented commands and errors.

If you want to help us with that, please do the following:

  1. Start FerretDB with debug logging and telemetry explicitly enabled. Confirm that telemetry is enabled from the logs.
  2. Test your application with integration tests or manually.
  3. Gracefully stop FerretDB with SIGTERM or docker stop (not with SIGKILL or docker kill).
  4. Optionally, locate instance UUID in the state.json file in the state directory (/state for Docker, current directory otherwise) and send it to us. That would allow us to locate your data and understand what FerretDB functionality should be implemented or fixed to improve compatibility with your application.