Skip to content

Commit 5059f24

Browse files
author
github-actions
committed
Sync docs from infrahub-skills repo
1 parent 857a24b commit 5059f24

2 files changed

Lines changed: 83 additions & 0 deletions

File tree

‎docs/docs-ai-skills/readme.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ For full lifecycle workflows. The AI generates files, loads them with `infrahubc
6060
| [Data Analyzer](./skills-reference/analyzing-data.mdx) | Queries and analyzes live Infrahub data via MCP |
6161
| [Repo Auditor](./skills-reference/auditing-repo.mdx) | Audits a repository against Infrahub best practices |
6262
| [Data Importer](./skills-reference/importing-data.mdx) | Converts CSV/TSV inputs into Infrahub object YAML and loads onto a fresh branch |
63+
| [Diagnostics Collector](./skills-reference/collecting-diagnostics.mdx) | Guides `infrahub-collect` to gather a support bundle when Infrahub is misbehaving, and reviews it before hand-off |
6364

6465
A shared reference library (`infrahub-common`) provides GraphQL query syntax, `.infrahub.yml` configuration format, YAML structure conventions, and the Profiles vs Object Templates distinction to all skills.
6566

‎docs/docs-ai-skills/skills-reference/collecting-diagnostics.mdx‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
title: Diagnostics Collector
3+
sidebar_position: 10
4+
---
5+
6+
The Diagnostics Collector guides you through producing a support bundle with OpsMill's [`infrahub-collect`](https://docs.infrahub.app/backup/guides/install-collect) tool when Infrahub is misbehaving. It installs and verifies the binary, detects your Docker Compose or Kubernetes deployment, runs `infrahub-collect create` with the flags that match your symptom, walks you through reviewing the bundle before you share it, and hands off — without diagnosing root cause or filing anything on your behalf.
7+
8+
## When to use
9+
10+
- Infrahub is broken, failing, erroring, or crashing and you need to collect logs for OpsMill support
11+
- Something went wrong after an upgrade (stuck branch, `NEED_UPGRADE_REBASE`)
12+
- A container is in `CrashLoopBackOff`, the API is returning 500s, or a worker was OOM-killed
13+
- Slow UI, slow diff, or slow/failing database operations
14+
- Preparing a hand-off for an OpsMill expert
15+
16+
## What it produces
17+
18+
- The correct `infrahub-collect` command sequence for your deployment: install/verify → `environment detect` → `create`
19+
- Symptom-appropriate flags (e.g. `--benchmark` for performance, `--include-queries` for database issues, `--include-backup` for reproduction)
20+
- A review-before-sharing checklist — the tool masks only key names, so you scan the bundle for anything else sensitive before it leaves your machine
21+
- A hand-off to OpsMill support, cross-linking the Issue Reporter if you also want to file a public issue
22+
23+
The bundle itself is written by `infrahub-collect` (by default under `./infrahub_bundles/`), with logs from every replica, container/service state, version and config, and a `bundle_information.json` manifest.
24+
25+
## Example prompts
26+
27+
- "Infrahub is throwing 500s — help me collect logs to send to OpsMill"
28+
- "A task-worker keeps getting OOM-killed on our Kubernetes deployment; gather a diagnostic bundle"
29+
- "Database queries are slow on our Docker Compose setup — collect what support needs to diagnose it"
30+
- "My proposed-change pipeline is stuck and the repo won't load schemas; put together a bundle for OpsMill"
31+
- "Something broke after the upgrade — collect diagnostics"
32+
33+
## Key rules enforced
34+
35+
- **The tool does the collecting** — deployment detection, every-replica logs, key-name redaction, the manifest, and the bundle layout are all `infrahub-collect`'s job; the skill never hand-rolls them
36+
- **Read-only** — collection runs against your existing Docker / kubectl access with no writes and no scale changes; on Kubernetes it needs only `pods/log` and `pods/exec`
37+
- **No API token** — `infrahub-collect` authenticates through your local Docker/kubectl access, not an Infrahub API token
38+
- **Review before sharing** — masking covers only keys named `password`/`secret`/`token`/`key`; the skill stops for you to scan `bundle/logs/` and `bundle/server/` for internal hostnames, customer data, and secrets stored under other key names
39+
- **Symptom-driven flags** — start with plain `infrahub-collect create` and add a flag only when the symptom calls for it, rather than piling on every flag
40+
- **Hints, not diagnoses** — the skill produces a bundle for an expert; it does not claim a root cause
41+
- **Cross-link, don't duplicate** — for filing a public GitHub issue it hands off to the Issue Reporter instead of reimplementing that routing
42+
43+
## Common mistakes it catches
44+
45+
| Mistake | What the skill does instead |
46+
| --------- | --------------------------- |
47+
| Hand-collecting logs and config by hand | Runs `infrahub-collect`, which captures every replica and previous-container logs consistently |
48+
| Trusting the automatic masking as complete | Stops for a review-before-sharing pass, because masking is key-name-only |
49+
| Piling every flag onto `create` | Adds `--benchmark` / `--include-queries` / `--include-backup` only when the symptom matches |
50+
| Sending an Infrahub API token to collect state | Uses existing Docker/kubectl access; no token is involved |
51+
| Discarding a partial bundle on a degraded deployment | Sends the partial bundle as-is — `create` records collector failures in the manifest and still exits cleanly |
52+
| Filing a GitHub issue from here | Hands off to the Issue Reporter for that |
53+
54+
## Installing and running
55+
56+
The skill produces these commands. Install and verify the binary, confirm detection, then create the bundle:
57+
58+
```bash
59+
# Install the binary for your OS/architecture
60+
curl https://infrahub.opsmill.io/ops/$(uname -s)/$(uname -m)/infrahub-collect -o infrahub-collect
61+
chmod +x infrahub-collect
62+
sudo mv infrahub-collect /usr/local/bin/ # optional
63+
64+
# Verify
65+
infrahub-collect version
66+
67+
# Confirm the tool sees your deployment
68+
infrahub-collect environment detect
69+
70+
# Create the bundle (add symptom flags as needed)
71+
infrahub-collect create
72+
infrahub-collect create --benchmark # performance / OOM
73+
infrahub-collect create --include-queries # slow/failing database queries
74+
```
75+
76+
:::warning
77+
`infrahub-collect` masks values only when the key name contains `password`, `secret`, `token`, or `key`. Logs, database query logs (`--include-queries`), and secrets stored under other key names are collected as-is. Review the bundle before sharing it.
78+
:::
79+
80+
:::tip
81+
Collector failures on a degraded deployment are expected — a stopped container can't answer status queries. `create` still exits successfully and records each failure in the manifest; send the partial bundle as-is. See the [troubleshooting-bundle guide](https://docs.infrahub.app/backup/guides/collect-troubleshooting-bundle) for the full workflow.
82+
:::

0 commit comments

Comments
 (0)