Usage

How to work with traces and events in FlowScope JS

Overview

FlowScope JS visualizes backend execution in the form of traces — sequences of events that occur within a single user action or logical flow (for example, a login or a message exchange).

Each trace consists of ordered events passing through different system nodes such as clients, WebSocket, API, cache, and database.

The interface is divided into three main areas: the event generation panel, the system map with trace timeline, and the event inspector. This allows you to analyze flows as a whole or step by step at the level of individual events.

Sending and generating events

Events in FlowScope JS can appear in two ways. The first is through user actions performed in the chat panel on the left, such as sending a message or logging in.

The second way is explicit event generation directly from application code.

Each user action or generated event initiates backend processing that is immediately reflected on the system map and added to the trace timeline.

Generating trace events in code

To add events to traces, the project uses a standardized trace event function (internally referred to as a “beacon”).

This function accepts a parameter object whose fields can be populated by the developer with any relevant information available at the current execution point.

When such a beacon is executed, a new event appears in the trace timeline. If multiple beacons share the same traceId, they are grouped into a single trace.

sendTraceEvent({
  traceId,
  type,
  node,
  actorId: user.id,
  outcome: "error",
  error: { message: "selfId is required" },
  timestamp: Date.now(),
});

System map

The system map provides a high-level view of the logical nodes involved in a trace, such as clients, the WebSocket layer, cache, API, database, and other services.

During trace playback or selection, nodes are highlighted as events pass through them. This makes it easy to understand which components participated in the flow, in what order, and where an error occurred if one was produced.

Trace timeline

The trace timeline displays all recorded traces in chronological order. Each row corresponds to a single trace and shows compact visual indicators of node-level activity.

Selecting a trace focuses the system map on that flow and enables step-by-step inspection of its events.

Selecting events

To display a specific event in the event inspector, click on a system node in the system map or on an individual event indicator in the trace timeline.

Once selected, the event inspector automatically updates to show detailed information for that exact step of the flow.

Event inspector

The event inspector displays the full information of the selected event without aggregation or simplification.

This includes event type, trace and action identifiers, system node, timestamp, execution outcome, and the full payload.

This level of detail allows you to precisely understand what happened at each step of a flow.

Live mode and replay

In live mode, incoming events are appended to the trace timeline in real time.

Replay mode allows you to pause playback, move forward and backward through events, and control playback speed.

This makes it possible to deterministically analyze complex flows and understand the exact order and timing of events.

FlowScope JS focuses on event-level transparency and trace navigation rather than metrics, alerting, or long-term data storage.