Skip to main content
`Ctrl`+`K`

# Tracing Guide

Guide to tracing in libcamera.

## Profiling vs Tracing

Tracing is recording timestamps at specific locations. libcamera provides a tracing facility. This guide shows how to use this tracing facility.

Tracing should not be confused with profiling, which samples execution at periodic points in time. This can be done with other tools such as callgrind, perf, gprof, etc., without modification to the application, and is out of scope for this guide.

## Compiling

To compile libcamera with tracing support, it must be enabled through the meson `tracing` option. It depends on the lttng-ust library (available in the `liblttng-ust-dev` package for Debian-based distributions). By default the tracing option in meson is set to `auto`, so if liblttng is detected, it will be enabled by default. Conversely, if the option is set to disabled, then libcamera will be compiled without tracing support.

## Defining tracepoints

libcamera already contains a set of tracepoints. To define additional tracepoints, create a file `include/libcamera/internal/tracepoints/{file}.tp`, where `file` is a reasonable name related to the category of tracepoints that you wish to define. For example, the tracepoints file for the Request object is called `request.tp`. An entry for this file must be added in `include/libcamera/internal/tracepoints/meson.build`.

In this tracepoints file, define your tracepoints as mandated by lttng. The header boilerplate must not be included (as it will conflict with the rest of our infrastructure), and only the tracepoint definitions (with the `TRACEPOINT_*` macros) should be included.

All tracepoint providers shall be `libcamera`. According to lttng, the tracepoint provider should be per-project; this is the rationale for this decision. To group tracepoint events, we recommend using `{class_name}_{tracepoint_name}`, for example, `request_construct` for a tracepoint for the constructor of the Request class.

Tracepoint arguments may take C++ objects pointers, in which case the usual C++ namespacing rules apply. The header that contains the necessary class definitions must be included at the top of the tracepoint provider file.

Note: the final parameter in `TP_ARGS` must not have a trailing comma, and the parameters to `TP_FIELDS` are space-separated. Not following these will cause compilation errors.

## Using tracepoints (in libcamera)

To use tracepoints in libcamera, first the header needs to be included:

`#include "libcamera/internal/tracepoints.h"`

Then to use the tracepoint:

`LIBCAMERA_TRACEPOINT({tracepoint_event}, args...)`

This macro must be used, as opposed to lttng’s macros directly, because lttng is an optional dependency of libcamera, so the code must compile and run even when lttng is not present or when tracing is disabled.

The tracepoint provider name, as declared in the tracepoint definition, is not included in the parameters of the tracepoint.

There are also two special tracepoints available for tracing IPA calls:

`LIBCAMERA_TRACEPOINT_IPA_BEGIN({pipeline_name}, {ipa_function})`

`LIBCAMERA_TRACEPOINT_IPA_END({pipeline_name}, {ipa_function})`

These shall be placed where an IPA function is called from the pipeline handler, and when the pipeline handler receives the corresponding response from the IPA, respectively. These are the tracepoints that our sample analysis script (see “Analyzing a trace”) scans for when computing statistics on IPA call time.

## Using tracepoints (from an application)

As applications are not part of libcamera, but rather users of libcamera, applications should seek their own tracing mechanisms. For ease of tracing the application alongside tracing libcamera, it is recommended to also use lttng.

## Using tracepoints (from closed-source IPA)

Similar to applications, closed-source IPAs can simply use lttng on their own, or any other tracing mechanism if desired.

## Collecting a trace

A trace can be collected fairly simply from lttng:

    lttng create $SESSION_NAME
    lttng enable-event -u libcamera:\*
    lttng start
    # run libcamera application
    lttng stop
    lttng view
    lttng destroy $SESSION_NAME

See the lttng documentation for further details.

The location of the trace file is printed when running `lttng create $SESSION_NAME`. After destroying the session, it can still be viewed by: `lttng view -t $PATH_TO_TRACE`, where `$PATH_TO_TRACE` is the path that was printed when the session was created. This is the same path that is used when analyzing traces programatically, as described in the next section.

## Analyzing a trace

As mentioned above, while an lttng tracing session exists and the trace is not running, the trace output can be viewed as text by `lttng view`.

The trace log can also be viewed as text using babeltrace2. See the lttng trace analysis documentation for further details.

babeltrace2 also has a C API and python bindings that can be used to process traces. See the lttng python bindings documentation and the lttng C API documentation for more details.

As an example, there is a script `utils/tracepoints/analyze-ipa-trace.py` that gathers statistics for the time taken for an IPA function call, by measuring the time difference between pairs of events `libcamera:ipa_call_start` and `libcamera:ipa_call_finish`.