Telemetry

What it is

The Volcano CLI sends one usage event to the Volcano API each time you run a command. The Volcano team uses it to see which commands people use, where they fail, and which coding agents run them. Telemetry is on by default. The first time you run a command, the CLI prints a notice that explains this and sends nothing, so you can turn telemetry off before any event is sent.

The CLI saves that the notice was shown in ~/.volcano/config.json. If it can't save that, as in a sandbox with a read-only home directory that has never run the CLI, it shows no notice and sends nothing, on that run and every later one. A home where the notice was already saved keeps sending even when it is mounted read-only; turn telemetry off with VOLCANO_TELEMETRY_DISABLED=1 there.

What is collected

When a command fails, the event also carries the type of failure (api, network, local_not_running, usage, or other), the HTTP status and error code of an API error, and the error message. Before sending the message, the CLI replaces your home directory with ~, strips terminal color codes, and removes bearer tokens, JWTs, Volcano keys and tokens (pk-, pt-, sk-, ak-, vbt_, vpg_, sbp1.), passwords in URLs, email addresses, and URL query strings. It then cuts the message to 500 characters.

Some errors can quote your files or data, so the CLI replaces that part with [redacted]:

• reading or validating volcano-config.yaml
• reading an env file such as volcano.env
• a failed database migration, whose PostgreSQL error can quote row values
• the error a function returns to volcano functions invoke, which can hold your application's data; only its HTTP status is sent
• an execution name passed where volcano durable expects an execution ID

An error message can contain what you typed, such as an unknown command, a flag value the CLI rejected, a file path, or a resource name. The CLI does not look for secrets in what you typed beyond the shapes listed above, so pass secrets only through the inputs meant for them, such as volcano login --token or an env file.

Resource names come from the arguments that name a resource, such as <database> and <branch> in volcano databases branch get <database> <branch>, and from the --name, --function, --database, --project, --topic, and --bucket flags. volcano durable start --name is not sent, since it is an idempotency key that can hold your application's data. Other arguments and flag values, such as file paths, search queries, payloads, and commands run in a sandbox, are not sent as resource names, though they can appear in an error message. A name that looks like a path or a Volcano token or key is dropped.

The CLI does not send file contents or environment variable values, except in two cases. The selected cloud project ID can come from VOLCANO_PROJECT_ID. The agent name and its raw value come from AI_AGENT, AGENT, or VOLCANO_AGENT when one of those is set. The CLI limits them to letters, digits, and ._-/@+: and to 64 characters, and the Volcano API forwards only known agent names to analytics and reports any other as other. See agent-detection.md.

If you are logged in, the event is linked to your Volcano account. Every event also carries a random machine ID, stored in ~/.volcano/config.json. The ID is kept after volcano logout, so events sent while logged out can be linked to the account last used on that machine.

Shell completion (volcano completion and pressing Tab), commands run with --offline, and volcano telemetry commands are never recorded.

How it is sent

The CLI starts a short background process that posts the event to the Volcano API, so commands do not wait on the network. The API checks every field against a fixed list or pattern before it stores the event, and drops anything else.

Turn it off

Use either of these:

volcano telemetry disable    # saved in ~/.volcano/config.json
export VOLCANO_TELEMETRY_DISABLED=1

The CLI reads the setting when a command starts, so a change applies from the next command. volcano telemetry status shows the current setting, and volcano telemetry enable turns it back on. Logging out does not change the setting.

See what is sent

Set VOLCANO_TELEMETRY_DEBUG=1 to print each event to stderr instead of sending it. It is off unless set:

VOLCANO_TELEMETRY_DEBUG=1 volcano functions list