# How to Start an Investigation with an Alert File in OpenSRE

> Start an investigation with an alert file in OpenSRE using the opensre investigate -i command. Trigger LangGraph for root-cause analysis and get a structured report.

- Repository: [Tracer/opensre](https://github.com/Tracer-Cloud/opensre)
- Tags: how-to-guide
- Published: 2026-04-18

---

**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`](https://github.com/Tracer-Cloud/opensre/blob/main/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`](https://github.com/Tracer-Cloud/opensre/blob/main/alert.json) or [`datadog_k8s_alert.json`](https://github.com/Tracer-Cloud/opensre/blob/main/datadog_k8s_alert.json).

### Run the Investigation Command

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

```bash
opensre investigate -i path/to/alert.json

```

For specifying an output file to save the structured report:

```bash
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`](https://github.com/Tracer-Cloud/opensre/blob/main/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`](https://github.com/Tracer-Cloud/opensre/blob/main/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`](https://github.com/Tracer-Cloud/opensre/blob/main/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`](https://github.com/Tracer-Cloud/opensre/blob/main/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`](https://github.com/Tracer-Cloud/opensre/blob/main/app/pipeline/runners.py) to begin execution.

### LangGraph Execution in runners.py

[`app/pipeline/runners.py`](https://github.com/Tracer-Cloud/opensre/blob/main/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`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/commands/general.py), [`app/main.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/main.py), [`app/cli/investigate.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/investigate.py), and finally [`app/pipeline/runners.py`](https://github.com/Tracer-Cloud/opensre/blob/main/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`](https://github.com/Tracer-Cloud/opensre/blob/main/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`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/commands/general.py) defines the CLI interface; [`app/main.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/main.py) serves as the entry point dispatcher; [`app/cli/investigate.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/investigate.py) contains `run_investigation_cli` for setup and configuration; and [`app/pipeline/runners.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/pipeline/runners.py) implements the core `run_investigation` function using LangGraph for AI-driven analysis.