Causeline

v0.1 alpha · open source · Spring Boot + React

Follow one click all the way to the database, and back.

Causeline traces a user action from the React click, through your Spring Boot controllers, services and SQL, out to the APIs you call, and back to the state update. One timeline. Then replay the request and compare the two runs.

Start in 5 minutes
Checkout trace 4bf92f35…e4736 1084 ms
BrowserServer
UIClick “Checkout”1084 ms
HTTPPOST /api/orders1008 ms
CTRLOrderController.createOrder959 ms
SVCOrderService.createOrder948 ms
SQLinsert into orders (item, qty) values ('book', 1)27 ms
HTTPPOST /chargebottleneck812 ms
SQLupdate orders set status='PAID' where id=4233 ms
STATEsetStatus('paid')<1 ms
RENDER<CheckoutPage>31 ms
InsightPrimary bottleneck: POST /charge to the payment provider spends 812 ms of its own time, 75% of the trace. Your code is fine; the provider is slow.
01 · The problem

“Checkout is slow, and sometimes it fails.”

Finding out why means stitching together five tools that have never heard of each other. Each shows one layer. None shows the cause.

The usual way

  • Browser Network tab request timing
  • React DevTools state and renders
  • Spring Boot logs grep by timestamp
  • A debugger one breakpoint at a time
  • Postman to replay, by hand

With Causeline

One trace that starts at the click and ends at the re-render, with every layer in between, in order, with its timing and its data.

02 · What you get

See it, find it, replay it.

  1. 01

    One timeline

    The click, the request, the controller, your @Observed services, Spring Data repositories, every SQL statement with its real values, outbound HTTP calls, the state update and the re-render, as one tree.Browser and server clocks are lined up by the span tree, not by wall time.

  2. 02

    The bottleneck, named

    The slowest operation is flagged by self time, so a slow parent doesn't hide the real culprit. Repeated queries (N+1) and exceptions are called out too, including the ones your code catches and only logs.Exceptions point to the file and line in your code that threw.

  3. 03

    Replay and compare

    Send a captured request again, to local, dev or QA, with that environment's credentials. Then compare the two runs span by span to see exactly what changed after your fix.POST, PUT and DELETE ask for confirmation first.

  4. 04

    All the data, kept local

    Headers, request and response bodies and SQL values are shown in full while you debug, because hidden data slows you down. Anything that leaves the app, like an OTLP export or a shared trace file, is redacted.Block any header, field or query key with one setting.

03 · How it works

Standard headers. No magic.

Causeline builds on W3C Trace Context, Micrometer and OpenTelemetry, so it fits the way Spring Boot already observes your app.

In the browser

@causeline/react wraps fetch and XHR, names the click with trace(), and adds a traceparent header to your own API calls.

In Spring Boot

The starter picks up the header. HTTP handling, controllers, services, repositories, JDBC and outbound clients become spans in the same trace.

At /causeline

Spans from both sides land in an in-memory store inside your app. Open /causeline and the whole action is there, on one timeline.

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01 trace id · parent span · sampled

04 · Local-first

Your traces never leave localhost.

No account, no agent, no cloud. Causeline runs inside your Spring Boot app, is off until you switch it on in a dev profile, and refuses to start under a production profile.

0external services. The UI and its API are served by your own app.
<1 msadded p99 latency per request, measured on the demo app.
8 KBgzipped React SDK, with no dependencies besides React.
64 MBmemory cap for stored traces. Oldest go first.
05 · Install

Five minutes to your first trace.

Spring Boot 4.1 with Java 21+, and React 18+. Published on Maven Central and npm.

<dependency>
  <groupId>dev.causeline</groupId>
  <artifactId>causeline-spring-boot</artifactId>
  <version>0.1.0-alpha.0</version>
</dependency>

  1. Add the starter

    One dependency. No agent, no extra process.

  2. Switch it on in a dev profile

    causeline.enabled: true. It stays off everywhere else.

  3. Wrap your app

    <CauselineProvider endpoint="/causeline/api/spans">, then name actions with trace('Checkout', …).

  4. Click, then open the link

    The log prints a Causeline UI: link with an access token. Your click is waiting there.

06 · Questions

Before you ask.

Is Causeline safe to run in production?

No, and it makes sure of that. Causeline is for development and QA. It is off unless causeline.enabled is true, and it refuses to start when a prod or production profile is active, because it shows headers, cookies and bodies in full.

Do I need an account, an agent or a collector?

No. Causeline runs inside your Spring Boot application and serves its UI at /causeline. There is no account, no cloud service and no separate process to run.

Which versions are supported?

Spring Boot 4.1 with Spring MVC on Java 21 or newer, and React 18 or newer. WebFlux is not supported yet.

Does it work with my OpenTelemetry setup?

Yes. It propagates the W3C traceparent header and is built on Micrometer Observation and OpenTelemetry. It can also export redacted spans over OTLP to Jaeger, Grafana Tempo or an OpenTelemetry Collector.

What does it record, and can I hide sensitive data?

By default it records headers, query strings, request and response bodies, SQL with bound values and exception details, and shows them only in your local UI. Any of it can be blocked with causeline.capture.* settings or the React capture prop, and anything exported is redacted.

Is it free?

Yes. Causeline is open source under the Apache License 2.0. The code, issues and roadmap are on GitHub.

07 · The developer

The developer behind Causeline.

Senior Full Stack & AI Engineer

Sudharma BG

Sudharma has spent more than five years building backend systems with Spring Boot and front ends with React, along with RAG pipelines and LLM-based platforms. Causeline is built for exactly that kind of work: following a request across React and Spring Boot without switching between five tools.

5+ years
building production systems
Full stack
Spring Boot, Java and React
AI
RAG pipelines and LLM platforms
  • Spring Boot
  • React
  • Java
  • LLMs & RAG
  • Redis
  • MySQL
LinkedIn GitHub

Using Causeline, or want to help shape it? Say hello on LinkedIn or open an issue.

Stop guessing which layer is slow.

Read the quick start Star on GitHub