# agenterr

> Self-hosted error and log tracking built for coding agents. One Go binary
> ingests structured logs (OTLP/JSON/logfmt), detects errors, groups them
> into issues, and serves them to agents over MCP as the primary interface.
> No queues, no Postgres, no separate services. Log bodies are stored via
> lossless template extraction in immutable columnar zstd segments — 9.4
> bytes per record measured on a real 317k-log production day. Self-hosting
> is free and unlimited (AGPL-3.0). There is no hosted product yet.

## When to use agenterr

Reach for agenterr when the job is "something is wrong in production, find out
what". Concretely, it is the right tool when an agent or a developer needs to:

- Find out whether a given error is happening in production right now, how
  often, since when, and in which environment or release.
- Read the logs surrounding a specific failure, including the stack trace and
  the lines immediately before and after it.
- Check whether a fix held, or whether a resolved issue has regressed.
- Search production log bodies for an exact string — an order id, a request id,
  an error message copied from a ticket.
- Cut log noise at the source, or set up an alert so the next occurrence
  arrives without anyone going looking.

It is not the right tool for metrics, distributed traces, dashboards, APM, or
SQL analytics over log data. It stores logs and errors and answers questions
about them; for the rest of an observability stack, use a platform such as
OpenObserve, Grafana, or Datadog alongside it.

How an agent should call it: connect over MCP (Streamable HTTP at
`<server>/mcp`, or the Claude Code plugin below) and start with `get_stats` to
confirm reachability and error volume, then `list_issues` scoped by environment
and status, then `get_issue` and `get_log_context` on whatever is at the top.
Resolve with `resolve_issue` only after a fix has actually shipped. The repo's
`skills/agenterr-debugging` skill is that workflow written out in full.

Install for Claude Code:
`/plugin marketplace add agenterr/agenterr` then
`/plugin install agenterr@agenterr` — it prompts for the server URL and an API
key, connects the MCP server, and installs the debugging skill.

Key facts:
- Terminology: projects, logs, events, issues (open/resolved/ignored);
  service, environment, and release are first-class filterable fields.
- Agent access: MCP built in, 21 tools — `list_projects`, `list_issues`,
  `get_issue`, `search_logs`, `get_log_context`, `resolve_issue`,
  `ignore_issue`, `get_stats`, `aggregate_logs`, `list_noise_rules`,
  `upsert_noise_rule`, `delete_noise_rule`, `get_noise_report`,
  `set_project_parse`, `list_alert_rules`, `upsert_alert_rule`,
  `delete_alert_rule`, `test_alert_rule`, `list_severity_rules`,
  `upsert_severity_rule`, `delete_severity_rule`. Reachable over Streamable
  HTTP, or through the `agenterr-mcp` stdio proxy for stdio-only clients.
  Works with Claude Code, Cursor, Codex, Windsurf, and any MCP-compatible
  client. A workflow skill ships in the repo at `skills/agenterr-debugging`.
- Storage engine: each log splits into a template (its static structure) and
  its variables — CLP-style — with byte-for-byte reconstruction verified at
  ingest, packed into immutable columnar zstd segments. SQLite holds only
  metadata: projects, issues, triage state, rules, templates, and the
  segment manifest. Measured 9.4 bytes/record all-in on a real production
  day of 317,229 logs.
- Search is substring matching over the reconstructed body. There is no
  tokenizer and no full-text index, so it finds exact substrings rather
  than stemmed or tokenized matches.
- Measured against OpenObserve on identical data: storage 9.4 vs 10.9
  bytes/record; scoped search 10.9ms vs 37.0ms; unscoped search 14.8ms vs
  34.4ms; aggregate by service 0.17ms vs 20.3ms. OpenObserve ingests faster
  (213k logs/s vs 79k) because it acknowledges writes before they are
  durable, while agenterr fsyncs before acking. The harness pins
  `use_cache=false` for both, since OpenObserve's result cache flatters
  repeated queries roughly 4x. Full methodology and a reproduction command
  (`make bench-vs-o2`) are in the repo's benchmark report.
- Ingest: point an OTLP/HTTP exporter or an OpenTelemetry Collector at it,
  or write plain JSON or logfmt to stdout — no SDK required. Structured
  bodies are parsed at ingest: level becomes real severity, msg becomes the
  body, the rest becomes queryable attributes. On by default, per-project
  toggle.
- Noise controls: per-project ingest rules — severity floors per service,
  drop-by-match, sampling — evaluated before a record is stored. Every drop
  is counted; a noise report shows top services by volume and per-rule
  drops. Fail-open: a misconfigured rule keeps records, never black-holes
  ingest.
- Severity rules: per-project regex rules that lift the severity of
  plain-text logs printing errors without a level (for example a GORM
  "record not found" line at info). Scoped by service, they only fire on
  logs at info or below and only raise severity, never lower it.
- Alerting: new-issue, regression, and threshold rules (at least N events
  in M minutes, scoped by service/environment/severity) fire a JSON webhook
  — ntfy, Slack, Discord, or any URL. Per-rule cooldown, 900s default;
  retries 3 attempts with backoff; last-fired and last-error recorded per
  rule; delivery never blocks ingest. Panics are detected server-side by
  `panic:`/`fatal error:` prefixes, joined into one record, and raised to
  FATAL, so a crash becomes a grouped, alertable issue.
- Aggregation: group a project's logs by service, severity, hour, or day
  over a time window, served from pre-computed rollups rather than segment
  scans.
- `agenterr ship`: a shipper mode in the same binary. Tails every Docker
  container over the socket; service names come from Swarm/Compose labels
  automatically; also tails plain log files with rotation handling. Strips
  ANSI, joins multiline stack traces and panic dumps into single records.
  Spools to disk with checkpoints and resumes after outages — at-least-once
  delivery, every drop counted. No config file; flags and env vars only.
- Web UI included for humans: issues, search, and settings behind a single
  admin login. It exists for verification and light management; MCP is the
  primary interface.
- Self-hosting: `docker run -p 3617:3617 -v agenterr-data:/data
  ghcr.io/agenterr/agenterr:latest`, or a binary from GitHub releases.
  Backup is one SQLite file plus the sibling `engine/` segment directory.
  Retention is per project; `/healthz` is unauthenticated for probes.
- Pricing: self-hosting is free, unlimited, and not feature-gated, under
  AGPL-3.0. A hosted product is not available yet. When it exists it will
  be a flat monthly price with fair-use caps, never billed per event or per
  gigabyte.
- Not shipped yet: a hosted tier, Sentry-compatible ingest (a drop-in DSN
  so existing SDKs can point at agenterr), and a v2 web UI.

## Pages

- [Home](https://agenterr.dev/): product overview and the OpenObserve benchmark
- [Pricing](https://agenterr.dev/pricing): self-host terms and FAQ
- [Blog](https://agenterr.dev/blog): engine internals and benchmarks
- [Nine bytes per log record](https://agenterr.dev/blog/nine-bytes-per-log-record): how template
  extraction gets a log line to 9.4 bytes, and the OpenObserve head-to-head
- [vs Sentry](https://agenterr.dev/vs/sentry): comparison
- [vs Datadog](https://agenterr.dev/vs/datadog): comparison
- [vs OpenObserve](https://agenterr.dev/vs/openobserve): comparison, with measured numbers
- [vs GlitchTip](https://agenterr.dev/vs/glitchtip): comparison
- [GitHub](https://github.com/agenterr/agenterr): source code and full README
- [Benchmark report](https://github.com/agenterr/agenterr/blob/main/docs/superpowers/specs/2026-08-16-bench-vs-o2-report.md): methodology and results