From 602e43c129daa10350b0cbd92e3a1dea89b455d7 Mon Sep 17 00:00:00 2001 From: Fatih Acar Date: Thu, 8 Oct 2026 12:29:41 +0000 Subject: [PATCH] docs(collect): document the telemetry export and --telemetry-days Every troubleshooting bundle carries telemetry/telemetry-export.json, but no page mentioned it, so a customer reviewing a bundle before sharing it could not learn that it was there or what it holds. List the telemetry collector wherever the docs list bundle contents or collect flags. In "Review before sharing", explain that the export is written without masking and what Infrahub stores in each snapshot. Document --telemetry-days (INFRAHUB_TELEMETRY_DAYS). Closes #169 Co-Authored-By: Claude Opus 5.5 --- changelog/169.fixed.md | 1 + docs/docs/collect/create.mdx | 26 +++++++++++++++++++++++--- docs/docs/collect/index.mdx | 15 ++++++++++++++- docs/docs/reference/commands.mdx | 5 +++++ docs/docs/reference/configuration.mdx | 1 + 5 files changed, 44 insertions(+), 4 deletions(-) create mode 100644 changelog/169.fixed.md diff --git a/changelog/169.fixed.md b/changelog/169.fixed.md new file mode 100644 index 00000000..00036674 --- /dev/null +++ b/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. diff --git a/docs/docs/collect/create.mdx b/docs/docs/collect/create.mdx index 6895ccff..fa63a8d3 100644 --- a/docs/docs/collect/create.mdx +++ b/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 `.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: diff --git a/docs/docs/collect/index.mdx b/docs/docs/collect/index.mdx index c7fdc67c..285eebbd 100644 --- a/docs/docs/collect/index.mdx +++ b/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. diff --git a/docs/docs/reference/commands.mdx b/docs/docs/reference/commands.mdx index 1f9aa35c..59ba2648 100644 --- a/docs/docs/reference/commands.mdx +++ b/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 ` | 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_.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`) | diff --git a/docs/docs/reference/configuration.mdx b/docs/docs/reference/configuration.mdx index 25848bc9..12c98383 100644 --- a/docs/docs/reference/configuration.mdx +++ b/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