[verse]
#define *TRACEPOINT_ENUM*('prov_name', 'enum_name', 'mappings')
#define *TRACEPOINT_EVENT*('prov_name', 't_name', 'args', 'fields')
-#define *TRACEPOINT_EVENT_CLASS*('prov_name', 'class_name',
- 'args', 'fields')
-#define *TRACEPOINT_EVENT_INSTANCE*('prov_name', 'class_name',
- 't_name', 'args')
+#define *TRACEPOINT_EVENT_CLASS*('prov_name', 'class_name', 'args', 'fields')
+#define *TRACEPOINT_EVENT_INSTANCE*('prov_name', 'class_name', 't_name', 'args')
#define *TRACEPOINT_LOGLEVEL*('prov_name', 't_name', 'level')
#define *ctf_array*('int_type', 'field_name', 'expr', 'count')
#define *ctf_array_nowrite*('int_type', 'field_name', 'expr', 'count')
+#define *ctf_array_hex*('int_type', 'field_name', 'expr', 'count')
+#define *ctf_array_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
+#define *ctf_array_network*('int_type', 'field_name', 'expr', 'count')
+#define *ctf_array_network_nowrite*('int_type', 'field_name', 'expr', 'count')
+#define *ctf_array_network_hex*('int_type', 'field_name', 'expr', 'count')
+#define *ctf_array_network_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
#define *ctf_array_text*(char, 'field_name', 'expr', 'count')
#define *ctf_array_text_nowrite*(char, 'field_name', 'expr', 'count')
#define *ctf_enum*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr')
-#define *ctf_enum_nowrite*('prov_name', 'enum_name', 'int_type',
- 'field_name', 'expr')
+#define *ctf_enum_nowrite*('prov_name', 'enum_name', 'int_type', 'field_name',
+ 'expr')
#define *ctf_enum_value*('label', 'value')
#define *ctf_enum_range*('label', 'start', 'end')
#define *ctf_float*('float_type', 'field_name', 'expr')
#define *ctf_integer_network_hex*('int_type', 'field_name', 'expr')
#define *ctf_integer_nowrite*('int_type', 'field_name', 'expr')
#define *ctf_sequence*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
-#define *ctf_sequence_nowrite*('int_type', 'field_name', 'expr',
- 'len_type', 'len_expr')
+#define *ctf_sequence_nowrite*('int_type', 'field_name', 'expr', 'len_type',
+ 'len_expr')
+#define *ctf_sequence_hex*('int_type', 'field_name', 'expr', 'len_type',
+ 'len_expr')
+#define *ctf_sequence_nowrite_hex*('int_type', 'field_name', 'expr', 'len_type',
+ 'len_expr')
+#define *ctf_sequence_network*('int_type', 'field_name', 'expr', 'len_type',
+ 'len_expr')
+#define *ctf_sequence_network_nowrite*('int_type', 'field_name', 'expr',
+ 'len_type', 'len_expr')
+#define *ctf_sequence_network_hex*('int_type', 'field_name', 'expr', 'len_type',
+ 'len_expr')
+#define *ctf_sequence_network_nowrite_hex*('int_type', 'field_name', 'expr',
+ 'len_type', 'len_expr')
#define *ctf_sequence_text*(char, 'field_name', 'expr', 'len_type', 'len_expr')
-#define *ctf_sequence_text_nowrite*(char, 'field_name', 'expr',
- 'len_type', 'len_expr')
+#define *ctf_sequence_text_nowrite*(char, 'field_name', 'expr', 'len_type',
+ 'len_expr')
#define *ctf_string*('field_name', 'expr')
#define *ctf_string_nowrite*('field_name', 'expr')
#define *do_tracepoint*('prov_name', 't_name', ...)
*ctf_string*('field_name', 'expr')
*ctf_string_nowrite*('field_name', 'expr')
-Statically-sized array of integers:
+Statically-sized array of integers (`_hex` versions displayed in
+hexadecimal, `_network` versions in network byte order):
[verse]
*ctf_array*('int_type', 'field_name', 'expr', 'count')
*ctf_array_nowrite*('int_type', 'field_name', 'expr', 'count')
+*ctf_array_hex*('int_type', 'field_name', 'expr', 'count')
+*ctf_array_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
+*ctf_array_network*('int_type', 'field_name', 'expr', 'count')
+*ctf_array_network_nowrite*('int_type', 'field_name', 'expr', 'count')
+*ctf_array_network_hex*('int_type', 'field_name', 'expr', 'count')
+*ctf_array_network_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
Statically-sized array, printed as text; no need to be null-terminated:
*ctf_array_text*(char, 'field_name', 'expr', 'count')
*ctf_array_text_nowrite*(char, 'field_name', 'expr', 'count')
-Dynamically-sized array of integers:
+Dynamically-sized array of integers (`_hex` versions displayed in
+hexadecimal, `_network` versions in network byte order):
[verse]
*ctf_sequence*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
*ctf_sequence_nowrite*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
+*ctf_sequence_hex*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
+*ctf_sequence_nowrite_hex*('int_type', 'field_name', 'expr', 'len_type',
+ 'len_expr')
+*ctf_sequence_network*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
+*ctf_sequence_network_nowrite*('int_type', 'field_name', 'expr', 'len_type',
+ 'len_expr')
+*ctf_sequence_network_hex*('int_type', 'field_name', 'expr', 'len_type',
+ 'len_expr')
+*ctf_sequence_network_nowrite_hex*('int_type', 'field_name', 'expr',
+ 'len_type', 'len_expr')
Dynamically-sized array, displayed as text; no need to be null-terminated:
The parameters are:
-'int_type'::
- Integer C type. The size of this type determines the size of the
- integer/enumeration field.
-
-'float_type'::
- Float C type (`float` or `double`). The size of this type determines
- the size of the floating point number field.
+'count'::
+ Number of elements in array/sequence. This must be known at
+ compile time.
-'field_name'::
- Event field name (C identifier syntax, :not: a literal string).
+'enum_name'::
+ Name of an enumeration field previously defined with the
+ `TRACEPOINT_ENUM()` macro. See the
+ <<tracepoint-enum,`TRACEPOINT_ENUM()` usage>> section for more
+ information.
'expr'::
C expression resulting in the field's value. This expression can
of a given tracepoint are defined in the `TP_ARGS()` macro (see
the <<creating-tp,Creating a tracepoint provider>> section above).
-'count'::
- Number of elements in array/sequence. This must be known at
- compile time.
+'field_name'::
+ Event field name (C identifier syntax, :not: a literal string).
-'len_type'::
- Unsigned integer C type of sequence's length.
+'float_type'::
+ Float C type (`float` or `double`). The size of this type determines
+ the size of the floating point number field.
+
+'int_type'::
+ Integer C type. The size of this type determines the size of the
+ integer/enumeration field.
'len_expr'::
C expression resulting in the sequence's length. This expression
can use one or more arguments passed to the tracepoint.
+'len_type'::
+ Unsigned integer C type of sequence's length.
+
'prov_name'::
Tracepoint provider name. This must be the same as the tracepoint
provider name used in a previous field definition.
-'enum_name'::
- Name of an enumeration field previously defined with the
- `TRACEPOINT_ENUM()` macro. See the
- <<tracepoint-enum,`TRACEPOINT_ENUM()` usage>> section for more
- information.
-
The `_nowrite` versions omit themselves from the recorded trace, but are
otherwise identical. Their primary purpose is to make some of the
event context available to the event filters without having to commit
the process namespace.
+[[state-dump]]
LTTng-UST state dump
~~~~~~~~~~~~~~~~~~~~
If an application that uses `liblttng-ust` becomes part of a tracing
session, information about its currently loaded shared objects, their
-build IDs, and their debug link informations are emitted as events
+build IDs, and their debug link information are emitted as events
by the tracer.
The following LTTng-UST state dump events exist and must be enabled
+
This event has no fields.
-`lttng_ust_statedump:soinfo`::
- Emitted when information about a currently loaded shared object is
- found.
+`lttng_ust_statedump:bin_info`::
+ Emitted when information about a currently loaded executable or
+ shared object is found.
+
Fields:
+
[options="header"]
-|==============================================================
-| Field name | Description
-| `baddr` | Base address of loaded library
-| `memsz` | Size of loaded library in memory
-| `sopath` | Path to loaded library file
-|==============================================================
+|===
+|Field name |Description
+
+|`baddr`
+|Base address of loaded executable.
+
+|`memsz`
+|Size of loaded executable in memory.
+
+|`path`
+|Path to loaded executable file.
+
+|`is_pic`
+|Whether the executable is position-independent code.
+|===
`lttng_ust_statedump:build_id`::
Emitted when a build ID is found in a currently loaded shared
Fields:
+
[options="header"]
-|==============================================================
-| Field name | Description
-| `baddr` | Base address of loaded library
-| `build_id` | Build ID
-|==============================================================
+|===
+|Field name |Description
+
+|`baddr`
+|Base address of loaded library.
+
+|`build_id`
+|Build ID.
+|===
`lttng_ust_statedump:debug_link`::
Emitted when debug link information is found in a currently loaded
Fields:
+
[options="header"]
-|==============================================================
-| Field name | Description
-| `baddr` | Base address of loaded library
-| `crc` | Debug link file's CRC
-| `filename` | Debug link file name
-|==============================================================
+|===
+|Field name |Description
+
+|`baddr`
+|Base address of loaded library.
+
+|`crc`
+|Debug link file's CRC.
+
+|`filename`
+|Debug link file name.
+|===
[[example]]
sections. The <<build-static,static linking>> method is chosen here
to link the application with the tracepoint provider.
-Let's start with the tracepoint provider header file (`tp.h`):
+You can compile the source files and link them together statically
+like this:
+
+[role="term"]
+-------------------------------------
+cc -c -I. tp.c
+cc -c app.c
+cc -o app tp.o app.o -llttng-ust -ldl
+-------------------------------------
+
+Using the man:lttng(1) tool, create an LTTng tracing session, enable
+all the events of this tracepoint provider, and start tracing:
+
+[role="term"]
+----------------------------------------------
+lttng create my-session
+lttng enable-event --userspace 'my_provider:*'
+lttng start
+----------------------------------------------
+
+You may also enable specific events:
+
+[role="term"]
+----------------------------------------------------------
+lttng enable-event --userspace my_provider:big_event
+lttng enable-event --userspace my_provider:event_instance2
+----------------------------------------------------------
+
+Run the application:
+
+[role="term"]
+--------------------
+./app some arguments
+--------------------
+
+Stop the current tracing session and inspect the recorded events:
+
+[role="term"]
+----------
+lttng stop
+lttng view
+----------
+
+
+Tracepoint provider header file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+`tp.h`:
------------------------------------------------------------------------
#undef TRACEPOINT_PROVIDER
#include <lttng/tracepoint-event.h>
------------------------------------------------------------------------
-The tracepoint provider source file looks like this (`tp.c`):
+
+Tracepoint provider source file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+`tp.c`:
------------------------------------------------------------------------
#define TRACEPOINT_CREATE_PROBES
#include "tp.h"
------------------------------------------------------------------------
-The included `app.h`, where the application structure resides, is:
+
+Application header file
+~~~~~~~~~~~~~~~~~~~~~~~
+`app.h`:
------------------------------------------------------------------------
#ifndef _APP_H
#endif /* _APP_H */
------------------------------------------------------------------------
-Finally, the application itself, `app.c`, using the defined tracepoints:
+
+Application source file
+~~~~~~~~~~~~~~~~~~~~~~~
+`app.c`:
------------------------------------------------------------------------
#include <stdlib.h>
}
------------------------------------------------------------------------
-Here are the steps to compile the source files and link them together
-statically:
-[role="term"]
--------------------------------------
-cc -c -I. tp.c
-cc -c app.c
-cc -o app tp.o app.o -llttng-ust -ldl
--------------------------------------
+ENVIRONMENT VARIABLES
+---------------------
+`LTTNG_HOME`::
+ Alternative user's home directory. This variable is useful when the
+ user running the instrumented application has a non-writable home
+ directory.
++
+Unix sockets used for the communication between `liblttng-ust` and the
+LTTng session and consumer daemons (part of the LTTng-tools project)
+are located in a specific directory under `$LTTNG_HOME` (or `$HOME` if
+`$LTTNG_HOME` is not set).
+
+`LTTNG_UST_BLOCKING_RETRY_TIMEOUT`::
+ Maximum duration (milliseconds) to retry event tracing when
+ there's no space left for the event record in the sub-buffer.
++
+--
+`0` (default)::
+ Never block the application.
+
+Positive value::
+ Block the application for the specified number of milliseconds. If
+ there's no space left after this duration, discard the event
+ record.
+
+Negative value::
+ Block the application until there's space left for the event record.
+--
++
+This option can be useful in workloads generating very large trace data
+throughput, where blocking the application is an acceptable trade-off to
+prevent discarding event records.
++
+WARNING: Setting this environment variable to a non-zero value may
+significantly affect application timings.
+
+`LTTNG_UST_CLOCK_PLUGIN`::
+ Path to the shared object which acts as the clock override plugin.
+ An example of such a plugin can be found in the LTTng-UST
+ documentation under
+ https://github.com/lttng/lttng-ust/tree/master/doc/examples/clock-override[`examples/clock-override`].
+
+`LTTNG_UST_DEBUG`::
+ Activates `liblttng-ust`'s debug and error output if set to `1`.
+
+`LTTNG_UST_GETCPU_PLUGIN`::
+ Path to the shared object which acts as the `getcpu()` override
+ plugin. An example of such a plugin can be found in the LTTng-UST
+ documentation under
+ https://github.com/lttng/lttng-ust/tree/master/doc/examples/getcpu-override[`examples/getcpu-override`].
+
+`LTTNG_UST_REGISTER_TIMEOUT`::
+ Waiting time for the _registration done_ session daemon command
+ before proceeding to execute the main program (milliseconds).
++
+The value `0` means _do not wait_. The value `-1` means _wait forever_.
+Setting this environment variable to `0` is recommended for applications
+with time constraints on the process startup time.
++
+Default: {lttng_ust_register_timeout}.
+
+`LTTNG_UST_BLOCKING_RETRY_TIMEOUT`::
+ Maximum time during which event tracing retry is attempted on buffer
+ full condition (millliseconds). Setting this environment to non-zero
+ value effectively blocks the application on buffer full condition.
+ Setting this environment variable to non-zero values may
+ significantly affect application timings. Setting this to a negative
+ value may block the application indefinitely if there is no consumer
+ emptying the ring buffer. The delay between retry attempts is the
+ minimum between the specified timeout value and 100ms. This option
+ can be useful in workloads generating very large trace data
+ throughput, where blocking the application is an acceptable
+ trade-off to not discard events. _Use with caution_.
++
+The value `0` means _do not retry_. The value `-1` means _retry forever_.
+Value > `0` means a maximum timeout of the given value.
++
+Default: {lttng_ust_blocking_retry_timeout}.
+
+`LTTNG_UST_WITHOUT_BADDR_STATEDUMP`::
+ Prevents `liblttng-ust` from performing a base address state dump
+ (see the <<state-dump,LTTng-UST state dump>> section above) if
+ set to `1`.
include::common-footer.txt[]
projects / lttng-ust.git / blobdiff