Collaboration diagram for Recording session descriptor API:

Data Structures
struct	lttng_session_descriptor
	Recording session descriptor (opaque type). More...

Enumerations
enum	lttng_session_descriptor_status { LTTNG_SESSION_DESCRIPTOR_STATUS_OK , LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID , LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET }
	Return type of recording session descriptor functions. More...

enum	lttng_trace_format { LTTNG_TRACE_FORMAT_DEFAULT , LTTNG_TRACE_FORMAT_CTF_1_8 , LTTNG_TRACE_FORMAT_CTF_2 }
	Trace format of a recording session. More...

Functions
struct lttng_session_descriptor *	lttng_session_descriptor_create (const char *session_name)
	Creates a recording session descriptor to create a no-output, local recording session named `session_name`.

void	lttng_session_descriptor_destroy (struct lttng_session_descriptor *session_descriptor)
	Destroys the recording session descriptor `session_descriptor`.

enum lttng_session_descriptor_status	lttng_session_descriptor_get_session_name (const struct lttng_session_descriptor session_descriptor, const char *session_name)
	Sets `*session_name` to the name of the recording session which lttng_create_session_ext() created from the recording session descriptor `session_descriptor`.

struct lttng_session_descriptor *	lttng_session_descriptor_live_network_create (const char session_name, const char control_url, const char *data_url, unsigned long long live_timer_period)
	Creates a recording session descriptor to create a live recording session named `session_name`.

struct lttng_session_descriptor *	lttng_session_descriptor_local_create (const char session_name, const char trace_dir)
	Creates a recording session descriptor to create a local recording session named `session_name`.

struct lttng_session_descriptor *	lttng_session_descriptor_network_create (const char session_name, const char control_url, const char *data_url)
	Creates a recording session descriptor to create a network streaming recording session named `session_name`.

enum lttng_session_descriptor_status	lttng_session_descriptor_set_trace_format (struct lttng_session_descriptor *descriptor, enum lttng_trace_format format)
	Sets the trace format of the recording session descriptor `session_descriptor` to `format`.

struct lttng_session_descriptor *	lttng_session_descriptor_snapshot_create (const char *session_name)
	Creates a recording session descriptor to create a snapshot recording session named `session_name` without an initial output.

struct lttng_session_descriptor *	lttng_session_descriptor_snapshot_local_create (const char session_name, const char trace_dir)
	Creates a recording session descriptor to create a snapshot recording session named `session_name` and having an initial local output.

struct lttng_session_descriptor *	lttng_session_descriptor_snapshot_network_create (const char session_name, const char control_url, const char *data_url)
	Creates a recording session descriptor to create a snapshot recording session named `session_name` and having an initial remote output.

Detailed Description

A recording session descriptor describes the properties of a recording session to be (not created yet).

To create a recording session from a recording session descriptor:

Create a recording session descriptor with one of the dedicated creation functions, depending on the recording session mode:
Local mode
One of:
- lttng_session_descriptor_create()
- lttng_session_descriptor_local_create()
Network streaming mode

lttng_session_descriptor_network_create()

Snapshot mode
One of:
Live mode

lttng_session_descriptor_live_network_create()
Optional: Set the trace format of the recording session descriptor with lttng_session_descriptor_set_trace_format().

The default trace format is LTTNG_TRACE_FORMAT_DEFAULT: the recording session will use the default trace format of the connected session daemon (see the --default-trace-format option of lttng-sessiond(8)).
Call lttng_create_session_ext(), passing the recording session descriptor of step 1.

After a successful call to this function, you can call lttng_session_descriptor_get_session_name() to get the name of the created recording session (set when creating the descriptor or automatically generated).
When you're done with the recording session descriptor, destroy it with lttng_session_descriptor_destroy().

Enumeration Type Documentation

◆ lttng_session_descriptor_status

enum lttng_session_descriptor_status

Return type of recording session descriptor functions.

Error status enumerators have a negative value.

Enumerator
LTTNG_SESSION_DESCRIPTOR_STATUS_OK	Success.
LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID	Unsatisfied precondition.
LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET	Recording session descriptor property is not set.

◆ lttng_trace_format

enum lttng_trace_format

Trace format of a recording session.

Enumerator

LTTNG_TRACE_FORMAT_DEFAULT

Use the default trace format of the connected session daemon.

See the --default-trace-format option of lttng-sessiond(8).

LTTNG_TRACE_FORMAT_CTF_1_8

Common Trace Format version 1.8.

LTTNG_TRACE_FORMAT_CTF_2

Common Trace Format version 2.

Function Documentation

◆ lttng_session_descriptor_create()

struct lttng_session_descriptor * lttng_session_descriptor_create ( const char * session_name )

extern

Creates a recording session descriptor to create a no-output, local recording session named session_name.

LTTng won't write any trace data for a recording session created from the returned descriptor.

Parameters

[in]

session_name

Recording session name.

If NULL, LTTng automatically generates a recording session name when you call lttng_create_session_ext().

Call lttng_session_descriptor_get_session_name() with the returned recording session descriptor after successfully calling lttng_create_session_ext() to get the generated name.

Returns

Recording session descriptor on success, or NULL on error.

Destroy the returned descriptor with lttng_session_descriptor_destroy().

See also: lttng_session_descriptor_local_create() – Creates a recording session descriptor to create a local recording session with an output.

Precondition

session_name is not auto.

◆ lttng_session_descriptor_destroy()

void lttng_session_descriptor_destroy ( struct lttng_session_descriptor * session_descriptor )

extern

Destroys the recording session descriptor session_descriptor.

Note

This function doesn't destroy the recording session which lttng_create_session_ext() created from session_descriptor, but only the descriptor itself.

Use lttng_destroy_session_ext() to destroy a recording session.

Parameters

[in]

session_descriptor

Recording session descriptor to destroy.

May be NULL.

◆ lttng_session_descriptor_get_session_name()

enum lttng_session_descriptor_status lttng_session_descriptor_get_session_name	(	const struct lttng_session_descriptor *	session_descriptor,
		const char **	session_name
	)

extern

Sets *session_name to the name of the recording session which lttng_create_session_ext() created from the recording session descriptor session_descriptor.

Call this function after successfully calling lttng_create_session_ext() when session_descriptor wasn't created with a specific recording session name to get the automatically generated name of the created recording session.

Parameters

[in] session_descriptor Recording session descriptor from which lttng_create_session_ext() previously created the recording session of which to get the name.

[out]

session_name

On success, this function sets *session_name to the name of the recording session which lttng_create_session_ext() previously created from session_descriptor.

session_descriptor owns *session_name.

*session_name remains valid until the next recording session descriptor function call with session_descriptor.

Return values

LTTNG_SESSION_DESCRIPTOR_STATUS_OK	Success.
LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID	Unsatisfied precondition.
LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET	The name property of `session_descriptor` is not set.

Precondition

session_descriptor is not NULL.
You successfully called lttng_create_session_ext() with session_descriptor.
session_name is not NULL.

◆ lttng_session_descriptor_live_network_create()

struct lttng_session_descriptor * lttng_session_descriptor_live_network_create	(	const char *	session_name,
		const char *	control_url,
		const char *	data_url,
		unsigned long long	live_timer_period
	)

extern

Creates a recording session descriptor to create a live recording session named session_name.

The valid combinations of control_url and data_url are:

`control_url`	`data_url`	Behaviour
`NULL`	`NULL`	Use `net://127.0.0.1:5342` as `control_url`. Use `net://127.0.0.1:5343` as `data_url`.
Single-port output URL	`NULL`	Use the protocol, host, and trace directory (if any) of `control_url` and the port 5343 as `data_url`.
Single-port output URL	Single-port output URL with the exact same protocol, host, and trace directory (if any) as `control_url`.	Use the specified output URLs.
Two-port output URL	`NULL`	Use the protocol, host, data port, and trace directory (if any) of `control_url` as `data_url`.

Parameters

[in]	session_name	Recording session name. If `NULL`, LTTng automatically generates a recording session name when you call lttng_create_session_ext(). Call lttng_session_descriptor_get_session_name() with the returned recording session descriptor after successfully calling lttng_create_session_ext() to get the generated name.
[in]	control_url	One of: Single-port output URL Indicates where (to which relay daemon; see `lttng-relayd(8)`) to send the control data. Two-port output URL Indicates where to send the control and trace data. This function copies `control_url`. If `NULL`, this function uses `net://127.0.0.1:5342:5343`.
[in]	data_url	Single-port output URL which indicates where to send the trace data (copied). May be `NULL`: see the table above for the default value depending on `control_url`.
[in]	live_timer_period	Period (µs) of the live timers of all the event record channels of a recording session which lttng_create_session_ext() creates from the returned descriptor.

Returns

Recording session descriptor on success, or NULL on error.

Destroy the returned descriptor with lttng_session_descriptor_destroy().

Precondition

session_name is not auto.
control_url and data_url satisfy one of the valid combinations shown in the table above.
live_timer_period ≥ 1

◆ lttng_session_descriptor_local_create()

struct lttng_session_descriptor * lttng_session_descriptor_local_create	(	const char *	session_name,
		const char *	trace_dir
	)

extern

Creates a recording session descriptor to create a local recording session named session_name.

Parameters

[in]

session_name

Recording session name.

If NULL, LTTng automatically generates a recording session name when you call lttng_create_session_ext().

Call lttng_session_descriptor_get_session_name() with the returned recording session descriptor after successfully calling lttng_create_session_ext() to get the generated name.

[in]

trace_dir

Absolute path of the directory containing the traces of the recording session you create from the returned descriptor (copied).

If NULL, the output directory is, after calling lttng_create_session_ext(), $LTTNG_HOME/lttng-traces/NAME-TS, with:

$LTTNG_HOME

The value of the LTTNG_HOME environment variable, or of the HOME environment variable if LTTNG_HOME isn't set.

NAME

Recording session name (session_name if not NULL, or an automatically generated name otherwise).

TS

Timestamp of the creation of the recording session using the YYYYmmdd-HHMMSS form.

Returns

Recording session descriptor on success, or NULL on error.

Destroy the returned descriptor with lttng_session_descriptor_destroy().

Precondition

session_name is not auto.
If not NULL, trace_dir is a valid path.

See also: lttng_session_descriptor_create() – Creates a recording session descriptor to create a local recording session without an output.

◆ lttng_session_descriptor_network_create()

struct lttng_session_descriptor * lttng_session_descriptor_network_create	(	const char *	session_name,
		const char *	control_url,
		const char *	data_url
	)

extern

Creates a recording session descriptor to create a network streaming recording session named session_name.

The valid combinations of control_url and data_url are:

`control_url`	`data_url`	Behaviour
`NULL`	`NULL`	Use `net://127.0.0.1:5342` as `control_url`. Use `net://127.0.0.1:5343` as `data_url`.
Single-port output URL	`NULL`	Use the protocol, host, and trace directory (if any) of `control_url` and the port 5343 as `data_url`.
Single-port output URL	Single-port output URL with the exact same protocol, host, and trace directory (if any) as `control_url`.	Use the specified output URLs.
Two-port output URL	`NULL`	Use the protocol, host, data port, and trace directory (if any) of `control_url` as `data_url`.

Parameters

[in]

session_name

Recording session name.

If NULL, LTTng automatically generates a recording session name when you call lttng_create_session_ext().

Call lttng_session_descriptor_get_session_name() with the returned recording session descriptor after successfully calling lttng_create_session_ext() to get the generated name.

[in]

control_url

One of:

Single-port output URL

Indicates where (to which relay daemon; see lttng-relayd(8)) to send the control data.

Two-port output URL

Indicates where to send the control and trace data.

This function copies control_url.

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

[in]

data_url

Single-port output URL which indicates where to send the trace data (copied).

May be NULL: see the table above for the default value depending on control_url.

Returns

Recording session descriptor on success, or NULL on error.

Destroy the returned descriptor with lttng_session_descriptor_destroy().

Precondition

session_name is not auto.
control_url and data_url satisfy one of the valid combinations shown in the table above.

◆ lttng_session_descriptor_set_trace_format()

enum lttng_session_descriptor_status lttng_session_descriptor_set_trace_format	(	struct lttng_session_descriptor *	descriptor,
		enum lttng_trace_format	format
	)

extern

Sets the trace format of the recording session descriptor session_descriptor to format.

Call this to set the trace format of the recording session to create from session_descriptor before you call lttng_create_session_ext().

Parameters

[in]	session_descriptor	Recording session descriptor of which to set the trace format.
[in]	format	Trace format of `session_descriptor`.

Return values

LTTNG_SESSION_DESCRIPTOR_STATUS_OK	Success.
LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID	Unsatisfied precondition.

Precondition

session_descriptor is not NULL.

◆ lttng_session_descriptor_snapshot_create()

struct lttng_session_descriptor * lttng_session_descriptor_snapshot_create ( const char * session_name )

extern

Creates a recording session descriptor to create a snapshot recording session named session_name without an initial output.

A recording session which lttng_create_session_ext() creates from the returned descriptor 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().

Parameters

[in]

session_name

Recording session name.

If NULL, LTTng automatically generates a recording session name when you call lttng_create_session_ext().

Call lttng_session_descriptor_get_session_name() with the returned recording session descriptor after successfully calling lttng_create_session_ext() to get the generated name.

Returns

Recording session descriptor on success, or NULL on error.

Destroy the returned descriptor with lttng_session_descriptor_destroy().

Precondition

session_name is not auto.

See also: lttng_session_descriptor_snapshot_local_create() – Creates a recording session descriptor to create a snapshot recording session with an initial local output.; lttng_session_descriptor_snapshot_network_create() – Creates a recording session descriptor to create a snapshot recording session with an initial remote output.

◆ lttng_session_descriptor_snapshot_local_create()

struct lttng_session_descriptor * lttng_session_descriptor_snapshot_local_create	(	const char *	session_name,
		const char *	trace_dir
	)

extern

Creates a recording session descriptor to create a snapshot recording session named session_name and having an initial local output.

Using the returned descriptor when you call lttng_create_session_ext() to create a snapshot recording session is similar to using a descriptor which lttng_session_descriptor_snapshot_create() returns and calling lttng_snapshot_add_output() after creating the recording session.

The name of this initial snapshot output is snapshot-0.

Parameters

[in]

session_name

Recording session name.

If NULL, LTTng automatically generates a recording session name when you call lttng_create_session_ext().

Call lttng_session_descriptor_get_session_name() with the returned recording session descriptor after successfully calling lttng_create_session_ext() to get the generated name.

[in]

trace_dir

Absolute path of an initial snapshot output (copied).

If NULL, the snapshot output directory is, after calling lttng_create_session_ext(), $LTTNG_HOME/lttng-traces/NAME-TS, with:

$LTTNG_HOME

The value of the LTTNG_HOME environment variable, or of the HOME environment variable if LTTNG_HOME isn't set.

NAME

Recording session name (session_name if not NULL, or an automatically generated name otherwise).

TS

Timestamp of the creation of the recording session using the YYYYmmdd-HHMMSS form.

Returns

Recording session descriptor on success, or NULL on error.

Destroy the returned descriptor with lttng_session_descriptor_destroy().

Precondition

session_name is not auto.
If not NULL, trace_dir is a valid path.

See also: lttng_session_descriptor_snapshot_create() – Creates a recording session descriptor to create a snapshot recording session without an initial output.; lttng_session_descriptor_snapshot_network_create() – Creates a recording session descriptor to create a snapshot recording session with an initial remote output.

◆ lttng_session_descriptor_snapshot_network_create()

struct lttng_session_descriptor * lttng_session_descriptor_snapshot_network_create	(	const char *	session_name,
		const char *	control_url,
		const char *	data_url
	)

extern

Creates a recording session descriptor to create a snapshot recording session named session_name and having an initial remote output.

Using the returned descriptor when you call lttng_create_session_ext() to create a snapshot recording session is similar to using a descriptor which lttng_session_descriptor_snapshot_create() returns and calling lttng_snapshot_add_output() after creating the recording session.

The name of this initial snapshot output is snapshot-0.

The valid combinations of control_url and data_url are:

`control_url`	`data_url`	Behaviour
`NULL`	`NULL`	Use `net://127.0.0.1:5342` as `control_url`. Use `net://127.0.0.1:5343` as `data_url`.
Single-port output URL	`NULL`	Use the protocol, host, and trace directory (if any) of `control_url` and the port 5343 as `data_url`.
Single-port output URL	Single-port output URL with the exact same protocol, host, and trace directory (if any) as `control_url`.	Use the specified output URLs.
Two-port output URL	`NULL`	Use the protocol, host, data port, and trace directory (if any) of `control_url` as `data_url`.

Parameters

[in]

session_name

Recording session name.

If NULL, LTTng automatically generates a recording session name when you call lttng_create_session_ext().

Call lttng_session_descriptor_get_session_name() with the returned recording session descriptor after successfully calling lttng_create_session_ext() to get the generated name.

[in]

control_url

Control data URL of an initial snapshot output.

One of:

Single-port output URL

Indicates where (to which relay daemon; see lttng-relayd(8)) to send the control data.

Two-port output URL

Indicates where to send the control and trace data.

This function copies control_url.

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

[in]

data_url

Trace data URL of an initial snapshot output (copied).

Single-port output URL which indicates where to send the trace data.

May be NULL: see the table above for the default value depending on control_url.

Returns

Recording session descriptor on success, or NULL on error.

Destroy the returned descriptor with lttng_session_descriptor_destroy().

Precondition

session_name is not auto.
control_url and data_url satisfy one of the valid combinations shown in the table above.

See also: lttng_session_descriptor_snapshot_create() – Creates a recording session descriptor to create a snapshot recording session without an initial output.; lttng_session_descriptor_snapshot_local_create() – Creates a recording session descriptor to create a snapshot recording session with an initial local output.

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ lttng_session_descriptor_status

◆ lttng_trace_format

Function Documentation

◆ lttng_session_descriptor_create()

◆ lttng_session_descriptor_destroy()

◆ lttng_session_descriptor_get_session_name()

◆ lttng_session_descriptor_live_network_create()

◆ lttng_session_descriptor_local_create()

◆ lttng_session_descriptor_network_create()

◆ lttng_session_descriptor_set_trace_format()

◆ lttng_session_descriptor_snapshot_create()

◆ lttng_session_descriptor_snapshot_local_create()

◆ lttng_session_descriptor_snapshot_network_create()