Collaboration diagram for Recording session snapshot API:

Warning

The documentation of the recording session snapshot API is incomplete.

The text below shows the typical usage of this API, but the types, enumerators, and functions of lttng/snapshot.h aren't documented individually.

A recording session snapshot is a dump, local or remote, of the current ring buffers of all the event record channels of a recording session, without clearing them.

Unlike recording session rotations, snapshots may overlap: successive snapshots may contain the same event records.

Recording session snapshot.

When you create a recording session descriptor with lttng_session_descriptor_snapshot_create(), the recording session which lttng_create_session_ext() creates from it has no default snapshot output: you need to either set one with lttng_snapshot_add_output() or provide one when you take a snapshot with lttng_snapshot_record().

Snapshot output API usage

A recording session may have zero or one default snapshot output.

To set the default snapshot output of a recording session:

Create a snapshot output descriptor with lttng_snapshot_output_create().
Configure the descriptor as needed:
- Set a custom snapshot ID with lttng_snapshot_output_set_id().
- Set the name with lttng_snapshot_output_set_name().
- Set the maximum total size (bytes) of snapshot trace files with lttng_snapshot_output_set_size().
- Specify the output destination with one of:
  
  Local filesystem path
  
  lttng_snapshot_output_set_local_path()
  
  Single remote URL (LTTng relay daemon; see lttng-relayd(8))
  
  lttng_snapshot_output_set_network_url()
  
  Separate control/data URLs
  
  lttng_snapshot_output_set_network_urls()
  
  Individual control and data URLs
  
  lttng_snapshot_output_set_ctrl_url() and lttng_snapshot_output_set_data_url()
  
  See Output URL format to learn more about output URLs.
Set the default snapshot output of the targeted recording session from the descriptor with lttng_snapshot_add_output().
When you're done with the descriptor, destroy it with lttng_snapshot_output_destroy().

This only destroys the descriptor; it doesn't remove the default snapshot output of the targeted recording session (use lttng_snapshot_del_output() for this).

To inspect the existing snapshot outputs of a given recording session:

Get the list of snapshot output descriptors for the recording session with lttng_snapshot_list_output().
Iterate the list of step 1 with lttng_snapshot_output_list_get_next() until it returns NULL.

With a (borrowed) snapshot output descriptor, you may get:
- Its ID with lttng_snapshot_output_get_id().
- Its name with lttng_snapshot_output_get_name() (borrowed).
- The maximum total size (bytes) of snapshot trace files with lttng_snapshot_output_get_maxsize().
- Its control and data URLs with lttng_snapshot_output_get_ctrl_url() and lttng_snapshot_output_get_data_url() (borrowed).
When you're done with the snapshot output descriptor list, destroy it with lttng_snapshot_output_list_destroy().

Snapshot API usage

To take a snapshot of a recording session:

Ensure that the targeted recording session has a default snapshot output, or create a snapshot output descriptor to pass directly to lttng_snapshot_record().
Call lttng_snapshot_record().

Passing NULL as the output uses the default snapshot output of the targeted recording session.

The wait parameter is currently ignored: the call always blocks until the snapshot operation completes.

The function returns 0 on success, or a negative lttng_error_code enumerator on error.

Note: The “Take recording session snapshot” trigger action API “take recording session snapshot” trigger action can also take a snapshot.

See also