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

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

All alert ingestion in OpenSRE flows through the load_payload function located in 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).

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) 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) 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 (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

opensre investigate --input alerts/example.json

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

opensre investigate --input alerts/alert.md

# 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

cat alert.json | opensre investigate -

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

# Same output as loading the file directly

Using Built-in Templates

opensre investigate --template grafana

payload = build_alert_template("grafana")

# Returns the full Grafana-style template dict

Interactive Paste Mode

opensre investigate --interactive

# Paste JSON, then press Ctrl+D

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, 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 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 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, 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.

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