Skip to content

docs: Enhance investigation and integration documentation#2807

Merged
Devesh36 merged 2 commits into
Tracer-Cloud:mainfrom
Devesh36:docss
Jun 14, 2026
Merged

docs: Enhance investigation and integration documentation#2807
Devesh36 merged 2 commits into
Tracer-Cloud:mainfrom
Devesh36:docss

Conversation

@Devesh36

Copy link
Copy Markdown
Collaborator

This pull request makes significant improvements to the OpenSRE documentation, focusing on clarifying investigation workflows, integrations setup, and session management. It adds new overview pages, refines the features list, and restructures integration guides for better usability. Additionally, it removes outdated or redundant documentation.

Documentation structure and navigation:

  • Added new pages for "Investigation overview" and "Benchmark" to the docs navigation, improving discoverability of key workflows and features.
  • Removed outdated pages: docs/integrations/aws.mdx and docs/integrations/macos.mdx, which are no longer relevant or have been superseded. [1] [2]

Investigation workflow and features:

  • Rewrote the "Features" page to detail the investigation workflow, integrations, masking, and remote runtime investigations, replacing the old "coming soon" list with actionable descriptions and links to relevant guides.
  • Added a comprehensive "Investigations overview" page, including guidance on starting investigations, using plain-language REPL commands, reviewing artifacts, and session continuity. [1] [2] [3] [4]

Integrations setup and catalog:

  • Rewrote the "Integrations overview" page to clearly distinguish between local CLI and hosted (cloud) setup paths, provide a full integration catalog, and offer step-by-step setup and verification instructions.

Session management and continuity:

  • Expanded the sessions documentation to explain how session IDs are provided on exit and how to resume or find previous sessions.

Masking and privacy:

  • Clarified the masking workflow documentation to better explain how sensitive identifiers are handled during investigations and report delivery.

Hermes contributor workflow:

  • Added a reference to the Hermes surface-attribution evaluation workflow for contributors.

- Added a new "Investigation workflow" section detailing the structured RCA pipeline for alerts.
- Updated "Integrations overview" to clarify setup paths and added a catalog of available integrations.
- Introduced a new "Benchmark" group in the documentation navigation.
- Improved descriptions and examples for using the interactive shell and session management.
- Added a link to the hermes_runbook for contributors in the Hermes documentation.
- Removed outdated AWS and macOS integration pages to streamline content.
@github-actions

Copy link
Copy Markdown
Contributor

Greptile code review

This repo uses Greptile for automated review. Before merge, aim for Confidence Score: 5/5 with zero unresolved review threads — see CONTRIBUTING.md.

Run a review — add a PR comment with:

@greptile review

Give it ~5-10 minutes (sometimes longer) for results, then fix feedback and re-trigger until you reach Confidence Score: 5/5.

Optional: automate with the greploop skill.

@greptile-apps

greptile-apps Bot commented Jun 14, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

This PR enhances the OpenSRE documentation by rewriting several pages for clarity, adding new overview pages for investigations and benchmarking, restructuring the integrations guide into local-CLI and hosted paths, expanding session-exit documentation, and removing two orphaned integration files.

  • Navigation and structure: investigation-overview is added to "First steps" and a new "Benchmark" group surfaces cloudopsbench; both pages exist on disk. The two deleted files (integrations/aws.mdx, integrations/macos.mdx) were not referenced in docs.json navigation, so their removal is clean.
  • Integrations catalog: The rewritten integrations-overview.mdx introduces a comprehensive table covering 40+ integrations across seven categories; all slug links were verified against docs.json navigation entries.
  • Session continuity and masking: New sessions.mdx content documents the exit-time resume hint for three exit paths; masking.mdx removes internal function-name references in favour of user-facing language.

Confidence Score: 5/5

Documentation-only changes with no code impact; all cross-links and navigation entries verified.

Every page referenced in the updated navigation exists on disk, deleted files were confirmed orphans not present in docs.json, and all internal cross-links resolve to valid nav entries. The changes are additive improvements with no regressions.

No files require special attention.

Important Files Changed

Filename Overview
docs/docs.json Adds investigation-overview to "First steps" and a new "Benchmark" group with cloudopsbench — both referenced files exist on disk.
docs/features.mdx Replaces "Coming soon" bullets with actionable descriptions of the investigation workflow, integrations, masking, and remote runtime investigations; all cross-links resolve to existing nav entries.
docs/hermes.mdx Adds a "Further reading" bullet linking to docs/hermes_runbook.mdx on GitHub with the correct .mdx extension; file confirmed to exist in the repo.
docs/integrations-overview.mdx Restructured to distinguish Local CLI vs Hosted paths and adds a comprehensive catalog table; all integration slug links match docs.json navigation entries.
docs/integrations/aws.mdx Deleted — file was orphaned (not referenced in docs.json navigation); the canonical AWS integration page at docs/aws.mdx remains.
docs/integrations/macos.mdx Deleted — file was orphaned (not referenced in docs.json navigation); the macOS environment page at environments/macos remains under the Tracer tab.
docs/investigation-overview.mdx Adds plain-language routing examples, a list-style command routing table, a session-continuity note, and a newline fix at end-of-file; all cross-links resolve correctly.
docs/masking.mdx Removes internal function-name references (node_investigate, diagnose_root_cause, masking_map) in favour of user-facing language; semantics are preserved.
docs/sessions.mdx Adds a "When you exit" table covering /exit, Ctrl+C, and Ctrl+D exit paths with resume hints; the Ctrl+D row has a minor documentation gap about behavior when a dispatch is active.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User] -->|"opensre (TTY)"| B[Interactive REPL]
    A -->|"opensre investigate -i alert.json"| C[Direct Investigation]
    B -->|Plain-language or slash command| D[REPL Planner]
    D -->|Routes intent| E["Slash Commands\n/health, /integrations, /investigate…"]
    E --> F[Investigation Pipeline]
    C --> F
    F --> G["Extract context\nfrom alert + integrations"]
    G --> H["Plan evidence collection\nlogs, metrics, deploys"]
    H --> I["Test hypotheses\ntool-calling loop"]
    I --> J["Publish artifacts\nproblem.md / report.md / rca.json"]
    J -->|If Slack configured| K[Slack report]
    B -->|On exit| L["Session persisted\n~/.opensre/sessions/"]
    L -->|Resume hint printed| A
Loading

Reviews (2): Last reviewed commit: "docs: Update link to hermes_runbook in H..." | Re-trigger Greptile

Comment thread docs/hermes.mdx Outdated
- Corrected the file extension in the link to the hermes_runbook from `.md` to `.mdx` for accuracy.
@Devesh36

Copy link
Copy Markdown
Collaborator Author

@greptile-apps review again

@Devesh36 Devesh36 merged commit 835e664 into Tracer-Cloud:main Jun 14, 2026
4 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

💜 One more reason the project grows. Thanks @Devesh36 — your contribution just landed!


👋 Join us on Discord - OpenSRE : hang out, contribute, or hunt for features and issues. Everyone's welcome.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant