package tracing

  1. Overview
  2. Docs

This is a high-level API for parsing Fuchsia Trace Format traces created by a Tracing_zero.Writer.t (or one of the wrappers like Trace.t).

To create a parser, pass in an Iobuf.t containing the output of a trace. Each call to parse_next will advance through the iobuf and will either return a Fuchsia record or a parse error.

module Time_ns = Time_ns_unix
module Event_type : sig ... end
module Thread : sig ... end
module Parse_error : sig ... end
module Warnings : sig ... end
module String_index : sig ... end

String indices are in the range 1, 32767.

module Thread_index : sig ... end

Thread indices are in the range 1, 255.

module Event_arg : sig ... end
module Event : sig ... end
module Record : sig ... end
type t
val create : ?ignore_not_found:bool -> ?buffer:(Core.read, Iobuf.seek) Iobuf.t -> unit -> t

Creates parser. A buffer may be provided to start parsing from. Equivalently, the user may call set_buffer to initialize parsing.

If ignore_not_found is specified, the parser will not raise when parsing events that refer to interned thread and string indices that have not yet been set. Instead, the event will be returned including the unknown indices.

val set_buffer : t -> (Core.read, Iobuf.seek) Iobuf.t -> unit

Provides a new data buffer for the parser to continue reading from. Optionally prepends prefix to the buffer, allowing the user to preserve state returned by Parse_error.Incomplete_record. If the new buffer completes the record, it will be returned by the next call to parse_next.

val parse_next : t -> (Record.t, Parse_error.t) Core.Result.t

Advance through the trace until we find a Fuchsia record matching one of the record types defined above.

When Parse_error.No_more_words is returned, the buffer is left to point to the beginning of the incomplete record. Therefore, the next call to parse_next will attempt to parse the incomplete record again and return the error again.

When any other parse error is returned, the buffer is left to point to the beginning of the next record, having advanced past the record containing the error. Since we look at the record size to know how many words to skip, if the record size is incorrect then the parser may enter an invalid state and skip over records/read garbage values in the next call to parse_next.

val warnings : t -> Warnings.t
exception String_not_found
exception Thread_not_found
val ticks_per_second : t -> int
val base_time : t -> Time_ns.Option.t
val lookup_string_exn : t -> index:String_index.t -> string
val lookup_thread_exn : t -> index:Thread_index.t -> Thread.t
OCaml

Innovation. Community. Security.