eventlog-tools

eventlog-tools is a library and set of tools to parse and interact with traces generated by the Multicore OCaml instrumented runtime (4.12+domains+effects) and higher.

Installation

You can install this package through OPAM.

opam pin eventlog-tools .

It will install the eventlog-tools library, as well as ocaml-eventlog-to_chrome:

• ocaml-eventlog-to-chrome takes an eventlog tracefile as an input, as well as an output file path as output. It will generate a JSON file to be loaded inside Google Chrome's chrome:\\tracing viewer.

Getting started with the instrumented runtime

You can generate a trace file for any OCaml (starting with OCaml 4.11) by compiling it with the appropriate flags.

Here is a sample program:

module SMap = Map.Make(String)

let s i = String.make 512 (Char.chr (i mod 256))

let clear map = SMap.fold (fun k _ m -> SMap.remove k m) map map

let rec seq i = if i = 0 then Seq.empty else fun () -> (Seq.Cons (i, seq (i - 1)))

let () =
  seq 1_000_000
  |> Seq.fold_left (fun m i -> SMap.add (s i) i m) SMap.empty
  |> clear
  |> ignore

To enable instrumentation while compiling this program, you need to use the -runtime-variant=i flag.

ocamlopt -runtime-variant=i program.ml -o program.exe

This can also be achieved with dune using the flag stanza:

(executable
  (name program)
 (flags "-runtime-variant=i"))

To run, and enable tracing in the freshly compiled program, do as follow:

OCAML_EVENTLOG_ENABLED=1 ./program.exe

Which will create new files in the running directory, named caml-$pid-$domain_id.eventlog. where $pid is the initial pid of the program, and $domain_id represents the domain id of each domains started by the program.

●●●● ls
caml-180445-0.eventlog caml-180445-2.eventlog caml-180445-4.eventlog  program.cmi  program.cmx  program.exe*  program.ml  program.o

Note that the OCAML_EVENTLOG_PREFIX environment variable can also be used to prefix the generated filenames. For instances, if you have a subdir trace, you can use OCAML_EVENTLOG_PREFIX=trace/prefix to tell the runtime to generate the files in this directory, prefixing these by trace/prefix

●●●● OCAML_EVENTLOG_ENABLED=1 OCAML_EVENTLOG_PREFIX=test_trace/prefix ./a.out
wait OK
sleep OK
●●●● ls test_trace/
prefix-caml-215814-0.eventlog  prefix-caml-215814-258.eventlog  prefix-caml-215814-2.eventlog

We can now read this file using the tools provided by this package.

ocaml-eventlog-to-chrome

This tool allows to convert a tool from OCaml's CTF schema to the Catapult format used by the Google Chrome's trace viewing utility, chrome:/tracing.

●●●● ocaml-eventlog-to-chrome test_trace/ -o out.json
     # alternatively, you can pass as an argument a single tracefile, or many tracefiles (like caml-eventlog-*)
●●●● ocaml-eventlog-to-chrome test_trace/prefix-caml-* -o out.json
●●●● ocaml-eventlog-to-chrome test_trace/prefix-caml-215814-258.eventlog -o out.json

Note that in the case where you only pass one or a few select files, you will only find in the result profile the trace data for this specific domains. A complete trace should include all domains, but it can be useful, for filesize purpose, to inspect it domain by domain.

You can then head to the address chrome://tracing in Google Chrome and load the newly generated out.json file.