6. PopVision trace instrumentation library

The PopVision trace instrumentation library (libpvti) provides functions to control the capture of profiling information for the host-code of your IPU application. This data can then be explored with the PopVision System Analyser.

6.1. Overview

When your application runs with tracing enabled (see Section 6.3, Configuring trace options) it will create a single trace file, which is named using the current date, time and process number. The name of the trace file can be retrieved as follows:

>>> import libpvti as pvti
>>> pvti.getCurrentTraceFilename()
'Thu_Aug_27_09:46:55_2020_BST_2341.pvti'

6.2. Tracepoints

The trace file will contain an event for each entry logged using pvti::Tracepoint::begin(), pvti::Tracepoint::end() or pvti::Tracepoint::event()

>>> pvti.Tracepoint.begin(pvti.traceDrivers, "begin event")

6.3. Configuring trace options

You can enable trace globally by setting the PVTI_OPTIONS environment variable:

export PVTI_OPTIONS='{"enable":"true"}'

If the environment variable is not set, no trace file is created and no events are logged. If the environment variable is set but cannot be parsed, trace will be enabled with all default options.

You can further configure trace behaviour using the following options:

• enable : Enable trace: true or false. Defaults to true if not set.

• directory : Directory where trace files should be stored. Defaults to the current directory if not set.

• channels : List of trace channels to enable. If empty or not set, all channels are enabled.

6.4. Channels

You can create your own trace channels and send trace events to them:

>>> traceCustom = createTraceChannel("Custom channel")

You can list the trace channels and whether they are enabled or not:

>>> pvti.listTraceChannel()
[['Drivers', True], ['Poplar', True], ['Framework', True]]

6.5. Enabling and disabling trace

You can enable individual trace channels at runtime. Events logged to disabled channels will not appear in the trace file

>>> pvti.disableTraceChannel(traceCustom)
>>> pvti.Tracepoint.event(traceCustom, "channel disabled: this event should not appear")

When you re-enable the channel, events will again be logged to the trace file as normal:

>>> pvti.enableTraceChannel(traceCustom)
>>> pvti.Tracepoint.end(traceCustom, "now events will be logged as normal")

6.6. Closing the trace file

The trace file will be closed when the program ends.

You can also call pvti::closeTrace() to close the trace file during execution. The program should not log any further events after this.

6.7. Python

Python has two additional approaches to instrument code. You can use a context manager or a decorator, as shown below.

Context manager:

>>> with pvti.Tracepoint(channel, "flowers"):
>>>    ...

Decorator:

>>> @pvti.instrument_fn(channel)
>>> def test_fn():
>>>    pass

6.8. C++ API

The C++ API is similar to the Python API. Channels are created as follows:

pvti::TraceChannel channel = {"Tests Channel"};

The following example produces a similar trace file to the Python examples above:

#include "pvti.hpp"
#include <iostream>

pvti::TraceChannel channel = {"C custom channel"};
int main(int argc, char **argv) {

  auto filename = pvti::getCurrentTraceFilename();

  std::cout << "Trace file is " << filename << std::endl;

  pvti::Tracepoint::begin(&pvti::traceDrivers, "begin");

  pvti::Tracepoint::begin(&channel, "begin on custom channel");

  pvti::Tracepoint::event(&channel, "another event on custom channel");

  pvti::disableTraceChannel(&channel);

  pvti::Tracepoint::event(&channel, "event while disabled, not logged");

  pvti::enableTraceChannel(&channel);

  pvti::Tracepoint::end(&channel, "now events are logged again");

  pvti::closeTrace();
}