qtrace_p.h File Reference

(c4b93e8ab8dbb49bfe71c13b6b7aae453edbd786)

#include <QtCore/private/qglobal_p.h>
#include <QtCore/qscopeguard.h>

Include dependency graph for qtrace_p.h:

Go to the source code of this file.

Macros
#define	Q_HAS_TRACEPOINTS   0
#define	Q_TRACE(x, ...)
#define	Q_TRACE_EXIT(x, ...)
#define	Q_TRACE_SCOPE(x, ...)
#define	Q_UNCONDITIONAL_TRACE(x, ...)
#define	Q_TRACE_ENABLED(x)

Macro Definition Documentation

Q_HAS_TRACEPOINTS

#define Q_HAS_TRACEPOINTS   0

Tracing needs to be enabled using configure -trace. As explained by configure --help, the backend can be given as an optional argument. Currently supported backends include LTTNG on Linux, ETW on Windows, and CTF (common trace format) as a cross-platform solution.

API

The Qt tracepoints API consists of five macros:

Macro	Behavior
Q_TRACE(tracepoint, args...)	Fires 'tracepoint' if it is enabled.
Q_TRACE_EXIT(tracepoint, args...)	Fires 'tracepoint' if it is enabled when the current scope exists.
Q_TRACE_SCOPE(tracepoint, args...)	Wrapper around Q_TRACE/_EXIT to trace entry and exit. First it traces ${tracepoint}_entry and then ${tracepoint}_exit on scope exit.
Q_UNCONDITIONAL_TRACE(tracepoint, args...)	Fires 'tracepoint' unconditionally: no check is performed to query whether 'tracepoint' is enabled.
Q_TRACE_ENABLED(tracepoint)	Returns 'true' if 'tracepoint' is enabled; false otherwise.

When using LTTNG, Q_TRACE(), Q_UNCONDITIONAL_TRACE() and Q_TRACE_ENABLED() map ultimately to tracepoint(), do_tracepoint() and tracepoint_enabled(), respectively, described on the lttng-ust manpage (man 3 lttng-ust).

On ETW, Q_TRACE() and Q_UNCONDITIONAL_TRACE() are equivalent, ultimately amounting to a call to TraceLoggingWrite(), whereas Q_TRACE_ENABLED() wraps around TraceLoggingProviderEnabled().

A tracepoint provider is defined in a separate file, that follows the following format:

tracepoint_name(arg_type arg_name, ...)

For instance:

qcoreapplication_ctor(int argc, const char * const argv)
qcoreapplication_foo(int argc, const char[10] argv)
qcoreapplication_baz(const char[len] some_string, unsigned int len)
qcoreapplication_qstring(const QString &foo)
qcoreapplication_qrect(const QRect &rect)

The provider file is then parsed by src/tools/tracegen (which gets built to libexec/tracegen), which can be switched to output ETW, CTF or LTTNG tracepoint definitions. The provider name is deduced to be basename(provider_file).

To use the above (inside qtcore), you need include <providername_tracepoints_p.h>. After that, the following call becomes possible:

Q_TRACE(qcoreapplication_qrect, myRect);

Currently, all C++ primitive non-pointer types are supported for arguments. Additionally, char * is supported, and is assumed to be a nullptr-terminated string. Finally, the following subset of Qt types are also currently supported:

• QString
• QByteArray
• QUrl
• QRect
• QRectF
• QSize
• QSizeF

Dynamic arrays are supported using the syntax illustrated by qcoreapplication_baz above.

One can also add prefix for the generated providername_tracepoints_p.h file by specifying it inside brackets { } in the tracepoints file. One can for example add a forward declaration for a type:

{
   QT_BEGIN_NAMESPACE
   class QEvent;
   QT_END_NAMESPACE
}

Metadata

Metadata is used to add textual information for different types such as enums and flags. How this data is handled depends on the used backend. For ETW, the values are converted to text; for CTF and LTTNG they are used to add CTF enumerations, which are converted to text after tracing.

Enumerations are specified using ENUM:

ENUM {
   Enum0 = 0,
   Enum1 = 1,
   Enum2,
   RANGE(RangeEnum, 3 ... 10),
} Name;

Name must match to one of the enumerations used in the tracepoints. Range of values can be provided using RANGE(name, first ... last). All values must be unique.

Flags are specified using FLAGS:

FLAGS {
   Default = 0,
   Flag0 = 1,
   Flag1 = 2,
   Flag2 = 4,
} Name;

Name must match to one of the flags used in the tracepoints. Each value must be power of two and unique.

The Qt tracepoints can also be defined directly in the source files using the macros Q_TRACE_INSTRUMENT(), Q_TRACE_PARAM_REPLACE(), Q_TRACE_POINT(), Q_TRACE_PREFIX() and Q_TRACE_METADATA(). If using these macros, the tracepoints file is automatically generated using the tracepointgen tool. The tool scans the input files for these macros. These macros are ignored during compile time. Both automatic generation and manually specifying tracepoints in a file can't be done at the same time for the same provider.

Note

Traces are not object-oriented. Often, the purpose of a specific tracepoint is to record the fact that a function was called; but you cannot see on which object instance a method was called, unless some information about the object (such as its pointer or ID) is given as one of the arguments to the trace macro. So far, we have not standardized that.

Definition at line 170 of file qtrace_p.h.

Q_TRACE

#define Q_TRACE	(		x,
			... )

This macro fires tracepoint if it is enabled.

Definition at line 175 of file qtrace_p.h.

Q_TRACE_ENABLED

#define Q_TRACE_ENABLED

(

x

)

Value:

false

This macro returns true if tracepoint is enabled, or false otherwise.

Definition at line 197 of file qtrace_p.h.

Q_TRACE_EXIT

#define Q_TRACE_EXIT	(		x,
			... )

This macro fires tracepoint if it is enabled when the current scope exits.

Definition at line 180 of file qtrace_p.h.

Q_TRACE_SCOPE

#define Q_TRACE_SCOPE	(		x,
			... )

This macro is a wrapper around Q_TRACE/_EXIT to trace entry and exit. First it traces {${tracepoint}_entry}, and then {${tracepoint}_exit} on scope exit.

Definition at line 186 of file qtrace_p.h.

Q_UNCONDITIONAL_TRACE

#define Q_UNCONDITIONAL_TRACE	(		x,
			... )

This macro fires tracepoint unconditionally: no check is performed to query whether tracepoint is enabled.

Definition at line 192 of file qtrace_p.h.