Dfx telemetry proposal (2025)

Developers
,
1

Introduction

DFINITY is looking into adding analytics to dfx in order to better understand how it is used.

Over the past few years, dfx has evolved into a rather sophisticated tool that allows users to manage identities and tokens, and orchestrate complex application builds and deployments. This analytics initiative seeks to enhance the user experience by identifying the most frequently used functionalities, enabling data-driven decisions—such as removing unused commands and detecting common error patterns.

The need for analytics

The lack of data makes it difficult to:

  • Understand which versions of the tool are being used and how.
  • Make decisions on which functionality is safe to deprecate.
  • Prioritize bug fixes or feature development based on user impact.

Feedback is currently gathered through forum posts and direct communication with developers, making it challenging to differentiate between issues raised by a small but vocal group and those impacting a larger, quieter majority.

Opting out

Users can opt out temporarily by setting an environment variable such as:

DFX_TELEMETRY=off

Alternatively, users will be able to opt out permanently by setting a global config with a command such as:

dfx config telemetry off

Telemetry Collection and Transmission

At a high level, dfx will log a sanitized version of the executed commands and transmit the logs to DFINITY periodically: once every few days to a week, or more often after reaching some threshold of pending commands to report.

To provide transparency, you can inspect your local telemetry log which will contain JSON-formatted entries, one per line. You can obtain the path using:

dfx info telemetry-log-path

dfx will report the following for every command execution:

  • A session id
    • Randomly generated on a periodic basis
  • the dfx version
  • the command executed
  • which parameters were passed
    • this will not include parameter values, except parameters that accept a limited set of enumerated values, such as the --output (json|idl|raw|pp) parameter of dfx canister call, or true/false parameters
  • values of enumerated-value parameters, like “dfx canisters call - - output json”
  • exit code
  • the replica reject code and error code, if any
  • certain error causes, for example, if dfx start failed because dfx was already running
  • execution time
  • whether you used the cycles ledger or a cycles wallet
  • the type of identity you used (plaintext, encrypted, HSM, keychain)
  • the type of network (local project, local shared, mainnet, or something else)
  • the number and type of canisters in the project

The backend that processes this data is not open source (we are planning to use clickhouse), meaning its handling is not independently verifiable and may change over time. We recognize that transparency is important. While this initial version uses a traditional backend, a future iteration could explore a verifiable approach, such as an Internet Computer canister.

Community feedback

DFINITY values community input on this proposal. Your feedback will help determine what and how data should be reported without compromising privacy.

Please join the discussion by sharing your thoughts.

Thanks!

Related posts

4 Likes