Module Tracing_zero.Writer

include Writer_intf.S
type t
val close : t -> unit
module Tick_translation = Writer_intf.Tick_translation
val make_tick_translation : unit -> Tick_translation.t
val write_tick_initialization : t -> Tick_translation.t -> unit
module String_id : sig ... end
val max_interned_string_length : int
val intern_string : t -> string -> String_id.t

Intern a string into the trace so that it can be referred to with very low cost. Note that this does not check if the string has already been interned, see intern_string_cached.

Note that only around 32k strings can be interned this way, so use it for things like identifiers where there won't be that many. See set_temp_string_slot for things like string arguments with many possible values.

See the comment at the top of lib/tracing/src/trace.mli for more info on string interning.

val set_temp_string_slot : t -> slot:int -> string -> String_id.t

This interns a string while re-using a set of 100 reserved string IDs (by default, the number can be overriden at writer creation). Setting the string in a slot overwrites what was previously in that slot so any further events written in the trace see the new value. This allows arbitrarily many unique strings to be used in a trace, unlike intern_string.

val num_temp_strs : t -> int
module Thread_id : sig ... end

The trace format interns the 64 bit thread and process IDs into an 8-bit thread ID and we expose this to the user.

val set_thread_slot : t -> slot:int -> pid:int -> tid:int -> Thread_id.t

Similar to set_temp_string_slot, interns a thread into a slot ID, overwriting any thread which may have previously been in that slot. The number of thread slots is very limited (0<=slot<255) so you may need to manage them carefully.

If a pid is the same as the tid, Perfetto will consider that thread a "main thread" and sort it first among the threads, contrary to its usual alphabetical sorting by thread name. So if you don't want this to happen allocate tids such that they're never the same as a pid.

Note that Perfetto doesn't require tids to be unique across different pids, but the Fuchsia Trace Format spec implies they should be. I think it's safe to assume that any tool Jane Street uses will allow per-process tids but it's still safer to make them globally unique.

val set_process_name : t -> pid:int -> name:String_id.t -> unit

Sets the name on the collapsible process section header in the UI.

Perfetto sorts these headers by pid.

val set_thread_name : t -> pid:int -> tid:int -> name:String_id.t -> unit

Sets the name on a thread track.

Perfetto sorts threads within a process alphabetically.

module Arg_types : sig ... end

Events are written with a header which specifies how large the record is and how many arguments it has, which means you need to pre-commit to how many arguments of each type you will later write for an event. This is checked and will throw an exception if you write another event or close the writer without having written the correct arguments.

type 'a event_writer = t -> arg_types:Arg_types.t -> thread:Thread_id.t -> category:String_id.t -> name:String_id.t -> ticks:int -> 'a

Most event writer functions take a common set of arguments including a commitment to what event arguments will be added (arg_types), a thread the event occured on, a category which is an arbitrary string classifying the event visible in UIs and potentially used for filtering, a name that's the main label for the event, and a timestamp in "ticks" which defaults to nanoseconds since the start of the trace, but the format allows adjusting to other units like rdtsc clock cycles.

val write_instant : unit event_writer

An event with a time but no duration.

val write_counter : (counter_id:int -> unit) event_writer

A counters event uses its arguments to specify "counters" which may be represented by trace viewers as a chart over time. Its arguments must be numerical and there should be at least one.

The counter ID is in theory for associating events that should be plotted on the same graph but in practice Perfetto ignores it and uses the name. The Tracing.Trace wrapper chooses an ID based on the name to match this.

val write_duration_begin : unit event_writer

Begin a duration slice which will be finished with a matching end event.

val write_duration_end : unit event_writer

End a duration event, should be properly nested and with matching name/category

val write_duration_complete : (ticks_end:int -> unit) event_writer

A duration event where the start and end are known up front.

Takes 3*8 bytes instead of 2*2*8 bytes for separate events, saving 8 bytes per span

val write_async_begin : (async_id:int -> unit) event_writer

Begin an async slice. async_id disambiguates concurrent contexts.

val write_async_instant : (async_id:int -> unit) event_writer

Write an event with a time but no duration associated with an async context.

val write_async_end : (async_id:int -> unit) event_writer

End an async slice.

Flow events connect enclosing duration events with arrows in the trace viewer.

See Tracing.Flow.t to make it easier to write the correct flow event type.

val write_flow_begin : t -> thread:Thread_id.t -> ticks:int -> flow_id:int -> unit

Begins a flow, the chronologically first event in each flow must use this event.

Multiple flows with different IDs can start from one enclosing duration slice.

val write_flow_step : t -> thread:Thread_id.t -> ticks:int -> flow_id:int -> unit

An intermediate step in the flow that's neither the first or last step.

val write_flow_end : t -> thread:Thread_id.t -> ticks:int -> flow_id:int -> unit

Close a flow with a final step. Perfetto allows the flow_id to be re-used after.

module Write_arg : Writer_intf.Arg_writers with type t := t and type string_id := String_id.t

These argument writers need to be called immediately after an event writer with matching Arg_types counts for each type.

module Expert : sig ... end