anaconda-anon-usage

Simple, anonymous telemetry for conda

This package augments the request header data that conda delivers to package servers during index and package requests. Specifically, a set of tokens are appended to the "user agent" that Conda already sends with each request.

These tokens are anonymous by design. An Anaconda Cloud token is included only if the user chooses to log in. They enable Anaconda to better disaggregate individual user patterns from our access logs. Use cases include:

• Counting the number of conda clients on a network
• Providing more accurate estimates of package popularity
• Other statistical analyses of conda usage patterns; e.g., environment count, frequency of updates, etc.

This package is installed as a dependency of certain Anaconda-branded packages, such as Navigator. While we ask that you allow us to gather this data to help us improve our user experience, the additional behavior can still be disabled with a single conda config.

Installation

You will likely not need to install anaconda-anon-usage yourself, as it will come as a dependency of other Anaconda packages such as anaconda-navigator. Nevertheless, it can readily be installed as follows:

conda install -n base anaconda-anon-usage

This package has no additional dependencies other than conda itself. It employs a conda pre-command plugin to modify the user agent string.

Explaining the behavior

The easiest way to verify that it is engaged is by typing conda info and examining the user-agent line. The user-agent string will look something like this (split over multiple lines for readability):

conda/22.11.1 requests/2.28.1 CPython/3.10.4 Darwin/22.2.0 OSX/13.1
aau/0.1.0 c/sgzzP8ytS_aywmqkDTJ69g s/3ItHH93LRUmCoJZkMOiD3g e/hCmim1vFSbinlm4waR6dZw
a/6NxsCXJLQ-uoMUBAZmGsTQ i/anaconda-2024 o/acme-corp m/ws-12345

The first five tokens constitute the standard user-agent string that conda normally sends with HTTP requests, and are similar to what a standard web browser such as Chrome, Safari, or Edge send every time a page is requested. The remaining tokens are generated by the anaconda-anon-usage package. See the Token reference section below for a complete description of each token type.

Here is an easy way to see precisely what is being shipped to the upstream server on Unix:

conda clean --index --yes
conda search -vvv fakepackage 2>&1 | grep 'User-Agent'

This produces an output like this:

> User-Agent: conda/22.11.1 requests/2.28.1 CPython/3.10.4 Darwin/22.2.0 OSX/13.1 aau/0.1.0 c/sgzzP8ytS_aywmqkDTJ69g s/3ItHH93LRUmCoJZkMOiD3g e/hCmim1vFSbinlm4waR6dZw

Token reference

The following table summarizes all token types supported by anaconda-anon-usage:

Prefix	Name	Description	Anonymous	Persistence
aau/	Version	Package version of anaconda-anon-usage	Yes	N/A
c/	Client	Identifies the conda client/user	Yes	Saved in ~/.conda/aau_token
s/	Session	Identifies a single conda process	Yes	Generated per process
e/	Environment	Identifies a conda environment	Yes	Saved in $CONDA_PREFIX/etc/aau_token
a/	Anaconda Cloud	Encodes Anaconda Cloud user ID	No	Derived from Anaconda auth token
i/	Installer	Identifies the installer used	Yes	System-configured
o/	Organization	Identifies an organization	Yes	System-configured
m/	Machine	Identifies a specific machine	Yes	System-configured

Token details:

• Version (aau/): Always present. Reports the installed version of anaconda-anon-usage.

• Client (c/): A randomly generated token stored in ~/.conda/aau_token. The same value is delivered across all conda commands for the user. If the token file is missing or unreadable, this token is omitted. The token is tied to the host machine to prevent accidental sharing across machines.

• Session (s/): A randomly generated token created fresh each time conda runs. Useful for correlating multiple requests within a single conda operation.

• Environment (e/): A randomly generated token stored in $CONDA_PREFIX/etc/aau_token, unique to each conda environment. If the token file is missing or unreadable, this token is omitted.

• Anaconda Cloud (a/): Unlike other tokens, this is not anonymous. It is derived from the user's Anaconda Cloud login (via anaconda-auth) and encodes the user's Anaconda ID. Only present when the user has authenticated with Anaconda Cloud.

• Installer (i/): A system-configured token identifying the installer that created the conda installation. Can be set via file (installer_token or .installer_token in conda config directories) or environment variable (ANACONDA_ANON_USAGE_INSTALLER_TOKEN). Multiple values are supported.

• Organization (o/): A system-configured token for identifying groups of conda installations. Typically set by system administrators. Can be set via file (org_token or .org_token) or environment variable (ANACONDA_ANON_USAGE_ORG_TOKEN). Multiple values are supported.

• Machine (m/): A system-configured token providing a unique machine identifier without revealing hostname information. Can be set via file (machine_token or .machine_token) or environment variable (ANACONDA_ANON_USAGE_MACHINE_TOKEN). Multiple values are supported.

Anonymous token design

All tokens except a/ (Anaconda Cloud) are designed to ensure that they do not reveal identifying information about the user or the host. Specifically, for the c, s, and e tokens:

• Each token is generated using os.urandom for cryptographically secure random data, then encoded with base64 in a URL-safe output.
• The client token is saved in ~/.conda/aau_token, so that it can be read with every conda command. If for some reason the token cannot be created or read, the c/ token will be omitted.
• Similarly, the environment token is saved in $CONDA_PREFIX/etc/aau_token, so it can be read with every conda command applied to that environment. If for some reason the token cannot be created or read, the e/ token will be omitted.

In short, these tokens were designed so that they cannot be used to recover an underlying username, hostname, or environment name. The underlying purpose of these tokens is disaggregation: to distinguish between different users, sessions, and/or environments for analytics purposes. This works because the probability that two different users will produce the same tokens is vanishingly small.

Disabling

Because this package is delivered as a dependency of other Anaconda packages, you may not be able to remove it from your conda environment. You may, however, disable the delivery of the tokens

conda config --set anaconda_anon_usage off

(false or no may also be used). With this setting in place, the additional tokens will be removed; e.g.

user-agent : conda/22.11.1 requests/2.28.1 CPython/3.10.4 Darwin/22.2.0 OSX/13.1 aau/0.1.0

To re-enable it, you may use the command

conda config --set anaconda_anon_usage on

(true or yes may also be used).

Advanced usage

Starting with version 0.6.0, anaconda-anon-usage has included capabilities intended to enable organizations to enhance the telemetry generated by this module to more precisely track their organization's usage.

It is important to note that these additional capabilities are off by default, and are only enabled when taking deliberate steps, usually by a system administrator. For a typical Anaconda user, therefore, nothing in this section applies.

System tokens (installer, organization, and machine)

This module supports three system-configured token types (i/, o/, m/) that must be manually installed on a user's machine. See the Token reference section for a summary of what each token represents. Typically these will be configured by a system administrator, sometimes using a mobile device management tool.

To enable these tokens, the following files should be created in a standard conda configuration directory; we recommend /etc/conda/ on Unix/macOS and C:\ProgramData\conda\ on Windows:

• installer_token: identifies the installer that created this conda installation.
• org_token: the organization token. This value should be identical for all machines within the same organization.
• machine_token: the machine token. This value should be unique to each machine.
• condarc: To ensure that the anaconda-anon-usage telemetry remains enabled, this file should include the following lines:

  anaconda_anon_usage: true #!final
  aggressive_update_packages: [anaconda-anon-usage]
  

These tokens can also be activated using environment variables:

• installer_token: ANACONDA_ANON_USAGE_INSTALLER_TOKEN
• org_token: ANACONDA_ANON_USAGE_ORG_TOKEN
• machine_token: ANACONDA_ANON_USAGE_MACHINE_TOKEN

The environment variable approach may be appropriate in CI/CD systems or containerized workflows.

Unlike the client, environment, and session tokens, it is possible to provide multiple system tokens of the same type. For example, one can be placed in /etc/conda/org_token and another in an environment variable. When this occurs, all of them are included in the user agent string, to ensure that one does not shadow the other.

For convenience, the tokens submodule includes a function to generate a random token ready for use as a system token:

python -m anaconda_anon_usage.tokens --random

Tokens can also be constructed manually, but must include only characters in the ranges a-z, A-Z, 0-9, -, and _, and no spaces. A maximum length of 36 characters is also enforced, to help ensure that the total header length remains well within HTTP limits.

Activation heartbeats

The anaconda-anon-usage telemetry provides helpful information when a user installs a package or searches the package repository. By default, however, it provides no information about when a user uses a conda environment.

To address that limitation, anaconda-anon-usage implements an opt-in activation heartbeat that is triggered when performing a full conda environment activation; e.g., using conda activate. This heartbeat takes the form of a lightweight HEAD request to the upstream repository, and thus includes the user agent string enhanced by anaconda-anon-usage. The heartbeat is run in a background thread, with a short network timeout, and with all exceptions swallowed, to ensure that the user's workflow is not disrupted.

This heartbeat functionality is off by default, even when the rest of anaconda-anon-usage is enabled. To enable it, add this additional line to the system condarc file discussed above:

anaconda_heartbeat: true #!final