Developer Tool · Observability · Architecture · 2026 · Solo build
Arc Trace
A three-phase tool that parses OTLP JSON trace exports (Jaeger/Zipkin/Tempo), builds a directed service-call graph with DFS cycle detection and p95 latency statistics, renders a Sugiyama-layered SVG topology, and commits a self-contained HTML architecture artifact to a user's GitHub repository via the GitHub Contents API.
The problem
Real production systems diverge from hand-drawn architecture diagrams within weeks of deployment. During incidents, engineers spend critical time asking which service actually calls which — the answer is buried in trace data, not in a diagram that was accurate 18 months ago. Arc Trace extracts the ground truth from actual OTLP telemetry: upload a Jaeger, Zipkin, or Tempo trace export, and the tool parses every span using the OTLP JSON schema (where service.name is a KeyValue array with typed AnyValue unions). It builds a directed call graph using only CLIENT spans (kind=3), deduplicating multi-span edges into weighted edges with call counts, p50/p95 latency, and error rates. DFS cycle detection finds async re-entry loops. A Sugiyama-style layered layout engine assigns services to depth layers by BFS from root nodes. The primary outcome is a committed, version-controlled self-contained HTML file in the user's GitHub repository, written via the GitHub Contents API. Twenty-seven TDD tests covering OTLP parsing, span graph construction, edge aggregation, cycle detection, and service role inference were written and watched fail before any implementation existed.
Architecture
Key decisions
CLIENT-spans-only for call edges
Using both CLIENT and SERVER spans doubles every cross-service call. The canonical approach is to use only CLIENT spans (kind=3) and resolve the caller via parentSpanId lookup.
BigInt for nanosecond arithmetic
OTLP nanosecond timestamps exceed JavaScript safe integer range. BigInt arithmetic prevents float precision loss in duration calculation.
GitHub Contents API PUT for idempotent commits
The Contents API PUT endpoint handles both create and update in one call when supplied with the existing file SHA, requiring only a pre-check GET.
DFS path tracking for cycle detection
DFS path tracking records exact cycle member nodes shown as dashed red edges. Kahn algorithm detects cycles but does not identify which nodes form them.