Telemetry and diagnostics

When diagnostics are enabled, a script run reports to https://telemetry.community-scripts.org/telemetry: that an install started, that it is progressing, and how it ended. The data shows which scripts break, on which OS and host version, and at which command. The aggregated result is public at community-scripts.org/analytics.

Everything here is implemented in the engine's api/ folder; the file-by-file reference is in API reference.

Opting in and outCopy Anchor Link

Reporting is controlled by one file with one line:

DIAGNOSTICS=yes

The first run asks. If the file does not exist, diagnostics_check shows a dialog titled DIAGNOSTICS before the install menu:

Send Diagnostics of LXC Installation?

(This only transmits data without user data, just RAM, CPU, LXC name, ...)

Yes writes DIAGNOSTICS=yes, No writes DIAGNOSTICS=no. Later runs read the file and do not ask again.

Changing it later. In the install menu choose Settings, then Manage API-Diagnostic Setting. The dialog DIAGNOSTIC SETTINGS shows the current value and offers the opposite. Or edit the file:

sed -i 's/^DIAGNOSTICS=.*/DIAGNOSTICS=no/' /usr/local/community-scripts/diagnostics

Deciding before the first run, so that no dialog appears:

mkdir -p /usr/local/community-scripts
echo "DIAGNOSTICS=no" > /usr/local/community-scripts/diagnostics

With DIAGNOSTICS=no, or with the variable unset, every sender returns before it builds a payload. Nothing is sent without curl either.

The host passes its setting into the container it builds. During the install the container writes its own /usr/local/community-scripts/diagnostics with that value, which is what add-on scripts run inside the container later read. VM scripts and host tools read /usr/local/community-scripts/diagnostics directly.

The comment block the dialog writes into the file lists nine fields. That list is older than the payload; the table below is what the code sends today.

What is sentCopy Anchor Link

Every record from the host is one JSON document, built by _tm_payload in api/telemetry.func. All fields are present in every record; the error fields are empty unless the run failed.

Identity and statusCopy Anchor Link

Guest settingsCopy Anchor Link

Host factsCopy Anchor Link

Collected once per run by telemetry_collect_sysinfo in api/sysinfo.func.

OutcomeCopy Anchor Link

A complete installing record looks like this:

{
    "payload_version": 3,
    "random_id": "5f0c3a52-8a1e-4c1b-9a41-2f6f0b7d9e11",
    "execution_id": "5f0c3a52-8a1e-4c1b-9a41-2f6f0b7d9e11",
    "type": "lxc",
    "nsapp": "debian",
    "status": "installing",
    "ct_type": 1,
    "disk_size": 2,
    "core_count": 1,
    "ram_size": 512,
    "os_type": "debian",
    "os_version": "13",
    "pve_version": "9.0.3",
    "method": "default",
    "exit_code": 0,
    "error": "",
    "error_category": "",
    "error_message": "",
    "error_step": "",
    "error_phase": "",
    "install_duration": 0,
    "cpu_vendor": "intel",
    "cpu_model": "Intel Core i5-8500T CPU @ 2.10GHz",
    "gpu_vendor": "intel",
    "gpu_model": "Intel Corporation CoffeeLake-S GT2 [UHD Graphics 630]",
    "gpu_passthrough": "no",
    "ram_speed": "2666",
    "arch": "amd64",
    "platform": "pve",
    "has_arm": false,
    "kernel_version": "6.14.8-2-pve",
    "app_version": "",
    "failed_command": "",
    "failed_line": 0,
    "failed_function": "",
    "repo_source": "ProxmoxVE",
    "repo_slug": "community-scripts/ProxmoxVE"
}

The hardware values in the example are illustrative.

When it is sent, and from whereCopy Anchor Link

Container installsCopy Anchor Link

On Incus the host additionally sends a progress record with status installing right before the install script starts.

Nothing before step 1. A run that ends in the preflight checks, in the menu or in a dialog reports nothing at all, not even a failure. The terminal sender checks whether the install record was due and returns otherwise. A host that was not ready is not a failed install.

One terminal record per attempt. post_update_to_api sends once and then ignores further calls. If a run exits with status 0 but never reported success (you backed out of a late dialog), it is reported as aborted, not as success.

Retries are separate executions. Choosing a retry in the recovery menu calls telemetry_new_attempt: the random_id stays, the execution_id changes, and the new attempt reports its own start and end.

Progress pings from inside the containerCopy Anchor Link

The container sends progress pings and nothing else. They are fired by lxc/install.func at the end of setting_up_container, update_os, motd_ssh and customize. The server uses them to tell a running install from a stuck one.

A ping is much smaller than a host record. It contains exactly these fields:

{
    "payload_version": 3,
    "random_id": "5f0c3a52-8a1e-4c1b-9a41-2f6f0b7d9e11",
    "execution_id": "5f0c3a52-8a1e-4c1b-9a41-2f6f0b7d9e11",
    "type": "lxc",
    "nsapp": "debian",
    "status": "configuring",
    "platform": "pve",
    "repo_source": "ProxmoxVE",
    "repo_slug": "community-scripts/ProxmoxVE"
}

The container never sends a terminal status. When the install fails inside the container, the error handler writes two files there instead:

The host reads both after the install returns and sends the one failed record. That keeps the report complete and prevents two records with different verdicts for the same run.

Virtual machinesCopy Anchor Link

VM scripts call post_to_api_vm, which sets type to vm and ct_type to 2 and then behaves like a container install on the host side: one installing record, one terminal record. There are no pings from inside a VM.

Host tools and add-onsCopy Anchor Link

Tool and add-on scripts call init_tool_telemetry once, for example init_tool_telemetry "add-tailscale-lxc" "addon" in tools/addon/add-tailscale-lxc.sh. It installs an EXIT trap that sends a single record when the script ends:

• type is pve for a host tool and addon for an add-on; nsapp is the tool's name.
• Every run gets its own fresh UUID.
• There is no installing record.
• A failure with one of the "requirement not met" exit codes sends nothing: 10, 103, 104, 106, 232, 233, 234, 236, 238 (wrong shell, not root, wrong architecture, wrong host, a prerequisite missing).
• Cancelling a whiptail dialog (exit status 1 or 255) is reported as aborted with the reason "Dialog cancelled, or no terminal to show it".

Most add-ons run inside the guest, so their record is sent from the container and uses the container's diagnostics file.

UpdatesCopy Anchor Link

Running a script again inside a container to update the application sends nothing. An update never sends the install record, and without it the terminal sender stays silent.

DeliveryCopy Anchor Link

Records are sent with curl as an HTTP POST with Content-Type: application/json and the user agent community-scripts-core/3.

A failed delivery is ignored. The senders run with errexit and the caller's ERR trap switched off, so an unreachable telemetry server can never turn into an install failure.

Failure recordsCopy Anchor Link

A failed record carries a description of the failure, assembled by api/errorlog.func from the error handler's capture.

The error field starts with a header line and, after a line containing ---, continues with output:

exit_code=100 | APT: Package manager error (broken packages / dependency problems) | step: Installing Dependencies | at line 23: apt install -y example-package
---
E: Unable to locate package example-package

The header is always exit_code=<n> | <explanation> followed, when known, by | step: <step>, | in <function> and | at line <n>: <command> (or | command: <command> when the line is not known).

The output part is the output of the failing command when the handler captured it, otherwise the log lines of the failing step (everything after the last [INFO] or [OK] log entry). Before it is sent, _tm_clean_log and _tm_focus:

• remove ANSI colour codes and carriage returns;
• replace the last three octets of every IPv4 address: 192.168.1.50 becomes 192.x.x.x;
• drop lines that never explain a failure: package download and unpack progress from apt, apk, dnf, pip, npm, cargo, go, git, curl and wget progress, engine status lines and blank lines;
• cut each line to 1000 characters, keep the last 60 lines, and of those the last 10240 bytes.

error_message gets the same IPv4 replacement.

An aborted record carries only the header (exit code, explanation, step) and no command, line, function, message or output.

If the terminal record cannot be delivered, it is retried with the error field reduced to the first 600 bytes of its header line.

CategoriesCopy Anchor Link

error_category is computed by categorize_error in api/exitcodes.func. The first rule that applies wins:

1. An explicit override set by the engine (ERROR_CATEGORY_OVERRIDE). Aborted runs get user_aborted this way.

2. Exit codes that mean the same whichever program returned them:

3. The program that failed, taken from the first word of the failing command. Several tools share exit codes, so the tool is a better guide than the number:

4. The exit code:

The same exit codes 113, 114, 122, 129, 130, 143, 253 and 254 also turn a failed status into aborted: they are a declined question or a signal, a decision by the user and not a defect. What each code means is listed in Exit codes.

What is never sentCopy Anchor Link

The payload has no field for any of the following, and the engine does not read them for telemetry:

• the host name, the container's host name or its ID;
• IP addresses, MAC addresses, bridge, VLAN, gateway or DNS settings;
• passwords, SSH keys, API tokens;
• storage names, paths or pool sizes;
• user names or anything from your files.

No persistent identifier exists. random_id is generated for the run and thrown away; two installs from the same host cannot be linked through it.

Two limits to be aware of:

• A failure trace is log output. It is filtered and capped as described above, and IPv4 addresses are masked, but a line an installer prints (a path, a domain name, an IPv6 address) is sent as printed. Successful runs send no log output at all.
• Sending a record is an HTTP request, so the server sees the address it comes from, like any web server does.

Inspecting and redirectingCopy Anchor Link

TELEMETRY_URL overrides the endpoint, on the host and, because the host passes it on, in the container:

TELEMETRY_URL=http://192.0.2.10:8080/telemetry mode=default \
  bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/debian.sh)"

When the variable DEV_MODE is true, _tm_send prints every payload and the HTTP status it got back to standard error, prefixed with [DEBUG] telemetry.

RelatedCopy Anchor Link

• API reference: the api/ folder function by function
• Telemetry service: the endpoints
• Exit codes
• Runtime and errors