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  * Write an element of type double.
 358  *
 359  * writer An instance of a machine interface writer.
 360  * element_name Element name.
 361  * value Double value of the element.
 362  *
 363  * Returns zero if the element's value could be written.
 364  * Negative values indicate an error.
 365  */
 366 int mi_lttng_writer_write_element_double(struct mi_writer *writer,
 367                 const char *element_name,
 368                 double value);
 369
 370 /*
 371  * Machine interface of struct version.
 372  *
 373  * writer An instance of a machine interface writer.
 374  * version Version struct.
 375  * lttng_description String value of the version description.
 376  * lttng_license String value of the version license.
 377  *
 378  * Returns zero if the element's value could be written.
 379  * Negative values indicate an error.
 380  */
 381 int mi_lttng_version(struct mi_writer *writer, struct mi_lttng_version *version,
 382                 const char *lttng_description, const char *lttng_license);
 383
 384 /*
 385  * Machine interface: open a sessions element.
 386  *
 387  * writer An instance of a machine interface writer.
 388  *
 389  * Returns zero if the element's value could be written.
 390  * Negative values indicate an error.
 391  */
 392 int mi_lttng_sessions_open(struct mi_writer *writer);
 393
 394 /*
 395  * Machine interface of struct session.
 396  *
 397  * writer An instance of a machine interface writer.
 398  * session An instance of a session.
 399  * is_open Defines whether or not the session element shall be closed.
 400  *         This should be used carefully and the client
 401  *         must close the session element.
 402  *         Use case: nested additional information on a session
 403  *                  ex: domain,channel event.
 404  *
 405  * Returns zero if the element's value could be written.
 406  * Negative values indicate an error.
 407  */
 408 int mi_lttng_session(struct mi_writer *writer,
 409                 struct lttng_session *session, int is_open);
 410
 411 /*
 412  * Machine interface: open a domains element.
 413  *
 414  * writer An instance of a machine interface writer.
 415  *
 416  * Returns zero if the element's value could be written.
 417  * Negative values indicate an error.
 418  */
 419 int mi_lttng_domains_open(struct mi_writer *writer);
 420
 421 /*
 422  * Machine interface of struct domain.
 423  *
 424  * writer An instance of a machine interface writer.
 425  * domain An instance of a domain.
 426  *
 427  * is_open Defines whether or not the session element shall be closed.
 428  *         This should be used carefully and the client
 429  *         must close the domain element.
 430  *         Use case: nested addition information on a domain
 431  *                  ex: channel event.
 432  *
 433  * Returns zero if the element's value could be written.
 434  * Negative values indicate an error.
 435  */
 436 int mi_lttng_domain(struct mi_writer *writer,
 437                 struct lttng_domain *domain, int is_open);
 438
 439 /*
 440  * Machine interface: open a channels element.
 441  *
 442  * writer An instance of a machine interface writer.
 443  *
 444  * Returns zero if the element's value could be written.
 445  * Negative values indicate an error.
 446  */
 447 int mi_lttng_channels_open(struct mi_writer *writer);
 448
 449 /*
 450  * Machine interface of struct channel.
 451  *
 452  * writer An instance of a machine interface writer.
 453  * channel An instance of a channel.
 454  *
 455  * is_open Defines whether or not the session element shall be closed.
 456  *         This should be used carefully and the client
 457  *         must close the channel element.
 458  *         Use case: nested addition information on a channel.
 459  *                  ex: channel event.
 460  *
 461  * Returns zero if the element's value could be written.
 462  * Negative values indicate an error.
 463  */
 464 int mi_lttng_channel(struct mi_writer *writer,
 465                 struct lttng_channel *channel, int is_open);
 466
 467 /*
 468  * Machine interface of struct channel_attr.
 469  *
 470  * writer An instance of a machine interface writer.
 471  * attr An instance of a channel_attr struct.
 472  *
 473  * Returns zero if the element's value could be written.
 474  * Negative values indicate an error.
 475  */
 476 int mi_lttng_channel_attr(struct mi_writer *writer,
 477                 struct lttng_channel_attr *attr);
 478
 479 /*
 480 * Machine interface for event common attributes.
 481 *
 482 * writer An instance of a mi writer.
 483 * event single trace event.
 484 *
 485 * The common attribute are:
 486 * - mi event element
 487 * - event name
 488 * - event type
 489 * - enabled tag
 490 * - event filter
 491 *
 492 * Returns zero if the element's value could be written.
 493 * Negative values indicate an error.
 494 */
 495 int mi_lttng_event_common_attributes(struct mi_writer *writer,
 496                 struct lttng_event *event);
 497
 498 /*
 499  * Machine interface for kernel tracepoint event with a loglevel.
 500  *
 501  * writer An instance of a mi writer.
 502  * event single trace event.
 503  * domain Event's domain
 504  *
 505  * Returns zero if the element's value could be written.
 506  * Negative values indicate an error.
 507  */
 508 int mi_lttng_event_tracepoint_loglevel(struct mi_writer *writer,
 509                 struct lttng_event *event, enum lttng_domain_type domain);
 510
 511 /*
 512  * Machine interface for kernel tracepoint event with no loglevel.
 513  *
 514  * writer An instance of a mi writer.
 515  * event single trace event.
 516  *
 517  * Returns zero if the element's value could be written.
 518  * Negative values indicate an error.
 519  */
 520 int mi_lttng_event_tracepoint_no_loglevel(struct mi_writer *writer,
 521                 struct lttng_event *event);
 522
 523 /*
 524  * Machine interface for kernel function and probe event.
 525  *
 526  * writer An instance of a mi writer.
 527  * event single trace event.
 528  *
 529  * Returns zero if the element's value could be written.
 530  * Negative values indicate an error.
 531  */
 532 int mi_lttng_event_function_probe(struct mi_writer *writer,
 533                 struct lttng_event *event);
 534
 535 /*
 536  * Machine interface for kernel function entry event.
 537  *
 538  * writer An instance of a mi writer.
 539  * event single trace event.
 540  *
 541  * Returns zero if the element's value could be written.
 542  * Negative values indicate an error.
 543  */
 544 int mi_lttng_event_function_entry(struct mi_writer *writer,
 545                 struct lttng_event *event);
 546
 547 /*
 548  * Machine interface: open an events element.
 549  *
 550  * writer An instance of a machine interface writer.
 551  *
 552  * Returns zero if the element's value could be written.
 553  * Negative values indicate an error.
 554  */
 555 int mi_lttng_events_open(struct mi_writer *writer);
 556
 557 /*
 558  * Machine interface for printing an event.
 559  * The trace event type currently supported are:
 560  *  TRACEPOINT,
 561  *  PROBE,
 562  *  FUNCTION,
 563  *  FUNCTION_ENTRY,
 564  *  SYSCALL
 565  *
 566  * writer An instance of a mi writer.
 567  * event single trace event.
 568  * is_open Defines whether or not the session element shall be closed.
 569  *         This should be used carefully and the client
 570  *         must close the event element.
 571  *         Use case: nested additional information
 572  * domain Event's domain
 573  *
 574  * Returns zero if the element's value could be written.
 575  * Negative values indicate an error.
 576  */
 577 int mi_lttng_event(struct mi_writer *writer, struct lttng_event *event,
 578                 int is_open, enum lttng_domain_type domain);
 579
 580 /*
 581  * Machine interface for struct lttng_event_field.
 582  *
 583  * writer An instance of a mi writer.
 584  * field An event_field instance.
 585  *
 586  * Returns zero if the element's value could be written.
 587  * Negative values indicate an error.
 588  */
 589 int mi_lttng_event_field(struct mi_writer *writer,
 590                 struct lttng_event_field *field);
 591
 592 /*
 593  * Machine interface: open a event_fields element.
 594  *
 595  * writer An instance of a machine interface writer.
 596  *
 597  * Returns zero if the element have be written.
 598  * Negative values indicate an error.
 599  */
 600 int mi_lttng_event_fields_open(struct mi_writer *writer);
 601
 602 /*
 603  * Machine interface: open a trackers element.
 604  *
 605  * writer An instance of a machine interface writer.
 606  *
 607  * Returns zero if the element's value could be written.
 608  * Negative values indicate an error.
 609  */
 610 int mi_lttng_trackers_open(struct mi_writer *writer);
 611
 612 /*
 613  * Machine interface: open a process attribute tracker element.
 614  *
 615  * writer An instance of a machine interface writer.
 616  *
 617  * Returns zero if the element's value could be written.
 618  * Negative values indicate an error.
 619  *
 620  * Note: A targets element is also opened for each tracker definition
 621  */
 622 int mi_lttng_process_attribute_tracker_open(
 623                 struct mi_writer *writer, enum lttng_process_attr process_attr);
 624
 625 /*
 626  * Machine interface: open a PIDs element.
 627  *
 628  * writer An instance of a machine interface writer.
 629  *
 630  * Returns zero if the element's value could be written.
 631  * Negative values indicate an error.
 632  */
 633 int mi_lttng_pids_open(struct mi_writer *writer);
 634
 635 /*
 636  * Machine interface: open a processes element.
 637  *
 638  * writer An instance of a machine interface writer.
 639  *
 640  * Returns zero if the element's value could be written.
 641  * Negative values indicate an error.
 642  */
 643 int mi_lttng_processes_open(struct mi_writer *writer);
 644
 645 /*
 646  * Machine interface of a Process.
 647  *
 648  * writer An instance of a machine interface writer.
 649  * pid A PID.
 650  *
 651  * is_open Defines whether or not the session element shall be closed.
 652  *         This should be used carefully and the client
 653  *         must close the pid element.
 654  *         Use case: nested addition information on a domain
 655  *                  ex: channel event.
 656  *
 657  * Returns zero if the element's value could be written.
 658  * Negative values indicate an error.
 659  */
 660 int mi_lttng_process(struct mi_writer *writer, pid_t pid , const char *name,
 661                 int is_open);
 662
 663 /*
 664  * TODO: move pid of lttng list -u to process semantic on mi api bump
 665  * Machine interface of a Process.
 666  *
 667  * writer An instance of a machine interface writer.
 668  * pid A PID.
 669  *
 670  * is_open Defines whether or not the session element shall be closed.
 671  *         This should be used carefully and the client
 672  *         must close the pid element.
 673  *         Use case: nested addition information on a domain
 674  *                  ex: channel event.
 675  *
 676  * Returns zero if the element's value could be written.
 677  * Negative values indicate an error.
 678  */
 679 int mi_lttng_pid(struct mi_writer *writer, pid_t pid , const char *name,
 680                 int is_open);
 681
 682 /*
 683  * Machine interface: open a process attribute values element.
 684  *
 685  * writer An instance of a machine interface writer.
 686  *
 687  * Returns zero if the element's value could be written.
 688  * Negative values indicate an error.
 689  */
 690 int mi_lttng_process_attr_values_open(struct mi_writer *writer);
 691
 692 /*
 693  * Machine interface for track/untrack of all process attribute values.
 694  *
 695  * writer An instance of a machine interface writer.
 696  *
 697  * Returns zero if the element's value could be written.
 698  * Negative values indicate an error.
 699  */
 700 int mi_lttng_all_process_attribute_value(struct mi_writer *writer,
 701                 enum lttng_process_attr process_attr,
 702                 bool is_open);
 703
 704 /*
 705  * Machine interface for track/untrack of an integral process attribute value.
 706  *
 707  * writer An instance of a machine interface writer.
 708  *
 709  * Returns zero if the element's value could be written.
 710  * Negative values indicate an error.
 711  */
 712 int mi_lttng_integral_process_attribute_value(struct mi_writer *writer,
 713                 enum lttng_process_attr process_attr,
 714                 int64_t value,
 715                 bool is_open);
 716
 717 /*
 718  * Machine interface for track/untrack of a string process attribute value.
 719  *
 720  * writer An instance of a machine interface writer.
 721  *
 722  * Returns zero if the element's value could be written.
 723  * Negative values indicate an error.
 724  */
 725 int mi_lttng_string_process_attribute_value(struct mi_writer *writer,
 726                 enum lttng_process_attr process_attr,
 727                 const char *value,
 728                 bool is_open);
 729
 730 /*
 731  * Machine interface of a context.
 732  *
 733  * writer An instance of a machine interface writer
 734  *
 735  * context An instance of a lttng_event_context
 736  *
 737  * is_open Define if we close the context element
 738  *         This should be used carefully and the client
 739  *         need to close the context element.
 740  * Returns zero if the element's value could be written.
 741  * Negative values indicate an error.
 742  */
 743 int mi_lttng_context(struct mi_writer *writer,
 744                 struct lttng_event_context *context, int is_open);
 745
 746 /*
 747  * Machine interface of a perf_counter_context.
 748  *
 749  * writer An instance of a machine interface writer
 750  *
 751  * contest An instance of a lttng_event_perf_counter_ctx
 752  *
 753  * Returns zero if the element's value could be written.
 754  * Negative values indicate an error.
 755  */
 756 int mi_lttng_perf_counter_context(struct mi_writer *writer,
 757                 struct lttng_event_perf_counter_ctx  *perf_context);
 758
 759 /*
 760  * Machine interface of the snapshot list_output.
 761  * It specifies the session for which we are listing snapshots,
 762  * and it opens a snapshots element to list a sequence
 763  * of snapshots.
 764  *
 765  * writer An instance of a machine interface writer.
 766  *
 767  * session_name: Snapshot output for session "session_name".
 768  *
 769  * Note: The client has to close the session and the snapshots elements after
 770  * having listed every lttng_snapshot_output.
 771  *
 772  * Returns zero if the element's value could be written.
 773  * Negative values indicate an error.
 774  */
 775 int mi_lttng_snapshot_output_session_name(struct mi_writer *writer,
 776                 const char *session_name);
 777
 778 /*
 779  * Machine interface of the snapshot output.
 780  * The machine interface serializes the following attributes:
 781  * - id: ID of the snapshot output.
 782  * - name: Name of the output.
 783  * - data_url : Destination of the output.
 784  * - ctrl_url: Destination of the output.
 785  * - max_size: total size of all stream combined.
 786  *
 787  * writer An instance of a machine interface writer.
 788  *
 789  * output: A list of snapshot_output.
 790  *
 791  * Returns zero if the element's value could be written.
 792  * Negative values indicate an error.
 793  */
 794 int mi_lttng_snapshot_list_output(struct mi_writer *writer,
 795                 struct lttng_snapshot_output *output);
 796
 797 /*
 798  * Machine interface of the output of the command snapshot del output
 799  * when deleting a snapshot either by id or by name.
 800  * If the snapshot was found and successfully deleted using its id,
 801  * it return the id of the snapshot and the current session name on which it
 802  * was attached.
 803  *
 804  * Otherwise, it do the same process with the name of the snapshot, if the
 805  * snapshot output id is undefined.
 806  *
 807  * writer An instance of a machine interface writer.
 808  *
 809  * id: ID of the snapshot output.
 810  *
 811  * name: Name of the snapshot.
 812  *
 813  * current_session_name: Session to which the snapshot belongs.
 814  *
 815  * Returns zero if the element's value could be written.
 816  * Negative values indicate an error.
 817  */
 818 int mi_lttng_snapshot_del_output(struct mi_writer *writer, int id,
 819                 const char *name, const char *current_session_name);
 820
 821 /*
 822  * Machine interface of the output of the command snapshot add output
 823  * when adding a snapshot from a user URL.
 824  *
 825  * If the snapshot was successfully added, the machine interface lists
 826  * these information:
 827  * - id: ID of the newly add snapshot output.
 828  * - current_session_name: Name of the session to which the output was added.
 829  * - ctrl_url: Destination of the output.
 830  * - max_size: total size of all stream combined.
 831  *
 832  * writer An instance of a machine interface writer.
 833  *
 834  * current_session_name: Session to which the snapshot belongs.
 835  *
 836  * n_ptr:
 837  *
 838  * output: iterator over a lttng_snapshot_output_list which contain
 839  * the snapshot output informations.
 840  *
 841  * Returns zero if the element's value could be written.
 842  * Negative values indicate an error.
 843  */
 844 int mi_lttng_snapshot_add_output(struct mi_writer *writer,
 845                 const char *current_session_name, const char *n_ptr,
 846                 struct lttng_snapshot_output *output);
 847
 848 /*
 849  * Machine interface of the output of the command snapshot
 850  * record  from a URL (if given).
 851  *
 852  * If the snapshot is successfully recorded from a url, the machine interface
 853  * output the following information:
 854  * - url: Destination of the output stored in the snapshot.
 855  *
 856  * Otherwise, the machine interface output the data and ctrl url received
 857  * from the command-line.
 858  *
 859  * writer An instance of a machine interface writer.
 860  *
 861  * current_session_name: Snapshot record for session "current_session_name".
 862  *
 863  * ctrl_url, data_url: Destination of the output receive from the command-line.
 864  *
 865  * Returns zero if the element's value could be written.
 866  * Negative values indicate an error.
 867  */
 868 int mi_lttng_snapshot_record(struct mi_writer *writer,
 869                 const char *current_session_name, const char *url,
 870                 const char *cmdline_ctrl_url, const char *cmdline_data_url);
 871
 872 /*
 873  * Machine interface representation of a session rotation schedule.
 874  *
 875  * The machine interface serializes the provided schedule as one of the choices
 876  * from 'rotation_schedule_type'.
 877  *
 878  * writer: An instance of a machine interface writer.
 879  *
 880  * schedule: An lttng rotation schedule descriptor object.
 881  *
 882  * Returns zero if the element's value could be written.
 883  * Negative values indicate an error.
 884  */
 885 int mi_lttng_rotation_schedule(struct mi_writer *writer,
 886                 const struct lttng_rotation_schedule *schedule);
 887
 888 /*
 889  * Machine interface of a session rotation schedule result.
 890  * This is an element that is part of the output of the enable-rotation and
 891  * disable-rotation commands.
 892  *
 893  * The machine interface provides the following information:
 894  * - schedule: the session rotation schedule descriptor.
 895  * - success: whether the sub-command succeeded.
 896  *
 897  * writer: An instance of a machine interface writer.
 898  *
 899  * schedule: An lttng rotation schedule descriptor object.
 900  *
 901  * success: Whether the sub-command suceeded.
 902  *
 903  * Returns zero if the element's value could be written.
 904  * Negative values indicate an error.
 905  */
 906 int mi_lttng_rotation_schedule_result(struct mi_writer *writer,
 907                 const struct lttng_rotation_schedule *schedule,
 908                 bool success);
 909
 910 /*
 911  * Machine interface of a session rotation result.
 912  * This is an element that is part of the output of the rotate command.
 913  *
 914  * The machine interface provides the following information:
 915  * - session_name: the session to be rotated.
 916  * - state: the session rotation state.
 917  * - location: the location of the completed chunk archive.
 918  *
 919  * writer: An instance of a machine interface writer.
 920  *
 921  * session_name: The session to which the rotate command applies.
 922  *
 923  * location: A location descriptor object.
 924  *
 925  * success: Whether the sub-command suceeded.
 926  *
 927  * Returns zero if the element's value could be written.
 928  * Negative values indicate an error.
 929  */
 930 int mi_lttng_rotate(struct mi_writer *writer,
 931                 const char *session_name,
 932                 enum lttng_rotation_state rotation_state,
 933                 const struct lttng_trace_archive_location *location);
 934
 935 #endif /* _MI_LTTNG_H */