| 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 | #include <lttng/lttng-export.h> |
| 16 | |
| 17 | /*! |
| 18 | @addtogroup api_session_descr |
| 19 | @{ |
| 20 | */ |
| 21 | |
| 22 | /*! |
| 23 | @struct lttng_session_descriptor |
| 24 | |
| 25 | @brief |
| 26 | Recording session descriptor (opaque type). |
| 27 | */ |
| 28 | struct lttng_session_descriptor; |
| 29 | |
| 30 | /* |
| 31 | * Session descriptor API. |
| 32 | * |
| 33 | * A session descriptor is an object describing the immutable configuration |
| 34 | * options of an LTTng tracing session. |
| 35 | * |
| 36 | * When used with the lttng_create_session_ext() function, a session descriptor |
| 37 | * allows the creation of a tracing session of the following types: regular, |
| 38 | * snapshot, and live. |
| 39 | * |
| 40 | * Certain parameters can be omitted at the time of creation of a session |
| 41 | * descriptor to use default or auto-generated values selected by the |
| 42 | * session daemon. For instance, a session's name can be left unspecified, |
| 43 | * in which case one that is guaranteed not to clash with pre-existing |
| 44 | * sessions will be automatically be generated by the session daemon. |
| 45 | * |
| 46 | * Most session descriptors can be created in either "no output", local, or |
| 47 | * network output modes. The various output modes supported vary by session |
| 48 | * type. |
| 49 | * |
| 50 | * Regular session creation functions and output modes: |
| 51 | * * "no output": lttng_session_descriptor_create() |
| 52 | * * local: lttng_session_descriptor_local_create() |
| 53 | * * network: lttng_session_descriptor_network_create() |
| 54 | * |
| 55 | * Snapshot session creation functions and output modes: |
| 56 | * * "no output": lttng_session_descriptor_snapshot_create() |
| 57 | * * local: lttng_session_descriptor_snapshot_local_create() |
| 58 | * * network: lttng_session_descriptor_snapshot_network_create() |
| 59 | * |
| 60 | * Live session creation functions and output modes: |
| 61 | * * "no output": lttng_session_descriptor_live_create() |
| 62 | * * network: lttng_session_descriptor_live_network_create() |
| 63 | * |
| 64 | * Local output functions accept a 'path' parameter that must be an absolute |
| 65 | * path to which the user has write access. When a local output is automatically |
| 66 | * generated, it adopts the form: |
| 67 | * $LTTNG_HOME/DEFAULT_TRACE_DIR_NAME/SESSION_NAME-CREATION_TIME |
| 68 | * |
| 69 | * Where CREATION_TIME is time of the creation of the session on the session |
| 70 | * daemon in the form "yyyymmdd-hhmmss". |
| 71 | * |
| 72 | * Network output locations can also be auto-generated by leaving the |
| 73 | * 'control_url' and 'data_url' output parameters unspecified. In such cases, |
| 74 | * the session daemon will create a default output targeting a relay daemon |
| 75 | * at net://127.0.0.1, using the default 'control' and 'data' ports. |
| 76 | * |
| 77 | * The format of the 'control_url' and 'data_url' parameters is: |
| 78 | * NETPROTO://(HOST | IPADDR)[:CTRLPORT[:DATAPORT]][/TRACEPATH] |
| 79 | * |
| 80 | * NETPROTO: Network protocol, amongst: |
| 81 | * * net: TCP over IPv4; the default values of 'CTRLPORT' and 'DATAPORT' |
| 82 | * are defined at build time of the lttng toolchain. |
| 83 | * * net6: TCP over IPv6: same default ports as the 'net' protocol. |
| 84 | * * tcp: Same as the 'net' protocol. |
| 85 | * * tcp6: Same as the 'net6' protocol. |
| 86 | * |
| 87 | * HOST | IPADDR: Hostname or IP address (IPv6 address *must* be enclosed |
| 88 | * in brackets; see RFC 2732). |
| 89 | * |
| 90 | * CTRLPORT: Control port. |
| 91 | * |
| 92 | * DATAPORT: Data port. |
| 93 | * |
| 94 | * TRACEPATH: Path of trace files on the remote file system. This path is |
| 95 | * relative to the base output directory set on the relay daemon |
| 96 | * end. |
| 97 | * |
| 98 | * The 'data_url' parameter is optional: |
| 99 | * * This parameter is meaningless for local tracing. |
| 100 | * * If 'control_url' is specified and a network protocol is used, the |
| 101 | * default data port, and the 'control_url' host will be used. |
| 102 | */ |
| 103 | |
| 104 | /*! |
| 105 | @brief |
| 106 | Return type of recording session descriptor fuctions. |
| 107 | |
| 108 | Error status enumerators have a negative value. |
| 109 | */ |
| 110 | enum lttng_session_descriptor_status { |
| 111 | /// Success. |
| 112 | LTTNG_SESSION_DESCRIPTOR_STATUS_OK = 0, |
| 113 | |
| 114 | /// Unsatisfied precondition. |
| 115 | LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID = -1, |
| 116 | |
| 117 | /// Recording session descriptor property is not set. |
| 118 | LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET = 1, |
| 119 | }; |
| 120 | |
| 121 | /*! |
| 122 | @brief |
| 123 | Creates a recording session descriptor to create a no-output, |
| 124 | \ref api-session-local-mode "local" recording session |
| 125 | named \lt_p{session_name}. |
| 126 | |
| 127 | LTTng won't write any trace data for a recording session created from |
| 128 | the returned descriptor. |
| 129 | |
| 130 | @param[in] session_name |
| 131 | @parblock |
| 132 | Recording session name. |
| 133 | |
| 134 | If \c NULL, LTTng automatically generates a recording session name |
| 135 | when you call lttng_create_session_ext(). |
| 136 | |
| 137 | Call lttng_session_descriptor_get_session_name() with the returned |
| 138 | recording session descriptor after successfully calling |
| 139 | lttng_create_session_ext() to get the generated name. |
| 140 | @endparblock |
| 141 | |
| 142 | @returns |
| 143 | @parblock |
| 144 | Recording session descriptor on success, or \c NULL on error. |
| 145 | |
| 146 | Destroy the returned descriptor with |
| 147 | lttng_session_descriptor_destroy(). |
| 148 | @endparblock |
| 149 | |
| 150 | @sa lttng_session_descriptor_local_create() -- |
| 151 | Creates a recording session descriptor to create a |
| 152 | \ref api-session-local-mode "local" recording session with an |
| 153 | output. |
| 154 | |
| 155 | @lt_pre_sess_name_not_auto{session_name} |
| 156 | */ |
| 157 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
| 158 | lttng_session_descriptor_create(const char *session_name); |
| 159 | |
| 160 | /*! |
| 161 | @brief |
| 162 | Creates a recording session descriptor to create a |
| 163 | \ref api-session-local-mode "local" recording session |
| 164 | named \lt_p{session_name}. |
| 165 | |
| 166 | @param[in] session_name |
| 167 | @parblock |
| 168 | Recording session name. |
| 169 | |
| 170 | If \c NULL, LTTng automatically generates a recording session name |
| 171 | when you call lttng_create_session_ext(). |
| 172 | |
| 173 | Call lttng_session_descriptor_get_session_name() with the returned |
| 174 | recording session descriptor after successfully calling |
| 175 | lttng_create_session_ext() to get the generated name. |
| 176 | @endparblock |
| 177 | @param[in] trace_dir |
| 178 | @parblock |
| 179 | Absolute path of the directory containing the traces of the |
| 180 | recording session you create from the returned descriptor. |
| 181 | |
| 182 | If \c NULL, the output directory is, after calling |
| 183 | lttng_create_session_ext(), |
| 184 | <code><em>$LTTNG_HOME</em>/lttng-traces/<em>NAME</em>-<em>TS</em></code>, |
| 185 | with: |
| 186 | |
| 187 | <dl> |
| 188 | <dt><code><em>$LTTNG_HOME</em></code> |
| 189 | <dd> |
| 190 | The value of the \c LTTNG_HOME environment variable, or |
| 191 | of the \c HOME environment variable if \c LTTNG_HOME isn't |
| 192 | set. |
| 193 | |
| 194 | <dt><code><em>NAME</em></code> |
| 195 | <dd> |
| 196 | Recording session name (\lt_p{session_name} if not \c NULL, or |
| 197 | an automatically generated name otherwise). |
| 198 | |
| 199 | <dt><code><em>TS</em></code> |
| 200 | <dd> |
| 201 | \link lttng_session_get_creation_time() Timestamp of the |
| 202 | creation\endlink of the recording session using the |
| 203 | <code>YYYYmmdd-HHMMSS</code> form. |
| 204 | </dl> |
| 205 | @endparblock |
| 206 | |
| 207 | @returns |
| 208 | @parblock |
| 209 | Recording session descriptor on success, or \c NULL on error. |
| 210 | |
| 211 | Destroy the returned descriptor with |
| 212 | lttng_session_descriptor_destroy(). |
| 213 | @endparblock |
| 214 | |
| 215 | @lt_pre_sess_name_not_auto{session_name} |
| 216 | @pre |
| 217 | <strong>If not \c NULL</strong>, \lt_p{trace_dir} is a valid path. |
| 218 | |
| 219 | @sa lttng_session_descriptor_create() -- |
| 220 | Creates a recording session descriptor to create a |
| 221 | \ref api-session-local-mode "local" recording session without an |
| 222 | output. |
| 223 | */ |
| 224 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
| 225 | lttng_session_descriptor_local_create(const char *session_name, const char *trace_dir); |
| 226 | |
| 227 | /*! |
| 228 | @brief |
| 229 | Creates a recording session descriptor to create a |
| 230 | \ref api-session-net-mode "network streaming" recording session |
| 231 | named \lt_p{session_name}. |
| 232 | |
| 233 | The valid combinations of \lt_p{control_url} and \lt_p{data_url} are: |
| 234 | |
| 235 | <table> |
| 236 | <tr> |
| 237 | <th>\lt_p{control_url} |
| 238 | <th>\lt_p{data_url} |
| 239 | <th>Behaviour |
| 240 | <tr> |
| 241 | <td>\c NULL |
| 242 | <td>\c NULL |
| 243 | <td> |
| 244 | Use \lt_def_net_ctrl_url as \lt_p{control_url}. |
| 245 | |
| 246 | Use \lt_def_net_data_url as \lt_p{data_url}. |
| 247 | <tr> |
| 248 | <td>\ref api-session-one-port-url "Single-port output URL" |
| 249 | <td>\c NULL |
| 250 | <td> |
| 251 | Use the protocol, host, and trace directory (if any) of |
| 252 | \lt_p{control_url} and the port \lt_def_net_data_port |
| 253 | as \lt_p{data_url}. |
| 254 | <tr> |
| 255 | <td>Single-port output URL |
| 256 | <td> |
| 257 | Single-port output URL with the exact same protocol, host, |
| 258 | and trace directory (if any) as \lt_p{control_url}. |
| 259 | <td> |
| 260 | Use the specified output URLs. |
| 261 | <tr> |
| 262 | <td>\ref api-session-two-port-url "Two-port output URL" |
| 263 | <td>\c NULL |
| 264 | <td> |
| 265 | Use the protocol, host, data port, and trace directory (if any) |
| 266 | of \lt_p{control_url} as \lt_p{data_url}. |
| 267 | </table> |
| 268 | |
| 269 | @param[in] session_name |
| 270 | @parblock |
| 271 | Recording session name. |
| 272 | |
| 273 | If \c NULL, LTTng automatically generates a recording session name |
| 274 | when you call lttng_create_session_ext(). |
| 275 | |
| 276 | Call lttng_session_descriptor_get_session_name() with the returned |
| 277 | recording session descriptor after successfully calling |
| 278 | lttng_create_session_ext() to get the generated name. |
| 279 | @endparblock |
| 280 | @param[in] control_url |
| 281 | @parblock |
| 282 | One of: |
| 283 | |
| 284 | <dl> |
| 285 | <dt>\ref api-session-one-port-url "Single-port output URL" |
| 286 | <dd> |
| 287 | Indicates where (to which relay daemon; see |
| 288 | \lt_man{lttng-relayd,8}) to send the control data. |
| 289 | |
| 290 | <dt>\ref api-session-two-port-url "Two-port output URL" |
| 291 | <dd> |
| 292 | Indicates where to send the control \em and trace data. |
| 293 | </dl> |
| 294 | |
| 295 | If \c NULL, this function uses \lt_def_net_url. |
| 296 | @endparblock |
| 297 | @param[in] data_url |
| 298 | @parblock |
| 299 | \ref api-session-one-port-url "Single-port output URL" which |
| 300 | indicates where to send the trace data. |
| 301 | |
| 302 | May be <code>NULL</code>: see the table above for the default value |
| 303 | depending on \lt_p{control_url}. |
| 304 | @endparblock |
| 305 | |
| 306 | @returns |
| 307 | @parblock |
| 308 | Recording session descriptor on success, or \c NULL on error. |
| 309 | |
| 310 | Destroy the returned descriptor with |
| 311 | lttng_session_descriptor_destroy(). |
| 312 | @endparblock |
| 313 | |
| 314 | @lt_pre_sess_name_not_auto{session_name} |
| 315 | @pre |
| 316 | \lt_p{control_url} and \lt_p{data_url} satisfy one of the valid |
| 317 | combinations shown in the table above. |
| 318 | */ |
| 319 | LTTNG_EXPORT extern struct lttng_session_descriptor *lttng_session_descriptor_network_create( |
| 320 | const char *session_name, const char *control_url, const char *data_url); |
| 321 | |
| 322 | /*! |
| 323 | @brief |
| 324 | Creates a recording session descriptor to create a |
| 325 | \ref api-session-snapshot-mode "snapshot" recording session |
| 326 | named \lt_p{session_name} without an initial output. |
| 327 | |
| 328 | A recording session which lttng_create_session_ext() creates from the |
| 329 | returned descriptor has no initial snapshot output: you need to either |
| 330 | add one with lttng_snapshot_add_output() or provide one when you take a |
| 331 | snapshot with lttng_snapshot_record(). |
| 332 | |
| 333 | @param[in] session_name |
| 334 | @parblock |
| 335 | Recording session name. |
| 336 | |
| 337 | If \c NULL, LTTng automatically generates a recording session name |
| 338 | when you call lttng_create_session_ext(). |
| 339 | |
| 340 | Call lttng_session_descriptor_get_session_name() with the returned |
| 341 | recording session descriptor after successfully calling |
| 342 | lttng_create_session_ext() to get the generated name. |
| 343 | @endparblock |
| 344 | |
| 345 | @returns |
| 346 | @parblock |
| 347 | Recording session descriptor on success, or \c NULL on error. |
| 348 | |
| 349 | Destroy the returned descriptor with |
| 350 | lttng_session_descriptor_destroy(). |
| 351 | @endparblock |
| 352 | |
| 353 | @lt_pre_sess_name_not_auto{session_name} |
| 354 | |
| 355 | @sa lttng_session_descriptor_snapshot_local_create() -- |
| 356 | Creates a recording session descriptor to create a |
| 357 | \ref api-session-snapshot-mode "snapshot" recording session |
| 358 | with an initial local output. |
| 359 | @sa lttng_session_descriptor_snapshot_network_create() -- |
| 360 | Creates a recording session descriptor to create a |
| 361 | \ref api-session-snapshot-mode "snapshot" recording session |
| 362 | with an initial remote output. |
| 363 | */ |
| 364 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
| 365 | lttng_session_descriptor_snapshot_create(const char *session_name); |
| 366 | |
| 367 | /*! |
| 368 | @brief |
| 369 | Creates a recording session descriptor to create a |
| 370 | \ref api-session-snapshot-mode "snapshot" recording session |
| 371 | named \lt_p{session_name} and having an initial local output. |
| 372 | |
| 373 | Using the returned descriptor when you call lttng_create_session_ext() |
| 374 | to create a snapshot recording session is similar to using a descriptor |
| 375 | which lttng_session_descriptor_snapshot_create() returns and calling |
| 376 | lttng_snapshot_add_output() after creating the recording session. |
| 377 | |
| 378 | The name of this initial snapshot output is <code>snapshot-0</code>. |
| 379 | |
| 380 | @param[in] session_name |
| 381 | @parblock |
| 382 | Recording session name. |
| 383 | |
| 384 | If \c NULL, LTTng automatically generates a recording session name |
| 385 | when you call lttng_create_session_ext(). |
| 386 | |
| 387 | Call lttng_session_descriptor_get_session_name() with the returned |
| 388 | recording session descriptor after successfully calling |
| 389 | lttng_create_session_ext() to get the generated name. |
| 390 | @endparblock |
| 391 | @param[in] trace_dir |
| 392 | @parblock |
| 393 | Absolute path of an initial snapshot output. |
| 394 | |
| 395 | If \c NULL, the snapshot output directory is, after calling |
| 396 | lttng_create_session_ext(), |
| 397 | <code><em>$LTTNG_HOME</em>/lttng-traces/<em>NAME</em>-<em>TS</em></code>, |
| 398 | with: |
| 399 | |
| 400 | <dl> |
| 401 | <dt><code><em>$LTTNG_HOME</em></code> |
| 402 | <dd> |
| 403 | The value of the \c LTTNG_HOME environment variable, or |
| 404 | of the \c HOME environment variable if \c LTTNG_HOME isn't |
| 405 | set. |
| 406 | |
| 407 | <dt><code><em>NAME</em></code> |
| 408 | <dd> |
| 409 | Recording session name (\lt_p{session_name} if not \c NULL, or |
| 410 | an automatically generated name otherwise). |
| 411 | |
| 412 | <dt><code><em>TS</em></code> |
| 413 | <dd> |
| 414 | \link lttng_session_get_creation_time() Timestamp of the |
| 415 | creation\endlink of the recording session using the |
| 416 | <code>YYYYmmdd-HHMMSS</code> form. |
| 417 | </dl> |
| 418 | @endparblock |
| 419 | |
| 420 | @returns |
| 421 | @parblock |
| 422 | Recording session descriptor on success, or \c NULL on error. |
| 423 | |
| 424 | Destroy the returned descriptor with |
| 425 | lttng_session_descriptor_destroy(). |
| 426 | @endparblock |
| 427 | |
| 428 | @lt_pre_sess_name_not_auto{session_name} |
| 429 | @pre |
| 430 | <strong>If not \c NULL</strong>, \lt_p{trace_dir} is a valid path. |
| 431 | |
| 432 | @sa lttng_session_descriptor_snapshot_create() -- |
| 433 | Creates a recording session descriptor to create a |
| 434 | \ref api-session-snapshot-mode "snapshot" recording session |
| 435 | without an initial output. |
| 436 | @sa lttng_session_descriptor_snapshot_network_create() -- |
| 437 | Creates a recording session descriptor to create a |
| 438 | \ref api-session-snapshot-mode "snapshot" recording session |
| 439 | with an initial remote output. |
| 440 | */ |
| 441 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
| 442 | lttng_session_descriptor_snapshot_local_create(const char *session_name, const char *trace_dir); |
| 443 | |
| 444 | /*! |
| 445 | @brief |
| 446 | Creates a recording session descriptor to create a |
| 447 | \ref api-session-snapshot-mode "snapshot" recording session |
| 448 | named \lt_p{session_name} and having an initial remote output. |
| 449 | |
| 450 | Using the returned descriptor when you call lttng_create_session_ext() |
| 451 | to create a snapshot recording session is similar to using a descriptor |
| 452 | which lttng_session_descriptor_snapshot_create() returns and calling |
| 453 | lttng_snapshot_add_output() after creating the recording session. |
| 454 | |
| 455 | The name of this initial snapshot output is <code>snapshot-0</code>. |
| 456 | |
| 457 | The valid combinations of \lt_p{control_url} and \lt_p{data_url} are: |
| 458 | |
| 459 | <table> |
| 460 | <tr> |
| 461 | <th>\lt_p{control_url} |
| 462 | <th>\lt_p{data_url} |
| 463 | <th>Behaviour |
| 464 | <tr> |
| 465 | <td>\c NULL |
| 466 | <td>\c NULL |
| 467 | <td> |
| 468 | Use \lt_def_net_ctrl_url as \lt_p{control_url}. |
| 469 | |
| 470 | Use \lt_def_net_data_url as \lt_p{data_url}. |
| 471 | <tr> |
| 472 | <td>\ref api-session-one-port-url "Single-port output URL" |
| 473 | <td>\c NULL |
| 474 | <td> |
| 475 | Use the protocol, host, and trace directory (if any) of |
| 476 | \lt_p{control_url} and the port \lt_def_net_data_port |
| 477 | as \lt_p{data_url}. |
| 478 | <tr> |
| 479 | <td>Single-port output URL |
| 480 | <td> |
| 481 | Single-port output URL with the exact same protocol, host, |
| 482 | and trace directory (if any) as \lt_p{control_url}. |
| 483 | <td> |
| 484 | Use the specified output URLs. |
| 485 | <tr> |
| 486 | <td>\ref api-session-two-port-url "Two-port output URL" |
| 487 | <td>\c NULL |
| 488 | <td> |
| 489 | Use the protocol, host, data port, and trace directory (if any) |
| 490 | of \lt_p{control_url} as \lt_p{data_url}. |
| 491 | </table> |
| 492 | |
| 493 | @param[in] session_name |
| 494 | @parblock |
| 495 | Recording session name. |
| 496 | |
| 497 | If \c NULL, LTTng automatically generates a recording session name |
| 498 | when you call lttng_create_session_ext(). |
| 499 | |
| 500 | Call lttng_session_descriptor_get_session_name() with the returned |
| 501 | recording session descriptor after successfully calling |
| 502 | lttng_create_session_ext() to get the generated name. |
| 503 | @endparblock |
| 504 | @param[in] control_url |
| 505 | @parblock |
| 506 | Control data URL of an initial snapshot output. |
| 507 | |
| 508 | One of: |
| 509 | |
| 510 | <dl> |
| 511 | <dt>\ref api-session-one-port-url "Single-port output URL" |
| 512 | <dd> |
| 513 | Indicates where (to which relay daemon; see |
| 514 | \lt_man{lttng-relayd,8}) to send the control data. |
| 515 | |
| 516 | <dt>\ref api-session-two-port-url "Two-port output URL" |
| 517 | <dd> |
| 518 | Indicates where to send the control \em and trace data. |
| 519 | </dl> |
| 520 | |
| 521 | If \c NULL, this function uses \lt_def_net_url. |
| 522 | @endparblock |
| 523 | @param[in] data_url |
| 524 | @parblock |
| 525 | Trace data URL of an initial snapshot output. |
| 526 | |
| 527 | \ref api-session-one-port-url "Single-port output URL" which |
| 528 | indicates where to send the trace data. |
| 529 | |
| 530 | May be <code>NULL</code>: see the table above for the default value |
| 531 | depending on \lt_p{control_url}. |
| 532 | @endparblock |
| 533 | |
| 534 | @returns |
| 535 | @parblock |
| 536 | Recording session descriptor on success, or \c NULL on error. |
| 537 | |
| 538 | Destroy the returned descriptor with |
| 539 | lttng_session_descriptor_destroy(). |
| 540 | @endparblock |
| 541 | |
| 542 | @lt_pre_sess_name_not_auto{session_name} |
| 543 | @pre |
| 544 | \lt_p{control_url} and \lt_p{data_url} satisfy one of the valid |
| 545 | combinations shown in the table above. |
| 546 | |
| 547 | @sa lttng_session_descriptor_snapshot_create() -- |
| 548 | Creates a recording session descriptor to create a |
| 549 | \ref api-session-snapshot-mode "snapshot" recording session |
| 550 | without an initial output. |
| 551 | @sa lttng_session_descriptor_snapshot_local_create() -- |
| 552 | Creates a recording session descriptor to create a |
| 553 | \ref api-session-snapshot-mode "snapshot" recording session |
| 554 | with an initial local output. |
| 555 | */ |
| 556 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
| 557 | lttng_session_descriptor_snapshot_network_create(const char *session_name, |
| 558 | const char *control_url, |
| 559 | const char *data_url); |
| 560 | |
| 561 | /* |
| 562 | * NOTE: Not documented with Doxygen as what lttng_create_session_ext() |
| 563 | * creates from such a descriptor is useless (a live recording session |
| 564 | * without any output). Original documentation follows. |
| 565 | * |
| 566 | * Create a live session descriptor without an output. |
| 567 | * |
| 568 | * The 'name' parameter can be left NULL to auto-generate a session name. |
| 569 | * |
| 570 | * The 'live_timer_interval_us' parameter is the live timer's period, specified |
| 571 | * in microseconds. |
| 572 | * |
| 573 | * This parameter can't be 0. There is no default value defined for a live |
| 574 | * timer's period. |
| 575 | * |
| 576 | * Returns an lttng_session_descriptor instance on success, NULL on error. |
| 577 | */ |
| 578 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
| 579 | lttng_session_descriptor_live_create(const char *name, unsigned long long live_timer_interval_us); |
| 580 | |
| 581 | /*! |
| 582 | @brief |
| 583 | Creates a recording session descriptor to create a |
| 584 | \ref api-session-live-mode "live" recording session |
| 585 | named \lt_p{session_name}. |
| 586 | |
| 587 | The valid combinations of \lt_p{control_url} and \lt_p{data_url} are: |
| 588 | |
| 589 | <table> |
| 590 | <tr> |
| 591 | <th>\lt_p{control_url} |
| 592 | <th>\lt_p{data_url} |
| 593 | <th>Behaviour |
| 594 | <tr> |
| 595 | <td>\c NULL |
| 596 | <td>\c NULL |
| 597 | <td> |
| 598 | Use \lt_def_net_ctrl_url as \lt_p{control_url}. |
| 599 | |
| 600 | Use \lt_def_net_data_url as \lt_p{data_url}. |
| 601 | <tr> |
| 602 | <td>\ref api-session-one-port-url "Single-port output URL" |
| 603 | <td>\c NULL |
| 604 | <td> |
| 605 | Use the protocol, host, and trace directory (if any) of |
| 606 | \lt_p{control_url} and the port \lt_def_net_data_port |
| 607 | as \lt_p{data_url}. |
| 608 | <tr> |
| 609 | <td>Single-port output URL |
| 610 | <td> |
| 611 | Single-port output URL with the exact same protocol, host, |
| 612 | and trace directory (if any) as \lt_p{control_url}. |
| 613 | <td> |
| 614 | Use the specified output URLs. |
| 615 | <tr> |
| 616 | <td>\ref api-session-two-port-url "Two-port output URL" |
| 617 | <td>\c NULL |
| 618 | <td> |
| 619 | Use the protocol, host, data port, and trace directory (if any) |
| 620 | of \lt_p{control_url} as \lt_p{data_url}. |
| 621 | </table> |
| 622 | |
| 623 | @param[in] session_name |
| 624 | @parblock |
| 625 | Recording session name. |
| 626 | |
| 627 | If \c NULL, LTTng automatically generates a recording session name |
| 628 | when you call lttng_create_session_ext(). |
| 629 | |
| 630 | Call lttng_session_descriptor_get_session_name() with the returned |
| 631 | recording session descriptor after successfully calling |
| 632 | lttng_create_session_ext() to get the generated name. |
| 633 | @endparblock |
| 634 | @param[in] control_url |
| 635 | @parblock |
| 636 | One of: |
| 637 | |
| 638 | <dl> |
| 639 | <dt>\ref api-session-one-port-url "Single-port output URL" |
| 640 | <dd> |
| 641 | Indicates where (to which relay daemon; see |
| 642 | \lt_man{lttng-relayd,8}) to send the control data. |
| 643 | |
| 644 | <dt>\ref api-session-two-port-url "Two-port output URL" |
| 645 | <dd> |
| 646 | Indicates where to send the control \em and trace data. |
| 647 | </dl> |
| 648 | |
| 649 | If \c NULL, this function uses \lt_def_net_url. |
| 650 | @endparblock |
| 651 | @param[in] data_url |
| 652 | @parblock |
| 653 | \ref api-session-one-port-url "Single-port output URL" which |
| 654 | indicates where to send the trace data. |
| 655 | |
| 656 | May be <code>NULL</code>: see the table above for the default value |
| 657 | depending on \lt_p{control_url}. |
| 658 | @endparblock |
| 659 | @param[in] live_timer_period |
| 660 | Period (µs) of the \ref api-channel-live-timer "live timers" of all |
| 661 | the channels of a recording session which lttng_create_session_ext() |
| 662 | creates from the returned descriptor. |
| 663 | |
| 664 | @returns |
| 665 | @parblock |
| 666 | Recording session descriptor on success, or \c NULL on error. |
| 667 | |
| 668 | Destroy the returned descriptor with |
| 669 | lttng_session_descriptor_destroy(). |
| 670 | @endparblock |
| 671 | |
| 672 | @lt_pre_sess_name_not_auto{session_name} |
| 673 | @pre |
| 674 | \lt_p{control_url} and \lt_p{data_url} satisfy one of the valid |
| 675 | combinations shown in the table above. |
| 676 | @pre |
| 677 | \lt_p{live_timer_period} ≥ 1 |
| 678 | */ |
| 679 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
| 680 | lttng_session_descriptor_live_network_create(const char *session_name, |
| 681 | const char *control_url, |
| 682 | const char *data_url, |
| 683 | unsigned long long live_timer_period); |
| 684 | |
| 685 | /* |
| 686 | * Get a session descriptor's session name. |
| 687 | * |
| 688 | * The 'name' parameter is used as an output parameter and will point to |
| 689 | * the session descriptor's session name on success |
| 690 | * (LTTNG_SESSION_DESCRIPTOR_STATUS_OK). Its content of is left unspecified |
| 691 | * for other return codes. The pointer returned through 'name' is only |
| 692 | * guaranteed to remain valid until the next method call on the session |
| 693 | * descriptor. |
| 694 | * |
| 695 | * Returns LTTNG_SESSION_DESCRIPTOR_STATUS_OK on success, |
| 696 | * LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID if 'descriptor' or 'name' are |
| 697 | * NULL, and LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET if the descriptor's |
| 698 | * name parameter is unset. |
| 699 | */ |
| 700 | |
| 701 | /*! |
| 702 | @brief |
| 703 | Sets \lt_p{*session_name} to the name of the recording session |
| 704 | which lttng_create_session_ext() created from the recording |
| 705 | session descriptor \lt_p{session_descriptor}. |
| 706 | |
| 707 | Call this function after successfully calling lttng_create_session_ext() |
| 708 | when \lt_p{session_descriptor} wasn't created with a specific recording |
| 709 | session name to get the automatically generated name of the created |
| 710 | recording session. |
| 711 | |
| 712 | @param[in] session_descriptor |
| 713 | Recording session descriptor from which lttng_create_session_ext() |
| 714 | previously created the recording session of which to get the name. |
| 715 | @param[out] session_name |
| 716 | @parblock |
| 717 | <strong>On success</strong>, this function sets \lt_p{*session_name} |
| 718 | to the name of the recording session which |
| 719 | lttng_create_session_ext() previously created from |
| 720 | \lt_p{session_descriptor}. |
| 721 | |
| 722 | \lt_p{session_descriptor} owns \lt_p{*session_name}. |
| 723 | |
| 724 | \lt_p{*session_name} remains valid until the next recording |
| 725 | session descriptor function call with \lt_p{session_descriptor}. |
| 726 | @endparblock |
| 727 | |
| 728 | @retval #LTTNG_SESSION_DESCRIPTOR_STATUS_OK |
| 729 | Success. |
| 730 | @retval #LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID |
| 731 | Unsatisfied precondition. |
| 732 | @retval #LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET |
| 733 | The name property of \lt_p{session_descriptor} is not set. |
| 734 | |
| 735 | @lt_pre_not_null{session_descriptor} |
| 736 | @pre |
| 737 | You successfully called lttng_create_session_ext() with |
| 738 | \lt_p{session_descriptor}. |
| 739 | @lt_pre_not_null{session_name} |
| 740 | */ |
| 741 | LTTNG_EXPORT extern enum lttng_session_descriptor_status |
| 742 | lttng_session_descriptor_get_session_name(const struct lttng_session_descriptor *session_descriptor, |
| 743 | const char **session_name); |
| 744 | |
| 745 | /*! |
| 746 | @brief |
| 747 | Destroys the recording session descriptor \lt_p{session_descriptor}. |
| 748 | |
| 749 | @note |
| 750 | @parblock |
| 751 | This function doesn't destroy the recording session which |
| 752 | lttng_create_session_ext() created from \lt_p{session_descriptor}, |
| 753 | but only the descriptor itself. |
| 754 | |
| 755 | Use lttng_destroy_session_ext() to destroy a recording session. |
| 756 | @endparblock |
| 757 | |
| 758 | @param[in] session_descriptor |
| 759 | @parblock |
| 760 | Recording session descriptor to destroy. |
| 761 | |
| 762 | May be \c NULL. |
| 763 | @endparblock |
| 764 | */ |
| 765 | LTTNG_EXPORT extern void |
| 766 | lttng_session_descriptor_destroy(struct lttng_session_descriptor *session_descriptor); |
| 767 | |
| 768 | /// @} |
| 769 | |
| 770 | #ifdef __cplusplus |
| 771 | } |
| 772 | #endif |
| 773 | |
| 774 | #endif /* LTTNG_SESSION_DESCRIPTOR_H */ |