src/common/mi-lttng.h

   1 /*
   2  * Copyright (C) 2014 Jonathan Rajotte <jonathan.r.julien@gmail.com>
   3  * Copyright (C) 2014 Olivier Cotte <olivier.cotte@polymtl.ca>
   4  * Copyright (C) 2016 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   5  *
   6  * SPDX-License-Identifier: GPL-2.0-only
   7  *
   8  */
   9
  10 #ifndef _MI_LTTNG_H
  11 #define _MI_LTTNG_H
  12
  13 #include <stdint.h>
  14
  15 #include <common/error.h>
  16 #include <common/macros.h>
  17 #include <common/config/session-config.h>
  18 #include <lttng/lttng.h>
  19
  20 /* Don't want to reference snapshot-internal.h here */
  21 struct lttng_snapshot_output;
  22
  23 /* Instance of a machine interface writer. */
  24 struct mi_writer {
  25         struct config_writer *writer;
  26         enum lttng_mi_output_type type;
  27 };
  28
  29 /*
  30  * Version information for the machine interface.
  31  */
  32 struct mi_lttng_version {
  33         char version[LTTNG_NAME_MAX]; /* Version number of package */
  34         uint32_t version_major; /* LTTng-Tools major version number */
  35         uint32_t version_minor; /* LTTng-Tools minor version number */
  36         uint32_t version_patchlevel; /* LTTng-Tools patchlevel version number */
  37         char version_commit[LTTNG_NAME_MAX]; /* Commit hash of the current version */
  38         char version_name[LTTNG_NAME_MAX];
  39         char package_url[LTTNG_NAME_MAX]; /* Define to the home page for this package. */
  40 };
  41
  42 /* Strings related to command */
  43 extern const char * const mi_lttng_element_command;
  44 extern const char * const mi_lttng_element_command_action;
  45 extern const char * const mi_lttng_element_command_add_context;
  46 extern const char * const mi_lttng_element_command_create;
  47 extern const char * const mi_lttng_element_command_destroy;
  48 extern const char * const mi_lttng_element_command_disable_channel;
  49 extern const char * const mi_lttng_element_command_disable_event;
  50 extern const char * const mi_lttng_element_command_enable_channels;
  51 extern const char * const mi_lttng_element_command_enable_event;
  52 extern const char * const mi_lttng_element_command_list;
  53 extern const char * const mi_lttng_element_command_load;
  54 extern const char * const mi_lttng_element_command_metadata;
  55 extern const char * const mi_lttng_element_command_metadata_action;
  56 extern const char * const mi_lttng_element_command_regenerate;
  57 extern const char * const mi_lttng_element_command_regenerate_action;
  58 extern const char * const mi_lttng_element_command_name;
  59 extern const char * const mi_lttng_element_command_output;
  60 extern const char * const mi_lttng_element_command_save;
  61 extern const char * const mi_lttng_element_command_set_session;
  62 extern const char * const mi_lttng_element_command_snapshot;
  63 extern const char * const mi_lttng_element_command_snapshot_add;
  64 extern const char * const mi_lttng_element_command_snapshot_del;
  65 extern const char * const mi_lttng_element_command_snapshot_list;
  66 extern const char * const mi_lttng_element_command_snapshot_record;
  67 extern const char * const mi_lttng_element_command_start;
  68 extern const char * const mi_lttng_element_command_stop;
  69 extern const char * const mi_lttng_element_command_success;
  70 extern const char * const mi_lttng_element_command_track;
  71 extern const char * const mi_lttng_element_command_untrack;
  72 extern const char * const mi_lttng_element_command_version;
  73 extern const char * const mi_lttng_element_command_rotate;
  74 extern const char * const mi_lttng_element_command_enable_rotation;
  75 extern const char * const mi_lttng_element_command_disable_rotation;
  76 extern const char * const mi_lttng_element_command_clear;
  77
  78 /* Strings related to version command */
  79 extern const char * const mi_lttng_element_version;
  80 extern const char * const mi_lttng_element_version_commit;
  81 extern const char * const mi_lttng_element_version_description;
  82 extern const char * const mi_lttng_element_version_license;
  83 extern const char * const mi_lttng_element_version_major;
  84 extern const char * const mi_lttng_element_version_minor;
  85 extern const char * const mi_lttng_element_version_patch_level;
  86 extern const char * const mi_lttng_element_version_str;
  87 extern const char * const mi_lttng_element_version_web;
  88
  89 /* String related to a lttng_event_field */
  90 extern const char * const mi_lttng_element_event_field;
  91 extern const char * const mi_lttng_element_event_fields;
  92
  93 /* String related to lttng_event_perf_counter_ctx */
  94 extern const char * const mi_lttng_element_perf_counter_context;
  95
  96 /* Strings related to pid */
  97 extern const char * const mi_lttng_element_pid_id;
  98
  99 /* Strings related to save command */
 100 extern const char * const mi_lttng_element_save;
 101
 102 /* Strings related to load command */
 103 extern const char * const mi_lttng_element_load;
 104 LTTNG_HIDDEN extern const char * const mi_lttng_element_load_overrides;
 105 LTTNG_HIDDEN extern const char * const mi_lttng_element_load_override_url;
 106
 107 /* General element of mi_lttng */
 108 extern const char * const mi_lttng_element_empty;
 109 extern const char * const mi_lttng_element_id;
 110 extern const char * const mi_lttng_element_nowrite;
 111 extern const char * const mi_lttng_element_success;
 112 extern const char * const mi_lttng_element_type_enum;
 113 extern const char * const mi_lttng_element_type_float;
 114 extern const char * const mi_lttng_element_type_integer;
 115 extern const char * const mi_lttng_element_type_other;
 116 extern const char * const mi_lttng_element_type_string;
 117
 118 /* String related to loglevel */
 119 extern const char * const mi_lttng_loglevel_str_alert;
 120 extern const char * const mi_lttng_loglevel_str_crit;
 121 extern const char * const mi_lttng_loglevel_str_debug;
 122 extern const char * const mi_lttng_loglevel_str_debug_function;
 123 extern const char * const mi_lttng_loglevel_str_debug_line;
 124 extern const char * const mi_lttng_loglevel_str_debug_module;
 125 extern const char * const mi_lttng_loglevel_str_debug_process;
 126 extern const char * const mi_lttng_loglevel_str_debug_program;
 127 extern const char * const mi_lttng_loglevel_str_debug_system;
 128 extern const char * const mi_lttng_loglevel_str_debug_unit;
 129 extern const char * const mi_lttng_loglevel_str_emerg;
 130 extern const char * const mi_lttng_loglevel_str_err;
 131 extern const char * const mi_lttng_loglevel_str_info;
 132 extern const char * const mi_lttng_loglevel_str_notice;
 133 extern const char * const mi_lttng_loglevel_str_unknown;
 134 extern const char * const mi_lttng_loglevel_str_warning;
 135
 136 /* String related to loglevel JUL */
 137 extern const char * const mi_lttng_loglevel_str_jul_all;
 138 extern const char * const mi_lttng_loglevel_str_jul_config;
 139 extern const char * const mi_lttng_loglevel_str_jul_fine;
 140 extern const char * const mi_lttng_loglevel_str_jul_finer;
 141 extern const char * const mi_lttng_loglevel_str_jul_finest;
 142 extern const char * const mi_lttng_loglevel_str_jul_info;
 143 extern const char * const mi_lttng_loglevel_str_jul_off;
 144 extern const char * const mi_lttng_loglevel_str_jul_severe;
 145 extern const char * const mi_lttng_loglevel_str_jul_warning;
 146
 147 /* String related to loglevel Log4j */
 148 extern const char * const mi_lttng_loglevel_str_log4j_off;
 149 extern const char * const mi_lttng_loglevel_str_log4j_fatal;
 150 extern const char * const mi_lttng_loglevel_str_log4j_error;
 151 extern const char * const mi_lttng_loglevel_str_log4j_warn;
 152 extern const char * const mi_lttng_loglevel_str_log4j_info;
 153 extern const char * const mi_lttng_loglevel_str_log4j_debug;
 154 extern const char * const mi_lttng_loglevel_str_log4j_trace;
 155 extern const char * const mi_lttng_loglevel_str_log4j_all;
 156
 157 /* String related to loglevel Python */
 158 extern const char * const mi_lttng_loglevel_str_python_critical;
 159 extern const char * const mi_lttng_loglevel_str_python_error;
 160 extern const char * const mi_lttng_loglevel_str_python_warning;
 161 extern const char * const mi_lttng_loglevel_str_python_info;
 162 extern const char * const mi_lttng_loglevel_str_python_debug;
 163 extern const char * const mi_lttng_loglevel_str_python_notset;
 164
 165 /* String related to loglevel type */
 166 extern const char * const mi_lttng_loglevel_type_all;
 167 extern const char * const mi_lttng_loglevel_type_range;
 168 extern const char * const mi_lttng_loglevel_type_single;
 169 extern const char * const mi_lttng_loglevel_type_unknown;
 170
 171 /* String related to a lttng_snapshot */
 172 extern const char * const mi_lttng_element_snapshot_ctrl_url;
 173 extern const char * const mi_lttng_element_snapshot_data_url;
 174 extern const char * const mi_lttng_element_snapshot_max_size;
 175 extern const char * const mi_lttng_element_snapshot_n_ptr;
 176 extern const char * const mi_lttng_element_snapshot_session_name;
 177 extern const char * const mi_lttng_element_snapshots;
 178
 179 /* String related to track/untrack command */
 180 extern const char * const mi_lttng_element_track_untrack_all_wildcard;
 181
 182 LTTNG_HIDDEN extern const char * const mi_lttng_element_session_name;
 183
 184 /* String related to rotate command */
 185 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotation;
 186 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotate_status;
 187 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotation_schedule;
 188 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotation_schedules;
 189 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotation_schedule_periodic;
 190 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotation_schedule_periodic_time_us;
 191 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotation_schedule_size_threshold;
 192 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotation_schedule_size_threshold_bytes;
 193 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotation_schedule_result;
 194 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotation_schedule_results;
 195 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotation_state;
 196 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotation_location;
 197 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotation_location_local;
 198 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotation_location_local_absolute_path;
 199 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotation_location_relay;
 200 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotation_location_relay_host;
 201 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotation_location_relay_control_port;
 202 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotation_location_relay_data_port;
 203 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotation_location_relay_protocol;
 204 LTTNG_HIDDEN extern const char * const mi_lttng_element_rotation_location_relay_relative_path;
 205
 206 /* String related to enum lttng_rotation_state */
 207 LTTNG_HIDDEN extern const char * const mi_lttng_rotation_state_str_ongoing;
 208 LTTNG_HIDDEN extern const char * const mi_lttng_rotation_state_str_completed;
 209 LTTNG_HIDDEN extern const char * const mi_lttng_rotation_state_str_expired;
 210 LTTNG_HIDDEN extern const char * const mi_lttng_rotation_state_str_error;
 211
 212 /* String related to enum lttng_trace_archive_location_relay_protocol_type */
 213 LTTNG_HIDDEN extern const char * const mi_lttng_rotation_location_relay_protocol_str_tcp;
 214
 215 /* String related to add-context command */
 216 LTTNG_HIDDEN extern const char * const mi_lttng_element_context_symbol;
 217
 218 /* Utility string function  */
 219 const char *mi_lttng_loglevel_string(int value, enum lttng_domain_type domain);
 220 const char *mi_lttng_logleveltype_string(enum lttng_loglevel_type value);
 221 const char *mi_lttng_eventfieldtype_string(enum lttng_event_field_type value);
 222 const char *mi_lttng_domaintype_string(enum lttng_domain_type value);
 223 const char *mi_lttng_buffertype_string(enum lttng_buffer_type value);
 224 const char *mi_lttng_rotation_state_string(enum lttng_rotation_state value);
 225 const char *mi_lttng_trace_archive_location_relay_protocol_type_string(
 226                 enum lttng_trace_archive_location_relay_protocol_type value);
 227
 228 /*
 229  * Create an instance of a machine interface writer.
 230  *
 231  * fd_output File to which the XML content must be written. The file will be
 232  * closed once the mi_writer has been destroyed.
 233  *
 234  * Returns an instance of a machine interface writer on success, NULL on
 235  * error.
 236  */
 237 struct mi_writer *mi_lttng_writer_create(int fd_output, int mi_output_type);
 238
 239 /*
 240  * Destroy an instance of a machine interface writer.
 241  *
 242  * writer An instance of a machine interface writer.
 243  *
 244  * Returns zero if the XML document could be closed cleanly. Negative values
 245  * indicate an error.
 246  */
 247 int mi_lttng_writer_destroy(struct mi_writer *writer);
 248
 249 /*
 250  * Open a command tag and add it's name node.
 251  *
 252  * writer An instance of a machine interface writer.
 253  * command The command name.
 254  *
 255  * Returns zero if the XML document could be closed cleanly.
 256  * Negative values indicate an error.
 257  */
 258 int mi_lttng_writer_command_open(struct mi_writer *writer, const char *command);
 259
 260 /*
 261  * Close a command tag.
 262  *
 263  * writer An instance of a machine interface writer.
 264  *
 265  * Returns zero if the XML document could be closed cleanly.
 266  * Negative values indicate an error.
 267  */
 268 int mi_lttng_writer_command_close(struct mi_writer *writer);
 269
 270 /*
 271  * Open an element tag.
 272  *
 273  * writer An instance of a machine interface writer.
 274  * element_name Element tag name.
 275  *
 276  * Returns zero if the XML document could be closed cleanly.
 277  * Negative values indicate an error.
 278  */
 279 int mi_lttng_writer_open_element(struct mi_writer *writer,
 280                 const char *element_name);
 281
 282 /*
 283  * Close the current element tag.
 284  *
 285  * writer An instance of a machine interface writer.
 286  *
 287  * Returns zero if the XML document could be closed cleanly.
 288  * Negative values indicate an error.
 289  */
 290 int mi_lttng_writer_close_element(struct mi_writer *writer);
 291
 292 /*
 293  * Close multiple element.
 294  *
 295  * writer An instance of a machine interface writer.
 296  * nb_element Number of elements.
 297  *
 298  * Returns zero if the XML document could be closed cleanly.
 299  * Negative values indicate an error.
 300  */
 301 int mi_lttng_close_multi_element(struct mi_writer *writer,
 302                 unsigned int nb_element);
 303
 304 /*
 305  * Write an element of type unsigned int.
 306  *
 307  * writer An instance of a machine interface writer.
 308  * element_name Element name.
 309  * value Unsigned int value of the element
 310  *
 311  * Returns zero if the element's value could be written.
 312  * Negative values indicate an error.
 313  */
 314 int mi_lttng_writer_write_element_unsigned_int(struct mi_writer *writer,
 315                 const char *element_name, uint64_t value);
 316
 317 /*
 318  * Write an element of type signed int.
 319  *
 320  * writer An instance of a machine interface writer.
 321  * element_name Element name.
 322  * value Signed int value of the element.
 323  *
 324  * Returns zero if the element's value could be written.
 325  * Negative values indicate an error.
 326  */
 327 int mi_lttng_writer_write_element_signed_int(struct mi_writer *writer,
 328                 const char *element_name, int64_t value);
 329
 330 /*
 331  * Write an element of type boolean.
 332  *
 333  * writer An instance of a machine interface writer.
 334  * element_name Element name.
 335  * value Boolean value of the element.
 336  *
 337  * Returns zero if the element's value could be written.
 338  * Negative values indicate an error.
 339  */
 340 int mi_lttng_writer_write_element_bool(struct mi_writer *writer,
 341                 const char *element_name, int value);
 342
 343 /*
 344  * Write an element of type string.
 345  *
 346  * writer An instance of a machine interface writer.
 347  * element_name Element name.
 348  * value String value of the element.
 349  *
 350  * Returns zero if the element's value could be written.
 351  * Negative values indicate an error.
 352  */
 353 int mi_lttng_writer_write_element_string(struct mi_writer *writer,
 354                 const char *element_name, const char *value);
 355
 356 /*
 357  * Machine interface of struct version.
 358  *
 359  * writer An instance of a machine interface writer.
 360  * version Version struct.
 361  * lttng_description String value of the version description.
 362  * lttng_license String value of the version license.
 363  *
 364  * Returns zero if the element's value could be written.
 365  * Negative values indicate an error.
 366  */
 367 int mi_lttng_version(struct mi_writer *writer, struct mi_lttng_version *version,
 368                 const char *lttng_description, const char *lttng_license);
 369
 370 /*
 371  * Machine interface: open a sessions element.
 372  *
 373  * writer An instance of a machine interface writer.
 374  *
 375  * Returns zero if the element's value could be written.
 376  * Negative values indicate an error.
 377  */
 378 int mi_lttng_sessions_open(struct mi_writer *writer);
 379
 380 /*
 381  * Machine interface of struct session.
 382  *
 383  * writer An instance of a machine interface writer.
 384  * session An instance of a session.
 385  * is_open Defines whether or not the session element shall be closed.
 386  *         This should be used carefully and the client
 387  *         must close the session element.
 388  *         Use case: nested additional information on a session
 389  *                  ex: domain,channel event.
 390  *
 391  * Returns zero if the element's value could be written.
 392  * Negative values indicate an error.
 393  */
 394 int mi_lttng_session(struct mi_writer *writer,
 395                 struct lttng_session *session, int is_open);
 396
 397 /*
 398  * Machine interface: open a domains element.
 399  *
 400  * writer An instance of a machine interface writer.
 401  *
 402  * Returns zero if the element's value could be written.
 403  * Negative values indicate an error.
 404  */
 405 int mi_lttng_domains_open(struct mi_writer *writer);
 406
 407 /*
 408  * Machine interface of struct domain.
 409  *
 410  * writer An instance of a machine interface writer.
 411  * domain An instance of a domain.
 412  *
 413  * is_open Defines whether or not the session element shall be closed.
 414  *         This should be used carefully and the client
 415  *         must close the domain element.
 416  *         Use case: nested addition information on a domain
 417  *                  ex: channel event.
 418  *
 419  * Returns zero if the element's value could be written.
 420  * Negative values indicate an error.
 421  */
 422 int mi_lttng_domain(struct mi_writer *writer,
 423                 struct lttng_domain *domain, int is_open);
 424
 425 /*
 426  * Machine interface: open a channels element.
 427  *
 428  * writer An instance of a machine interface writer.
 429  *
 430  * Returns zero if the element's value could be written.
 431  * Negative values indicate an error.
 432  */
 433 int mi_lttng_channels_open(struct mi_writer *writer);
 434
 435 /*
 436  * Machine interface of struct channel.
 437  *
 438  * writer An instance of a machine interface writer.
 439  * channel An instance of a channel.
 440  *
 441  * is_open Defines whether or not the session element shall be closed.
 442  *         This should be used carefully and the client
 443  *         must close the channel element.
 444  *         Use case: nested addition information on a channel.
 445  *                  ex: channel event.
 446  *
 447  * Returns zero if the element's value could be written.
 448  * Negative values indicate an error.
 449  */
 450 int mi_lttng_channel(struct mi_writer *writer,
 451                 struct lttng_channel *channel, int is_open);
 452
 453 /*
 454  * Machine interface of struct channel_attr.
 455  *
 456  * writer An instance of a machine interface writer.
 457  * attr An instance of a channel_attr struct.
 458  *
 459  * Returns zero if the element's value could be written.
 460  * Negative values indicate an error.
 461  */
 462 int mi_lttng_channel_attr(struct mi_writer *writer,
 463                 struct lttng_channel_attr *attr);
 464
 465 /*
 466 * Machine interface for event common attributes.
 467 *
 468 * writer An instance of a mi writer.
 469 * event single trace event.
 470 *
 471 * The common attribute are:
 472 * - mi event element
 473 * - event name
 474 * - event type
 475 * - enabled tag
 476 * - event filter
 477 *
 478 * Returns zero if the element's value could be written.
 479 * Negative values indicate an error.
 480 */
 481 int mi_lttng_event_common_attributes(struct mi_writer *writer,
 482                 struct lttng_event *event);
 483
 484 /*
 485  * Machine interface for kernel tracepoint event with a loglevel.
 486  *
 487  * writer An instance of a mi writer.
 488  * event single trace event.
 489  * domain Event's domain
 490  *
 491  * Returns zero if the element's value could be written.
 492  * Negative values indicate an error.
 493  */
 494 int mi_lttng_event_tracepoint_loglevel(struct mi_writer *writer,
 495                 struct lttng_event *event, enum lttng_domain_type domain);
 496
 497 /*
 498  * Machine interface for kernel tracepoint event with no loglevel.
 499  *
 500  * writer An instance of a mi writer.
 501  * event single trace event.
 502  *
 503  * Returns zero if the element's value could be written.
 504  * Negative values indicate an error.
 505  */
 506 int mi_lttng_event_tracepoint_no_loglevel(struct mi_writer *writer,
 507                 struct lttng_event *event);
 508
 509 /*
 510  * Machine interface for kernel function and probe event.
 511  *
 512  * writer An instance of a mi writer.
 513  * event single trace event.
 514  *
 515  * Returns zero if the element's value could be written.
 516  * Negative values indicate an error.
 517  */
 518 int mi_lttng_event_function_probe(struct mi_writer *writer,
 519                 struct lttng_event *event);
 520
 521 /*
 522  * Machine interface for kernel function entry event.
 523  *
 524  * writer An instance of a mi writer.
 525  * event single trace event.
 526  *
 527  * Returns zero if the element's value could be written.
 528  * Negative values indicate an error.
 529  */
 530 int mi_lttng_event_function_entry(struct mi_writer *writer,
 531                 struct lttng_event *event);
 532
 533 /*
 534  * Machine interface: open an events element.
 535  *
 536  * writer An instance of a machine interface writer.
 537  *
 538  * Returns zero if the element's value could be written.
 539  * Negative values indicate an error.
 540  */
 541 int mi_lttng_events_open(struct mi_writer *writer);
 542
 543 /*
 544  * Machine interface for printing an event.
 545  * The trace event type currently supported are:
 546  *  TRACEPOINT,
 547  *  PROBE,
 548  *  FUNCTION,
 549  *  FUNCTION_ENTRY,
 550  *  SYSCALL
 551  *
 552  * writer An instance of a mi writer.
 553  * event single trace event.
 554  * is_open Defines whether or not the session element shall be closed.
 555  *         This should be used carefully and the client
 556  *         must close the event element.
 557  *         Use case: nested additional information
 558  * domain Event's domain
 559  *
 560  * Returns zero if the element's value could be written.
 561  * Negative values indicate an error.
 562  */
 563 int mi_lttng_event(struct mi_writer *writer, struct lttng_event *event,
 564                 int is_open, enum lttng_domain_type domain);
 565
 566 /*
 567  * Machine interface for struct lttng_event_field.
 568  *
 569  * writer An instance of a mi writer.
 570  * field An event_field instance.
 571  *
 572  * Returns zero if the element's value could be written.
 573  * Negative values indicate an error.
 574  */
 575 int mi_lttng_event_field(struct mi_writer *writer,
 576                 struct lttng_event_field *field);
 577
 578 /*
 579  * Machine interface: open a event_fields element.
 580  *
 581  * writer An instance of a machine interface writer.
 582  *
 583  * Returns zero if the element have be written.
 584  * Negative values indicate an error.
 585  */
 586 int mi_lttng_event_fields_open(struct mi_writer *writer);
 587
 588 /*
 589  * Machine interface: open a trackers element.
 590  *
 591  * writer An instance of a machine interface writer.
 592  *
 593  * Returns zero if the element's value could be written.
 594  * Negative values indicate an error.
 595  */
 596 int mi_lttng_trackers_open(struct mi_writer *writer);
 597
 598 /*
 599  * Machine interface: open a process attribute tracker element.
 600  *
 601  * writer An instance of a machine interface writer.
 602  *
 603  * Returns zero if the element's value could be written.
 604  * Negative values indicate an error.
 605  *
 606  * Note: A targets element is also opened for each tracker definition
 607  */
 608 int mi_lttng_process_attribute_tracker_open(
 609                 struct mi_writer *writer, enum lttng_process_attr process_attr);
 610
 611 /*
 612  * Machine interface: open a PIDs element.
 613  *
 614  * writer An instance of a machine interface writer.
 615  *
 616  * Returns zero if the element's value could be written.
 617  * Negative values indicate an error.
 618  */
 619 int mi_lttng_pids_open(struct mi_writer *writer);
 620
 621 /*
 622  * Machine interface: open a processes element.
 623  *
 624  * writer An instance of a machine interface writer.
 625  *
 626  * Returns zero if the element's value could be written.
 627  * Negative values indicate an error.
 628  */
 629 int mi_lttng_processes_open(struct mi_writer *writer);
 630
 631 /*
 632  * Machine interface of a Process.
 633  *
 634  * writer An instance of a machine interface writer.
 635  * pid A PID.
 636  *
 637  * is_open Defines whether or not the session element shall be closed.
 638  *         This should be used carefully and the client
 639  *         must close the pid element.
 640  *         Use case: nested addition information on a domain
 641  *                  ex: channel event.
 642  *
 643  * Returns zero if the element's value could be written.
 644  * Negative values indicate an error.
 645  */
 646 int mi_lttng_process(struct mi_writer *writer, pid_t pid , const char *name,
 647                 int is_open);
 648
 649 /*
 650  * TODO: move pid of lttng list -u to process semantic on mi api bump
 651  * Machine interface of a Process.
 652  *
 653  * writer An instance of a machine interface writer.
 654  * pid A PID.
 655  *
 656  * is_open Defines whether or not the session element shall be closed.
 657  *         This should be used carefully and the client
 658  *         must close the pid element.
 659  *         Use case: nested addition information on a domain
 660  *                  ex: channel event.
 661  *
 662  * Returns zero if the element's value could be written.
 663  * Negative values indicate an error.
 664  */
 665 int mi_lttng_pid(struct mi_writer *writer, pid_t pid , const char *name,
 666                 int is_open);
 667
 668 /*
 669  * Machine interface: open a process attribute values element.
 670  *
 671  * writer An instance of a machine interface writer.
 672  *
 673  * Returns zero if the element's value could be written.
 674  * Negative values indicate an error.
 675  */
 676 int mi_lttng_process_attr_values_open(struct mi_writer *writer);
 677
 678 /*
 679  * Machine interface for track/untrack of all process attribute values.
 680  *
 681  * writer An instance of a machine interface writer.
 682  *
 683  * Returns zero if the element's value could be written.
 684  * Negative values indicate an error.
 685  */
 686 int mi_lttng_all_process_attribute_value(struct mi_writer *writer,
 687                 enum lttng_process_attr process_attr,
 688                 bool is_open);
 689
 690 /*
 691  * Machine interface for track/untrack of an integral process attribute value.
 692  *
 693  * writer An instance of a machine interface writer.
 694  *
 695  * Returns zero if the element's value could be written.
 696  * Negative values indicate an error.
 697  */
 698 int mi_lttng_integral_process_attribute_value(struct mi_writer *writer,
 699                 enum lttng_process_attr process_attr,
 700                 int64_t value,
 701                 bool is_open);
 702
 703 /*
 704  * Machine interface for track/untrack of a string process attribute value.
 705  *
 706  * writer An instance of a machine interface writer.
 707  *
 708  * Returns zero if the element's value could be written.
 709  * Negative values indicate an error.
 710  */
 711 int mi_lttng_string_process_attribute_value(struct mi_writer *writer,
 712                 enum lttng_process_attr process_attr,
 713                 const char *value,
 714                 bool is_open);
 715
 716 /*
 717  * Machine interface of a context.
 718  *
 719  * writer An instance of a machine interface writer
 720  *
 721  * context An instance of a lttng_event_context
 722  *
 723  * is_open Define if we close the context element
 724  *         This should be used carefully and the client
 725  *         need to close the context element.
 726  * Returns zero if the element's value could be written.
 727  * Negative values indicate an error.
 728  */
 729 int mi_lttng_context(struct mi_writer *writer,
 730                 struct lttng_event_context *context, int is_open);
 731
 732 /*
 733  * Machine interface of a perf_counter_context.
 734  *
 735  * writer An instance of a machine interface writer
 736  *
 737  * contest An instance of a lttng_event_perf_counter_ctx
 738  *
 739  * Returns zero if the element's value could be written.
 740  * Negative values indicate an error.
 741  */
 742 int mi_lttng_perf_counter_context(struct mi_writer *writer,
 743                 struct lttng_event_perf_counter_ctx  *perf_context);
 744
 745 /*
 746  * Machine interface of the snapshot list_output.
 747  * It specifies the session for which we are listing snapshots,
 748  * and it opens a snapshots element to list a sequence
 749  * of snapshots.
 750  *
 751  * writer An instance of a machine interface writer.
 752  *
 753  * session_name: Snapshot output for session "session_name".
 754  *
 755  * Note: The client has to close the session and the snapshots elements after
 756  * having listed every lttng_snapshot_output.
 757  *
 758  * Returns zero if the element's value could be written.
 759  * Negative values indicate an error.
 760  */
 761 int mi_lttng_snapshot_output_session_name(struct mi_writer *writer,
 762                 const char *session_name);
 763
 764 /*
 765  * Machine interface of the snapshot output.
 766  * The machine interface serializes the following attributes:
 767  * - id: ID of the snapshot output.
 768  * - name: Name of the output.
 769  * - data_url : Destination of the output.
 770  * - ctrl_url: Destination of the output.
 771  * - max_size: total size of all stream combined.
 772  *
 773  * writer An instance of a machine interface writer.
 774  *
 775  * output: A list of snapshot_output.
 776  *
 777  * Returns zero if the element's value could be written.
 778  * Negative values indicate an error.
 779  */
 780 int mi_lttng_snapshot_list_output(struct mi_writer *writer,
 781                 struct lttng_snapshot_output *output);
 782
 783 /*
 784  * Machine interface of the output of the command snapshot del output
 785  * when deleting a snapshot either by id or by name.
 786  * If the snapshot was found and successfully deleted using its id,
 787  * it return the id of the snapshot and the current session name on which it
 788  * was attached.
 789  *
 790  * Otherwise, it do the same process with the name of the snapshot, if the
 791  * snapshot output id is undefined.
 792  *
 793  * writer An instance of a machine interface writer.
 794  *
 795  * id: ID of the snapshot output.
 796  *
 797  * name: Name of the snapshot.
 798  *
 799  * current_session_name: Session to which the snapshot belongs.
 800  *
 801  * Returns zero if the element's value could be written.
 802  * Negative values indicate an error.
 803  */
 804 int mi_lttng_snapshot_del_output(struct mi_writer *writer, int id,
 805                 const char *name, const char *current_session_name);
 806
 807 /*
 808  * Machine interface of the output of the command snapshot add output
 809  * when adding a snapshot from a user URL.
 810  *
 811  * If the snapshot was successfully added, the machine interface lists
 812  * these information:
 813  * - id: ID of the newly add snapshot output.
 814  * - current_session_name: Name of the session to which the output was added.
 815  * - ctrl_url: Destination of the output.
 816  * - max_size: total size of all stream combined.
 817  *
 818  * writer An instance of a machine interface writer.
 819  *
 820  * current_session_name: Session to which the snapshot belongs.
 821  *
 822  * n_ptr:
 823  *
 824  * output: iterator over a lttng_snapshot_output_list which contain
 825  * the snapshot output informations.
 826  *
 827  * Returns zero if the element's value could be written.
 828  * Negative values indicate an error.
 829  */
 830 int mi_lttng_snapshot_add_output(struct mi_writer *writer,
 831                 const char *current_session_name, const char *n_ptr,
 832                 struct lttng_snapshot_output *output);
 833
 834 /*
 835  * Machine interface of the output of the command snapshot
 836  * record  from a URL (if given).
 837  *
 838  * If the snapshot is successfully recorded from a url, the machine interface
 839  * output the following information:
 840  * - url: Destination of the output stored in the snapshot.
 841  *
 842  * Otherwise, the machine interface output the data and ctrl url received
 843  * from the command-line.
 844  *
 845  * writer An instance of a machine interface writer.
 846  *
 847  * current_session_name: Snapshot record for session "current_session_name".
 848  *
 849  * ctrl_url, data_url: Destination of the output receive from the command-line.
 850  *
 851  * Returns zero if the element's value could be written.
 852  * Negative values indicate an error.
 853  */
 854 int mi_lttng_snapshot_record(struct mi_writer *writer,
 855                 const char *current_session_name, const char *url,
 856                 const char *cmdline_ctrl_url, const char *cmdline_data_url);
 857
 858 /*
 859  * Machine interface representation of a session rotation schedule.
 860  *
 861  * The machine interface serializes the provided schedule as one of the choices
 862  * from 'rotation_schedule_type'.
 863  *
 864  * writer: An instance of a machine interface writer.
 865  *
 866  * schedule: An lttng rotation schedule descriptor object.
 867  *
 868  * Returns zero if the element's value could be written.
 869  * Negative values indicate an error.
 870  */
 871 int mi_lttng_rotation_schedule(struct mi_writer *writer,
 872                 const struct lttng_rotation_schedule *schedule);
 873
 874 /*
 875  * Machine interface of a session rotation schedule result.
 876  * This is an element that is part of the output of the enable-rotation and
 877  * disable-rotation commands.
 878  *
 879  * The machine interface provides the following information:
 880  * - schedule: the session rotation schedule descriptor.
 881  * - success: whether the sub-command succeeded.
 882  *
 883  * writer: An instance of a machine interface writer.
 884  *
 885  * schedule: An lttng rotation schedule descriptor object.
 886  *
 887  * success: Whether the sub-command suceeded.
 888  *
 889  * Returns zero if the element's value could be written.
 890  * Negative values indicate an error.
 891  */
 892 int mi_lttng_rotation_schedule_result(struct mi_writer *writer,
 893                 const struct lttng_rotation_schedule *schedule,
 894                 bool success);
 895
 896 /*
 897  * Machine interface of a session rotation result.
 898  * This is an element that is part of the output of the rotate command.
 899  *
 900  * The machine interface provides the following information:
 901  * - session_name: the session to be rotated.
 902  * - state: the session rotation state.
 903  * - location: the location of the completed chunk archive.
 904  *
 905  * writer: An instance of a machine interface writer.
 906  *
 907  * session_name: The session to which the rotate command applies.
 908  *
 909  * location: A location descriptor object.
 910  *
 911  * success: Whether the sub-command suceeded.
 912  *
 913  * Returns zero if the element's value could be written.
 914  * Negative values indicate an error.
 915  */
 916 int mi_lttng_rotate(struct mi_writer *writer,
 917                 const char *session_name,
 918                 enum lttng_rotation_state rotation_state,
 919                 const struct lttng_trace_archive_location *location);
 920
 921 #endif /* _MI_LTTNG_H */