A local developer observability and investigation runtime. Ingest OpenTelemetry signals from what you are building right now; investigate logs, traces and metrics as one correlated story — in a developer-first UI, or through MCP from your AI agents.
runtime-trail is part of the ecoma-io
organisation.
A single small runtime that runs on your machine. Your locally running services
and agents send OpenTelemetry telemetry to it; runtime-trail keeps the three
signal kinds correlated and lets you follow one request across all of them:
- Traces — span trees and waterfalls for a single request.
- Logs — the log records that belong to that request's trace and spans.
- Metrics — the measurements around that request's time window.
Investigation is the product's centre of gravity, and it is exposed through one Investigation API with two clients: a developer UI and an MCP server.
It is not a production observability platform and not a lightweight Grafana clone — see non-goals.
Developers running services locally who need to answer "what actually happened in this request?" in seconds — and the AI agents working alongside them, which get the same investigation capabilities through MCP. See docs/product/vision.md.
Production backends are built for scale, tenancy and retention. Local
investigation needs the opposite: zero setup, negligible resource use, and
answers now. runtime-trail requires no external database, broker or
collector — it starts in seconds, runs in-memory by default, and can persist
to an embedded store when a session is worth keeping. Production tooling keeps
doing its job; runtime-trail covers the gap between "emit telemetry" and
"understand it", where developers actually live.
| Signal | Ingestion | Investigation |
|---|---|---|
| Traces | OTLP spans, parent/child structure preserved | waterfall + span tree, span inspection |
| Logs | OTLP log records | log explorer, logs ↔ trace navigation |
| Metrics | OTLP metric points | metric timelines, metrics ↔ trace context |
Cross-signal correlation — trace→logs, log→trace, metric-window→traces — is a first-class capability of the query and correlation engines, not a UI trick.
The developer UI is built with Vue 3 on Loom, the ecoma-io UI system: design tokens, accessibility-first components. The UI is a client of the Investigation API — it never touches storage or ingestion directly.
An MCP server exposes the same investigation capabilities to AI agents that the UI gives to humans — same API, same correlation, no separate access path. See docs/architecture/mcp-model.md.
- Docker — one image that starts the same core and server used everywhere.
- Desktop app — a desktop shell wrapping the same native core; the shell never contains a second implementation of it.
Both are presentation and packaging around one core. See docs/architecture/system.md.
┌──────────────────┐
│ Loom UI │
└────────┬─────────┘
│
┌────────▼─────────┐
│ Investigation API│
└────────┬─────────┘
│
┌────────▼─────────┐
│ Query Engine │
└────────┬─────────┘
│
┌───────────────▼────────────────┐
│ Correlation Engine │
└───────────────┬────────────────┘
│
┌────────▼─────────┐
│ Telemetry Model │
└────────┬─────────┘
│
┌──────────────▼──────────────┐
│ Storage Abstraction │
└──────────┬───────────┬──────┘
│ │
Memory SQLite
▲ ▲
└─────┬─────┘
│
┌────────▼────────┐
│ OTLP Ingestion │
└─────────────────┘
┌─────────────────┐
│ MCP Server │
└────────┬────────┘
│
└──► Investigation API
The rules behind the arrows — what may depend on what, and which edges are forbidden — are locked in docs/architecture/boundaries.md and enforced mechanically by Archkeep.
Phase 1 (telemetry ingestion) is in progress. The engineering foundation
of Phase 0 is in place — toolchain, architecture contracts (mechanically
enforced, with canary fixtures proving the enforcement bites), agent workflow,
CI, documentation, governance — and the core now ingests OpenTelemetry: one
binary binds loopback by default, serves OTLP/HTTP and OTLP/gRPC traces, logs
and metrics into a bounded in-memory queue and store under backpressure, and
answers /healthz and /version. What does not yet exist: query,
correlation, investigation UI, MCP, and file-backed persistence. The web and
desktop apps remain bootstrap shells around a status page, not the product UI.
Delivery status is tracked in docs/roadmap/README.md.
- Product — vision, scope, non-goals
- Architecture — system, boundaries, signal models, runtime constraints
- Roadmap — status, 1.0 scope, future direction
- Decisions — architecture decision records
- Benchmarks — resource budgets and measurement harness
- Contributing — how to work in this repository
- Security — how to report vulnerabilities
See LICENSE.