Crate tracing_tracy

source ·
Expand description

Collect Tracy profiles in tracing-enabled applications.

Assuming the application is well instrumented, this should in practice be a very low effort way to gain great amounts of insight into an application performance.

Note, however that Tracy is ultimately a profiling, not an observability, tool. As thus, some of tracing concepts cannot be represented well by Tracy. For instance, out-of-order span entries and exits, are not supported, and neither are spans that are entered and exited on different threads. This crate will attempt to mitigate the problems and retain trace validity at the cost of potentially invalid data. When such a mitigation occurs, trace will contain a message with a note about the problem.

Some other caveats to keep in mind:

  • Only span entries and exits are recorded;
  • Events show up as messages in Tracy, however Tracy can struggle with large numbers of messages;
  • Some additional functionality such as plotting and memory allocation profiling is only available as part of the tracy-client crate.

§Examples

The most basic way to setup the tracy subscriber globally is as follows:

use tracing_subscriber::layer::SubscriberExt;

tracing::subscriber::set_global_default(
    tracing_subscriber::registry().with(tracing_tracy::TracyLayer::default())
).expect("setup tracy layer");

§Important note

Depending on the configuration Tracy may broadcast discovery packets to the local network and expose the data it collects in the background to that same network. Traces collected by Tracy may include source and assembly code as well.

As thus, you may want make sure to only enable the tracing-tracy crate conditionally, via the enable feature flag provided by this crate.

§Features

The following crate features are provided to customize the functionality of the Tracy client:

  • enable – enables the Tracy client. Corresponds to the TRACY_ENABLE define.
  • flush-on-exit – waits for Tracy to connect and read out the profiling data before the program terminates. Corresponds to the TRACY_NO_EXIT define. Does not work in combination with the manual-lifetime feature.
  • manual-lifetime – allow for manual initialization and deinitialization of the profiler data structures. Corresponds to the TRACY_MANUAL_LIFETIME define. tracy_client::Client transparently switches to manual lifetime management when this feature is enabled. Implies delayed-init.
  • system-tracing – enable capture of system level details. Corresponds to the TRACY_NO_SYSTEM_TRACING define.
  • context-switch-tracing – enable capture of the context switch data. Corresponds to the TRACY_NO_CONTEXT_SWITCH define.
  • sampling – enable periodic sampling of the call stack. Corresponds to the TRACY_NO_SAMPLING define.
  • code-transfer – enable transfer of the machine code to the profiler. Corresponds to the TRACY_NO_CODE_TRANSFER define.
  • broadcast – announce presence of the client to the profilers on the local network. Corresponds to the TRACY_NO_BROADCAST define.
  • only-localhost – listen for profilers on the localhost interface only. Corresponds to the TRACY_ONLY_LOCALHOST define.
  • only-ipv4 – listen for profilers on IPv4 interfaces only. Corresponds to the TRACY_ONLY_IPV4 define.
  • timer-fallback – allow running on devices without a high resolution timer support. Corresponds to the TRACY_TIMER_FALLBACK define.
  • ondemand – start collecting traces only when a server connects to the client. Corresponds to the TRACY_ON_DEMAND define.
  • fibers – enable support for instrumenting fibers, coroutines and similar such asynchrony primitives. Corresponds to the TRACY_FIBERS define.
  • callstack-inlines - enables resolution of inline frames for call stacks. Disabling it will make the profiler use the basic but much faster frame resolution mode. Corresponds to the TRACY_NO_CALLSTACK_INLINES define.
  • delayed-init – initializes trace structures upon a first request, rather than at load time. Corresponds to the TRACY_DELAYED_INIT define.
  • demangle - requires that the demangling function be defined by the user. See the register_demangler! macro for more details. Corresponds to the TRACY_DEMANGLE define.
  • verify - enables verification that instrumentation is well formed. Enabling this introduces additional instrumentation overhead (~50% for 0 callstack depth spans.) When disabled corresponds to the TRACY_NO_VERIFY define.
  • debuginfod - enables debuginfo for system libraries on systems supporting debuginfod. Corresponds to the TRACY_DEBUGINFOD define.

Refer to this package’s Cargo.toml for the list of the features enabled by default. Refer to the Tracy manual for more information on the implications of each feature.

Re-exports§

Structs§

Traits§

Functions§