Collaboration diagram for Recording session API:

Modules
	Recording session descriptor API

	Recording session destruction handle API

	Domain and event record channel API

	Map channel API

	Process filter API

	Recording session clearing API

	Recording session snapshot API

	Recording session rotation API

	Recording session saving and loading API

Data Structures
struct	lttng_handle
	Recording session handle. More...

struct	lttng_session
	Recording session summary. More...

Enumerations
enum	lttng_get_session_shm_path_status { LTTNG_GET_SESSION_SHM_PATH_STATUS_OK , LTTNG_GET_SESSION_SHM_PATH_STATUS_UNSET , LTTNG_GET_SESSION_SHM_PATH_STATUS_INVALID_PARAMETER }
	Return type of lttng_get_session_shm_path_override(). More...

enum	lttng_get_session_trace_format_status { LTTNG_GET_SESSION_TRACE_FORMAT_STATUS_OK , LTTNG_GET_SESSION_TRACE_FORMAT_STATUS_INVALID }
	Return type of lttng_get_session_trace_format(). More...

Functions
struct lttng_handle *	lttng_create_handle (const char session_name, const struct lttng_domain domain)
	Creates and returns a recording session handle from the recording session name `session_name` and the optional tracing domain summary `domain`.

int	lttng_create_session (const char session_name, const char output_url)
	Creates a recording session named `session_name` in local or network streaming mode, optionally setting its output URL to `output_url`.

enum lttng_error_code	lttng_create_session_ext (struct lttng_session_descriptor *session_descriptor)
	Creates a recording session from the recording session descriptor `session_descriptor`.

int	lttng_create_session_live (const char session_name, const char output_url, unsigned int live_timer_period)
	Creates a recording session named `session_name` in live mode, optionally setting its URL to `output_url`.

int	lttng_create_session_snapshot (const char session_name, const char output_url)
	Creates a recording session named `session_name` in snapshot mode, optionally setting the URL of its initial snapshot output to `output_url`.

int	lttng_data_pending (const char *session_name)
	Returns whether or not you may read the traces of the recording session named `session_name`.

void	lttng_destroy_handle (struct lttng_handle *handle)
	Destroys the recording session handle `handle`.

int	lttng_destroy_session (const char *session_name)
	Destroys the recording session named `session_name`, blocking until the operation completes.

enum lttng_error_code	lttng_destroy_session_ext (const char session_name, struct lttng_destruction_handle *handle)
	Initiates a destruction operation of the recording session named `session_name`.

int	lttng_destroy_session_no_wait (const char *session_name)
	Initiates the destruction operation of the recording session named `session_name`.

enum lttng_get_session_shm_path_status	lttng_get_session_shm_path_override (const struct lttng_session session, const char *shm_dir)
	Sets `*shm_dir` to the path of the custom directory on the local file system containing the shared memory files holding the event record channel ring buffers of the recording session summarized by `session`.

enum lttng_get_session_trace_format_status	lttng_get_session_trace_format (const struct lttng_session session, enum lttng_trace_format format)
	Sets `*format` to the trace format of the recording session summarized by `session`.

int	lttng_list_channels (const struct lttng_handle handle, struct lttng_channel *channels)
	Sets `*channels` to the summaries of the event record channels of the recording session handle `handle`.

int	lttng_list_domains (const char session_name, struct lttng_domain *domains)
	Sets `*domains` to the summaries of the tracing domains which contain at least one event record channel within the recording session named `session_name`.

int	lttng_list_sessions (struct lttng_session **sessions)
	Sets `*sessions` to the summaries of all the available recording sessions.

int	lttng_metadata_regenerate (const char *session_name)
	Regenerates the metadata streams of the recording session named `session_name`.

int	lttng_regenerate_metadata (const char *session_name)
	Regenerates the metadata streams of the recording session named `session_name`.

int	lttng_regenerate_statedump (const char *session_name)
	Regenerates the state dump event records of the recording session named `session_name`.

enum lttng_error_code	lttng_session_add_map_channel (const char session_name, const struct lttng_map_channel_descriptor descriptor)
	Adds the map channel described by `descriptor` to the recording session named `session_name`.

enum lttng_error_code	lttng_session_get_creation_time (const struct lttng_session session, uint64_t creation_timestamp)
	Sets `*creation_timestamp` to the timestamp of the creation of the recording session summarized by `session`.

enum lttng_error_code	lttng_session_get_map_channel_by_name (const char session_name, enum lttng_map_channel_type type, const char name, struct lttng_map_channel **channel)
	Sets `*channel` to the map channel of the recording session named `session_name` having the type `type` and the name `name`.

enum lttng_error_code	lttng_session_list_map_channels (const char session_name, enum lttng_map_channel_type type, struct lttng_map_channel_set *channels)
	Sets `*channels` to the map channels of the type `type` of the recording session named `session_name`.

int	lttng_set_session_shm_path (const char session_name, const char shm_dir)
	Sets the path of the directory containing the shared memory files holding the event record channel ring buffers of the recording session named `session_name` on the local file system to `shm_dir`.

int	lttng_start_tracing (const char *session_name)
	Makes the recording session named `session_name` active, starting all the tracers for its event record channels.

int	lttng_stop_tracing (const char *session_name)
	Makes the recording session named `session_name` inactive, stopping all the tracers for its event record channels, blocking until the operation completes.

int	lttng_stop_tracing_no_wait (const char *session_name)
	Makes the recording session named `session_name` inactive, stopping all the tracers for its event record channels without waiting for the operation to complete.

Detailed Description

A recording session is a stateful dialogue between an application and a session daemon for everything related to event recording.

Everything that you do when you control LTTng tracers to record events happens within a recording session. In particular, a recording session:

Has its own name, unique for a given session daemon.
Has its own set of trace files, if any.
Has its own state of activity (started or stopped).

An active recording session is an implicit recording event rule condition.

Similarly, LTTng only increments the values of the map channels of a recording session through “increment map value” trigger actions while the recording session is active.
Has its own mode (local, network streaming, snapshot, or live).
Has its own event record channels to which are attached their own recording event rules.
Has its own process filter.

Those attributes and objects are completely isolated between different recording sessions.

A recording session is like an ATM session: the operations you do on the banking system through the ATM don't alter the data of other users of the same system. In the case of the ATM, a session lasts as long as your bank card is inside. In the case of LTTng, a recording session lasts from a call to lttng_create_session_ext() to the completion of its destruction operation (which you can initiate with lttng_destroy_session_ext()).

A recording session belongs to a session daemon (see lttng-sessiond(8) and Session daemon connection). For a given session daemon, each Unix user has its own, private recording sessions. Note, however, that the root Unix user may operate on or destroy another user's recording session.

Each Unix user has its own, private recording sessions.

See also: The “RECORDING SESSION” section of lttng-concepts(7).

Operations

The recording session operations are:

Operation	Means
Creation	Create a recording session descriptor with one of the dedicated creation functions depending on the recording session mode. Call lttng_create_session_ext(), passing the recording session descriptor of step 1. When you're done with the recording session descriptor, destroy it with lttng_session_descriptor_destroy(). See also `lttng-create(1)`
Destruction	Call lttng_destroy_session_ext(), passing the name of the recording session to destroy. This function initiates a destruction operation, returning immediately. This function can set a pointer to a destruction handle (lttng_destruction_handle) so that you can wait for the completion of the operation. Without such a handle, you can't know when the destruction operation completes and whether or not it does successfully. If you have a destruction handle from step 1, then: Call lttng_destruction_handle_wait_for_completion() to wait for the completion of the destruction operation. Call lttng_destruction_handle_get_result() to get whether or not the destruction operation successfully completed. You can also call lttng_destruction_handle_get_rotation_state() and lttng_destruction_handle_get_archive_location() at this point. Destroy the destruction handle with lttng_destruction_handle_destroy(). See also `lttng-destroy(1)`
Basic property access	See: The members of lttng_session lttng_session_descriptor_get_session_name() lttng_session_get_creation_time() lttng_set_session_shm_path() lttng_data_pending() lttng_session_descriptor_set_trace_format() lttng_get_session_trace_format()
Tracing domain access	Call lttng_list_domains(), passing the name of the recording session of which to get the tracing domains. This function sets a pointer to an array of tracing domain summaries and returns the number of entries. Access the properties of each tracing domain summary through structure members. When you're done with the array of tracing domain summaries, free it with `free()`.
Event record channel access	Create a recording session handle with lttng_create_handle() to specify the name of the recording session and the summary of the tracing domain of the event record channels to access. Call lttng_list_channels(), passing the recording session handle of step 1. This function sets a pointer to an array of event record channel summaries and returns the number of entries. Destroy the recording session handle of step 1 with lttng_destroy_handle(). Access the properties of each event record channel summary through structure members or using dedicated getters. When you're done with the array of event record channel summaries, free it with `free()`.
Activity control	See: lttng_start_tracing() lttng_stop_tracing() lttng_stop_tracing_no_wait() The “start recording session” and “stop recording session” trigger actions can also activate and deactivate a recording session.
Listing	Call lttng_list_sessions(). This function sets a pointer to an array of recording session summaries and returns the number of entries. Access the properties of each recording session summary through structure members or using dedicated getters. When you're done with the array of recording session summaries, free it with `free()`. See also `lttng-list(1)`
Process filter access	See Process filter API.
Clearing	See Recording session clearing API.
Snapshot recording	See Recording session snapshot API. The “take recording session snapshot” trigger action can also take a recording session snapshot.
Rotation	See Recording session rotation API. The “rotate recording session” trigger action can also rotate a recording session.
Saving and loading	See Recording session saving and loading API.
Trace data regeneration	See: lttng_regenerate_metadata() lttng_regenerate_statedump() See also `lttng-regenerate(1)`

Recording session modes

LTTng offers four recording session modes:

Mode	Description	Descriptor creation function(s)
Local	Write the trace data to the local file system, or do not write any trace data.	lttng_session_descriptor_create() lttng_session_descriptor_local_create()
Network streaming	Send the trace data over the network to a listening relay daemon (see `lttng-relayd(8)`).	lttng_session_descriptor_network_create()
Snapshot	Only write the trace data to the local file system or send it to a listening relay daemon when LTTng takes a snapshot. LTTng takes a snapshot of such a recording session when: You call lttng_snapshot_record(). LTTng executes a “take recording session snapshot” trigger action. LTTng forces the event record loss mode of all the event record channels of such a recording session to be “overwrite”.	lttng_session_descriptor_snapshot_create() lttng_session_descriptor_snapshot_local_create() lttng_session_descriptor_snapshot_network_create()
Live	Send the trace data over the network to a listening relay daemon for live reading. An LTTng live reader (for example, Babeltrace 2) can connect to the same relay daemon to receive trace data while the recording session is active.	lttng_session_descriptor_live_network_create()

See also: The “Recording session modes” section of lttng-concepts(7).

Output URL format

Some functions of the LTTng control library C API require an output URL.

An output URL is a C string which specifies where to send trace data and, when LTTng connects to a relay daemon (see lttng-relayd(8)), control commands.

There are three available output URL formats:

Type Description Format

Local

Send trace data to the local file system, without connecting to a relay daemon.

Accepted by:

lttng_create_session() (deprecated)
lttng_create_session_snapshot() (deprecated)
lttng_snapshot_output_set_local_path()
lttng_save_session_attr_set_output_url()
lttng_load_session_attr_set_input_url()
lttng_load_session_attr_set_override_url()

file://TRACEDIR

TRACEDIR: Absolute path to the directory containing the trace data on the local file system.

Remote: single port

Send trace data and/or control commands to a specific relay daemon with a specific TCP port.

Accepted by:

lttng_session_descriptor_network_create()
lttng_session_descriptor_snapshot_network_create()
lttng_session_descriptor_live_network_create()
lttng_snapshot_output_set_network_urls()
lttng_snapshot_output_set_ctrl_url()
lttng_snapshot_output_set_data_url()
lttng_load_session_attr_set_override_ctrl_url()
lttng_load_session_attr_set_override_data_url()

PROTO://HOST[:PORT][/TRACEDIR]

PROTO

Network protocol, amongst:

net

TCP over IPv4.

net6

TCP over IPv6.

tcp

Same as net.

tcp6

Same as net6.

HOST

Hostname or IP address.

An IPv6 address must be enclosed in square brackets ([ and ]); see RFC 2732.

PORT

TCP port.

If it's missing, then the default control and data ports are respectively 5342 and 5343.

TRACEDIR

Path of the directory containing the trace data on the remote file system.

This path is relative to the base output directory of the LTTng relay daemon (see the Output directory section of lttng-relayd(8)).

Remote: control and data ports

Send trace data and control commands to a specific relay daemon with specific TCP ports.

This form is usually a shorthand for two single-port output URLs with specified ports.

Accepted by:

lttng_create_session_snapshot() (deprecated)
lttng_create_session_live() (deprecated)
lttng_session_descriptor_network_create()
lttng_session_descriptor_snapshot_network_create()
lttng_session_descriptor_live_network_create()
lttng_snapshot_output_set_network_url()
lttng_snapshot_output_set_network_urls()
lttng_snapshot_output_set_ctrl_url()
lttng_load_session_attr_set_override_url()
lttng_load_session_attr_set_override_ctrl_url()

PROTO://HOST:CTRLPORT:DATAPORT[/TRACEDIR]

PROTO

Network protocol, amongst:

net

TCP over IPv4.

net6

TCP over IPv6.

tcp

Same as net.

tcp6

Same as net6.

HOST

Hostname or IP address.

An IPv6 address must be enclosed in square brackets ([ and ]); see RFC 2732.

CTRLPORT

Control TCP port.

DATAPORT

Trace data TCP port.

TRACEDIR

Path of the directory containing the trace data on the remote file system.

This path is relative to the base output directory of the LTTng relay daemon (see the --output option of lttng-relayd(8)).

Enumeration Type Documentation

◆ lttng_get_session_shm_path_status

enum lttng_get_session_shm_path_status

Return type of lttng_get_session_shm_path_override().

Enumerator
LTTNG_GET_SESSION_SHM_PATH_STATUS_OK	Success.
LTTNG_GET_SESSION_SHM_PATH_STATUS_UNSET	Shared memory path isn't set.
LTTNG_GET_SESSION_SHM_PATH_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

◆ lttng_get_session_trace_format_status

enum lttng_get_session_trace_format_status

Return type of lttng_get_session_trace_format().

Enumerator
LTTNG_GET_SESSION_TRACE_FORMAT_STATUS_OK	Success.
LTTNG_GET_SESSION_TRACE_FORMAT_STATUS_INVALID	Unsatisfied precondition.

Function Documentation

◆ lttng_create_handle()

struct lttng_handle * lttng_create_handle	(	const char *	session_name,
		const struct lttng_domain *	domain
	)

extern

Creates and returns a recording session handle from the recording session name session_name and the optional tracing domain summary domain.

Parameters

[in]

session_name

Recording session name part of the recording session handle to create.

May be NULL.

[in]

domain

Tracing domain summary part of the recording session handle to create.

May be NULL.

Returns

New recording session handle.

Destroy the returned handle with lttng_destroy_handle().

See also: lttng_destroy_handle() – Destroys a recording session handle.

◆ lttng_create_session()

int lttng_create_session	(	const char *	session_name,
		const char *	output_url
	)

extern

Creates a recording session named session_name in local or network streaming mode, optionally setting its output URL to output_url.

Deprecated:: Use lttng_create_session_ext() with a dedicated local or network streaming recording session descriptor.

Parameters

[in] session_name Name of the new recording session.

[in]

output_url

Output URL of the recording session to create (copied).

If it's a single-port output URL, then the trace data port is 5343.

If NULL, LTTng doesn't write any trace data for this recording session.

Returns

0

Success

Negative lttng_error_code enumerator

Error

Precondition

liblttng-ctl can connect to a session daemon.
session_name is not NULL.
session_name is not auto.
No available recording session is named session_name.
If not NULL, output_url is a valid output URL.

See also: lttng_create_session_snapshot() – Creates a recording session in snapshot mode.; lttng_create_session_live() – Creates a recording session in live mode.; lttng-create(1)

◆ lttng_create_session_ext()

enum lttng_error_code lttng_create_session_ext ( struct lttng_session_descriptor * session_descriptor )

extern

Creates a recording session from the recording session descriptor session_descriptor.

See Recording session descriptor API to learn how to create a recording session descriptor.

On success, if the name property of session_descriptor isn't set, this function sets it to the automatically generated name of the recording session. Get the recording session name with lttng_session_descriptor_get_session_name().

Parameters

[in] session_descriptor Descriptor from which to create a recording session.

Returns

LTTNG_OK

Success

Another lttng_error_code enumerator

Error

Precondition

liblttng-ctl can connect to a session daemon.
session_descriptor is not NULL.
If the name property of session_descriptor is set, then no available recording session has this name.

See also: Recording session descriptor API.; lttng-create(1)

◆ lttng_create_session_live()

int lttng_create_session_live	(	const char *	session_name,
		const char *	output_url,
		unsigned int	live_timer_period
	)

extern

Creates a recording session named session_name in live mode, optionally setting its URL to output_url.

Deprecated:: Use lttng_create_session_ext() with a dedicated live recording session descriptor.

Parameters

[in] session_name Name of the new recording session.

[in]

output_url

Output URL of the recording session to create: single-port or two-port (copied).

If it's a single-port output URL, then the trace data port is 5343.

If NULL, this function uses net://127.0.0.1:5342:5343.

[in] live_timer_period Period (µs) of the live timers of all the event record channels of the created recording session.

Returns

0

Success

Negative lttng_error_code enumerator

Error

Precondition

liblttng-ctl can connect to a session daemon.
session_name is not NULL.
session_name is not auto.
No available recording session is named session_name.
If not NULL, output_url is a valid single-port output URL or two-port output URL.
live_timer_period ≥ 1

See also: lttng_create_session() – Creates a recording session in local or network streaming mode.; lttng_create_session_snapshot() – Creates a recording session in snapshot mode.; lttng-create(1)

◆ lttng_create_session_snapshot()

int lttng_create_session_snapshot	(	const char *	session_name,
		const char *	output_url
	)

extern

Creates a recording session named session_name in snapshot mode, optionally setting the URL of its initial snapshot output to output_url.

Deprecated:: Use lttng_create_session_ext() with a dedicated snapshot recording session descriptor.

Parameters

[in] session_name Name of the new recording session.

[in]

output_url

URL of an initial snapshot output which LTTng adds to this recording session (copied).

If it's a single-port output URL, then the trace data port is 5343.

This initial snapshot output is named snapshot-0.

If NULL, then the created recording session has no initial snapshot output: you need to either add one with lttng_snapshot_add_output() or provide one when you take a snapshot with lttng_snapshot_record().

Returns

0

Success

Negative lttng_error_code enumerator

Error

Precondition

liblttng-ctl can connect to a session daemon.
session_name is not NULL.
session_name is not auto.
No available recording session is named session_name.
If not NULL, output_url is a valid output URL.

See also: lttng_create_session() – Creates a recording session in local or network streaming mode.; lttng_create_session_live() – Creates a recording session in live mode.; lttng-create(1)

◆ lttng_data_pending()

int lttng_data_pending ( const char * session_name )

extern

Returns whether or not you may read the traces of the recording session named session_name.

It's not safe to read the traces of a recording session while LTTng is still consuming data from the tracers for its event record channels.

This function makes it possible to know when LTTng is done consuming trace data from tracers for the event record channels of the recording session named session_name.

Parameters

[in] session_name Name of the recording session of which get whether or not you may read its traces.

Returns

One of:

0

You may read the traces of the recording session named session_name.

This remains true as long as the recording session remains inactive (stopped).

1

You may not read the traces of the recording session named session_name.

Negative lttng_error_code enumerator

Error.

Precondition

liblttng-ctl can connect to a session daemon.
session_name is not NULL.
session_name names an accessible recording session within the connected session daemon.
session_name names an inactive (stopped) recording session.

◆ lttng_destroy_handle()

void lttng_destroy_handle ( struct lttng_handle * handle )

extern

Destroys the recording session handle handle.

Note

This function doesn't destroy the recording session named handle->session_name, but only the handle itself.

Use lttng_destroy_session_ext() to destroy a recording session.

Parameters

[in]

handle

Recording session handle to destroy.

May be NULL.

◆ lttng_destroy_session()

int lttng_destroy_session ( const char * session_name )

extern

Destroys the recording session named session_name, blocking until the operation completes.

Deprecated:: Use lttng_destroy_session_ext().

“Destroying” a recording session means freeing the resources which the LTTng daemons and tracers acquired for it, also making sure to flush all the recorded trace data to either the local file system or the connected LTTng relay daemon (see lttng-relayd(8)), depending on the recording session mode.

This function stops any recording activity within the recording session named session_name.

This function implicitly calls lttng_stop_tracing(), blocking until the trace data of the recording session becomes valid. Use lttng_destroy_session_no_wait() to avoid a blocking call.

Parameters

[in] session_name Name of the recording session to destroy.

Returns

0

Success

Negative lttng_error_code enumerator

Error

Precondition

liblttng-ctl can connect to a session daemon.
session_name is not NULL.
session_name names an accessible recording session within the connected session daemon.

See also: lttng_destroy_session_no_wait() – Initiates the destruction operation of a recording session, returning immediately.; lttng-destroy(1)

◆ lttng_destroy_session_ext()

enum lttng_error_code lttng_destroy_session_ext	(	const char *	session_name,
		struct lttng_destruction_handle **	handle
	)

extern

Initiates a destruction operation of the recording session named session_name.

“Destroying” a recording session means freeing the resources which the LTTng daemons and tracers acquired for it, also making sure to flush all the recorded trace data to either the local file system or the connected LTTng relay daemon (see lttng-relayd(8)), depending on the recording session mode.

This function doesn't block until the destruction operation completes: it only initiates the operation. Use *handle to wait for the operation to complete.

Parameters

[in] session_name Name of the recording session to destroy.

[out]

handle

On success, this function sets *handle to a handle which identifies this recording session destruction operation.

May be NULL.

Wait for the completion of this destruction operation with lttng_destruction_handle_wait_for_completion().

Destroy *handle with lttng_destruction_handle_destroy().

Returns

LTTNG_OK

Success

Another lttng_error_code enumerator

Error

Precondition

liblttng-ctl can connect to a session daemon.
session_name is not NULL.
session_name names an accessible recording session within the connected session daemon.
No destruction operation is in progress for the recording session named session_name.

See also: lttng-destroy(1)

◆ lttng_destroy_session_no_wait()

int lttng_destroy_session_no_wait ( const char * session_name )

extern

Initiates the destruction operation of the recording session named session_name.

Deprecated:: Use lttng_destroy_session_ext().

“Destroying” a recording session means freeing the resources which the LTTng daemons and tracers acquired for it, also making sure to flush all the recorded trace data to either the local file system or the connected LTTng relay daemon (see lttng-relayd(8)), depending on the recording session mode.

Unlike lttng_destroy_session(), this function does not block until the destruction operation is complete: it returns immediately. This means the trace(s) of the recording session might not be valid when this function returns, and there's no way to know when it/they become valid.

Parameters

[in] session_name Name of the recording session to destroy.

Returns

0

Success

Negative lttng_error_code enumerator

Error

Precondition

liblttng-ctl can connect to a session daemon.
session_name is not NULL.
session_name names an accessible recording session within the connected session daemon.
No destruction operation is in progress for the recording session named session_name.

See also: lttng_destroy_session() – Destroys a recording session, blocking until the operation completes.; lttng-destroy(1)

◆ lttng_get_session_shm_path_override()

enum lttng_get_session_shm_path_status lttng_get_session_shm_path_override	(	const struct lttng_session *	session,
		const char **	shm_dir
	)

extern

Sets *shm_dir to the path of the custom directory on the local file system containing the shared memory files holding the event record channel ring buffers of the recording session summarized by session.

This function only succeeds if the recording session summarized by session has a custom shared memory directory, as set with lttng_set_session_shm_path(); it returns LTTNG_GET_SESSION_SHM_PATH_STATUS_UNSET otherwise.

Parameters

[in] session Summary of the recording session, as obtained with lttng_list_sessions(), of which to get the shared memory directory path.

[out]

shm_dir

On success, this function sets *shm_dir to the path of the directory on the local file system containing the shared memory files holding the event record channel ring buffers of session.

*shm_dir remains valid as long as the recording session summary session exists.

Return values

LTTNG_GET_SESSION_SHM_PATH_STATUS_OK	Success.
LTTNG_GET_SESSION_SHM_PATH_STATUS_UNSET	= 1, Shared memory path isn't set.
LTTNG_GET_SESSION_SHM_PATH_STATUS_INVALID_PARAMETER	= -1, Unsatisfied precondition.

Precondition

session is not NULL.
The recording session summarized by session is accessible within the connected session daemon.
shm_path is not NULL.

See also: lttng_set_session_shm_path() – Sets the path of the directory containing the shared memory files holding the event record channel ring buffers of a recording session.

◆ lttng_get_session_trace_format()

enum lttng_get_session_trace_format_status lttng_get_session_trace_format	(	const struct lttng_session *	session,
		enum lttng_trace_format *	format
	)

extern

Sets *format to the trace format of the recording session summarized by session.

Parameters

[in]	session	Summary of the recording session, as obtained with lttng_list_sessions(), of which to get the trace format.
[out]	format	On success, this function sets `*format` to the trace format of `session`.

Return values

LTTNG_GET_SESSION_TRACE_FORMAT_STATUS_OK	Success.
LTTNG_GET_SESSION_TRACE_FORMAT_STATUS_INVALID	Unsatisfied precondition.

Precondition

session is not NULL.
format is not NULL.

See also: lttng_session_descriptor_set_trace_format() – Set the trace format of a recording session descriptor.

◆ lttng_list_channels()

int lttng_list_channels	(	const struct lttng_handle *	handle,
		struct lttng_channel **	channels
	)

extern

Sets *channels to the summaries of the event record channels of the recording session handle handle.

Parameters

[in] handle Recording session handle which contains the name of the recording session and the summary of the tracing domain which own the event record channels of which to get the summaries.

[out]

channels

On success, this function sets *channels to the summaries of the event record channels.

Free *channels with free().

Returns: The number of items in *channels on success, or a negative lttng_error_code enumerator otherwise.

Precondition

liblttng-ctl can connect to a session daemon.
handle is not NULL.
handle->session_name is a valid (null-terminated) C string.
handle->session_name names an accessible recording session within the connected session daemon.
handle->domain is valid as per the documentation of lttng_domain.
channels is not NULL.

◆ lttng_list_domains()

int lttng_list_domains	(	const char *	session_name,
		struct lttng_domain **	domains
	)

extern

Sets *domains to the summaries of the tracing domains which contain at least one event record channel within the recording session named session_name.

Parameters

[in] session_name Name of the recording session for which to get the tracing domain summaries.

[out]

domains

On success, this function sets *domains to the summaries of the tracing domains.

Free *domains with free().

Returns: The number of items in *domains on success, or a negative lttng_error_code enumerator otherwise.

Precondition

liblttng-ctl can connect to a session daemon.
session_name is not NULL.
session_name names an accessible recording session within the connected session daemon.
domains is not NULL.

◆ lttng_list_sessions()

int lttng_list_sessions ( struct lttng_session ** sessions )

extern

Sets *sessions to the summaries of all the available recording sessions.

Parameters

[out]

sessions

On success, this function sets *sessions to the summaries of the available recording sessions.

Free *sessions with free().

Returns: The number of items in *sessions on success, or a negative lttng_error_code enumerator otherwise.

Precondition

liblttng-ctl can connect to a session daemon.
sessions is not NULL.

See also: lttng-list(1)

◆ lttng_metadata_regenerate()

int lttng_metadata_regenerate ( const char * session_name )

extern

Regenerates the metadata streams of the recording session named session_name.

Deprecated:: Use lttng_regenerate_metadata().

Parameters

[in] session_name Name of the recording session of which to regenerate the metadata streams.

Returns

0

Success

Negative lttng_error_code enumerator

Error

Precondition

liblttng-ctl can connect to a session daemon.
session_name is not NULL.
session_name names an accessible recording session within the connected session daemon.

◆ lttng_regenerate_metadata()

int lttng_regenerate_metadata ( const char * session_name )

extern

Regenerates the metadata streams of the recording session named session_name.

Use this function to resample the offset between the monotonic clock and the wall time of the system, and then regenerate (overwrite) all the metadata stream files (local or remote) of the recording session named session_name.

More specifically, you may want to resample the wall time following a major NTP correction. As such, LTTng can trace a system booting with an incorrect wall time before its wall time is NTP-corrected. Regenerating the metadata of a recording session ensures that trace readers can accurately determine the event record timestamps relative to the Unix epoch.

Note that if you plan to rotate the recording session named session_name, this function only regenerates the metadata stream files of the current and next trace chunks.

See the preconditions of this function which show important limitations.

Parameters

[in] session_name Name of the recording session of which to regenerate the metadata streams.

Returns

0

Success

Negative lttng_error_code enumerator

Error

Precondition

liblttng-ctl can connect to a session daemon.
session_name is not NULL.
session_name names an accessible recording session within the connected session daemon.
The recording session named session_name was not created in live mode.
All the event record channels of the recording session named session_name use a user buffering ownership model.

See also: lttng_regenerate_statedump() – Regenerates the state dump event records of a recording session.; lttng-regenerate(1)

◆ lttng_regenerate_statedump()

int lttng_regenerate_statedump ( const char * session_name )

extern

Regenerates the state dump event records of the recording session named session_name.

Use this function to collect up-to-date state dump information and append corresponding event records to the sub-buffers of the recording session named session_name.

This is particularly useful if you created the recording session in snapshot mode or if LTTng rotates trace files for one of its event record channels: in both cases, the state dump information may be lost.

Parameters

[in] session_name Name of the recording session of which to regenerate the state dump event records.

Returns

0

Success

Negative lttng_error_code enumerator

Error

Precondition

liblttng-ctl can connect to a session daemon.
session_name is not NULL.
session_name names an accessible recording session within the connected session daemon.

See also: lttng_regenerate_metadata() – Regenerates the metadata streams of a recording session.; lttng-regenerate(1)

◆ lttng_session_add_map_channel()

enum lttng_error_code lttng_session_add_map_channel	(	const char *	session_name,
		const struct lttng_map_channel_descriptor *	descriptor
	)

extern

Adds the map channel described by descriptor to the recording session named session_name.

The session daemon copies the contents of descriptor: you may destroy it with lttng_map_channel_descriptor_destroy() as soon as this function returns.

When the name property of descriptor isn't set, the session daemon automatically generates a name for the resulting map channel. The generated name is a property of the map channel itself, not of descriptor: retrieve it through lttng_map_channel_get_name() with a map channel obtained with lttng_session_list_map_channels().

Within a recording session, a map channel is uniquely identified by the (type, name) pair carried by descriptor: two map channels may share the same name provided their types differ.

Parameters

[in]	session_name	Name of the recording session to which to add the map channel.
[in]	descriptor	Descriptor of the map channel to add to the recording session named `session_name`.

Returns: LTTNG_OK on success, or a negative lttng_error_code enumerator otherwise.

liblttng-ctl can connect to a session daemon.
session_name is not NULL.
session_name names an accessible recording session within the connected session daemon.
descriptor is not NULL.
Precondition
No map channel of the same type and name as those of descriptor already exists within the recording session named session_name.

See also
lttng_session_list_map_channels() – Lists the map channels of a recording session.

lttng_session_get_map_channel_by_name() – Returns a single map channel of a recording session by name.

◆ lttng_session_get_creation_time()

enum lttng_error_code lttng_session_get_creation_time	(	const struct lttng_session *	session,
		uint64_t *	creation_timestamp
	)

extern

Sets *creation_timestamp to the timestamp of the creation of the recording session summarized by session.

Parameters

[in]	session	Summary of the recording session of which to get the creation timestamp, as obtained with lttng_list_sessions().
[out]	creation_timestamp	On success, this function sets `*creation_timestamp` to the Unix timestamp of the creation of `session`.

Return values

LTTNG_OK	Success.
LTTNG_ERR_INVALID	Unsatisfied precondition.
LTTNG_ERR_SESSION_NOT_EXIST	The recording session summarized by `session` isn't accessible within the connected session daemon.

Returns

LTTNG_OK

Success

Another lttng_error_code enumerator

Error

Precondition

liblttng-ctl can connect to a session daemon.
session is not NULL.
The recording session summarized by session is accessible within the connected session daemon.
creation_timestamp is not NULL.

◆ lttng_session_get_map_channel_by_name()

enum lttng_error_code lttng_session_get_map_channel_by_name	(	const char *	session_name,
		enum lttng_map_channel_type	type,
		const char *	name,
		struct lttng_map_channel **	channel
	)

extern

Sets *channel to the map channel of the recording session named session_name having the type type and the name name.

Within a recording session, a map channel is uniquely identified by the (type, name) pair: two map channels may share the same name provided their types differ.

*channel is a "snapshot" taken at call time; LTTng doesn't update it as the recording session evolves.

*channel is a client-side handle on a map channel object which lives in the session daemon: it doesn't hold map values itself. Sample the values of the maps of a given map group with lttng_map_group_get_values(), having reached the group through lttng_map_channel_get_groups().

Parameters

[in]	session_name	Name of the recording session in which to look up the map channel.
[in]	type	Type of the map channel to look up.
[in]	name	Name of the map channel to look up within the recording session named `session_name` and having the type `type`.
[out]	channel	On success, this function sets `channel` to the matching map channel. Destroy `channel` with lttng_map_channel_destroy().

Returns: LTTNG_OK on success, or a negative lttng_error_code enumerator otherwise.

liblttng-ctl can connect to a session daemon.
session_name is not NULL.
session_name names an accessible recording session within the connected session daemon.
Precondition
type is a valid lttng_map_channel_type enumerator.
name is not NULL.
Precondition
A map channel of the type type and the name name exists within the recording session named session_name.
channel is not NULL.

See also: lttng_session_list_map_channels() – Lists the map channels of a recording session.

◆ lttng_session_list_map_channels()

enum lttng_error_code lttng_session_list_map_channels	(	const char *	session_name,
		enum lttng_map_channel_type	type,
		struct lttng_map_channel_set **	channels
	)

extern

Sets *channels to the map channels of the type type of the recording session named session_name.

*channels is a "snapshot" taken at call time: LTTng doesn't update it as map channels are added to or removed from the recording session afterwards.

If type is LTTNG_MAP_CHANNEL_TYPE_KERNEL and the Linux kernel tracer is unavailable (the session daemon isn't running as the root user, or kernel tracing is disabled), then this function sets *channels to an empty set and succeeds: a recording session can't have any kernel map channel without an available kernel tracer.

The returned map channel objects are client-side handles on map channel objects which live in the session daemon: they don't hold map values themselves. Sample the values of the maps of a given map group with lttng_map_group_get_values(), having reached the group through lttng_map_channel_get_groups().

Parameters

[in] session_name Name of the recording session of which to get the map channels.

[in] type Type of the map channels to get.

[out]

channels

On success, this function sets *channels to the map channels of the type type of the recording session named session_name.

Destroy *channels with lttng_map_channel_set_destroy().

Returns: LTTNG_OK on success, or a negative lttng_error_code enumerator otherwise.

liblttng-ctl can connect to a session daemon.
session_name is not NULL.
session_name names an accessible recording session within the connected session daemon.
channels is not NULL.

See also: lttng_session_get_map_channel_by_name() – Returns a single map channel of a recording session by name.

◆ lttng_set_session_shm_path()

int lttng_set_session_shm_path	(	const char *	session_name,
		const char *	shm_dir
	)

extern

Sets the path of the directory containing the shared memory files holding the event record channel ring buffers of the recording session named session_name on the local file system to shm_dir.

Specifying a location on an NVRAM file system makes it possible to recover the latest recorded trace data when the system reboots after a crash with the lttng-crash(1) utility.

Parameters

[in]	session_name	Name of the recording session of which to set the shared memory file directory path.
[in]	shm_dir	Path of the directory containing the shared memory files of the recording session named `session_name` (copied).

Returns

0 or a positive value

Success

Negative lttng_error_code enumerator

Error

Precondition

liblttng-ctl can connect to a session daemon.
session_name is not NULL.
session_name names an accessible recording session within the connected session daemon.
session_name names a recording session which never became active (started) since its creation.
shm_dir is not NULL.
shm_dir is a writable directory.

See also: lttng_get_session_shm_path_override() – Returns the path of the custom directory containing the shared memory files holding the event record channel ring buffers of a recording session.

◆ lttng_start_tracing()

int lttng_start_tracing ( const char * session_name )

extern

Makes the recording session named session_name active, starting all the tracers for its event record channels.

Note: A “start recording session” trigger action can also activate (start) a recording session.

Parameters

[in] session_name Name of the recording session to activate/start.

Returns

0 or a positive value

Success

Negative lttng_error_code enumerator

Error

Precondition

liblttng-ctl can connect to a session daemon.
session_name is not NULL.
session_name names an accessible recording session within the connected session daemon.
session_name names an inactive (stopped) recording session.

See also: lttng_stop_tracing() – Stops a recording session.; lttng-start(1)

◆ lttng_stop_tracing()

int lttng_stop_tracing ( const char * session_name )

extern

Makes the recording session named session_name inactive, stopping all the tracers for its event record channels, blocking until the operation completes.

This function blocks until the trace data of the recording session named session_name is valid. Use lttng_stop_tracing_no_wait() to avoid a blocking call.

If LTTng archived the current trace chunk of the recording session named session_name at least once during its lifetime, then this function renames the current trace chunk subdirectory. Although it's safe to read the content of this renamed subdirectory while the recording session remains inactive, it's not a trace chunk archive: you need to destroy the recording session or a rotation needs to occur to archive it.

Note: A “stop recording session” trigger action can also deactivate (stop) a recording session.

Parameters

[in] session_name Name of the recording session to deactivate/stop.

Returns

0 or a positive value

Success

Negative lttng_error_code enumerator

Error

Precondition

liblttng-ctl can connect to a session daemon.
session_name is not NULL.
session_name names an accessible recording session within the connected session daemon.
session_name names an active (started) recording session.

See also: lttng_stop_tracing_no_wait() – Deactivates a recording session without waiting for the operation to complete.; lttng_start_tracing() – Starts a recording session.; lttng-stop(1)

◆ lttng_stop_tracing_no_wait()

int lttng_stop_tracing_no_wait ( const char * session_name )

extern

Makes the recording session named session_name inactive, stopping all the tracers for its event record channels without waiting for the operation to complete.

Unlike lttng_stop_tracing(), this function does not block until the operation is complete: it returns immediately. This means the traces(s) of the recording session might not be valid when this function returns, and there's no way to know when it/they become valid.

Note: A “stop recording session” trigger action can also deactivate (stop) a recording session.

Parameters

[in] session_name Name of the recording session to deactivate/stop.

Returns

0 or a positive value

Success

Negative lttng_error_code enumerator

Error

Precondition

liblttng-ctl can connect to a session daemon.
session_name is not NULL.
session_name names an accessible recording session within the connected session daemon.
session_name names an active (started) recording session.
No deactivation operation is in progress for the recording session named session_name.

See also: lttng_stop_tracing() – Deactivates a recording session, blocking until the operation completes.; lttng_start_tracing() – Starts a recording session.; lttng-stop(1)

Modules

Data Structures

Enumerations

Functions

Detailed Description

Operations

Recording session modes

Output URL format

Enumeration Type Documentation

◆ lttng_get_session_shm_path_status

◆ lttng_get_session_trace_format_status

Function Documentation

◆ lttng_create_handle()

◆ lttng_create_session()

◆ lttng_create_session_ext()

◆ lttng_create_session_live()

◆ lttng_create_session_snapshot()

◆ lttng_data_pending()

◆ lttng_destroy_handle()

◆ lttng_destroy_session()

◆ lttng_destroy_session_ext()

◆ lttng_destroy_session_no_wait()

◆ lttng_get_session_shm_path_override()

◆ lttng_get_session_trace_format()

◆ lttng_list_channels()

◆ lttng_list_domains()

◆ lttng_list_sessions()

◆ lttng_metadata_regenerate()

◆ lttng_regenerate_metadata()

◆ lttng_regenerate_statedump()

◆ lttng_session_add_map_channel()

◆ lttng_session_get_creation_time()

◆ lttng_session_get_map_channel_by_name()

◆ lttng_session_list_map_channels()

◆ lttng_set_session_shm_path()

◆ lttng_start_tracing()

◆ lttng_stop_tracing()

◆ lttng_stop_tracing_no_wait()