This module implements a simple framework for event-based tracing.
A Tracer instance is used to record events. Each event is associated with a payload, which stores user-provided information about the event. As of now, there are only two types of events: begin and end events; but this is meant to be expanded as needed.
Types
EventPayload = object kind*: TracedItemKind nk*: TNodeKind loc*: TLineInfo sym*: PSym str*: string
- Stores the data associated with a trace event. For simplicity and in order to allow for figuring out the requirements, no object variant is used and all field are available for all trace item kinds Source Edit
PayloadId = distinct uint32
- The ID of a payload. Acts as the unique identifier of an event payload in the context of a Tracer instance - they're not unique across multiple instances Source Edit
TracedItemKind = enum tikParser = "Parser", tikModule = "Module", tikInclude = "Include", tikSem = "Sem", tikVmCodegen = "VmCodegen", tikVm = "Vm", tikTransform = "Transform", tikCodegen = "Codegen", tikMirgen = "Mir", tikPasses = "Passes", tikInjectDestr = "InjectDestructors", tikBackend = "Backend", tikOther = "Other"
- Used to loosely group events together (the kind is used as the event name in the output). This likely needs a complete redesign - the only goal so far was to make the output readable Source Edit
TraceEvent = object begin*: bool ## whether this is a 'begin' or 'end' event payload*: PayloadId ## the ID of the associated payload timeStamp*: MonoTime ## the timestamp of the event
- Source Edit
Tracer = object start*: MonoTime ## the point in time where the tracer became ## active. Used to turn the absolute timestamps of ## events into relative ones events*: seq[TraceEvent] ## all recorded events payloads*: seq[EventPayload] ## the payload data for events
- Source Edit
Procs
proc addPayload(t: var Tracer; payload: sink EventPayload): PayloadId {. ...raises: [], tags: [].}
- Add payload to the tracer and returns the ID assigned to it, which can then be used to Source Edit
proc finish(t: var Tracer) {....raises: [], tags: [TimeEffect].}
- Records the stop event. No further events should be recorded with the t after a call to finish Source Edit
proc record(t: var Tracer; begin: bool; payload: PayloadId) {.inline, ...raises: [], tags: [TimeEffect].}
- Records an begin/end event with the given payload. A payload can be associated with an unlimited amount of events Source Edit
proc startTracer(): Tracer {....raises: [], tags: [TimeEffect].}
- Intializes a new Tracer instance and returns it. The start time is initialized with the current time and the start event is recorded Source Edit