docs(collect): document the telemetry export and --telemetry-days

changelog/169.fixed.md

@@ -0,0 +1 @@
+The Infrahub Collect documentation and the command reference now list the telemetry export that every troubleshooting bundle contains (`telemetry/telemetry-export.json`), describe what it holds and that it is not masked, and document the `--telemetry-days` flag and its `INFRAHUB_TELEMETRY_DAYS` environment variable.

docs/docs/collect/create.mdx

@@ -102,8 +102,9 @@ INFO[0012] Collecting message-queue status...
 INFO[0013] Collecting cache status...
 INFO[0014] Collecting task-manager state...
 INFO[0016] Collecting server info...
-INFO[0017] Collecting container metrics...
-INFO[0018] Creating compressed archive...
+INFO[0017] Collecting telemetry export...
+INFO[0018] Collecting container metrics...
+INFO[0019] Creating compressed archive...
 INFO[0021] Bundle created: infrahub_bundles/support_bundle_20260702_141530.tar.gz
 ```
 
@@ -148,6 +149,7 @@ The manifest records what was attempted and what succeeded:
     {"name": "logs/infrahub-server", "status": "success"},
     {"name": "logs/task-worker", "status": "success"},
     {"name": "cache-status", "status": "failed", "reason": "container not running"},
+    {"name": "telemetry", "status": "success"},
     {"name": "benchmark", "status": "skipped", "reason": "not requested"}
   ]
 }
@@ -165,12 +167,13 @@ The bundle layout is identical on Docker Compose and Kubernetes. Inside the arch
 - `task-worker/` - Task worker state, one directory per replica
 - `task-manager/` - Work pools, work queues, recent flow runs, the pending and running flow and task runs, events, and automations
 - `server/` - Version, installed packages, API information, configuration, schema, worker schema-sync status (`infrahub_status.json`), environment variables
+- `telemetry/` - Infrahub product-telemetry snapshots from the last 30 days by default (`telemetry-export.json`), exported with `infrahubctl telemetry export`
 - `metrics/` - Container resource metrics
 
 Each file holds the output of the command that produced it and nothing else, so a `.json` file always parses. When a command fails, its file is absent and a sibling `<name>.err.txt` records what ran, how it failed, and what the command reported — for example `task-manager/flow-runs.err.txt` in place of `flow-runs.json`. The manifest lists the same failure as a reason on the collector.
 
 :::warning Review before sharing
-Masking is based on key names: environment variables and configuration keys containing `password`, `secret`, `token`, or `key` are replaced with `********` before they are written to the bundle. Secrets stored under other key names are not detected. Service logs are collected as-is, and database query logs (`--include-queries`) can contain customer data. Review the bundle contents before sharing.
+Masking is based on key names: environment variables and configuration keys containing `password`, `secret`, `token`, or `key` are replaced with `********` before they are written to the bundle. Secrets stored under other key names are not detected. Service logs are collected as-is, and database query logs (`--include-queries`) can contain customer data. The telemetry export is written without masking; see [what it contains](./index.mdx#review-before-sharing). Review the bundle contents before sharing.
 :::
 
 ## Step 5: Share the bundle with support
@@ -216,6 +219,23 @@ infrahub-collect create
 
 The effective limit is recorded in the manifest, so support knows whether logs were truncated.
 
+### Change the telemetry time window
+
+Every bundle includes the Infrahub product-telemetry snapshots stored in your Infrahub database. The collector runs `infrahubctl telemetry export` in the `task-worker` container and exports the snapshots from the last 30 days. To export a different number of days:
+
+```bash
+# Export 90 days of telemetry snapshots
+infrahub-collect create --telemetry-days=90
+
+# Or via environment variable
+export INFRAHUB_TELEMETRY_DAYS=90
+infrahub-collect create
+```
+
+A value of `0` or less uses the 30-day default. No flag removes the telemetry export from the bundle.
+
+The manifest records the `telemetry` collector as `skipped` when the export produces no file — for example, when no snapshots exist in the time window, or when the deployment runs an Infrahub version earlier than 1.9.0, which does not store telemetry snapshots. When `infrahubctl` printed output, the bundle keeps it in `telemetry/telemetry-export.err.txt`.
+
 ### Run a performance benchmark
 
 For performance investigations, support may ask you to include a benchmark run:

docs/docs/collect/index.mdx

@@ -2,7 +2,7 @@
 title: Infrahub Collect
 ---
 
-Use Infrahub Collect to gather everything OpsMill support needs to investigate an issue — service logs, diagnostic status, configuration, and metrics — into a single local archive. Run it when support asks for logs, or to attach diagnostic data to a support request. The same command produces the same bundle on Docker Compose and Kubernetes.
+Use Infrahub Collect to gather everything OpsMill support needs to investigate an issue — service logs, diagnostic status, configuration, Infrahub product telemetry, and metrics — into a single local archive. Run it when support asks for logs, or to attach diagnostic data to a support request. The same command produces the same bundle on Docker Compose and Kubernetes.
 
 ## Safe to run at any time
 
@@ -27,6 +27,7 @@ Each bundle is a single `tar.gz` archive. Inside, every file lives under a top-l
 | Task worker | Prefect worker state, one directory per replica |
 | Task manager | Work pools, work queues, recent flow runs, the pending and running flow and task runs, events, and automations |
 | Server | Version, installed packages, API information, configuration, schema, and masked environment variables |
+| Telemetry | The Infrahub product-telemetry snapshots stored in your Infrahub database, from the last 30 days by default (`--telemetry-days`) |
 | Metrics | Container resource usage |
 | Backup (opt-in) | A standalone backup produced by the standard backup behavior and referenced in the manifest, not embedded in the archive (`--include-backup`) |
 | Benchmark (opt-in) | Host resource benchmark results (`--benchmark`) |
@@ -36,3 +37,15 @@ The layout is identical on Docker Compose and Kubernetes.
 ## Review before sharing
 
 Masking is based on key names: environment variables and configuration keys containing `password`, `secret`, `token`, or `key` are replaced with `********` before they are written to the bundle. Secrets stored under other key names are not detected. Service logs are collected as-is, and database query logs (`--include-queries`) can contain customer data. Review the bundle contents before sharing it.
+
+The telemetry export, `telemetry/telemetry-export.json`, is written exactly as `infrahubctl telemetry export` returns it, without masking. It holds the daily snapshots that Infrahub stores in its own database. Infrahub stores these snapshots even when reporting to OpsMill is turned off with `INFRAHUB_TELEMETRY_OPTOUT`, so bundles from opted-out deployments also contain them. Each snapshot records:
+
+- The Infrahub version and the deployment identifier
+- Whether Infrahub sent the snapshot to OpsMill
+- The telemetry payload, which the Infrahub documentation describes as anonymous usage data with no personally identifiable information:
+  - Counters about the graph, schema, and features in use
+  - Counts of active accounts, account groups, and open branches
+  - Database, worker, and infrastructure statistics
+  - Activity over the previous day, such as logins, validation checks, artifact generation, branch operations, and webhook deliveries
+
+See [What telemetry does Infrahub send?](https://docs.infrahub.app/faq#what-telemetry-does-infrahub-send) and [Local telemetry storage](https://docs.infrahub.app/deploy-manage/run-observe/telemetry) in the Infrahub documentation. That description covers the telemetry export only: Infrahub Collect does not anonymize the logs, schema, or configuration in the rest of the bundle.

docs/docs/reference/commands.mdx

@@ -330,6 +330,7 @@ infrahub-collect create [flags]
 | `--include-backup` | Also create a backup using the standard backup behavior | `false` | `INFRAHUB_INCLUDE_BACKUP` |
 | `--include-queries` | Include database query logs (may contain customer data) | `false` | `INFRAHUB_INCLUDE_QUERIES` |
 | `--benchmark` | Run the OpsMill benchmark and include its results (requires image download; skipped with a warning if unavailable) | `false` | `INFRAHUB_BENCHMARK` |
+| `--telemetry-days <n>` | Number of days of Infrahub product-telemetry snapshots to export; a value of `0` or less uses the default | `30` | `INFRAHUB_TELEMETRY_DAYS` |
 
 **Examples:**
 
@@ -348,6 +349,9 @@ infrahub-collect create --include-backup
 
 # Performance investigation with benchmark
 infrahub-collect create --benchmark
+
+# Export 90 days of telemetry snapshots instead of 30
+infrahub-collect create --telemetry-days=90
 ```
 
 **Output:**
@@ -365,6 +369,7 @@ A single archive named `support_bundle_<timestamp>.tar.gz` in the output directo
 | Task-worker state | Prefect worker status, one directory per replica |
 | Task-manager state | Work pools, work queues, recent flow runs, events, and automations |
 | Server info | Versions, installed packages, API information/configuration/schema, masked environment variables |
+| Telemetry export | Infrahub product-telemetry snapshots for the last `--telemetry-days` days, exported with `infrahubctl telemetry export` in the `task-worker` container; written without masking; skipped when the export produces no file |
 | Container metrics | Resource usage via `docker compose stats` or `kubectl top` |
 | Backup (opt-in) | Backup produced by the standard backup behavior (`--include-backup`) |
 | Benchmark (opt-in) | OpsMill benchmark results (`--benchmark`) |

docs/docs/reference/configuration.mdx

@@ -86,6 +86,7 @@ Both rules combine as a union, and the most recent backup at each location alway
 | `--include-backup` | `INFRAHUB_INCLUDE_BACKUP` | Also create a backup during collection |
 | `--include-queries` | `INFRAHUB_INCLUDE_QUERIES` | Include database query logs in the bundle |
 | `--benchmark` | `INFRAHUB_BENCHMARK` | Run the OpsMill benchmark and include its results |
+| `--telemetry-days` | `INFRAHUB_TELEMETRY_DAYS` | Number of days of Infrahub product-telemetry snapshots to export (default `30`; a value of `0` or less uses the default) |
 
 ## Auto-detection behavior