How to Start an Investigation with an Alert File in OpenSRE

Use opensre investigate -i path/to/alert.json to start a root-cause analysis (RCA) against a pre-saved alert payload, which triggers the LangGraph-based investigation runner and returns a structured report.

OpenSRE is an open-source Site Reliability Engineering (SRE) platform that automates incident investigation using AI agents. When you need to start an investigation with an alert file, the CLI provides a direct interface to process JSON or text-based alerts through its specialized investigation pipeline.

The OpenSRE Investigate Command

The investigate sub-command is the primary interface for running automated root-cause analysis. According to the source code in app/cli/commands/general.py, this command accepts an --input (or -i) flag that specifies the path to your alert file. The CLI parses this file and passes it to the investigation orchestrator.

Step-by-Step: Starting an Investigation with an Alert File

Prepare Your Alert File

OpenSRE supports JSON, markdown, and plain text alert files. Ensure your alert payload contains relevant incident details such as alert name, severity, and service identifiers. Save this to a file like alert.json or datadog_k8s_alert.json.

Run the Investigation Command

Execute the investigation using the -i flag followed by your file path:

opensre investigate -i path/to/alert.json

For specifying an output file to save the structured report:

opensre investigate -i alerts/datadog_k8s_alert.json -o investigation_result.json

Review the Output

The command returns a structured report containing fields like slack_message, problem_md, and root_cause. The CLI captures analytics events, writes JSON output (or prints to stdout), and exits with appropriate success or failure codes.

How the Investigation Pipeline Works (Technical Deep Dive)

Understanding the internal flow helps debug issues and extend functionality. The pipeline traverses four main components:

CLI Parsing in general.py

In app/cli/commands/general.py (lines 26-34), the investigate command is defined with the --input option. When invoked, the command builds an argument vector and calls the main entry point, capturing the investigation_started analytics event.

Entry Point Orchestration in main.py

app/main.py (lines 9-13) serves as the central dispatcher. It receives the CLI arguments and immediately delegates to run_investigation_cli from app/cli/investigate.py, passing the input path and other configuration parameters.

Investigation Setup in investigate.py

The run_investigation_cli function in app/cli/investigate.py (lines 51-71) handles pre-execution setup. It loads LLM settings via LLMSettings.from_env(), resolves the alert name, pipeline, and severity from the input file, then lazily imports run_investigation from app/pipeline/runners.py to begin execution.

LangGraph Execution in runners.py

app/pipeline/runners.py contains the core run_investigation function. This implementation builds the LangGraph agent, executes tool calls (such as log fetching and service status checks), and returns an AgentState dictionary containing the investigation results. The runner handles the actual AI-driven root-cause analysis loop.

Advanced Usage Options

Beyond basic file input, the CLI supports additional patterns:

• Standard Input: Use -i - to read alert data directly from stdin, enabling pipeline integrations like cat alert.json | opensre investigate -i -.
• Output Redirection: The -o flag saves the structured JSON report to a specified file path instead of stdout.
• Environment Configuration: The investigation respects environment variables for LLM configuration loaded via LLMSettings.from_env().

Summary

To start an investigation with an alert file in OpenSRE:

• Use the opensre investigate -i <file_path> command to process JSON or text-based alerts.
• The pipeline flows through app/cli/commands/general.py, app/main.py, app/cli/investigate.py, and finally app/pipeline/runners.py.
• The system employs a LangGraph-based agent to perform automated root-cause analysis and returns structured reports containing root_cause, problem_md, and slack_message fields.

Frequently Asked Questions

What file formats does OpenSRE support for alert files?

OpenSRE accepts JSON, markdown (.md), and plain text (.txt) files for alert input. The investigate command parses these formats in app/cli/commands/general.py and processes them through the pipeline to extract alert name, severity, and service context.

Can I pipe alert data directly into the investigate command?

Yes. Use the -i - flag to read alert data from standard input. This enables Unix-style piping such as cat alert.json | opensre investigate -i - or integration with other tools that stream alert payloads directly to the CLI.

How does OpenSRE handle the investigation output?

The investigation returns a structured report as an AgentState dictionary containing fields like slack_message, problem_md, and root_cause. By default, results print to stdout, but you can use the -o flag to write the JSON output to a specified file path.

Where is the investigation logic implemented in the source code?

The investigation pipeline spans four key files: app/cli/commands/general.py defines the CLI interface; app/main.py serves as the entry point dispatcher; app/cli/investigate.py contains run_investigation_cli for setup and configuration; and app/pipeline/runners.py implements the core run_investigation function using LangGraph for AI-driven analysis.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}