Recording session rotation API

Collaboration diagram for Recording session rotation API:

Modules
	Trace chunk archive location API

Detailed Description

Warning

The documentation of the recording session rotation API is incomplete.

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

A recording session rotation is the action of archiving the current trace chunk of a recording session to the file system.

Once LTTng archives a trace chunk, it doesn't manage it anymore: you can read it, modify it, move it, or remove it.

Recording session rotation.

Trace chunk archive

A trace chunk archive is a collection of metadata and data stream files which form a self-contained LTTng trace. See the “Trace chunk naming” section of lttng-concepts(7) to learn how LTTng names a trace chunk archive directory.

The current trace chunk of a given recording session includes:

• The stream files which LTTng already wrote to the file system, and which are not part of a previously archived trace chunk, since the most recent event amongst:

  • The first time the recording session was started.

    See also

    • lttng_start_tracing()
    • “Start recording session” trigger action API
    • lttng-start(1)

  • The last rotation, performed with:

    • lttng_rotate_session().

      See also

      lttng-rotate(1)

    • A rotation schedule previously set with lttng_session_add_rotation_schedule().

      See also

      lttng-enable-rotation(1)

    • An executed “Rotate recording session snapshot” trigger action API “rotate recording session snapshot” trigger action.
• The content of all the non-flushed sub-buffers of the event record channels of the recording session.

Immediate rotation API usage

To perform an immediate recording session rotation:

1. Call lttng_rotate_session(), passing:
   • The name of the recording session to rotate.
   • An optional, immediate rotation descriptor (or NULL to use default options).
   • An #lttng_rotation_handle (rotation handle) pointer; on success, lttng_rotate_session() returns 0 and sets the handle.
2. With the rotation handle of step 1:
   1. Query the rotation state (enumerator of #lttng_rotation_state) with lttng_rotation_handle_get_state() until the current state is #LTTNG_ROTATION_STATE_COMPLETED.
   2. Borrow the resulting trace chunk archive location with lttng_rotation_handle_get_archive_location().
   3. When you're done with the rotation handle, destroy it with lttng_rotation_handle_destroy().

See also

lttng-rotate(1)

Rotation schedule API usage

A recording session rotation schedule allows automatic rotation based on a size or time threshold.

To add a rotation schedule to a given recording session:

1. Create and configure a rotation schedule descriptor with one of:

   Based on current trace chunk size

   Create with lttng_rotation_schedule_size_threshold_create().

   Then, set the size (bytes) threshold with lttng_rotation_schedule_size_threshold_set_threshold().

   Based on time

   Create with lttng_rotation_schedule_periodic_create().

   Then, set the period (µs) with lttng_rotation_schedule_periodic_set_period().

2. Add the rotation schedule to the targeted recording session using the descriptor of step 1 with lttng_session_add_rotation_schedule().

   Note

   As of LTTng-tools 16.2, you may only add one rotation schedule of each type to a given recording session.

3. When you're done with the rotation schedule descriptor, destroy it with lttng_rotation_schedule_destroy().

   This function doesn't cancel the rotation schedule: use lttng_session_remove_rotation_schedule() to remove a rotation schedule from a recording session.

To inspect the existing rotation schedules of a given recording session:

1. Get the list of rotation schedules of the recording session with lttng_session_list_rotation_schedules().

2. Borrow a rotation schedule from the list of step 1 with lttng_rotation_schedules_get_count() and lttng_rotation_schedules_get_at_index().

   With a rotation schedule, you may get:

   • Its type with lttng_rotation_schedule_get_type() (an #lttng_rotation_schedule_type enumerator).

   • Depending on its type:

     #LTTNG_ROTATION_SCHEDULE_TYPE_SIZE_THRESHOLD

     Its current trace chunk size (bytes) threshold with lttng_rotation_schedule_size_threshold_get_threshold().

     #LTTNG_ROTATION_SCHEDULE_TYPE_PERIODIC

     Its period (µs) with lttng_rotation_schedule_periodic_get_period().

3. When you're done with the rotation schedule list, destroy it with lttng_rotation_schedules_destroy().

See also

• lttng-enable-rotation(1)
• lttng-disable-rotation(1)