package tracing

You can search for identifiers within the package.

in-package search v0.2.0

Tracing library

Install

Dune Dependency

github.com Readme Changelog MIT License Edit opam file Versions (3)

Authors

J

Jane Street Group, LLC

Maintainers

J

Jane Street developers

Sources

v0.17.0.tar.gz

sha256=5621f8fd41d64521cc88295417e48174f525a7e6e4f8a72885ba89056d461a72

doc/tracing.tracing_zero/Tracing_zero/Writer/index.html

Module `Tracing_zero.Writer`Source

include Writer_intf.S

Sourcetype t

Sourceval close : t -> unit

Sourcemodule Tick_translation = Writer_intf.Tick_translation

Sourceval make_tick_translation : unit -> Tick_translation.t

Sourceval write_tick_initialization : t -> Tick_translation.t -> unit

Sourcemodule String_id : sig ... end

Sourceval 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.

Sourceval 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.

Sourceval num_temp_strs : t -> int

Sourcemodule 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.

Sourceval 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.

Sourceval 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.

Sourceval 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.

Sourcemodule 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.

Source

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.

Sourceval write_instant : unit event_writer

An event with a time but no duration.

Sourceval 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.

Sourceval write_duration_begin : unit event_writer

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

Sourceval write_duration_end : unit event_writer

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

Sourceval 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

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

Begin an async slice. async_id disambiguates concurrent contexts.

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

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

Sourceval 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.

Source

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.

Source

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.

Source

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.

Source

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.

Sourcemodule Expert : sig ... end

package tracing

Install

Dune Dependency

Authors

Maintainers

Sources

doc/tracing.tracing_zero/Tracing_zero/Writer/index.html

Module Tracing_zero.WriterSource

Module `Tracing_zero.Writer`Source