package tracy-client

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

Install

Dune Dependency

Authors

Maintainers

Sources

tracy-client-0.1.tbz
sha256=287fa7ad450f43951925ac119ad6b3b1e485a3942652e5bf9b483e49800ae772
sha512=72152274402cd2d2ad0c7e3ba0b3896c0bc1ab92d021460da94a2f9fe634759b2021d70d8175b3269aa6197b7917449007e96b53a8ccd8d534b50debd1b5162b

Description

Published: 12 Jun 2023

README

OCaml-tracy

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. 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.3"
  2. ocaml >= "4.08"
  3. dune >= "2.7"

Dev Dependencies (1)

  1. odoc with-doc

Used by

None

Conflicts

None

OCaml

Innovation. Community. Security.