nox-catapult#

Typed OCaml values and nox-json codecs for the Trace Event Format, the JSON trace format consumed by chrome://tracing, Perfetto and the Catapult tools.

Installation#

Install with opam:

$ opam install nox-catapult

If opam cannot find the package, it may not yet be released in the public opam-repository. Add the overlay repository, then install it:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install nox-catapult

Overview#

A trace is a list of events — spans, instants, counters, async operations, samples — each tagged with a single-character phase. This library models that format directly:

• Catapult.Event — one trace event: a Catapult.Phase.t plus the common members (name, cat, ts, pid, tid, dur, args, ...). Members the library does not type are kept verbatim and round-trip unchanged.
• Catapult.t — a whole trace in either container format: the JSON array format (events only, unterminated tail allowed) or the JSON object format (traceEvents plus stack frames, samples and metadata).
• Catapult.Writer — a streaming array-format emitter for producers; a crash loses at most the event being written and the resulting file is still readable.
• Catapult.merge and rewrite helpers — compose already-written Catapult files without inventing another telemetry model.

Usage#

Build a trace and serialize it:

# let trace =
    Catapult.v
      [
        Catapult.Event.process_name ~pid:1 "compiler";
        Catapult.Event.complete ~pid:1 ~tid:1 ~name:"parse" ~ts:10.
          ~dur:200. ();
      ]
  in
  print_string (Catapult.to_string trace)
[{"name":"process_name","ph":"M","ts":0,"pid":1,"args":{"name":"compiler"}},{"name":"parse","ph":"X","ts":10,"pid":1,"tid":1,"dur":200}]
- : unit = ()

Read a trace back, including crash-truncated array traces (the spec makes the closing ] optional so producers can append events without seeking):

# let t = Catapult.of_string_exn {|[{"ph": "B", "ts": 1}, {"ph": "E", "ts": 5},|} in
  List.map (fun (e : Catapult.Event.t) -> (Catapult.Phase.to_char e.ph, e.ts))
    t.events
- : (char * float) list = [('B', 1.); ('E', 5.)]

Stream events as they happen with Catapult.Writer, or pass Catapult.codec to any Json entry point for decoding with source locations or embedding traces in larger documents.

Merge traces collected from several producers:

let load path = In_channel.with_open_text path In_channel.input_all |> Catapult.of_string_exn

let merge_traces ~compiler_path ~worker_path =
  let compiler =
    load compiler_path
    |> Catapult.add_process_metadata ~pid:100 ~name:"compiler"
  in
  let worker =
    load worker_path
    |> Catapult.shift_time 2500.
    |> Catapult.set_pid 200
    |> Catapult.add_process_metadata ~pid:200 ~name:"worker"
  in
  Catapult.merge [ compiler; worker ]

Catapult.merge ?time_offset traces concatenates events and object-format extras. Stack-frame ids are namespaced by input index and sample references are rewritten, so profiler samples from different files cannot collide.

Related Work#

• catapult — an OCaml tracing client (probes, thread-local buffers, file/sqlite/daemon backends) that emits this format with hand-written JSON printing. This library is the complementary piece: a pure codec for the format itself, with decoding, typed values and nox-json integration, and no runtime tracing machinery.
• ocaml-trace — a tracing facade (the Logs of tracing); its trace-tef backend also emits this format with printf-built JSON. A facade backend could produce its output through Catapult.Writer instead.
• Perfetto and Catapult — the reference consumers of the format.

License#

MIT License. See LICENSE.md for details.