This is the low-level zero-alloc API for writing Fuchsia Trace Format traces. The API pays some performance costs to check some format constraints on the events you write, but not too many.
Most users probably want to use the Tracing.Trace higher-level API instead. A large part of the purpose of this API was to figure out how to efficiently write FTF traces without allocating. The low-overhead probe path uses a bunch of the underlying code and approach from this interface although uses the Expert submodule to precompute event headers.
val create_for_file : ?num_temp_strs:int -> filename:string -> unit -> tAllocates a writer which writes to filename with num_temp_strs temporary string slots (see set_temp_string_slot), with increases in num_temp_strs reducing the number of strings which can be allocated with intern_string.
val close : t -> unitmodule Tick_translation : sig ... endval write_tick_initialization : t -> Tick_translation.t -> unitmodule String_id : sig ... endval intern_string : t -> string -> String_id.tIntern 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.tThis 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 -> intmodule Thread_id : sig ... endThe 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.tSimilar 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 -> unitSets 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 -> unitSets the name on a thread track.
Perfetto sorts threads within a process alphabetically.
module Arg_types : sig ... endEvents 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 ->
'aMost 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_writerAn event with a time but no duration
Note: instant events currently are not visible in the Perfetto UI.
val write_counter : (counter_id:int -> unit) event_writerA 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_writerBegin a duration slice which will be finished with a matching end event.
val write_duration_end : unit event_writerEnd a duration event, should be properly nested and with matching name/category
val write_duration_complete : (ticks_end:int -> unit) event_writerA 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
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 ->
unitBegins 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 ->
unitAn 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 ->
unitClose a flow with a final step. Perfetto allows the flow_id to be re-used after.
module Write_arg : sig ... endThese argument writers need to be called immediately after an event writer with matching Arg_types counts for each type.
module Expert : sig ... end