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