Work with Lightrun Dynamic Traces for Java in JetBrains¶

You can capture and analyze the flow of an application by recording snapshots of code execution in real-time using Lightrun Dynamic Traces. A Dynamic Trace captures a sequence of Trace Snapshot hits within the same execution thread, organized chronologically to help you track the execution flow more effectively and narrow down real production issues. For an overview of Lightrun Dynamic Traces, including its benefits and main use cases, see Lightrun Dynamic Traces Overview.

Trace-specific terminology¶

This section defines key terms related to Lightrun Dynamic Traces to provide a clear understanding of their components and functionality.

• A Trace: A group of snapshots captured during the execution of a single thread sharing the same source. Dynamic Traces provide chronological insights into the flow of execution, helping developers isolate and analyze specific application behaviors. A Trace has a name identifying all the snapshots included in the Trace, for example, order_payment, as it gives meaning to the Trace.

• A Trace Snapshot: A Snapshot within a Dynamic Trace that runs on the same thread as the Trace's entry point.

• An Entry Point Trace Snapshot: The Trace Snapshot that marks the start of a Dynamic Trace. Each Trace must have a single entry point. Other Trace Snapshots this Trace Result will trigger only if executed on the same thread as its entry point.

• ID: A unique identifier for the thread in which the Trace is captured, as provided by the application. The thread ID is captured once the entry point is reached and Trace Snapshots of this thread will trigger only if executed in the same thread.

• A Trace Result: A single run of a Trace, initiated by a Trace Snapshot Entry Point. A single run of a Trace is a group of Trace Snapshot hits triggered in the same thread. A Trace Result is initiated by the Trace’s Entry point and Trace Snapshot hits are added to it until the Trace Result terminates. A Trace terminates if one of the following conditions is met:
  • The thread’s Call Stack gets back to the point where the Trace started.
  • The maximum number of Trace Snapshots’ hits has been reached.
  • The Termination Timeout has been reached.
  • The Trace was deactivated.

• Max Results: The maximum number of instances that are allowed to be captured.

• Trace Context: A set of key:value pairs that allows you to track variable values across the Trace and is available to all Trace Snapshots in the Trace. It works the same as regular Java snapshot expressions. For more information on Context, see Lightrun Traces Overview.

• A Snapshot Hit: An individual occurrence where a Trace Snapshot is triggered during runtime. Multiple hits from the same Trace Snapshot can occur within a single Trace.

Understanding the Traces workflow¶

This section explains the underlying workflow of Lightrun Traces, detailing the steps involved in creating and capturing Traces and how the mechanism operates behind the scenes.

1. Create the Trace: Define the Trace in the code editor or the Lightrun Plugin.
2. Add Trace Snapshots: Add one or more Trace Snapshots to capture key points in the application, ensuring one is defined as the Trace Snapshot Entry Point where Lightrun begins capturing.
3. Activate the Trace: Activate the Trace to begin monitoring.

4. Lightrun captures the Trace results (automated): Lightrun manages the Trace capture and termination based on the following predefined conditions:

   1. Trace Result capturing starts when the Trace Snapshot Entry Point is reached. At this stage, Lightrun identifies the application thread to follow.
   2. Any Trace Snapshot reached by this thread is captured and added to the Trace results.
   3. Trace capturing concludes when one of the following events occurs:

      - The maximum number of results is captured.

      - The termination timeout is reached.

5. Analyze the Trace results: The Trace results are displayed in the Traces view of the Lighrun Console, where you can analyze them to identify runtime behaviors and issues.

Get Started¶

Start by creating your first Trace.