X-Git-Url: https://git.liburcu.org/?p=lttng-tools.git;a=blobdiff_plain;f=include%2Flttng%2Fsession-descriptor.h;fp=include%2Flttng%2Fsession-descriptor.h;h=f4151b3a806d73da2753fb50475f6f48c94386e5;hp=a67a4bf1c65550b407552f5301aab7267c739131;hb=048f01efd5931e364cc777d47c284c3f7d7d6ed6;hpb=78f5b22de60c114c5c83410015a08bdd212edc0b diff --git a/include/lttng/session-descriptor.h b/include/lttng/session-descriptor.h index a67a4bf1c..f4151b3a8 100644 --- a/include/lttng/session-descriptor.h +++ b/include/lttng/session-descriptor.h @@ -8,12 +8,23 @@ #ifndef LTTNG_SESSION_DESCRIPTOR_H #define LTTNG_SESSION_DESCRIPTOR_H -#include - #ifdef __cplusplus extern "C" { #endif +#include + +/*! +@addtogroup api_session_descr +@{ +*/ + +/*! +@struct lttng_session_descriptor + +@brief + Recording session descriptor (opaque type). +*/ struct lttng_session_descriptor; /* @@ -90,90 +101,468 @@ struct lttng_session_descriptor; * default data port, and the 'control_url' host will be used. */ +/*! +@brief + Return type of recording session descriptor fuctions. + +Error status enumerators have a negative value. +*/ enum lttng_session_descriptor_status { - /* Invalid session descriptor parameter. */ - LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID = -1, + /// Success. LTTNG_SESSION_DESCRIPTOR_STATUS_OK = 0, - /* Session descriptor parameter is unset. */ + + /// Unsatisfied precondition. + LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID = -1, + + /// Recording session descriptor property is not set. LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET = 1, }; -/* - * Create a session descriptor in no-output mode. - * - * The 'name' parameter can be left NULL to auto-generate a session name. - * - * Returns an lttng_session_descriptor instance on success, NULL on error. - */ +/*! +@brief + Creates a recording session descriptor to create a no-output, + \ref api-session-local-mode "local" recording session + named \lt_p{session_name}. + +LTTng won't write any trace data for a recording session created from +the returned descriptor. + +@param[in] session_name + @parblock + Recording session name. + + If \c 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. + @endparblock + +@returns + @parblock + Recording session descriptor on success, or \c NULL on error. + + Destroy the returned descriptor with + lttng_session_descriptor_destroy(). + @endparblock + +@sa lttng_session_descriptor_local_create() -- + Creates a recording session descriptor to create a + \ref api-session-local-mode "local" recording session with an + output. + +@lt_pre_sess_name_not_auto{session_name} +*/ LTTNG_EXPORT extern struct lttng_session_descriptor * -lttng_session_descriptor_create(const char *name); +lttng_session_descriptor_create(const char *session_name); -/* - * Create a session descriptor with a local output destination. - * - * The 'name' parameter can be left NULL to auto-generate a session name. - * - * The 'path' must either be an absolute path or it can be left NULL to - * use the default local output destination. - * - * Returns an lttng_session_descriptor instance on success, NULL on error. - */ +/*! +@brief + Creates a recording session descriptor to create a + \ref api-session-local-mode "local" recording session + named \lt_p{session_name}. + +@param[in] session_name + @parblock + Recording session name. + + If \c 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. + @endparblock +@param[in] trace_dir + @parblock + Absolute path of the directory containing the traces of the + recording session you create from the returned descriptor. + + If \c NULL, the output directory is, after calling + lttng_create_session_ext(), + $LTTNG_HOME/lttng-traces/NAME-TS, + with: + +
+
$LTTNG_HOME +
+ The value of the \c LTTNG_HOME environment variable, or + of the \c HOME environment variable if \c LTTNG_HOME isn't + set. + +
NAME +
+ Recording session name (\lt_p{session_name} if not \c NULL, or + an automatically generated name otherwise). + +
TS +
+ \link lttng_session_get_creation_time() Timestamp of the + creation\endlink of the recording session using the + YYYYmmdd-HHMMSS form. +
+ @endparblock + +@returns + @parblock + Recording session descriptor on success, or \c NULL on error. + + Destroy the returned descriptor with + lttng_session_descriptor_destroy(). + @endparblock + +@lt_pre_sess_name_not_auto{session_name} +@pre + If not \c NULL, \lt_p{trace_dir} is a valid path. + +@sa lttng_session_descriptor_create() -- + Creates a recording session descriptor to create a + \ref api-session-local-mode "local" recording session without an + output. +*/ LTTNG_EXPORT extern struct lttng_session_descriptor * -lttng_session_descriptor_local_create(const char *name, const char *path); +lttng_session_descriptor_local_create(const char *session_name, const char *trace_dir); -/* - * Create a session descriptor with a remote output destination. - * - * The 'name' parameter can be left NULL to auto-generate a session name. - * - * The 'control_url' and 'data_url' must conform to the URL format - * described above or can be left NULL to use the default network output. - * - * Returns an lttng_session_descriptor instance on success, NULL on error. - */ +/*! +@brief + Creates a recording session descriptor to create a + \ref api-session-net-mode "network streaming" recording session + named \lt_p{session_name}. + +The valid combinations of \lt_p{control_url} and \lt_p{data_url} are: + + + + + + + +
\lt_p{control_url} + \lt_p{data_url} + Behaviour +
\c NULL + \c NULL + + Use \lt_def_net_ctrl_url as \lt_p{control_url}. + + Use \lt_def_net_data_url as \lt_p{data_url}. +
\ref api-session-one-port-url "Single-port output URL" + \c NULL + + Use the protocol, host, and trace directory (if any) of + \lt_p{control_url} and the port \lt_def_net_data_port + as \lt_p{data_url}. +
Single-port output URL + + Single-port output URL with the exact same protocol, host, + and trace directory (if any) as \lt_p{control_url}. + + Use the specified output URLs. +
\ref api-session-two-port-url "Two-port output URL" + \c NULL + + Use the protocol, host, data port, and trace directory (if any) + of \lt_p{control_url} as \lt_p{data_url}. +
+ +@param[in] session_name + @parblock + Recording session name. + + If \c 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. + @endparblock +@param[in] control_url + @parblock + One of: + +
+
\ref api-session-one-port-url "Single-port output URL" +
+ Indicates where (to which relay daemon; see + \lt_man{lttng-relayd,8}) to send the control data. + +
\ref api-session-two-port-url "Two-port output URL" +
+ Indicates where to send the control \em and trace data. +
+ + If \c NULL, this function uses \lt_def_net_url. + @endparblock +@param[in] data_url + @parblock + \ref api-session-one-port-url "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 \lt_p{control_url}. + @endparblock + +@returns + @parblock + Recording session descriptor on success, or \c NULL on error. + + Destroy the returned descriptor with + lttng_session_descriptor_destroy(). + @endparblock + +@lt_pre_sess_name_not_auto{session_name} +@pre + \lt_p{control_url} and \lt_p{data_url} satisfy one of the valid + combinations shown in the table above. +*/ LTTNG_EXPORT extern struct lttng_session_descriptor *lttng_session_descriptor_network_create( - const char *name, const char *control_url, const char *data_url); + const char *session_name, const char *control_url, const char *data_url); -/* - * Create a snapshot session descriptor without a default output. - * - * The 'name' parameter can be left NULL to auto-generate a session name. - * - * Returns an lttng_session_descriptor instance on success, NULL on error. - */ +/*! +@brief + Creates a recording session descriptor to create a + \ref api-session-snapshot-mode "snapshot" recording session + named \lt_p{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(). + +@param[in] session_name + @parblock + Recording session name. + + If \c 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. + @endparblock + +@returns + @parblock + Recording session descriptor on success, or \c NULL on error. + + Destroy the returned descriptor with + lttng_session_descriptor_destroy(). + @endparblock + +@lt_pre_sess_name_not_auto{session_name} + +@sa lttng_session_descriptor_snapshot_local_create() -- + Creates a recording session descriptor to create a + \ref api-session-snapshot-mode "snapshot" recording session + with an initial local output. +@sa lttng_session_descriptor_snapshot_network_create() -- + Creates a recording session descriptor to create a + \ref api-session-snapshot-mode "snapshot" recording session + with an initial remote output. +*/ LTTNG_EXPORT extern struct lttng_session_descriptor * -lttng_session_descriptor_snapshot_create(const char *name); +lttng_session_descriptor_snapshot_create(const char *session_name); -/* - * Create a snapshot session descriptor with a local output destination. - * - * The 'name' parameter can be left NULL to auto-generate a session name. - * - * The 'path' must either be an absolute path or it can be left NULL to - * use the default local output destination as the default snapshot output. - * - * Returns an lttng_session_descriptor instance on success, NULL on error. - */ +/*! +@brief + Creates a recording session descriptor to create a + \ref api-session-snapshot-mode "snapshot" recording session + named \lt_p{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. + +@param[in] session_name + @parblock + Recording session name. + + If \c 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. + @endparblock +@param[in] trace_dir + @parblock + Absolute path of an initial snapshot output. + + If \c 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 \c LTTNG_HOME environment variable, or + of the \c HOME environment variable if \c LTTNG_HOME isn't + set. + +
NAME +
+ Recording session name (\lt_p{session_name} if not \c NULL, or + an automatically generated name otherwise). + +
TS +
+ \link lttng_session_get_creation_time() Timestamp of the + creation\endlink of the recording session using the + YYYYmmdd-HHMMSS form. +
+ @endparblock + +@returns + @parblock + Recording session descriptor on success, or \c NULL on error. + + Destroy the returned descriptor with + lttng_session_descriptor_destroy(). + @endparblock + +@lt_pre_sess_name_not_auto{session_name} +@pre + If not \c NULL, \lt_p{trace_dir} is a valid path. + +@sa lttng_session_descriptor_snapshot_create() -- + Creates a recording session descriptor to create a + \ref api-session-snapshot-mode "snapshot" recording session + without an initial output. +@sa lttng_session_descriptor_snapshot_network_create() -- + Creates a recording session descriptor to create a + \ref api-session-snapshot-mode "snapshot" recording session + with an initial remote output. +*/ LTTNG_EXPORT extern struct lttng_session_descriptor * -lttng_session_descriptor_snapshot_local_create(const char *name, const char *path); +lttng_session_descriptor_snapshot_local_create(const char *session_name, const char *trace_dir); -/* - * Create a snapshot session descriptor with a remote output destination. - * - * The 'name' parameter can be left NULL to auto-generate a session name. - * - * The 'control_url' and 'data_url' must conform to the URL format - * described above or can be left NULL to use the default network output as - * the default snapshot output. - * - * Returns an lttng_session_descriptor instance on success, NULL on error. - */ +/*! +@brief + Creates a recording session descriptor to create a + \ref api-session-snapshot-mode "snapshot" recording session + named \lt_p{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 \lt_p{control_url} and \lt_p{data_url} are: + + + + + + + +
\lt_p{control_url} + \lt_p{data_url} + Behaviour +
\c NULL + \c NULL + + Use \lt_def_net_ctrl_url as \lt_p{control_url}. + + Use \lt_def_net_data_url as \lt_p{data_url}. +
\ref api-session-one-port-url "Single-port output URL" + \c NULL + + Use the protocol, host, and trace directory (if any) of + \lt_p{control_url} and the port \lt_def_net_data_port + as \lt_p{data_url}. +
Single-port output URL + + Single-port output URL with the exact same protocol, host, + and trace directory (if any) as \lt_p{control_url}. + + Use the specified output URLs. +
\ref api-session-two-port-url "Two-port output URL" + \c NULL + + Use the protocol, host, data port, and trace directory (if any) + of \lt_p{control_url} as \lt_p{data_url}. +
+ +@param[in] session_name + @parblock + Recording session name. + + If \c 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. + @endparblock +@param[in] control_url + @parblock + Control data URL of an initial snapshot output. + + One of: + +
+
\ref api-session-one-port-url "Single-port output URL" +
+ Indicates where (to which relay daemon; see + \lt_man{lttng-relayd,8}) to send the control data. + +
\ref api-session-two-port-url "Two-port output URL" +
+ Indicates where to send the control \em and trace data. +
+ + If \c NULL, this function uses \lt_def_net_url. + @endparblock +@param[in] data_url + @parblock + Trace data URL of an initial snapshot output. + + \ref api-session-one-port-url "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 \lt_p{control_url}. + @endparblock + +@returns + @parblock + Recording session descriptor on success, or \c NULL on error. + + Destroy the returned descriptor with + lttng_session_descriptor_destroy(). + @endparblock + +@lt_pre_sess_name_not_auto{session_name} +@pre + \lt_p{control_url} and \lt_p{data_url} satisfy one of the valid + combinations shown in the table above. + +@sa lttng_session_descriptor_snapshot_create() -- + Creates a recording session descriptor to create a + \ref api-session-snapshot-mode "snapshot" recording session + without an initial output. +@sa lttng_session_descriptor_snapshot_local_create() -- + Creates a recording session descriptor to create a + \ref api-session-snapshot-mode "snapshot" recording session + with an initial local output. +*/ LTTNG_EXPORT extern struct lttng_session_descriptor * -lttng_session_descriptor_snapshot_network_create(const char *name, +lttng_session_descriptor_snapshot_network_create(const char *session_name, const char *control_url, const char *data_url); /* + * NOTE: Not documented with Doxygen as what lttng_create_session_ext() + * creates from such a descriptor is useless (a live recording session + * without any output). Original documentation follows. + * * Create a live session descriptor without an output. * * The 'name' parameter can be left NULL to auto-generate a session name. @@ -189,27 +578,109 @@ lttng_session_descriptor_snapshot_network_create(const char *name, LTTNG_EXPORT extern struct lttng_session_descriptor * lttng_session_descriptor_live_create(const char *name, unsigned long long live_timer_interval_us); -/* - * Create a live session descriptor with a remote output destination. - * - * The 'name' parameter can be left NULL to auto-generate a session name. - * - * The 'control_url' and 'data_url' must conform to the URL format - * described above or can be left NULL to use the default network output. - * - * The 'live_timer_interval_us' parameter is the live timer's period, specified - * in microseconds. - * - * This parameter can't be 0. There is no default value defined for a live - * timer's period. - * - * Returns an lttng_session_descriptor instance on success, NULL on error. - */ +/*! +@brief + Creates a recording session descriptor to create a + \ref api-session-live-mode "live" recording session + named \lt_p{session_name}. + +The valid combinations of \lt_p{control_url} and \lt_p{data_url} are: + + + + + + + +
\lt_p{control_url} + \lt_p{data_url} + Behaviour +
\c NULL + \c NULL + + Use \lt_def_net_ctrl_url as \lt_p{control_url}. + + Use \lt_def_net_data_url as \lt_p{data_url}. +
\ref api-session-one-port-url "Single-port output URL" + \c NULL + + Use the protocol, host, and trace directory (if any) of + \lt_p{control_url} and the port \lt_def_net_data_port + as \lt_p{data_url}. +
Single-port output URL + + Single-port output URL with the exact same protocol, host, + and trace directory (if any) as \lt_p{control_url}. + + Use the specified output URLs. +
\ref api-session-two-port-url "Two-port output URL" + \c NULL + + Use the protocol, host, data port, and trace directory (if any) + of \lt_p{control_url} as \lt_p{data_url}. +
+ +@param[in] session_name + @parblock + Recording session name. + + If \c 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. + @endparblock +@param[in] control_url + @parblock + One of: + +
+
\ref api-session-one-port-url "Single-port output URL" +
+ Indicates where (to which relay daemon; see + \lt_man{lttng-relayd,8}) to send the control data. + +
\ref api-session-two-port-url "Two-port output URL" +
+ Indicates where to send the control \em and trace data. +
+ + If \c NULL, this function uses \lt_def_net_url. + @endparblock +@param[in] data_url + @parblock + \ref api-session-one-port-url "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 \lt_p{control_url}. + @endparblock +@param[in] live_timer_period + Period (µs) of the \ref api-channel-live-timer "live timers" of all + the channels of a recording session which lttng_create_session_ext() + creates from the returned descriptor. + +@returns + @parblock + Recording session descriptor on success, or \c NULL on error. + + Destroy the returned descriptor with + lttng_session_descriptor_destroy(). + @endparblock + +@lt_pre_sess_name_not_auto{session_name} +@pre + \lt_p{control_url} and \lt_p{data_url} satisfy one of the valid + combinations shown in the table above. +@pre + \lt_p{live_timer_period} â‰¥ 1 +*/ LTTNG_EXPORT extern struct lttng_session_descriptor * -lttng_session_descriptor_live_network_create(const char *name, +lttng_session_descriptor_live_network_create(const char *session_name, const char *control_url, const char *data_url, - unsigned long long live_timer_interval_us); + unsigned long long live_timer_period); /* * Get a session descriptor's session name. @@ -226,18 +697,75 @@ lttng_session_descriptor_live_network_create(const char *name, * NULL, and LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET if the descriptor's * name parameter is unset. */ + +/*! +@brief + Sets \lt_p{*session_name} to the name of the recording session + which lttng_create_session_ext() created from the recording + session descriptor \lt_p{session_descriptor}. + +Call this function after successfully calling lttng_create_session_ext() +when \lt_p{session_descriptor} wasn't created with a specific recording +session name to get the automatically generated name of the created +recording session. + +@param[in] session_descriptor + Recording session descriptor from which lttng_create_session_ext() + previously created the recording session of which to get the name. +@param[out] session_name + @parblock + On success, this function sets \lt_p{*session_name} + to the name of the recording session which + lttng_create_session_ext() previously created from + \lt_p{session_descriptor}. + + \lt_p{session_descriptor} owns \lt_p{*session_name}. + + \lt_p{*session_name} remains valid until the next recording + session descriptor function call with \lt_p{session_descriptor}. + @endparblock + +@retval #LTTNG_SESSION_DESCRIPTOR_STATUS_OK + Success. +@retval #LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID + Unsatisfied precondition. +@retval #LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET + The name property of \lt_p{session_descriptor} is not set. + +@lt_pre_not_null{session_descriptor} +@pre + You successfully called lttng_create_session_ext() with + \lt_p{session_descriptor}. +@lt_pre_not_null{session_name} +*/ LTTNG_EXPORT extern enum lttng_session_descriptor_status -lttng_session_descriptor_get_session_name(const struct lttng_session_descriptor *descriptor, - const char **name); +lttng_session_descriptor_get_session_name(const struct lttng_session_descriptor *session_descriptor, + const char **session_name); -/* - * Destroy a local lttng_session object. - * - * This does not destroy the session on the session daemon; it releases - * the resources allocated by the descriptor object. - */ +/*! +@brief + Destroys the recording session descriptor \lt_p{session_descriptor}. + +@note + @parblock + This function doesn't destroy the recording session which + lttng_create_session_ext() created from \lt_p{session_descriptor}, + but only the descriptor itself. + + Use lttng_destroy_session_ext() to destroy a recording session. + @endparblock + +@param[in] session_descriptor + @parblock + Recording session descriptor to destroy. + + May be \c NULL. + @endparblock +*/ LTTNG_EXPORT extern void -lttng_session_descriptor_destroy(struct lttng_session_descriptor *descriptor); +lttng_session_descriptor_destroy(struct lttng_session_descriptor *session_descriptor); + +/// @} #ifdef __cplusplus }