The Problem Production systems generate a flood of raw error events that alert‑ing tools surface without context. Engineers spend time hunting the related code, existing tickets, or Slack discussions to decide whether an alert is new, a regression, or already being handled. The lack of semantic linkage drives noise and slows incident response.

What This Does The repository implements an end‑to‑end agent that ingests raw errors, clusters them by root cause, enriches each cluster with code snippets, Linear tickets, and Slack threads via Airweave, and emits a single actionable alert per cluster. The pipeline lives in backend/ (Python) while a minimal React/Tailwind UI in frontend/ visualises the flow (e.g., frontend/src/App.tsx, frontend/src/components/pipeline-visualizer.tsx). Core data models live in backend/schemas.py (e.g., RawError, ErrorCluster). Configuration defaults are provided in .env.example and backend/config.py.

How It Is Wired

  1. Entry point – backend/main.py runs a FastAPI server. The two public routes are: run_demo (line 544) – triggers the demo pipeline, traversing 33 functions. websocket_endpoint (line 555) – streams live pipeline state, touching 34 functions.
  1. Pipeline kickoff – run_demo calls run_pipeline (line 100). run_pipeline constructs a PipelineStep chain and invokes run_pipeline -> broadcast (18 calls) and run_pipeline -> PipelineStep (5 calls).
  1. Core processing – Within backend/pipeline/ the steps are: Clustering (backend/pipeline/clustering.py::cluster_errors) → creates clusters via _create_cluster (called from 6 places). Enrichment (backend/pipeline/enrichment.py::enrich) → builds Airweave queries (_search_code) and calls the LLM (_init_llm). * Analysis (backend/pipeline/analysis.py::analyze_errors) → runs LLM‑based severity logic (_llm_analyze).
  1. External touches – Filesystem I/O: _read_json / _write_json (both invoked from 7 places) read/write state under backend/state.py. Network calls: backend/clients/airweave_client.py::search (Airweave API), backend/clients/linear_client.py::create_issue, and backend/clients/slack_client.py::post_alert.
  1. State handling – backend/state.py owns 22 functions, is referenced by 5 other modules, and performs the only persistent reads/writes.
  1. Module hot‑spots – The most connected module is backend/pipeline/__init__ (imports 6 others, instability 1). Its high import count means any change ripples through the entire pipeline. No circular dependencies were detected.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/error-monitoring-agent
cd error-monitoring-agent

# Backend setup
cp .env.example .env
python -m venv venv && source venv/bin/activate
pip install -r backend/requirements.txt
uvicorn backend/main:app --reload --port 8000   # starts FastAPI (run_demo available at /demo)

# Frontend setup
cd frontend
npm install
npm run dev   # Vite serves UI at http://localhost:3000

Configuration – Populate .env with Airweave keys (AIRWEAVE_API_KEY) and, for production, one of the data‑source blocks (e.g., SENTRY_AUTH_TOKEN, AZURE_CLIENT_ID). The backend/config.py module validates required variables.

Running the demo – Open the UI, click Run Demo; the backend executes run_demo, which walks the pipeline, stores interim state in JSON files, and returns a visual summary.

Real‑World Use A SaaS platform can replace the sample source (backend/sources/sample_source.py) with backend/sources/sentry_source.py by setting DATA_SOURCE=sentry. Errors streamed from Sentry feed into run_pipeline, which clusters them, pulls matching code and tickets via Airweave, and posts a single Slack message (via backend/clients/slack_client.py::post_alert) and Linear issue (via backend/clients/linear_client.py::create_issue). This reduces alert volume from hundreds to a handful of actionable items per hour.

Code Health & Issues

  • High – No LICENSE (root/): add MIT or Apache‑2.0.
  • High – No test suite (35 source files): introduce unit tests for public entry points, gate with CI.
  • High – No CI/CD (.github/ absent): add a GitHub Actions workflow that installs requirements.txt, runs pytest, and builds the frontend.
  • High – Wildcard CORS (backend/main.py): replace allow_origins=["*"] with an explicit whitelist.
  • Medium – Dependabot missing: add .github/dependabot.yml.
  • Medium – Large binary (docs/error-monitoring-agent-demo.mp4 8 MB): move to LFS or external storage.
  • Low – Missing repo conventions: add .editorconfig, .gitattributes, formatter config.

The Bottom Line The agent delivers a functional, end‑to‑end error‑context pipeline with clear separation between data ingestion, clustering, enrichment, and alerting. It is usable out‑of‑the‑box for demos, but production adoption requires adding licensing, tests, CI, and tightening security (CORS). Engineers modifying the pipeline should start at backend/main.py → run_pipeline and be aware that backend/pipeline/__init__ is the primary import hub.