[lttng-tools.git] / include / lttng / session-descriptor.h

/*
 * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * SPDX-License-Identifier: LGPL-2.1-only
 *
 */

#ifndef LTTNG_SESSION_DESCRIPTOR_H
#define LTTNG_SESSION_DESCRIPTOR_H

#ifdef __cplusplus
extern "C" {
#endif

struct lttng_session_descriptor;

/*
 * Session descriptor API.
 *
 * A session descriptor is an object describing the immutable configuration
 * options of an LTTng tracing session.
 *
 * When used with the lttng_create_session_ext() function, a session descriptor
 * allows the creation of a tracing session of the following types: regular,
 * snapshot, and live.
 *
 * Certain parameters can be omitted at the time of creation of a session
 * descriptor to use default or auto-generated values selected by the
 * session daemon. For instance, a session's name can be left unspecified,
 * in which case one that is guaranteed not to clash with pre-existing
 * sessions will be automatically be generated by the session daemon.
 *
 * Most session descriptors can be created in either "no output", local, or
 * network output modes. The various output modes supported vary by session
 * type.
 *
 * Regular session creation functions and output modes:
 *   * "no output": lttng_session_descriptor_create()
 *   * local:       lttng_session_descriptor_local_create()
 *   * network:     lttng_session_descriptor_network_create()
 *
 * Snapshot session creation functions and output modes:
 *   * "no output": lttng_session_descriptor_snapshot_create()
 *   * local:       lttng_session_descriptor_snapshot_local_create()
 *   * network:     lttng_session_descriptor_snapshot_network_create()
 *
 * Live session creation functions and output modes:
 *   * "no output": lttng_session_descriptor_live_create()
 *   * network:     lttng_session_descriptor_live_network_create()
 *
 * Local output functions accept a 'path' parameter that must be an absolute
 * path to which the user has write access. When a local output is automatically
 * generated, it adopts the form:
 *   $LTTNG_HOME/DEFAULT_TRACE_DIR_NAME/SESSION_NAME-CREATION_TIME
 *
 * Where CREATION_TIME is time of the creation of the session on the session
 * daemon in the form "yyyymmdd-hhmmss".
 *
 * Network output locations can also be auto-generated by leaving the
 * 'control_url' and 'data_url' output parameters unspecified. In such cases,
 * the session daemon will create a default output targeting a relay daemon
 * at net://127.0.0.1, using the default 'control' and 'data' ports.
 *
 * The format of the 'control_url' and 'data_url' parameters is:
 *   NETPROTO://(HOST | IPADDR)[:CTRLPORT[:DATAPORT]][/TRACEPATH]
 *
 * NETPROTO: Network protocol, amongst:
 *   * net:  TCP over IPv4; the default values of 'CTRLPORT' and 'DATAPORT'
 *           are defined at build time of the lttng toolchain.
 *   * net6: TCP over IPv6: same default ports as the 'net' protocol.
 *   * tcp:  Same as the 'net' protocol.
 *   * tcp6: Same as the 'net6' protocol.
 *
 * HOST | IPADDR:  Hostname or IP address (IPv6 address *must* be enclosed
 *                 in brackets; see RFC 2732).
 *
 * CTRLPORT: Control port.
 *
 * DATAPORT: Data port.
 *
 * TRACEPATH: Path of trace files on the remote file system. This path is
 *            relative to the base output directory set on the relay daemon
 *            end.
 *
 * The 'data_url' parameter is optional:
 *   * This parameter is meaningless for local tracing.
 *   * If 'control_url' is specified and a network protocol is used, the
 *     default data port, and the 'control_url' host will be used.
 */

enum lttng_session_descriptor_status {
	/* Invalid session descriptor parameter. */
	LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID = -1,
	LTTNG_SESSION_DESCRIPTOR_STATUS_OK = 0,
	/* Session descriptor parameter is unset. */
	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.
 */
extern struct lttng_session_descriptor *
lttng_session_descriptor_create(const char *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.
 */
extern struct lttng_session_descriptor *
lttng_session_descriptor_local_create(const char *name, const char *path);

/*
 * 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.
 */
extern struct lttng_session_descriptor *
lttng_session_descriptor_network_create(const char *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.
 */
extern struct lttng_session_descriptor *
lttng_session_descriptor_snapshot_create(const char *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.
 */
extern struct lttng_session_descriptor *
lttng_session_descriptor_snapshot_local_create(const char *name,
		const char *path);

/*
 * 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.
 */
extern struct lttng_session_descriptor *
lttng_session_descriptor_snapshot_network_create(const char *name,
		const char *control_url, const char *data_url);

/*
 * Create a live session descriptor without an output.
 *
 * The 'name' parameter can be left NULL to auto-generate a session name.
 *
 * 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.
 */
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.
 */
extern struct lttng_session_descriptor *
lttng_session_descriptor_live_network_create(
		const char *name,
		const char *control_url, const char *data_url,
		unsigned long long live_timer_interval_us);

/*
 * Get a session descriptor's session name.
 *
 * The 'name' parameter is used as an output parameter and will point to
 * the session descriptor's session name on success
 * (LTTNG_SESSION_DESCRIPTOR_STATUS_OK). Its content of is left unspecified
 * for other return codes. The pointer returned through 'name' is only
 * guaranteed to remain valid until the next method call on the session
 * descriptor.
 *
 * Returns LTTNG_SESSION_DESCRIPTOR_STATUS_OK on success,
 * LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID if 'descriptor' or 'name' are
 * NULL, and LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET if the descriptor's
 * name parameter is unset.
 */
extern enum lttng_session_descriptor_status
lttng_session_descriptor_get_session_name(
		const struct lttng_session_descriptor *descriptor,
		const char **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.
 */
extern void lttng_session_descriptor_destroy(
		struct lttng_session_descriptor *descriptor);

#ifdef __cplusplus
}
#endif

#endif /* LTTNG_SESSION_DESCRIPTOR_H */
Commit	Line	Data
	1	/*
	2	* Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
	3	*
	4	* SPDX-License-Identifier: LGPL-2.1-only
	5	*
	6	*/
	7
	8	#ifndef LTTNG_SESSION_DESCRIPTOR_H
	9	#define LTTNG_SESSION_DESCRIPTOR_H
	10
	11	#ifdef __cplusplus
	12	extern "C" {
	13	#endif
	14
	15	struct lttng_session_descriptor;
	16
	17	/*
	18	* Session descriptor API.
	19	*
	20	* A session descriptor is an object describing the immutable configuration
	21	* options of an LTTng tracing session.
	22	*
	23	* When used with the lttng_create_session_ext() function, a session descriptor
	24	* allows the creation of a tracing session of the following types: regular,
	25	* snapshot, and live.
	26	*
	27	* Certain parameters can be omitted at the time of creation of a session
	28	* descriptor to use default or auto-generated values selected by the
	29	* session daemon. For instance, a session's name can be left unspecified,
	30	* in which case one that is guaranteed not to clash with pre-existing
	31	* sessions will be automatically be generated by the session daemon.
	32	*
	33	* Most session descriptors can be created in either "no output", local, or
	34	* network output modes. The various output modes supported vary by session
	35	* type.
	36	*
	37	* Regular session creation functions and output modes:
	38	* * "no output": lttng_session_descriptor_create()
	39	* * local: lttng_session_descriptor_local_create()
	40	* * network: lttng_session_descriptor_network_create()
	41	*
	42	* Snapshot session creation functions and output modes:
	43	* * "no output": lttng_session_descriptor_snapshot_create()
	44	* * local: lttng_session_descriptor_snapshot_local_create()
	45	* * network: lttng_session_descriptor_snapshot_network_create()
	46	*
	47	* Live session creation functions and output modes:
	48	* * "no output": lttng_session_descriptor_live_create()
	49	* * network: lttng_session_descriptor_live_network_create()
	50	*
	51	* Local output functions accept a 'path' parameter that must be an absolute
	52	* path to which the user has write access. When a local output is automatically
	53	* generated, it adopts the form:
	54	* $LTTNG_HOME/DEFAULT_TRACE_DIR_NAME/SESSION_NAME-CREATION_TIME
	55	*
	56	* Where CREATION_TIME is time of the creation of the session on the session
	57	* daemon in the form "yyyymmdd-hhmmss".
	58	*
	59	* Network output locations can also be auto-generated by leaving the
	60	* 'control_url' and 'data_url' output parameters unspecified. In such cases,
	61	* the session daemon will create a default output targeting a relay daemon
	62	* at net://127.0.0.1, using the default 'control' and 'data' ports.
	63	*
	64	* The format of the 'control_url' and 'data_url' parameters is:
	65	* NETPROTO://(HOST \| IPADDR)[:CTRLPORT[:DATAPORT]][/TRACEPATH]
	66	*
	67	* NETPROTO: Network protocol, amongst:
	68	* * net: TCP over IPv4; the default values of 'CTRLPORT' and 'DATAPORT'
	69	* are defined at build time of the lttng toolchain.
	70	* * net6: TCP over IPv6: same default ports as the 'net' protocol.
	71	* * tcp: Same as the 'net' protocol.
	72	* * tcp6: Same as the 'net6' protocol.
	73	*
	74	* HOST \| IPADDR: Hostname or IP address (IPv6 address must be enclosed
	75	* in brackets; see RFC 2732).
	76	*
	77	* CTRLPORT: Control port.
	78	*
	79	* DATAPORT: Data port.
	80	*
	81	* TRACEPATH: Path of trace files on the remote file system. This path is
	82	* relative to the base output directory set on the relay daemon
	83	* end.
	84	*
	85	* The 'data_url' parameter is optional:
	86	* * This parameter is meaningless for local tracing.
	87	* * If 'control_url' is specified and a network protocol is used, the
	88	* default data port, and the 'control_url' host will be used.
	89	*/
	90
	91	enum lttng_session_descriptor_status {
	92	/* Invalid session descriptor parameter. */
	93	LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID = -1,
	94	LTTNG_SESSION_DESCRIPTOR_STATUS_OK = 0,
	95	/* Session descriptor parameter is unset. */
	96	LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET = 1,
	97	};
	98
	99	/*
	100	* Create a session descriptor in no-output mode.
	101	*
	102	* The 'name' parameter can be left NULL to auto-generate a session name.
	103	*
	104	* Returns an lttng_session_descriptor instance on success, NULL on error.
	105	*/
	106	extern struct lttng_session_descriptor *
	107	lttng_session_descriptor_create(const char *name);
	108
	109	/*
	110	* Create a session descriptor with a local output destination.
	111	*
	112	* The 'name' parameter can be left NULL to auto-generate a session name.
	113	*
	114	* The 'path' must either be an absolute path or it can be left NULL to
	115	* use the default local output destination.
	116	*
	117	* Returns an lttng_session_descriptor instance on success, NULL on error.
	118	*/
	119	extern struct lttng_session_descriptor *
	120	lttng_session_descriptor_local_create(const char name, const char path);
	121
	122	/*
	123	* Create a session descriptor with a remote output destination.
	124	*
	125	* The 'name' parameter can be left NULL to auto-generate a session name.
	126	*
	127	* The 'control_url' and 'data_url' must conform to the URL format
	128	* described above or can be left NULL to use the default network output.
	129	*
	130	* Returns an lttng_session_descriptor instance on success, NULL on error.
	131	*/
	132	extern struct lttng_session_descriptor *
	133	lttng_session_descriptor_network_create(const char *name,
	134	const char control_url, const char data_url);
	135
	136	/*
	137	* Create a snapshot session descriptor without a default output.
	138	*
	139	* The 'name' parameter can be left NULL to auto-generate a session name.
	140	*
	141	* Returns an lttng_session_descriptor instance on success, NULL on error.
	142	*/
	143	extern struct lttng_session_descriptor *
	144	lttng_session_descriptor_snapshot_create(const char *name);
	145
	146	/*
	147	* Create a snapshot session descriptor with a local output destination.
	148	*
	149	* The 'name' parameter can be left NULL to auto-generate a session name.
	150	*
	151	* The 'path' must either be an absolute path or it can be left NULL to
	152	* use the default local output destination as the default snapshot output.
	153	*
	154	* Returns an lttng_session_descriptor instance on success, NULL on error.
	155	*/
	156	extern struct lttng_session_descriptor *
	157	lttng_session_descriptor_snapshot_local_create(const char *name,
	158	const char *path);
	159
	160	/*
	161	* Create a snapshot session descriptor with a remote output destination.
	162	*
	163	* The 'name' parameter can be left NULL to auto-generate a session name.
	164	*
	165	* The 'control_url' and 'data_url' must conform to the URL format
	166	* described above or can be left NULL to use the default network output as
	167	* the default snapshot output.
	168	*
	169	* Returns an lttng_session_descriptor instance on success, NULL on error.
	170	*/
	171	extern struct lttng_session_descriptor *
	172	lttng_session_descriptor_snapshot_network_create(const char *name,
	173	const char control_url, const char data_url);
	174
	175	/*
	176	* Create a live session descriptor without an output.
	177	*
	178	* The 'name' parameter can be left NULL to auto-generate a session name.
	179	*
	180	* The 'live_timer_interval_us' parameter is the live timer's period, specified
	181	* in microseconds.
	182	*
	183	* This parameter can't be 0. There is no default value defined for a live
	184	* timer's period.
	185	*
	186	* Returns an lttng_session_descriptor instance on success, NULL on error.
	187	*/
	188	extern struct lttng_session_descriptor *
	189	lttng_session_descriptor_live_create(
	190	const char *name, unsigned long long live_timer_interval_us);
	191
	192	/*
	193	* Create a live session descriptor with a remote output destination.
	194	*
	195	* The 'name' parameter can be left NULL to auto-generate a session name.
	196	*
	197	* The 'control_url' and 'data_url' must conform to the URL format
	198	* described above or can be left NULL to use the default network output.
	199	*
	200	* The 'live_timer_interval_us' parameter is the live timer's period, specified
	201	* in microseconds.
	202	*
	203	* This parameter can't be 0. There is no default value defined for a live
	204	* timer's period.
	205	*
	206	* Returns an lttng_session_descriptor instance on success, NULL on error.
	207	*/
	208	extern struct lttng_session_descriptor *
	209	lttng_session_descriptor_live_network_create(
	210	const char *name,
	211	const char control_url, const char data_url,
	212	unsigned long long live_timer_interval_us);
	213
	214	/*
	215	* Get a session descriptor's session name.
	216	*
	217	* The 'name' parameter is used as an output parameter and will point to
	218	* the session descriptor's session name on success
	219	* (LTTNG_SESSION_DESCRIPTOR_STATUS_OK). Its content of is left unspecified
	220	* for other return codes. The pointer returned through 'name' is only
	221	* guaranteed to remain valid until the next method call on the session
	222	* descriptor.
	223	*
	224	* Returns LTTNG_SESSION_DESCRIPTOR_STATUS_OK on success,
	225	* LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID if 'descriptor' or 'name' are
	226	* NULL, and LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET if the descriptor's
	227	* name parameter is unset.
	228	*/
	229	extern enum lttng_session_descriptor_status
	230	lttng_session_descriptor_get_session_name(
	231	const struct lttng_session_descriptor *descriptor,
	232	const char **name);
	233
	234	/*
	235	* Destroy a local lttng_session object.
	236	*
	237	* This does not destroy the session on the session daemon; it releases
	238	* the resources allocated by the descriptor object.
	239	*/
	240	extern void lttng_session_descriptor_destroy(
	241	struct lttng_session_descriptor *descriptor);
	242
	243	#ifdef __cplusplus
	244	}
	245	#endif
	246
	247	#endif /* LTTNG_SESSION_DESCRIPTOR_H */