Tracer API

This module contains the centralized logging utility for the simulation engine.

class ml.tracer.LogRecord(timestamp, thread_name, component_id, event, details, level)

Bases: tuple

component_id: Alias for field number 2

details: Alias for field number 4

event: Alias for field number 3

level: Alias for field number 5

thread_name: Alias for field number 1

timestamp: Alias for field number 0

class ml.tracer.TimedEvent(timestamp, component_id, event_type, thread_name, details, tick)[source]

Bases: object

Represents a timed event with a start, end, and children.

complete(end_time, end_tick)[source]: Marks the event as complete and calculates its duration.

class ml.tracer.Tracer[source]

Bases: object

A thread-safe, centralized logging utility for the simulation engine.

It buffers log records and periodically flushes them to the console and/or a file in a formatted, column-aligned manner.

classmethod log(level: LogLevel, component_id: str, event: str, details: Dict[str, Any] | None = None, tick: int | None = None)[source]

Adds a log record to the buffer.

This method is thread-safe.

Parameters:

level – The severity level of the log.
component_id – The identifier of the component logging the event.
event – The name of the event being logged.
details – An optional dictionary of structured data. If a string is passed, it will be wrapped in a ‘message’ key.
tick – The optional simulation tick number.

classmethod start(level: LogLevel, flush_interval_seconds: float, output_file: str | None, log_to_console: bool = True, error_file: str | None = 'errors.log')[source]

Initializes and starts the tracer thread.

Parameters:

level – The minimum log level to record.
flush_interval_seconds – How often to flush logs.
output_file – An optional file path to write logs to.
log_to_console – If True, logs will also be printed to the console.
error_file – An optional file path to write detailed exception tracebacks to.

classmethod stop()[source]: Stops the tracer thread and performs a final flush of all logs.

ml.tracer.analyze_trace_log(log_path: str, output_format: str = 'text', output_file: str | None = None)[source]

Main analysis function. Parses the log and prints a performance report.

Parameters:

log_path – Path to the simulation trace log file.
output_format – The desired output format. Can be ‘text’, ‘json’, or ‘json:perfetto’.
output_file – Optional path to write the output to. If None, prints to stdout.