Session Tracing

Session tracing provides fine-grained lifecycle tracking for individual rollout sessions during RL training. Each session represents a single sample generation from prompt submission through reward computation and finalization. Session tracing records timestamped events, phase executions, and derived performance metrics for offline analysis and debugging.

For general method-level performance profiling, see Performance Tracing. For visualization tools, see Trace Visualization.

---

Overview

Session tracing tracks the complete lifecycle of rollout sessions through the async RL training loop. Unlike performance tracing which focuses on method execution times, session tracing follows individual data samples as they progress through generation, reward computation, and training phases.

Key capabilities:

• Lifecycle tracking: Submit → generate → reward → finalized timestamps areal/utils/perf_tracer.py425-476
• Phase execution: Multiple executions per phase (e.g., retries in multi-turn workflows) with start/end times areal/utils/perf_tracer.py500-520
• Status tracking: Accepted, rejected, failed, or dropped sessions areal/utils/perf_tracer.py276-293
• Derived metrics: Total duration, per-phase durations (generate, reward, toolcall) areal/utils/perf_tracer.py619-668
• Task hierarchy: One task (dataset item) can spawn multiple sessions (n_samples) areal/utils/perf_tracer.py920-958
• Automatic flushing: Batched writes to JSONL for minimal overhead based on a configurable flush_threshold areal/utils/perf_tracer.py1064-1092

The tracer is thread-safe and designed for concurrent async workflows where multiple sessions execute simultaneously using ContextVar for task and session identity propagation areal/utils/perf_tracer.py30-40

Sources: areal/utils/perf_tracer.py1-1150

---

Session Lifecycle Model

Natural Language to Code Entity Mapping

The following diagram bridges the conceptual lifecycle of an RL rollout to the specific SessionTraceEvent types and SessionRecord states used in the codebase.

Natural Language Concept	Code Entity / Identifier	File Reference
Session Start	SessionRecord.submit_ts	areal/utils/perf_tracer.py425-476
Generation Phase	SessionTraceEvent.GENERATE_START / GENERATE_END	areal/utils/perf_tracer.py244-293
Reward Calculation	SessionTraceEvent.REWARD_START / REWARD_END	areal/utils/perf_tracer.py244-293
Tool Execution	SessionTraceEvent.TOOLCALL_START / TOOLCALL_END	areal/utils/perf_tracer.py244-293
Session Finalized	SessionTraceEvent.FINALIZED	areal/utils/perf_tracer.py244-293

Sources: areal/utils/perf_tracer.py244-293 areal/utils/perf_tracer.py425-476

State Transitions

Lifecycle phases:

1. Registration: Assign session_id, record submit_ts areal/utils/perf_tracer.py971-998
2. Generate phase: Inference engine generates output tokens. Tracked via atrace_session_phase("generate") areal/workflow/rlvr.py129-130
3. Reward phase: Compute reward from completion. Tracked via @trace_session("reward") areal/workflow/rlvr.py82-83
4. Finalization: Training loop accepts/rejects session, record finalized_ts areal/utils/perf_tracer.py1044-1062

Sources: areal/utils/perf_tracer.py244-293 areal/utils/perf_tracer.py425-476 areal/workflow/rlvr.py82-136

---

Core Components

SessionTracer

The SessionTracer class manages the complete lifecycle of all sessions for a single rank/role.

Key methods:

Method	Purpose	File:Line
register_task(task_id)	Register a dataset-level task that groups multiple sessions	areal/utils/perf_tracer.py960-969
register_session(task_id)	Create new session, assign session_id, record submit_ts	areal/utils/perf_tracer.py971-998
record_event(session_id, event, **payload)	Record lifecycle event (e.g. GENERATE_START)	areal/utils/perf_tracer.py1000-1033
increment_counter(session_id, name, value)	Increment custom counter for session	areal/utils/perf_tracer.py1035-1042
flush()	Write ready sessions to disk in JSONL format	areal/utils/perf_tracer.py1064-1092

Sources: areal/utils/perf_tracer.py920-1062

SessionRecord and Phase Tracking

Represents the complete state and history of a single session. It calculates derived metrics during serialization.

Derived Metrics (Computed in to_dict):

Metric	Computation	Description
total_s	finalized_ts - submit_ts	Total session duration areal/utils/perf_tracer.py644
generate_s	Sum of all generate phase spans	Total time in generation areal/utils/perf_tracer.py650-653
reward_s	Sum of all reward phase spans	Total time computing rewards areal/utils/perf_tracer.py655-658
toolcall_s	Sum of all toolcall phase spans	Total time in tool calls areal/utils/perf_tracer.py660-663

Sources: areal/utils/perf_tracer.py619-668

---

Usage Patterns

Context Manager Decorators

The @session_context() decorator automatically registers sessions and manages their lifecycle within a workflow. It is extensively used in RLVRWorkflow areal/workflow/rlvr.py110-136 and VisionRLVRWorkflow areal/workflow/vision_rlvr.py75-101

What @session_context() does:

1. Retrieves current task_id from workflow_context areal/utils/perf_tracer.py773-774
2. Registers new session with SessionTracer areal/utils/perf_tracer.py778
3. Sets session_id in a ContextVar for nested calls areal/utils/perf_tracer.py780
4. Automatically finalizes session on function exit areal/utils/perf_tracer.py793-800

Sources: areal/utils/perf_tracer.py745-814 areal/workflow/rlvr.py110-136 areal/workflow/vision_rlvr.py75-101

Phase Tracing

Use atrace_session_phase() or @trace_session() for automatic phase start/end pairing.

• Decorator: @trace_session("reward") records REWARD_START on entry and REWARD_END on exit areal/utils/perf_tracer.py816-865 Used in RLVRWorkflow areal/workflow/rlvr.py82-108 and VisionRLVRWorkflow areal/workflow/vision_rlvr.py45-73
• Async Context Manager: async with atrace_session_phase("generate") records GENERATE_START and GENERATE_END areal/utils/perf_tracer.py868-917

Sources: areal/utils/perf_tracer.py816-917 areal/workflow/rlvr.py82-108 areal/workflow/vision_rlvr.py45-101

---

Visualization and Tools

Trace Conversion and Plotting

The system includes tools to convert raw JSONL traces into interactive visualizations.

Key Tools:

1. perf_trace_converter.py: Merges multi-rank performance traces into a single Chrome Trace format file areal/tools/perf_trace_converter.py121-214 It handles remapping of PIDs and TIDs for uniqueness across ranks areal/tools/perf_trace_converter.py121-160
2. plot_session_trace.py: Generates interactive Plotly reports from session data, including timeline views and histograms of durations areal/tools/plot_session_trace.py413-576 It parses the nested phases structure from SessionRecord areal/tools/plot_session_trace.py196-230

Sources: areal/tools/perf_trace_converter.py1-214 areal/tools/plot_session_trace.py1-1264

Output Format

Default path: {fileroot}/logs/{user}/{experiment_name}/{trial_name}/session_tracer/{role}/sessions-r{rank}.jsonl areal/utils/perf_tracer.py199-242

Example record structure (as produced by SessionRecord.to_dict):

Field	Type	Description
task_id	int	Global task identifier
session_id	int	Unique session identifier within task
status	str	Final state (accepted, rejected, etc.)
submit_ts	float	Unix timestamp of registration
total_s	float	Computed duration finalized_ts - submit_ts
phases	dict	Nested start/end timestamps for phases

Sources: areal/utils/perf_tracer.py619-668

---

Performance and Thread Safety

SessionTracer is designed for high-concurrency RL environments:

• Locking: Uses threading.Lock to protect internal dictionaries (_records, _ready) during updates areal/utils/perf_tracer.py937-938
• Context Management: Uses ContextVar (_current_session_id) to track session identity across asyncio task boundaries areal/utils/perf_tracer.py34
• Graceful Failure: If tracing is disabled or a session ID is missing, context managers return a _NullContext to avoid overhead and errors areal/utils/perf_tracer.py121-140
• Batching: flush_threshold ensures disk I/O is batched rather than occurring on every event areal/utils/perf_tracer.py157-167

Sources: areal/utils/perf_tracer.py1-1150