package tracy-client

  1. Overview
  2. Docs
Client bindings to the Tracy profiler (v0.10)

Install

Dune Dependency

Authors

Maintainers

Sources

tracy-client-0.5.tbz
sha256=11053d178438a76b94680275a46cedb79225da8bf72eb886787b404123ce6516
sha512=87b7d1fbd75b90a4881aa91fc86f85f1d7fa3a1ae54293f64a191294c7347840cd7954e0792887dbca40efa9cfed0f183926e2b1fa885b4f7b7d788c65c099e8

Description

Published: 28 Aug 2024

README

OCaml Tracy-client

This repo contains bindings to Tracy, a profiler and trace visualizer. It's licensed, like Tracy, under BSD-3-Clause.

The bindings are pretty basic and go through the C API, not the C++ one (RAII is not compatible with having a function call to enter, and one to exit).

It depends on a C++ compiler to build, along with the dependencies of Tracy-client.

Feature table

feature supported
zones
messages
plots
locks
screenshots
frames
gpu
fibers

In some cases the feature might not provide all options.

Example

The file examples/prof1.ml shows basic instrumentation on a program that computes the Fibonacci function (yes, not representative) in a loop on 3 threads. If Tracy is running and is waiting for a connection (press "connect"), running dune exec ./examples/prof1.exe should start tracing and display something like this:

Usage

  • the tracy_client library contains the bindings and can be used directly in OCaml programs. The Tracy C++ client is vendored and will be bundled along with the bindings.

    For example in prof1.ml, we start with:

    module T = Tracy_client
    T.name_thread (Printf.sprintf "thread_%d" th_n);
    

    to name the n-th worker thread. Then later we have calls like:

    T.with_ ~file:__FILE__ ~line:__LINE__ "inner.fib" @@ fun _sp ->
    T.set_color _sp 0xaa000f;
    (* rest of code in the span _sp *)
    …
    

    to create a span in Tracy, with a custom color, and the name inner.fib. One can also add text and values to the span. Alternatively, Tracy_client.enter and Tracy_client.exit can be used to delimit the span manually.

    The client automatically tries to connect to Tracy on startup.

    A pretty convenient helper is:

    let (let@) = (@@)
    

    to then be able to write spans this way:

    let@ _sp = T.with_ ~file:__FILE__ ~line:__LINE__ "inner.fib" in
    T.set_color _sp 0xaa000f;
    (* rest of code in the span _sp *)
    …
    

    For example, in a nested loop:

    let run n =
      for i=0 to n do
        let@ _sp = T.with_ ~file:__FILE__ ~line:__LINE__ "outer-loop" in
        for j=0 to n do
          let@ _sp = T.with_ ~file:__FILE__ ~line:__LINE__ "inner-loop" in
          (* do actual computation here with [i] and [j] *)
        done
      done
    
  • The library tracy-client.trace turns tracy-client into a collector for trace, which is a generic tracing library.

    In that case, Tracy_client_trace.setup() needs to be called at the beginning of the program.

Dependencies (3)

  1. trace >= "0.6" & < "0.7"
  2. ocaml >= "4.08"
  3. dune >= "2.7"

Dev Dependencies (1)

  1. odoc with-doc

Used by

None

Conflicts

None

OCaml

Innovation. Community. Security.