Skip to content
TraceItX Docs
Documentation

Breadcrumbs

The trail that led to the bug: screens, taps, logs, network and errors, on one clock.

Updated

Every report carries a single chronological chain, captured automatically.

{
  "t": 1765800000123,
  "seq": 42,
  "kind": "network",
  "level": "error",
  "message": "POST /api/cart",
  "data": {
    "reqId": 17,
    "status": 500
  }
}

Kinds

KindRecorded when
navigationA screen transition. Activities are automatic; see Screen tracking.
tapThe user taps a control — or, on TV, presses a remote key.
consoleTimber output and anything your app writes to System.out / System.err.
networkA request through the OkHttp interceptor completes or fails. See Console & network.
lifecycleThe app moves to the foreground or background.
errorAn uncaught exception. See Crash reporting.
customYou called addBreadcrumb.

Adding your own

TraceItX.addBreadcrumb(
    message = "Coupon applied",
    kind = "custom",
    level = "info",
    data = mapOf("code" to "SUMMER25"),
)

addBreadcrumb never throws. An unknown kind coerces to custom and an invalid level is dropped rather than passed through — instrumentation must not be able to break the app it is instrumenting.

Put identifiers in data, not in message. data survives as structured fields an agent can filter on; message is prose, and prose is truncated first.

Thread safety

addBreadcrumb and recordScreen are safe from any thread — the buffer is lock-guarded internally. You do not need to post to the main looper to record something that happened on a background thread, and doing so would misorder the chain relative to what actually happened.

The shared clock

t is absolute epoch milliseconds, on the same clock as the session replay, so a viewer can line a crumb up against the frame on screen when it fired. seq breaks ties inside the same millisecond.

Surviving a crash

The chain lives in a buffer the crash handler reads after your process is gone, and it is written to the outbox with the report — which is why an unattended report still carries the trail that led to it, even though it uploads on the next launch. See Crash reporting.

Limits

Caps and trimming behaviour are in Errors & limits.