include/lttng/lttng.h

   1 /*
   2  * lttng.h
   3  *
   4  * Linux Trace Toolkit Control Library Header File
   5  *
   6  * Copyright (C) 2011 EfficiOS Inc.
   7  *
   8  * SPDX-License-Identifier: LGPL-2.1-only
   9  *
  10  */
  11
  12 #ifndef LTTNG_H
  13 #define LTTNG_H
  14
  15 #include <lttng/lttng-export.h>
  16
  17 /* Error codes that can be returned by API calls */
  18 #include <lttng/lttng-error.h>
  19
  20 /* Include every LTTng ABI/API available. */
  21 #include <lttng/action/action.h>
  22 #include <lttng/action/list.h>
  23 #include <lttng/action/notify.h>
  24 #include <lttng/action/path.h>
  25 #include <lttng/action/rate-policy.h>
  26 #include <lttng/action/rotate-session.h>
  27 #include <lttng/action/snapshot-session.h>
  28 #include <lttng/action/start-session.h>
  29 #include <lttng/action/stop-session.h>
  30 #include <lttng/channel.h>
  31 #include <lttng/clear-handle.h>
  32 #include <lttng/clear.h>
  33 #include <lttng/condition/buffer-usage.h>
  34 #include <lttng/condition/condition.h>
  35 #include <lttng/condition/evaluation.h>
  36 #include <lttng/condition/event-rule-matches.h>
  37 #include <lttng/condition/session-consumed-size.h>
  38 #include <lttng/condition/session-rotation.h>
  39 #include <lttng/constant.h>
  40 #include <lttng/destruction-handle.h>
  41 #include <lttng/domain.h>
  42 #include <lttng/endpoint.h>
  43 #include <lttng/error-query.h>
  44 #include <lttng/event-expr.h>
  45 #include <lttng/event-field-value.h>
  46 #include <lttng/event-rule/event-rule.h>
  47 #include <lttng/event-rule/jul-logging.h>
  48 #include <lttng/event-rule/kernel-kprobe.h>
  49 #include <lttng/event-rule/kernel-syscall.h>
  50 #include <lttng/event-rule/kernel-tracepoint.h>
  51 #include <lttng/event-rule/kernel-uprobe.h>
  52 #include <lttng/event-rule/log4j-logging.h>
  53 #include <lttng/event-rule/log4j2-logging.h>
  54 #include <lttng/event-rule/python-logging.h>
  55 #include <lttng/event-rule/user-tracepoint.h>
  56 #include <lttng/event.h>
  57 #include <lttng/handle.h>
  58 #include <lttng/health.h>
  59 #include <lttng/kernel-probe.h>
  60 #include <lttng/kernel.h>
  61 #include <lttng/load.h>
  62 #include <lttng/location.h>
  63 #include <lttng/log-level-rule.h>
  64 #include <lttng/lttng-error.h>
  65 #include <lttng/notification/channel.h>
  66 #include <lttng/notification/notification.h>
  67 #include <lttng/rotation.h>
  68 #include <lttng/save.h>
  69 #include <lttng/session-descriptor.h>
  70 #include <lttng/session.h>
  71 #include <lttng/snapshot.h>
  72 #include <lttng/tracker.h>
  73 #include <lttng/trigger/trigger.h>
  74 #include <lttng/userspace-probe.h>
  75
  76 #ifdef __cplusplus
  77 extern "C" {
  78 #endif
  79
  80 enum lttng_calibrate_type {
  81         LTTNG_CALIBRATE_FUNCTION = 0,
  82 };
  83
  84 /* Machine interface output type */
  85 enum lttng_mi_output_type {
  86         LTTNG_MI_XML = 1 /* XML output */
  87 };
  88
  89 #define LTTNG_CALIBRATE_PADDING1 16
  90 struct lttng_calibrate {
  91         enum lttng_calibrate_type type;
  92
  93         char padding[LTTNG_CALIBRATE_PADDING1];
  94 };
  95
  96 /*!
  97 @brief
  98     Returns whether or not liblttng-ctl is able to connect to a
  99     listening session daemon.
 100
 101 @ingroup api_gen
 102
 103 How this function tries to
 104 \ref api-gen-sessiond-conn "connect to a session daemon" depends on the
 105 current Unix tracing group (initially \c tracing) of the library. Set
 106 the tracing group with lttng_set_tracing_group().
 107
 108 @returns
 109     @parblock
 110     One of:
 111
 112     <dl>
 113       <dt>1</dt>
 114       <dd>
 115         liblttng-ctl is able to connect to a session daemon.
 116
 117       <dt>0
 118       <dd>
 119         liblttng-ctl isn't able to connect to a session daemon.
 120
 121       <dt>Negative value
 122       <dd>
 123         Error: a negative #lttng_error_code enumerator.
 124     </dl>
 125     @endparblock
 126
 127 @sa lttng_set_tracing_group() --
 128     Sets the current Unix tracing group of liblttng-ctl.
 129 */
 130 LTTNG_EXPORT extern int lttng_session_daemon_alive(void);
 131
 132 /*!
 133 @brief
 134     Sets the current Unix tracing group of liblttng-ctl to \lt_p{group}.
 135
 136 @ingroup api_gen
 137
 138 How the liblttng-ctl functions
 139 \ref api-gen-sessiond-conn "connect to a session daemon" depends on
 140 the current Unix tracing group (initially \c tracing) of the library.
 141
 142 @param[in] group
 143     New Unix tracing group of liblttng-ctl.
 144
 145 @returns
 146     0 on success, or a \em negative #lttng_error_code enumerator
 147     otherwise.
 148
 149 @lt_pre_not_null{group}
 150 @pre
 151     \lt_p{group} names an existing Unix group.
 152 */
 153 LTTNG_EXPORT extern int lttng_set_tracing_group(const char *group);
 154
 155 /*
 156  * This call registers an "outside consumer" for a session and an lttng domain.
 157  * No consumer will be spawned and all fds/commands will go through the socket
 158  * path given (socket_path).
 159  *
 160  * NOTE that this is not recommended unless you absolutely know what you are
 161  * doing.
 162  *
 163  * Return 0 on success else a negative LTTng error code.
 164  */
 165 LTTNG_EXPORT extern int lttng_register_consumer(struct lttng_handle *handle,
 166                                                 const char *socket_path);
 167
 168 /*!
 169 @brief
 170     Makes the recording session named \lt_p{session_name} active,
 171     starting all the tracers for its
 172     \ref api-channel-channel "channels".
 173
 174 @ingroup api_session
 175
 176 @note
 177     An #LTTNG_ACTION_TYPE_START_SESSION trigger action can also activate
 178     (start) a recording session.
 179
 180 @param[in] session_name
 181     Name of the recording session to activate/start.
 182
 183 @returns
 184     0 on success, or a \em negative #lttng_error_code enumerator
 185     otherwise.
 186
 187 @lt_pre_conn
 188 @lt_pre_not_null{session_name}
 189 @lt_pre_sess_exists{session_name}
 190 @lt_pre_sess_inactive{session_name}
 191
 192 @sa lttng_stop_tracing() --
 193     Stops a recording session.
 194 @sa \lt_man{lttng-start,1}
 195 */
 196 LTTNG_EXPORT extern int lttng_start_tracing(const char *session_name);
 197
 198 /*!
 199 @brief
 200     Makes the recording session named \lt_p{session_name} inactive,
 201     stopping all the tracers for its
 202     \ref api-channel-channel "channels", blocking until the operation
 203     completes.
 204
 205 @ingroup api_session
 206
 207 This function blocks until the trace data of the
 208 recording session named \lt_p{session_name} is valid. Use
 209 lttng_stop_tracing_no_wait() to avoid a blocking call.
 210
 211 If LTTng \ref api_session_rotation "archived the current trace chunk"
 212 of the recording session named \lt_p{session_name} at least
 213 once during its lifetime, then this function renames the current trace
 214 chunk subdirectory. Although it's safe to
 215 read the content of this renamed subdirectory while the recording
 216 session remains inactive, it's \em not a trace chunk archive: you need to
 217 \link lttng_destroy_session_ext() destroy\endlink the recording session
 218 or a rotation needs to occur to archive it.
 219
 220 @note
 221     An #LTTNG_ACTION_TYPE_STOP_SESSION trigger action can also
 222     deactivate (stop) a recording session.
 223
 224 @param[in] session_name
 225     Name of the recording session to deactivate/stop.
 226
 227 @returns
 228     0 on success, or a \em negative #lttng_error_code enumerator
 229     otherwise.
 230
 231 @lt_pre_conn
 232 @lt_pre_not_null{session_name}
 233 @lt_pre_sess_exists{session_name}
 234 @lt_pre_sess_active{session_name}
 235
 236 @sa lttng_stop_tracing_no_wait() --
 237     Deactivates a recording session without waiting for the operation
 238     to complete.
 239 @sa lttng_start_tracing() --
 240     Starts a recording session.
 241 @sa \lt_man{lttng-stop,1}
 242 */
 243 LTTNG_EXPORT extern int lttng_stop_tracing(const char *session_name);
 244
 245 /*!
 246 @brief
 247     Makes the recording session named \lt_p{session_name} inactive,
 248     stopping all the tracers for its
 249     \ref api-channel-channel "channels" without waiting for the
 250     operation to complete.
 251
 252 @ingroup api_session
 253
 254 Unlike lttng_stop_tracing(), this function does \em not block until
 255 the operation is complete: it returns immediately. This
 256 means the traces(s) of the recording session might not be valid when
 257 this function returns, and there's no way to know when it/they become
 258 valid.
 259
 260 @note
 261     An #LTTNG_ACTION_TYPE_STOP_SESSION trigger action can also
 262     deactivate (stop) a recording session.
 263
 264 @param[in] session_name
 265     Name of the recording session to deactivate/stop.
 266
 267 @returns
 268     0 on success, or a \em negative #lttng_error_code enumerator
 269     otherwise.
 270
 271 @lt_pre_conn
 272 @lt_pre_not_null{session_name}
 273 @lt_pre_sess_exists{session_name}
 274 @lt_pre_sess_active{session_name}
 275 @pre
 276     No deactivation operation is in progress for the recording session
 277     named \lt_p{session_name}.
 278
 279 @sa lttng_stop_tracing() --
 280     Deactivates a recording session, blocking until the operation
 281     completes.
 282 @sa lttng_start_tracing() --
 283     Starts a recording session.
 284 @sa \lt_man{lttng-stop,1}
 285 */
 286 LTTNG_EXPORT extern int lttng_stop_tracing_no_wait(const char *session_name);
 287
 288 /*
 289  * Deprecated: As of LTTng 2.9, this function always returns
 290  * -LTTNG_ERR_UND.
 291  */
 292 #pragma GCC diagnostic push
 293 #pragma GCC diagnostic ignored "-Wshadow"
 294 LTTNG_EXPORT extern int lttng_calibrate(struct lttng_handle *handle,
 295                                         struct lttng_calibrate *calibrate);
 296 #pragma GCC diagnostic pop
 297
 298 /*
 299  * Set URL for a consumer for a session and domain.
 300  *
 301  * Both data and control URL must be defined. If both URLs are the same, only
 302  * the control URL is used even for network streaming.
 303  *
 304  * Default port are 5342 and 5343 respectively for control and data which uses
 305  * the TCP protocol.
 306  *
 307  * URL format: proto://[HOST|IP][:PORT1[:PORT2]][/TRACE_PATH]
 308  *
 309  * Possible protocols are:
 310  * > file://...
 311  *   Local filesystem full path.
 312  *
 313  * > net[6]://...
 314  *   This will use the default network transport layer which is TCP for both
 315  *   control (PORT1) and data port (PORT2).
 316  *
 317  * > tcp[6]://...
 318  *   TCP only streaming. For this one, both data and control URL must be given.
 319  *
 320  * Return 0 on success else a negative LTTng error code.
 321  */
 322 LTTNG_EXPORT extern int
 323 lttng_set_consumer_url(struct lttng_handle *handle, const char *control_url, const char *data_url);
 324
 325 /*!
 326 @brief
 327     Returns whether or not you may read the traces of the recording
 328     session named \lt_p{session_name}.
 329
 330 @ingroup api_session
 331
 332 It's not safe to read the traces of a recording session while
 333 LTTng is still consuming data from the tracers for its
 334 \ref api-channel-channel "channels".
 335
 336 This function makes it possible to know when LTTng is done consuming
 337 trace data from tracers for the channels of the recording session
 338 named \lt_p{session_name}.
 339
 340 @param[in] session_name
 341     Name of the recording session of which get whether or not
 342     you may read its traces.
 343
 344 @returns
 345     @parblock
 346     One of:
 347
 348     <dl>
 349       <dt>0
 350       <dd>
 351         You may read the traces of the recording session named
 352         \lt_p{session_name}.
 353
 354         This remains true as long as the recording session remains
 355         \link lttng_session::enabled inactive\endlink (stopped).
 356
 357       <dt>1</dt>
 358       <dd>
 359         You may \em not read the traces of the recording session named
 360         \lt_p{session_name}.
 361
 362       <dt>Negative value
 363       <dd>
 364         Error: a negative #lttng_error_code enumerator.
 365     </dl>
 366     @endparblock
 367
 368 @lt_pre_conn
 369 @lt_pre_not_null{session_name}
 370 @lt_pre_sess_exists{session_name}
 371 @lt_pre_sess_inactive{session_name}
 372 */
 373 LTTNG_EXPORT extern int lttng_data_pending(const char *session_name);
 374
 375 /*
 376  * Gets the status of the kernel tracer.
 377  *
 378  * Sets the value of the argument, which must not be null.
 379  */
 380 LTTNG_EXPORT extern enum lttng_error_code
 381 lttng_get_kernel_tracer_status(enum lttng_kernel_tracer_status *status);
 382
 383 /*!
 384 @brief
 385     Regenerates the metadata streams of the recording session named
 386     \lt_p{session_name}.
 387
 388 @ingroup api_session
 389
 390 @deprecated
 391     Use lttng_regenerate_metadata().
 392
 393 @param[in] session_name
 394     Name of the recording session of which to regenerate the metadata
 395     streams.
 396
 397 @returns
 398     0 on success, or a \em negative #lttng_error_code enumerator
 399     otherwise.
 400
 401 @lt_pre_conn
 402 @lt_pre_not_null{session_name}
 403 @lt_pre_sess_exists{session_name}
 404 */
 405 /// @cond DEPRECATED
 406 LTTNG_DEPRECATED()
 407 /// @endcond
 408 LTTNG_EXPORT extern int lttng_metadata_regenerate(const char *session_name);
 409
 410 /*!
 411 @brief
 412     Regenerates the metadata streams of the recording session named
 413     \lt_p{session_name}.
 414
 415 @ingroup api_session
 416
 417 Use this function to resample the offset between the monotonic clock and
 418 the wall time of the system, and then regenerate (overwrite) all the
 419 metadata stream files (local or remote) of the recording session
 420 named \lt_p{session_name}.
 421
 422 More specifically, you may want to resample the wall time following a
 423 major <a href="https://en.wikipedia.org/wiki/Network_Time_Protocol">NTP</a>
 424 correction. As such, LTTng can trace a system booting with an incorrect
 425 wall time before its wall time is NTP-corrected. Regenerating the
 426 metadata of a recording session ensures that trace readers
 427 can accurately determine the event record timestamps relative to the
 428 Unix epoch.
 429
 430 Note that if you plan to \ref api_session_rotation "rotate" the
 431 recording session named \lt_p{session_name}, this function only
 432 regenerates the metadata stream files of the \em current and \em next
 433 trace chunks.
 434
 435 See the preconditions of this function which show important limitations.
 436
 437 @param[in] session_name
 438     Name of the recording session of which to regenerate the metadata
 439     streams.
 440
 441 @returns
 442     0 on success, or a \em negative #lttng_error_code enumerator
 443     otherwise.
 444
 445 @lt_pre_conn
 446 @lt_pre_not_null{session_name}
 447 @lt_pre_sess_exists{session_name}
 448 @pre
 449     The recording session named \lt_p{session_name} was \em not created
 450     in \ref api-session-live-mode "live mode".
 451 @pre
 452     All the \ref api-channel-channel "channels" of the recording session
 453     named \lt_p{session_name} use a
 454     \ref api-channel-per-user-buf "per-user buffering scheme".
 455
 456 @sa lttng_regenerate_statedump() --
 457     Regenerates the state dump event records of a recording session.
 458 @sa \lt_man{lttng-regenerate,1}
 459 */
 460 LTTNG_EXPORT extern int lttng_regenerate_metadata(const char *session_name);
 461
 462 /*!
 463 @brief
 464     Regenerates the state dump event records of the recording session
 465     named \lt_p{session_name}.
 466
 467 @ingroup api_session
 468
 469 Use this function to collect up-to-date state dump information and
 470 append corresponding event records to the
 471 \ref api-channel-channel "sub-buffers" of the recording session named
 472 \lt_p{session_name}.
 473
 474 This is particularly useful if you created the recording session in
 475 \ref api-session-snapshot-mode "snapshot mode"
 476 or if LTTng \ref api_session_rotation "rotates" trace files for one of
 477 its \ref api-channel-channel "channels": in both cases, the state dump
 478 information may be lost.
 479
 480 @param[in] session_name
 481     Name of the recording session of which to regenerate the
 482     state dump event records.
 483
 484 @returns
 485     0 on success, or a \em negative #lttng_error_code enumerator
 486     otherwise.
 487
 488 @lt_pre_conn
 489 @lt_pre_not_null{session_name}
 490 @lt_pre_sess_exists{session_name}
 491
 492 @sa lttng_regenerate_metadata() --
 493     Regenerates the metadata streams of a recording session.
 494 @sa \lt_man{lttng-regenerate,1}
 495 */
 496 LTTNG_EXPORT extern int lttng_regenerate_statedump(const char *session_name);
 497
 498 #ifdef __cplusplus
 499 }
 500 #endif
 501
 502 #endif /* LTTNG_H */