Diagnostics & Issue Reporting
Relevant source files
The following files were used as context for generating this wiki page:
Diagnostics & Issue Reporting provides a structured workflow for identifying, triaging, and documenting problems within the Infrahub ecosystem. This system facilitates the collection of technical artifacts via dedicated tools, performs automated analysis of logs and tracebacks, and routes refined reports to the appropriate GitHub repositories.
The framework consists of four primary functional areas: diagnostic collection, automated analysis, general issue reporting for the Infrahub platform, and specific reporting for gaps in AI skill guidance. By segregating these tasks, the system ensures that sensitive environment data is redacted and that reports reach the maintainers with the context necessary for remediation. Sources: skills/infrahub-collecting-diagnostics/SKILL.md, skills/infrahub-analyzing-diagnostics/SKILL.md, skills/infrahub-reporting-issues/SKILL.md, skills/infrahub-reporting-skill-gaps/SKILL.md
Diagnostic Data Collection
The infrahub-collect utility serves as the primary mechanism for gathering environment state, configuration, and logs. It produces a consistent artifact bundle used by support engineers for triage.
Collection Workflow
- Verification: The system verifies the
infrahub-collectbinary is present usinginfrahub-collect version. - Detection: The tool detects the deployment environment (e.g., Docker Compose or Kubernetes) using
infrahub-collect environment detect. - Execution: The
infrahub-collect createcommand generates the diagnostic bundle. - Sanitization: The tool automatically masks well-known secret keys (e.g.,
password,token) in the output. Sources: skills/infrahub-collecting-diagnostics/SKILL.md:46-95
Contextual Collection Flags
| Flag | Use Case |
|---|---|
--benchmark | Performance issues or Out-of-Memory (OOM) errors. |
--include-queries | Slow or failing database operations. |
--include-backup | When a full reproducer is requested by support. |
Sources: skills/infrahub-collecting-diagnostics/SKILL.md:82-86
Automated Diagnostic Analysis
The Analysis system ingests bundles produced by the collector to transform raw logs into correlated incidents.
The diagram above illustrates the sequential processing of a diagnostic bundle from initial manifest reading to final report generation. Sources: skills/infrahub-analyzing-diagnostics/SKILL.md:65-123
Signal Triage and Correlation
The analyzer scans every service directory under bundle/logs/ for specific error classes:
- Python Tracebacks: Critical for identifying SDK or server-side crashes.
- System Signals: OOM kills, panics, and connection failures.
- Restart Evidence: The analyzer reads
*.previous.logfiles to determine pre-restart states. - Causal Chaining: Multiple downstream connection errors are grouped with their upstream root cause (e.g., a database OOM) into a single incident.
Sources: skills/infrahub-analyzing-diagnostics/SKILL.md:86-106, skills/infrahub-analyzing-diagnostics/rules/_sections.md:12-21
Ecosystem Issue Reporting
Issue reporting manages the classification and routing of bugs and feature requests across 11 different GitHub repositories.
Repository Routing Logic
The system applies a "default-to-main" rule: if a symptom is ambiguous or affects the platform layer, it routes to opsmill/infrahub. Specific routing cues include:
- SDK: Triggered by
infrahub-sdkdependencies orInfrahubClienterrors. - Ansible: Triggered by
opsmill.infrahubcollection usage or inventory plugin issues. - Skills: Triggered by problems with the AI skill guidance itself.
Sources: skills/infrahub-reporting-issues/SKILL.md:120-141, skills/infrahub-reporting-issues/reference.md:11-20
The Reporting Sequence
The sequence diagram shows the interaction between the user, the reporting skill, and the GitHub API, highlighting the mandatory review gate before any public submission. Sources: skills/infrahub-reporting-issues/SKILL.md:73-228
Skill Gap Reporting
Skill Gap Reporting addresses "quiet failures" where AI guidance is missing, wrong, or confusing. Unlike product bugs, these reports focus on improving the infrahub-skills ruleset.
Gap Detection Ladder
The system uses four probes to confirm a skill gap exists:
- Verifier Verdict: Detecting a "red-to-green" transition (e.g., a failed schema load that later passed).
- Coverage Read: Verifying if a rule covering the specific topic exists in
skills/<skill>/rules/. - Correction Delta: Analyzing the difference between the initial authored version and the final working version.
- Session Counters: Tracking retries, edit churn, and user nudges.
Sources: skills/infrahub-reporting-skill-gaps/SKILL.md:52-73
Triage and Handoff
Skill gaps are triaged into three categories which determine the final routing and title prefix:
- Bug: A rule exists but the model failed to follow it.
- Feature: No rule exists and external docs provided the answer.
- Docs Gap: No rule exists and external docs also failed to provide the answer.
Reports are never filed directly by this component; they are passed to the Issue Reporter as a redacted payload containing type, title, body, and searched repository context. Sources: skills/infrahub-reporting-skill-gaps/SKILL.md:83-149
Environment Sanitization
Strict redaction rules apply to all diagnostic and issue data to prevent the leakage of sensitive infrastructure information.
| Category | Redaction Rule |
|---|---|
| Secrets | Mask well-known keys like password, token, and secret. |
| Identities | Remove customer names, organization names, and project IDs. |
| Network | Redact internal IP addresses and internal hostnames. |
| Paths | Sanitize local user filesystem paths (e.g., /Users/<name>/). |
Sources: skills/infrahub-reporting-issues/SKILL.md:183-195, skills/infrahub-collecting-diagnostics/SKILL.md:97-105, skills/infrahub-reporting-skill-gaps/SKILL.md:120-129
The Diagnostics & Issue Reporting system ensures that Infrahub maintainers receive actionable, high-quality data while maintaining the security posture of the user's environment. By automating the collection and analysis of diagnostics, it reduces the time between failure detection and resolution. Sources: skills/infrahub-analyzing-diagnostics/SKILL.md:149-165, skills/infrahub-reporting-issues/SKILL.md:230-243