LTTng tooling

The 64-bit Linux version of the Synergy runtime is built with LTTng (Linux Trace Toolkit: next generation), which is not a Synergy utility but is supported by the runtime. LTTng is an open-source framework that enables the collection of metadata on a variety of metrics (e.g., how often routines are being used, how much CPU time and memory is being used, etc.) with very low impact on the running system. LTTng tooling allows detailed tracing of internal calls to help with debugging or performance profiling.

We recommend that you only use this tooling when instructed by Synergex.

The Synergy runtime currently uses LTTng 2.12. If you have a lower version of LTTng installed, tracing should still work, but some features may be limited. Higher versions of LTTng are not supported at this time.

In order to use LTTng tooling with Synergy programs, LTTng must be installed on your system. It is usually available through a package named lttng-tools, although details may vary between Linux distributions. Additional steps may be required to configure a package repository that provides LTTng. See The LTTng Documentation for details about installing LTTng.

To trace Synergy programs, you must create and start a session with the appropriate settings. For example,

$ lttng create my-session
$ lttng enable-event --session=my-session --userspace 'synergyde:*'
$ lttng add-context --userspace --type=vpid --type=vuid
$ lttng start

where my-session is the name you want to use for a session. This name will also be used in the names of the trace files.

The vpid and vuid types add additional information (process and user IDs) to logged events. They’re optional and may not be available in older versions of LTTng. You can limit the number of events logged by specifying the tracepoints instead of “synergyde:*”.

Once you’ve started a session, run your Synergy program to trace it. (Note that tracing only works on processes with the same user account used to start the LTTng session, unless the lttng-sessiond daemon was started as root.) To view logging, you must first stop the session:

$ lttng stop

You can then view logged tracepoints:

$ lttng view

The "lttng view" command uses the Babeltrace utility, which was probably installed at the same time as lttng-tools. You can also invoke Babeltrace manually to view the trace file from the current session or a previous session. For example,

babeltrace $HOME/lttng-traces/my-session-20240805-115046

The name and path of a trace file should be displayed when you initially create an LTTng session.

Before you trace again, you must destroy the current session ("lttng destroy") and start a new one. The "lttng view” command will no longer work after a session is destroyed, but you can still invoke Babeltrace manually to view previous sessions. Note that trace files can take up a significant amount of disk space, so you may want to delete older files periodically if you use LTTng tracing frequently.

If LTTng is installed, it’s enabled in the Synergy runtime by default, so any Synergy program will be traced if an LTTng session is running with synergyde events enabled. To disable, re-enable, or troubleshoot tracing in the runtime, use the ENABLE_LTTNG environment variable.

For more information about LTTng, see The LTTng Documentation.