Legend:
Library
Module
Module type
Parameter
Class
Class type
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.
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.
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.
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.
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_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.