# Supported Alert Input Formats for OpenSRE: JSON, Files, and Templates Explained

> Learn OpenSRE's supported alert input formats including JSON files and templates. OpenSRE efficiently processes alerts via command line, stdin, and more. Normalize alerts into Python dictionaries.

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

---

**OpenSRE accepts alerts as JSON objects through command-line arguments, files, stdin pipes, interactive prompts, or built-in templates, normalizing all inputs into Python dictionaries via the `load_payload` function.**

OpenSRE is an open-source Site Reliability Engineering (SRE) platform developed by Tracer Cloud that automates incident investigation and root cause analysis. Understanding the supported alert input formats for OpenSRE is essential for integrating the tool with your existing monitoring stack, as it determines how external alerting systems can communicate critical events to the investigation engine.

## The Entry Point: `load_payload` in [`app/cli/payload.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/payload.py)

All alert ingestion in OpenSRE flows through the `load_payload` function located in [`app/cli/payload.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/payload.py). This function acts as a central router that inspects CLI flags to determine the input source, then delegates to specialized loaders. Regardless of the source format, the output is always a Python `dict` containing the parsed alert data, ensuring consistent downstream processing.

## Supported Alert Input Formats

### Raw JSON Strings via `--input-json`

Pass a JSON object directly as a command-line argument using the `--input-json` flag. This input method triggers the `parse_payload_text` function, which deserializes the string using `json.loads` ([payload.py#L12](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/payload.py#L12)).

### File-Based Inputs with `--input`

The `--input` flag accepts file paths and automatically detects the format based on the file extension. The `load_file` function ([payload.py#L25](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/payload.py#L25)) handles two distinct scenarios:

- **`.json` files**: Parsed directly as JSON objects using the standard JSON decoder.
- **`.md` or `.txt` files**: Scanned for a fenced JSON block (```` ```json ... ``` ````). If found, the JSON within the fences is extracted and parsed. If no fenced block exists, the entire file content is wrapped as `{"raw_text": "<contents>"}`.

### Standard Input (stdin) Streams

Use a hyphen `-` as the input path to read alert data from stdin. The `load_stdin` function ([payload.py#L53](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/payload.py#L53)) applies the same parsing logic as file inputs, supporting both raw JSON and Markdown-wrapped JSON blocks. This method is ideal for piping alerts from other command-line tools or monitoring systems.

### Interactive Mode with `--interactive`

When you invoke OpenSRE with the `--interactive` flag, the `load_interactive` function reads from stdin until EOF (Ctrl+D), allowing you to paste JSON directly into the terminal. The pasted content is then passed through the standard `parse_payload_text` pipeline for validation and parsing.

### Built-in Alert Templates

For testing or rapid prototyping, OpenSRE provides pre-built alert structures via the `--template <name>` flag. The `build_alert_template` function in [`app/cli/alert_templates.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/alert_templates.py) ([alert_templates.py#L8](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/alert_templates.py#L8)) generates JSON payloads for the following sources: **generic**, **datadog**, **grafana**, **honeycomb**, and **coralogix**.

## Practical Code Examples

### Loading a Plain JSON File

```bash
opensre investigate --input alerts/example.json

```

```python
payload = load_payload(input_path="alerts/example.json", input_json=None, interactive=False)

# Returns: {'alert_name': 'HighErrorRate', 'severity': 'critical', ...}

```

### Loading a Markdown File with Fenced JSON

```bash
opensre investigate --input alerts/alert.md

```

```python

# alerts/alert.md contains:

#   ```json

#   {"alert_name":"HighErrorRate","severity":"critical"}

#   ```

payload = load_payload(input_path="alerts/alert.md", input_json=None, interactive=False)

# Returns: {"alert_name": "HighErrorRate", "severity": "critical"}

```

### Piping from Standard Input

```bash
cat alert.json | opensre investigate -

```

```python
payload = load_payload(input_path="-", input_json=None, interactive=False)

# Same output as loading the file directly

```

### Using Built-in Templates

```bash
opensre investigate --template grafana

```

```python
payload = build_alert_template("grafana")

# Returns the full Grafana-style template dict

```

### Interactive Paste Mode

```bash
opensre investigate --interactive

# Paste JSON, then press Ctrl+D

```

```python
payload = load_payload(input_path=None, input_json=None, interactive=True)

# Returns the parsed dict from your pasted input

```

## Fallback Behavior for Unstructured Text

When OpenSRE cannot extract a valid JSON object from the input, it does not fail. Instead, according to the implementation in [`app/cli/payload.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/payload.py), the `load_file` logic wraps the raw content in a dictionary: `{"raw_text": "<original content>"}`. This allows downstream processing nodes to handle unstructured alert data gracefully, preserving the original payload for manual inspection or alternative parsing strategies.

## Summary

- **Entry point**: All inputs route through `load_payload` in [`app/cli/payload.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/payload.py) and normalize to Python `dict` objects.
- **Supported formats**: Raw JSON strings (via `--input-json`), `.json` files, Markdown/text files with fenced JSON blocks, stdin pipes (via `-`), interactive input (via `--interactive`), and built-in templates (via `--template`).
- **Fallback strategy**: Non-JSON content is wrapped in `{"raw_text": "..."}` to prevent data loss.
- **Built-in templates**: Available for Datadog, Grafana, Honeycomb, Coralogix, and generic alert providers.

## Frequently Asked Questions

### Can OpenSRE process YAML alert files?

No, OpenSRE does not natively support YAML according to the [`app/cli/payload.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/payload.py) source code. Only JSON objects are parsed directly. If you provide a YAML file, it will be treated as raw text and wrapped in `{"raw_text": "<contents>"}`, or you must convert it to JSON before ingestion.

### What happens if my Markdown file doesn't contain a fenced JSON block?

If the file lacks a valid fenced JSON block (```` ```json ... ``` ````), the `load_file` function wraps the entire file contents in a dictionary: `{"raw_text": "<file_contents>"}`. This allows the investigation pipeline to process the text as unstructured data rather than failing with a parse error.

### How do I pipe alerts directly from another command or monitoring tool?

Use the hyphen `-` as your input path to trigger stdin mode: `cat alert.json | opensre investigate -` or `curl <webhook> | opensre investigate -`. The `load_stdin` function processes piped data using the same logic as file inputs, supporting both raw JSON and Markdown-formatted JSON.

### Which monitoring tools have built-in templates in OpenSRE?

According to [`app/cli/alert_templates.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/alert_templates.py), OpenSRE includes pre-built JSON templates for **Datadog**, **Grafana**, **Honeycomb**, **Coralogix**, and a **generic** alert format. Invoke these with `--template <provider_name>` to quickly generate standardized alert payloads for testing or development.