LTTng control library C API
Loading...
Searching...
No Matches
Data Structures | Enumerations | Functions
Recording session descriptor API
Recording session API
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 fuctions. 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.
 
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:

  1. Create a recording session descriptor with one of the dedicated creation functions, depending on the recording session mode:

    Local mode

    One of:

    Network streaming mode

    lttng_session_descriptor_network_create()

    Snapshot mode

    One of:

    Live mode
    lttng_session_descriptor_live_network_create()

  2. 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).

  3. 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 fuctions.

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.

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_descriptorRecording 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_OKSuccess.
LTTNG_SESSION_DESCRIPTOR_STATUS_INVALIDUnsatisfied precondition.
LTTNG_SESSION_DESCRIPTOR_STATUS_UNSETThe 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_periodPeriod (µs) of the live timers of all the 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_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.