fathom

Deterministic incident-context engine for three-signal observability.

fathom sits beside a durable observability store (amber), receives a copy of the telemetry stream (via coral fan-out), normalizes logs, traces, and metrics into one event substrate, links them at write time, and answers one product-shaped question cheaply and reproducibly:

Why did <metric> change for <service> in <window>?

The answer is an incident bundle — slow traces, linked logs, ranked candidate operations, and explicit evidence strings — assembled from precomputed binary incident indexes, not from scanning raw telemetry and not from an LLM crawling dashboards.

Status: project bootstrap, extracted 2026-07-02 from the CROS research prototype (~/work/yaop/research). Mechanics are validated by research gates; external validity on non-self-generated corpora is the next milestone.

Docs

Design docs (product, architecture, API contract + MCP design, roadmap, known debts) are maintained in the internal knowledge vault under yaop-labs/products/fathom.

Quickstart

Build and test:

go build ./...
go test ./...

Create a store from synthetic segments and ask for an incident bundle:

go run ./cmd/fathom -store /tmp/fathom-demo -segment-id seg-a -events 120 -seed 101 -summary=false
go run ./cmd/fathom -store /tmp/fathom-demo -segment-id seg-b -events 140 -seed 202 -summary=false
go run ./cmd/fathom -store /tmp/fathom-demo -explain -service payment -metric latency_p99 -limit 3 -summary=false
go run ./cmd/fathom -store /tmp/fathom-demo -readiness -service payment -metric latency_p99 -limit 3 -summary=false

Run the service:

go run ./cmd/fathomd -store /tmp/fathom-demo -addr 127.0.0.1:8099
curl 'http://127.0.0.1:8099/explain?service=payment&metric=latency_p99&limit=3'

Run the full coral replay gate (starts fathomd and coral, replays OTLP HTTP/protobuf traces, metrics, and logs):

./scripts/run-coral-fathom-gate.sh

Layout

*.go              engine: substrate, segments, indexes, queries, explain, HTTP
cmd/fathom/       CLI: ingest, query, explain, gates
cmd/fathomd/      service daemon (HTTP query layer)
cmd/coral-replay/ OTLP replay tool for the coral gate
fixtures/         OTLP JSON regression fixture
scripts/          gate scripts

Lineage

fathom is the productization of the CROS research prototype. The research answered "can motif+residual encoding beat Parquet?" with "no (0.98x)", and "can precomputed incident indexes answer RCA queries index-only?" with "yes (bytes_read=0, exact recall on research gates)". The second answer is this project. Research history stays in ~/work/yaop/research; working notes live in the knowledge vault under yaop-labs/products/fathom.