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 #if defined(__cplusplus)
  21 extern "C" {
  22 #endif
  23
  24 /* Don't want to reference snapshot-internal.h here */
  25 struct lttng_snapshot_output;
  26
  27 /* Instance of a machine interface writer. */
  28 struct mi_writer {
  29         struct config_writer *writer;
  30         enum lttng_mi_output_type type;
  31 };
  32
  33 /*
  34  * Version information for the machine interface.
  35  */
  36 struct mi_lttng_version_data {
  37         char version[LTTNG_NAME_MAX]; /* Version number of package */
  38         uint32_t version_major; /* LTTng-Tools major version number */
  39         uint32_t version_minor; /* LTTng-Tools minor version number */
  40         uint32_t version_patchlevel; /* LTTng-Tools patchlevel version number */
  41         char version_commit[LTTNG_NAME_MAX]; /* Commit hash of the current version */
  42         char version_name[LTTNG_NAME_MAX];
  43         char package_url[LTTNG_NAME_MAX]; /* Define to the home page for this package. */
  44 };
  45
  46 /* Error query callbacks. */
  47 typedef enum lttng_error_code (*mi_lttng_error_query_trigger_cb)(
  48                 const struct lttng_trigger *trigger,
  49                 struct lttng_error_query_results **results);
  50 typedef enum lttng_error_code (*mi_lttng_error_query_condition_cb)(
  51                 const struct lttng_trigger *trigger,
  52                 struct lttng_error_query_results **results);
  53 typedef enum lttng_error_code (*mi_lttng_error_query_action_cb)(
  54                 const struct lttng_trigger *trigger,
  55                 const struct lttng_action_path *action_path,
  56                 struct lttng_error_query_results **results);
  57
  58 struct mi_lttng_error_query_callbacks {
  59         mi_lttng_error_query_trigger_cb trigger_cb;
  60         mi_lttng_error_query_condition_cb condition_cb;
  61         mi_lttng_error_query_action_cb action_cb;
  62 };
  63
  64 /* Strings related to command */
  65 extern const char * const mi_lttng_element_command;
  66 extern const char * const mi_lttng_element_command_action;
  67 extern const char * const mi_lttng_element_command_add_context;
  68 extern const char * const mi_lttng_element_command_add_trigger;
  69 extern const char * const mi_lttng_element_command_create;
  70 extern const char * const mi_lttng_element_command_destroy;
  71 extern const char * const mi_lttng_element_command_disable_channel;
  72 extern const char * const mi_lttng_element_command_disable_event;
  73 extern const char * const mi_lttng_element_command_enable_channels;
  74 extern const char * const mi_lttng_element_command_enable_event;
  75 extern const char * const mi_lttng_element_command_list;
  76 extern const char * const mi_lttng_element_command_list_trigger;
  77 extern const char * const mi_lttng_element_command_load;
  78 extern const char * const mi_lttng_element_command_metadata;
  79 extern const char * const mi_lttng_element_command_metadata_action;
  80 extern const char * const mi_lttng_element_command_regenerate;
  81 extern const char * const mi_lttng_element_command_regenerate_action;
  82 extern const char * const mi_lttng_element_command_name;
  83 extern const char * const mi_lttng_element_command_output;
  84 extern const char * const mi_lttng_element_command_remove_trigger;
  85 extern const char * const mi_lttng_element_command_save;
  86 extern const char * const mi_lttng_element_command_set_session;
  87 extern const char * const mi_lttng_element_command_snapshot;
  88 extern const char * const mi_lttng_element_command_snapshot_add;
  89 extern const char * const mi_lttng_element_command_snapshot_del;
  90 extern const char * const mi_lttng_element_command_snapshot_list;
  91 extern const char * const mi_lttng_element_command_snapshot_record;
  92 extern const char * const mi_lttng_element_command_start;
  93 extern const char * const mi_lttng_element_command_stop;
  94 extern const char * const mi_lttng_element_command_success;
  95 extern const char * const mi_lttng_element_command_track;
  96 extern const char * const mi_lttng_element_command_untrack;
  97 extern const char * const mi_lttng_element_command_version;
  98 extern const char * const mi_lttng_element_command_rotate;
  99 extern const char * const mi_lttng_element_command_enable_rotation;
 100 extern const char * const mi_lttng_element_command_disable_rotation;
 101 extern const char * const mi_lttng_element_command_clear;
 102
 103 /* Strings related to version command */
 104 extern const char * const mi_lttng_element_version;
 105 extern const char * const mi_lttng_element_version_commit;
 106 extern const char * const mi_lttng_element_version_description;
 107 extern const char * const mi_lttng_element_version_license;
 108 extern const char * const mi_lttng_element_version_major;
 109 extern const char * const mi_lttng_element_version_minor;
 110 extern const char * const mi_lttng_element_version_patch_level;
 111 extern const char * const mi_lttng_element_version_str;
 112 extern const char * const mi_lttng_element_version_web;
 113
 114 /* String related to a lttng_event_field */
 115 extern const char * const mi_lttng_element_event_field;
 116 extern const char * const mi_lttng_element_event_fields;
 117
 118 /* String related to lttng_event_perf_counter_ctx */
 119 extern const char * const mi_lttng_element_perf_counter_context;
 120
 121 /* Strings related to pid */
 122 extern const char * const mi_lttng_element_pid_id;
 123
 124 /* Strings related to save command */
 125 extern const char * const mi_lttng_element_save;
 126
 127 /* Strings related to load command */
 128 extern const char * const mi_lttng_element_load;
 129 extern const char * const mi_lttng_element_load_overrides;
 130 extern const char * const mi_lttng_element_load_override_url;
 131
 132 /* General element of mi_lttng */
 133 extern const char * const mi_lttng_element_empty;
 134 extern const char * const mi_lttng_element_id;
 135 extern const char * const mi_lttng_element_nowrite;
 136 extern const char * const mi_lttng_element_success;
 137 extern const char * const mi_lttng_element_type_enum;
 138 extern const char * const mi_lttng_element_type_float;
 139 extern const char * const mi_lttng_element_type_integer;
 140 extern const char * const mi_lttng_element_type_other;
 141 extern const char * const mi_lttng_element_type_string;
 142
 143 /* String related to loglevel */
 144 extern const char * const mi_lttng_loglevel_str_alert;
 145 extern const char * const mi_lttng_loglevel_str_crit;
 146 extern const char * const mi_lttng_loglevel_str_debug;
 147 extern const char * const mi_lttng_loglevel_str_debug_function;
 148 extern const char * const mi_lttng_loglevel_str_debug_line;
 149 extern const char * const mi_lttng_loglevel_str_debug_module;
 150 extern const char * const mi_lttng_loglevel_str_debug_process;
 151 extern const char * const mi_lttng_loglevel_str_debug_program;
 152 extern const char * const mi_lttng_loglevel_str_debug_system;
 153 extern const char * const mi_lttng_loglevel_str_debug_unit;
 154 extern const char * const mi_lttng_loglevel_str_emerg;
 155 extern const char * const mi_lttng_loglevel_str_err;
 156 extern const char * const mi_lttng_loglevel_str_info;
 157 extern const char * const mi_lttng_loglevel_str_notice;
 158 extern const char * const mi_lttng_loglevel_str_unknown;
 159 extern const char * const mi_lttng_loglevel_str_warning;
 160
 161 /* String related to loglevel JUL */
 162 extern const char * const mi_lttng_loglevel_str_jul_all;
 163 extern const char * const mi_lttng_loglevel_str_jul_config;
 164 extern const char * const mi_lttng_loglevel_str_jul_fine;
 165 extern const char * const mi_lttng_loglevel_str_jul_finer;
 166 extern const char * const mi_lttng_loglevel_str_jul_finest;
 167 extern const char * const mi_lttng_loglevel_str_jul_info;
 168 extern const char * const mi_lttng_loglevel_str_jul_off;
 169 extern const char * const mi_lttng_loglevel_str_jul_severe;
 170 extern const char * const mi_lttng_loglevel_str_jul_warning;
 171
 172 /* String related to loglevel Log4j */
 173 extern const char * const mi_lttng_loglevel_str_log4j_off;
 174 extern const char * const mi_lttng_loglevel_str_log4j_fatal;
 175 extern const char * const mi_lttng_loglevel_str_log4j_error;
 176 extern const char * const mi_lttng_loglevel_str_log4j_warn;
 177 extern const char * const mi_lttng_loglevel_str_log4j_info;
 178 extern const char * const mi_lttng_loglevel_str_log4j_debug;
 179 extern const char * const mi_lttng_loglevel_str_log4j_trace;
 180 extern const char * const mi_lttng_loglevel_str_log4j_all;
 181
 182 /* String related to loglevel Python */
 183 extern const char * const mi_lttng_loglevel_str_python_critical;
 184 extern const char * const mi_lttng_loglevel_str_python_error;
 185 extern const char * const mi_lttng_loglevel_str_python_warning;
 186 extern const char * const mi_lttng_loglevel_str_python_info;
 187 extern const char * const mi_lttng_loglevel_str_python_debug;
 188 extern const char * const mi_lttng_loglevel_str_python_notset;
 189
 190 /* String related to loglevel type */
 191 extern const char * const mi_lttng_loglevel_type_all;
 192 extern const char * const mi_lttng_loglevel_type_range;
 193 extern const char * const mi_lttng_loglevel_type_single;
 194 extern const char * const mi_lttng_loglevel_type_unknown;
 195
 196 /* String related to a lttng_snapshot */
 197 extern const char * const mi_lttng_element_snapshot_ctrl_url;
 198 extern const char * const mi_lttng_element_snapshot_data_url;
 199 extern const char * const mi_lttng_element_snapshot_max_size;
 200 extern const char * const mi_lttng_element_snapshot_n_ptr;
 201 extern const char * const mi_lttng_element_snapshot_session_name;
 202 extern const char * const mi_lttng_element_snapshots;
 203
 204 /* String related to track/untrack command */
 205 extern const char * const mi_lttng_element_track_untrack_all_wildcard;
 206
 207 extern const char * const mi_lttng_element_session_name;
 208
 209 /* String related to rotate command */
 210 extern const char * const mi_lttng_element_rotation;
 211 extern const char * const mi_lttng_element_rotate_status;
 212 extern const char * const mi_lttng_element_rotation_schedule;
 213 extern const char * const mi_lttng_element_rotation_schedules;
 214 extern const char * const mi_lttng_element_rotation_schedule_periodic;
 215 extern const char * const mi_lttng_element_rotation_schedule_periodic_time_us;
 216 extern const char * const mi_lttng_element_rotation_schedule_size_threshold;
 217 extern const char * const mi_lttng_element_rotation_schedule_size_threshold_bytes;
 218 extern const char * const mi_lttng_element_rotation_schedule_result;
 219 extern const char * const mi_lttng_element_rotation_schedule_results;
 220 extern const char * const mi_lttng_element_rotation_state;
 221 extern const char * const mi_lttng_element_rotation_location;
 222 extern const char * const mi_lttng_element_rotation_location_local;
 223 extern const char * const mi_lttng_element_rotation_location_local_absolute_path;
 224 extern const char * const mi_lttng_element_rotation_location_relay;
 225 extern const char * const mi_lttng_element_rotation_location_relay_host;
 226 extern const char * const mi_lttng_element_rotation_location_relay_control_port;
 227 extern const char * const mi_lttng_element_rotation_location_relay_data_port;
 228 extern const char * const mi_lttng_element_rotation_location_relay_protocol;
 229 extern const char * const mi_lttng_element_rotation_location_relay_relative_path;
 230
 231 /* String related to enum lttng_rotation_state */
 232 extern const char * const mi_lttng_rotation_state_str_ongoing;
 233 extern const char * const mi_lttng_rotation_state_str_completed;
 234 extern const char * const mi_lttng_rotation_state_str_expired;
 235 extern const char * const mi_lttng_rotation_state_str_error;
 236
 237 /* String related to enum lttng_trace_archive_location_relay_protocol_type */
 238 extern const char * const mi_lttng_rotation_location_relay_protocol_str_tcp;
 239
 240 /* String related to rate_policy elements */
 241 extern const char *const mi_lttng_element_rate_policy;
 242 extern const char *const mi_lttng_element_rate_policy_every_n;
 243 extern const char *const mi_lttng_element_rate_policy_once_after_n;
 244
 245 extern const char
 246                 *const mi_lttng_element_rate_policy_every_n_interval;
 247 extern const char
 248                 *const mi_lttng_element_rate_policy_once_after_n_threshold;
 249
 250 /* String related to action elements */
 251 extern const char *const mi_lttng_element_action;
 252 extern const char *const mi_lttng_element_action_list;
 253 extern const char *const mi_lttng_element_action_notify;
 254 extern const char *const mi_lttng_element_action_start_session;
 255 extern const char *const mi_lttng_element_action_stop_session;
 256 extern const char *const mi_lttng_element_action_rotate_session;
 257 extern const char *const mi_lttng_element_action_snapshot_session;
 258 extern const char
 259                 *const mi_lttng_element_action_snapshot_session_output;
 260
 261 /* String related to condition */
 262 extern const char *const mi_lttng_element_condition;
 263 extern const char
 264                 *const mi_lttng_element_condition_buffer_usage_high;
 265 extern const char
 266                 *const mi_lttng_element_condition_buffer_usage_low;
 267 extern const char
 268                 *const mi_lttng_element_condition_event_rule_matches;
 269 extern const char
 270                 *const mi_lttng_element_condition_session_consumed_size;
 271 extern const char
 272                 *const mi_lttng_element_condition_session_rotation;
 273 extern const char
 274                 *const mi_lttng_element_condition_session_rotation_completed;
 275 extern const char
 276                 *const mi_lttng_element_condition_session_rotation_ongoing;
 277 extern const char *const mi_lttng_element_condition_channel_name;
 278 extern const char *const mi_lttng_element_condition_threshold_ratio;
 279 extern const char *const mi_lttng_element_condition_threshold_bytes;
 280
 281 /* String related to capture descriptor */
 282 extern const char *const mi_lttng_element_capture_descriptor;
 283 extern const char *const mi_lttng_element_capture_descriptors;
 284
 285 /* String related to event expression */
 286 extern const char *const mi_lttng_element_event_expr;
 287 extern const char *const mi_lttng_element_event_expr_payload_field;
 288 extern const char
 289                 *const mi_lttng_element_event_expr_channel_context_field;
 290 extern const char
 291                 *const mi_lttng_element_event_expr_app_specific_context_field;
 292 extern const char
 293                 *const mi_lttng_element_event_expr_array_field_element;
 294
 295 extern const char *const mi_lttng_element_event_expr_provider_name;
 296 extern const char *const mi_lttng_element_event_expr_type_name;
 297 extern const char *const mi_lttng_element_event_expr_index;
 298
 299 /* String related to event rule */
 300 extern const char *const mi_lttng_element_event_rule;
 301
 302 /* String related to lttng_event_rule */
 303 extern const char *const mi_lttng_element_event_rule_event_name;
 304 extern const char *const mi_lttng_element_event_rule_name_pattern;
 305 extern const char
 306                 *const mi_lttng_element_event_rule_filter_expression;
 307 extern const char *const mi_lttng_element_event_rule_jul_logging;
 308 extern const char *const mi_lttng_element_event_rule_kernel_kprobe;
 309 extern const char *const mi_lttng_element_event_rule_kernel_syscall;
 310 extern const char
 311                 *const mi_lttng_element_event_rule_kernel_tracepoint;
 312 extern const char *const mi_lttng_element_event_rule_kernel_uprobe;
 313 extern const char *const mi_lttng_element_event_rule_log4j_logging;
 314 extern const char *const mi_lttng_element_event_rule_python_logging;
 315 extern const char
 316                 *const mi_lttng_element_event_rule_user_tracepoint;
 317
 318 /* String related to lttng_event_rule_kernel_syscall. */
 319 extern const char
 320                 *const mi_lttng_element_event_rule_kernel_syscall_emission_site;
 321
 322 /* String related to enum lttng_event_rule_kernel_syscall_emission_site. */
 323 extern const char *const
 324                 mi_lttng_event_rule_kernel_syscall_emission_site_entry_exit;
 325 extern const char
 326                 *const mi_lttng_event_rule_kernel_syscall_emission_site_entry;
 327 extern const char
 328                 *const mi_lttng_event_rule_kernel_syscall_emission_site_exit;
 329
 330 extern const char *const
 331                 mi_lttng_element_event_rule_user_tracepoint_name_pattern_exclusions;
 332 extern const char *const
 333                 mi_lttng_element_event_rule_user_tracepoint_name_pattern_exclusion;
 334
 335 /* String related to log level rule. */
 336 extern const char *const mi_lttng_element_log_level_rule;
 337 extern const char *const mi_lttng_element_log_level_rule_exactly;
 338 extern const char
 339                 *const mi_lttng_element_log_level_rule_at_least_as_severe_as;
 340 extern const char *const
 341                 mi_lttng_element_log_level_rule_at_least_as_severe_as_thre;
 342 extern const char *const mi_lttng_element_log_level_rule_level;
 343
 344 /* String related to kernel probe location. */
 345 extern const char *const mi_lttng_element_kernel_probe_location;
 346 extern const char
 347                 *const mi_lttng_element_kernel_probe_location_symbol_offset;
 348 extern const char *const
 349                 mi_lttng_element_kernel_probe_location_symbol_offset_name;
 350 extern const char *const
 351                 mi_lttng_element_kernel_probe_location_symbol_offset_offset;
 352 extern const char
 353                 *const mi_lttng_element_kernel_probe_location_address;
 354 extern const char
 355                 *const mi_lttng_element_kernel_probe_location_address_address;
 356
 357 /* String related to userspace probe location. */
 358 extern const char *const mi_lttng_element_userspace_probe_location;
 359 extern const char
 360                 *const mi_lttng_element_userspace_probe_location_binary_path;
 361 extern const char
 362                 *const mi_lttng_element_userspace_probe_location_function;
 363 extern const char
 364                 *const mi_lttng_element_userspace_probe_location_function_name;
 365 extern const char
 366                 *const mi_lttng_element_userspace_probe_location_lookup_method;
 367 extern const char *const
 368                 mi_lttng_element_userspace_probe_location_lookup_method_function_default;
 369 extern const char *const
 370                 mi_lttng_element_userspace_probe_location_lookup_method_function_elf;
 371 extern const char *const
 372                 mi_lttng_element_userspace_probe_location_lookup_method_tracepoint_sdt;
 373 extern const char
 374                 *const mi_lttng_element_userspace_probe_location_tracepoint;
 375 extern const char *const
 376                 mi_lttng_element_userspace_probe_location_tracepoint_probe_name;
 377 extern const char *const
 378                 mi_lttng_element_userspace_probe_location_tracepoint_provider_name;
 379
 380 /* String related to enum
 381  * lttng_userspace_probe_location_function_instrumentation_type */
 382 extern const char *const
 383                 mi_lttng_element_userspace_probe_location_function_instrumentation_type;
 384 extern const char *const
 385                 mi_lttng_userspace_probe_location_function_instrumentation_type_entry;
 386
 387 /* String related to trigger */
 388 extern const char *const mi_lttng_element_triggers;
 389 extern const char *const mi_lttng_element_trigger;
 390 extern const char *const mi_lttng_element_trigger_owner_uid;
 391
 392 /* String related to error_query. */
 393 extern const char *const mi_lttng_element_error_query_result;
 394 extern const char
 395                 *const mi_lttng_element_error_query_result_counter;
 396 extern const char
 397                 *const mi_lttng_element_error_query_result_counter_value;
 398 extern const char
 399                 *const mi_lttng_element_error_query_result_description;
 400 extern const char *const mi_lttng_element_error_query_result_name;
 401 extern const char *const mi_lttng_element_error_query_result_type;
 402 extern const char *const mi_lttng_element_error_query_results;
 403
 404 /* String related to add-context command */
 405 extern const char * const mi_lttng_element_context_symbol;
 406
 407 /* Utility string function  */
 408 const char *mi_lttng_loglevel_string(int value, enum lttng_domain_type domain);
 409 const char *mi_lttng_logleveltype_string(enum lttng_loglevel_type value);
 410 const char *mi_lttng_eventfieldtype_string(enum lttng_event_field_type value);
 411 const char *mi_lttng_domaintype_string(enum lttng_domain_type value);
 412 const char *mi_lttng_buffertype_string(enum lttng_buffer_type value);
 413 const char *mi_lttng_rotation_state_string(enum lttng_rotation_state value);
 414 const char *mi_lttng_trace_archive_location_relay_protocol_type_string(
 415                 enum lttng_trace_archive_location_relay_protocol_type value);
 416
 417 /*
 418  * Create an instance of a machine interface writer.
 419  *
 420  * fd_output File to which the XML content must be written. The file will be
 421  * closed once the mi_writer has been destroyed.
 422  *
 423  * Returns an instance of a machine interface writer on success, NULL on
 424  * error.
 425  */
 426 struct mi_writer *mi_lttng_writer_create(int fd_output, int mi_output_type);
 427
 428 /*
 429  * Destroy an instance of a machine interface writer.
 430  *
 431  * writer An instance of a machine interface writer.
 432  *
 433  * Returns zero if the XML document could be closed cleanly. Negative values
 434  * indicate an error.
 435  */
 436 int mi_lttng_writer_destroy(struct mi_writer *writer);
 437
 438 /*
 439  * Open a command tag and add it's name node.
 440  *
 441  * writer An instance of a machine interface writer.
 442  * command The command name.
 443  *
 444  * Returns zero if the XML document could be closed cleanly.
 445  * Negative values indicate an error.
 446  */
 447 int mi_lttng_writer_command_open(struct mi_writer *writer, const char *command);
 448
 449 /*
 450  * Close a command tag.
 451  *
 452  * writer An instance of a machine interface writer.
 453  *
 454  * Returns zero if the XML document could be closed cleanly.
 455  * Negative values indicate an error.
 456  */
 457 int mi_lttng_writer_command_close(struct mi_writer *writer);
 458
 459 /*
 460  * Open an element tag.
 461  *
 462  * writer An instance of a machine interface writer.
 463  * element_name Element tag name.
 464  *
 465  * Returns zero if the XML document could be closed cleanly.
 466  * Negative values indicate an error.
 467  */
 468 int mi_lttng_writer_open_element(struct mi_writer *writer,
 469                 const char *element_name);
 470
 471 /*
 472  * Close the current element tag.
 473  *
 474  * writer An instance of a machine interface writer.
 475  *
 476  * Returns zero if the XML document could be closed cleanly.
 477  * Negative values indicate an error.
 478  */
 479 int mi_lttng_writer_close_element(struct mi_writer *writer);
 480
 481 /*
 482  * Close multiple element.
 483  *
 484  * writer An instance of a machine interface writer.
 485  * nb_element Number of elements.
 486  *
 487  * Returns zero if the XML document could be closed cleanly.
 488  * Negative values indicate an error.
 489  */
 490 int mi_lttng_close_multi_element(struct mi_writer *writer,
 491                 unsigned int nb_element);
 492
 493 /*
 494  * Write an element of type unsigned int.
 495  *
 496  * writer An instance of a machine interface writer.
 497  * element_name Element name.
 498  * value Unsigned int value of the element
 499  *
 500  * Returns zero if the element's value could be written.
 501  * Negative values indicate an error.
 502  */
 503 int mi_lttng_writer_write_element_unsigned_int(struct mi_writer *writer,
 504                 const char *element_name, uint64_t value);
 505
 506 /*
 507  * Write an element of type signed int.
 508  *
 509  * writer An instance of a machine interface writer.
 510  * element_name Element name.
 511  * value Signed int value of the element.
 512  *
 513  * Returns zero if the element's value could be written.
 514  * Negative values indicate an error.
 515  */
 516 int mi_lttng_writer_write_element_signed_int(struct mi_writer *writer,
 517                 const char *element_name, int64_t value);
 518
 519 /*
 520  * Write an element of type boolean.
 521  *
 522  * writer An instance of a machine interface writer.
 523  * element_name Element name.
 524  * value Boolean value of the element.
 525  *
 526  * Returns zero if the element's value could be written.
 527  * Negative values indicate an error.
 528  */
 529 int mi_lttng_writer_write_element_bool(struct mi_writer *writer,
 530                 const char *element_name, int value);
 531
 532 /*
 533  * Write an element of type string.
 534  *
 535  * writer An instance of a machine interface writer.
 536  * element_name Element name.
 537  * value String value of the element.
 538  *
 539  * Returns zero if the element's value could be written.
 540  * Negative values indicate an error.
 541  */
 542 int mi_lttng_writer_write_element_string(struct mi_writer *writer,
 543                 const char *element_name, const char *value);
 544
 545 /*
 546  * Write an element of type double.
 547  *
 548  * writer An instance of a machine interface writer.
 549  * element_name Element name.
 550  * value Double value of the element.
 551  *
 552  * Returns zero if the element's value could be written.
 553  * Negative values indicate an error.
 554  */
 555 int mi_lttng_writer_write_element_double(struct mi_writer *writer,
 556                 const char *element_name,
 557                 double value);
 558
 559 /*
 560  * Machine interface of struct version.
 561  *
 562  * writer An instance of a machine interface writer.
 563  * version Version struct.
 564  * lttng_description String value of the version description.
 565  * lttng_license String value of the version license.
 566  *
 567  * Returns zero if the element's value could be written.
 568  * Negative values indicate an error.
 569  */
 570 int mi_lttng_version(struct mi_writer *writer, struct mi_lttng_version_data *version,
 571                 const char *lttng_description, const char *lttng_license);
 572
 573 /*
 574  * Machine interface: open a sessions element.
 575  *
 576  * writer An instance of a machine interface writer.
 577  *
 578  * Returns zero if the element's value could be written.
 579  * Negative values indicate an error.
 580  */
 581 int mi_lttng_sessions_open(struct mi_writer *writer);
 582
 583 /*
 584  * Machine interface of struct session.
 585  *
 586  * writer An instance of a machine interface writer.
 587  * session An instance of a session.
 588  * is_open Defines whether or not the session element shall be closed.
 589  *         This should be used carefully and the client
 590  *         must close the session element.
 591  *         Use case: nested additional information on a session
 592  *                  ex: domain,channel event.
 593  *
 594  * Returns zero if the element's value could be written.
 595  * Negative values indicate an error.
 596  */
 597 int mi_lttng_session(struct mi_writer *writer,
 598                 struct lttng_session *session, int is_open);
 599
 600 /*
 601  * Machine interface: open a domains element.
 602  *
 603  * writer An instance of a machine interface writer.
 604  *
 605  * Returns zero if the element's value could be written.
 606  * Negative values indicate an error.
 607  */
 608 int mi_lttng_domains_open(struct mi_writer *writer);
 609
 610 /*
 611  * Machine interface of struct domain.
 612  *
 613  * writer An instance of a machine interface writer.
 614  * domain An instance of a domain.
 615  *
 616  * is_open Defines whether or not the session element shall be closed.
 617  *         This should be used carefully and the client
 618  *         must close the domain element.
 619  *         Use case: nested addition information on a domain
 620  *                  ex: channel event.
 621  *
 622  * Returns zero if the element's value could be written.
 623  * Negative values indicate an error.
 624  */
 625 int mi_lttng_domain(struct mi_writer *writer,
 626                 struct lttng_domain *domain, int is_open);
 627
 628 /*
 629  * Machine interface: open a channels element.
 630  *
 631  * writer An instance of a machine interface writer.
 632  *
 633  * Returns zero if the element's value could be written.
 634  * Negative values indicate an error.
 635  */
 636 int mi_lttng_channels_open(struct mi_writer *writer);
 637
 638 /*
 639  * Machine interface of struct channel.
 640  *
 641  * writer An instance of a machine interface writer.
 642  * channel An instance of a channel.
 643  *
 644  * is_open Defines whether or not the session element shall be closed.
 645  *         This should be used carefully and the client
 646  *         must close the channel element.
 647  *         Use case: nested addition information on a channel.
 648  *                  ex: channel event.
 649  *
 650  * Returns zero if the element's value could be written.
 651  * Negative values indicate an error.
 652  */
 653 int mi_lttng_channel(struct mi_writer *writer,
 654                 struct lttng_channel *channel, int is_open);
 655
 656 /*
 657  * Machine interface of struct channel_attr.
 658  *
 659  * writer An instance of a machine interface writer.
 660  * attr An instance of a channel_attr struct.
 661  *
 662  * Returns zero if the element's value could be written.
 663  * Negative values indicate an error.
 664  */
 665 int mi_lttng_channel_attr(struct mi_writer *writer,
 666                 struct lttng_channel_attr *attr);
 667
 668 /*
 669 * Machine interface for event common attributes.
 670 *
 671 * writer An instance of a mi writer.
 672 * event single trace event.
 673 *
 674 * The common attribute are:
 675 * - mi event element
 676 * - event name
 677 * - event type
 678 * - enabled tag
 679 * - event filter
 680 *
 681 * Returns zero if the element's value could be written.
 682 * Negative values indicate an error.
 683 */
 684 int mi_lttng_event_common_attributes(struct mi_writer *writer,
 685                 struct lttng_event *event);
 686
 687 /*
 688  * Machine interface for kernel tracepoint event with a loglevel.
 689  *
 690  * writer An instance of a mi writer.
 691  * event single trace event.
 692  * domain Event's domain
 693  *
 694  * Returns zero if the element's value could be written.
 695  * Negative values indicate an error.
 696  */
 697 int mi_lttng_event_tracepoint_loglevel(struct mi_writer *writer,
 698                 struct lttng_event *event, enum lttng_domain_type domain);
 699
 700 /*
 701  * Machine interface for kernel tracepoint event with no loglevel.
 702  *
 703  * writer An instance of a mi writer.
 704  * event single trace event.
 705  *
 706  * Returns zero if the element's value could be written.
 707  * Negative values indicate an error.
 708  */
 709 int mi_lttng_event_tracepoint_no_loglevel(struct mi_writer *writer,
 710                 struct lttng_event *event);
 711
 712 /*
 713  * Machine interface for kernel function and probe event.
 714  *
 715  * writer An instance of a mi writer.
 716  * event single trace event.
 717  *
 718  * Returns zero if the element's value could be written.
 719  * Negative values indicate an error.
 720  */
 721 int mi_lttng_event_function_probe(struct mi_writer *writer,
 722                 struct lttng_event *event);
 723
 724 /*
 725  * Machine interface for kernel function entry event.
 726  *
 727  * writer An instance of a mi writer.
 728  * event single trace event.
 729  *
 730  * Returns zero if the element's value could be written.
 731  * Negative values indicate an error.
 732  */
 733 int mi_lttng_event_function_entry(struct mi_writer *writer,
 734                 struct lttng_event *event);
 735
 736 /*
 737  * Machine interface: open an events element.
 738  *
 739  * writer An instance of a machine interface writer.
 740  *
 741  * Returns zero if the element's value could be written.
 742  * Negative values indicate an error.
 743  */
 744 int mi_lttng_events_open(struct mi_writer *writer);
 745
 746 /*
 747  * Machine interface for printing an event.
 748  * The trace event type currently supported are:
 749  *  TRACEPOINT,
 750  *  PROBE,
 751  *  FUNCTION,
 752  *  FUNCTION_ENTRY,
 753  *  SYSCALL
 754  *
 755  * writer An instance of a mi writer.
 756  * event single trace event.
 757  * is_open Defines whether or not the session element shall be closed.
 758  *         This should be used carefully and the client
 759  *         must close the event element.
 760  *         Use case: nested additional information
 761  * domain Event's domain
 762  *
 763  * Returns zero if the element's value could be written.
 764  * Negative values indicate an error.
 765  */
 766 int mi_lttng_event(struct mi_writer *writer, struct lttng_event *event,
 767                 int is_open, enum lttng_domain_type domain);
 768
 769 /*
 770  * Machine interface for struct lttng_event_field.
 771  *
 772  * writer An instance of a mi writer.
 773  * field An event_field instance.
 774  *
 775  * Returns zero if the element's value could be written.
 776  * Negative values indicate an error.
 777  */
 778 int mi_lttng_event_field(struct mi_writer *writer,
 779                 struct lttng_event_field *field);
 780
 781 /*
 782  * Machine interface: open a event_fields element.
 783  *
 784  * writer An instance of a machine interface writer.
 785  *
 786  * Returns zero if the element have be written.
 787  * Negative values indicate an error.
 788  */
 789 int mi_lttng_event_fields_open(struct mi_writer *writer);
 790
 791 /*
 792  * Machine interface: open a trackers element.
 793  *
 794  * writer An instance of a machine interface writer.
 795  *
 796  * Returns zero if the element's value could be written.
 797  * Negative values indicate an error.
 798  */
 799 int mi_lttng_trackers_open(struct mi_writer *writer);
 800
 801 /*
 802  * Machine interface: open a process attribute tracker element.
 803  *
 804  * writer An instance of a machine interface writer.
 805  *
 806  * Returns zero if the element's value could be written.
 807  * Negative values indicate an error.
 808  *
 809  * Note: A targets element is also opened for each tracker definition
 810  */
 811 int mi_lttng_process_attribute_tracker_open(
 812                 struct mi_writer *writer, enum lttng_process_attr process_attr);
 813
 814 /*
 815  * Machine interface: open a PIDs element.
 816  *
 817  * writer An instance of a machine interface writer.
 818  *
 819  * Returns zero if the element's value could be written.
 820  * Negative values indicate an error.
 821  */
 822 int mi_lttng_pids_open(struct mi_writer *writer);
 823
 824 /*
 825  * Machine interface: open a processes element.
 826  *
 827  * writer An instance of a machine interface writer.
 828  *
 829  * Returns zero if the element's value could be written.
 830  * Negative values indicate an error.
 831  */
 832 int mi_lttng_processes_open(struct mi_writer *writer);
 833
 834 /*
 835  * Machine interface of a Process.
 836  *
 837  * writer An instance of a machine interface writer.
 838  * pid A PID.
 839  *
 840  * is_open Defines whether or not the session element shall be closed.
 841  *         This should be used carefully and the client
 842  *         must close the pid element.
 843  *         Use case: nested addition information on a domain
 844  *                  ex: channel event.
 845  *
 846  * Returns zero if the element's value could be written.
 847  * Negative values indicate an error.
 848  */
 849 int mi_lttng_process(struct mi_writer *writer, pid_t pid , const char *name,
 850                 int is_open);
 851
 852 /*
 853  * TODO: move pid of lttng list -u to process semantic on mi api bump
 854  * Machine interface of a Process.
 855  *
 856  * writer An instance of a machine interface writer.
 857  * pid A PID.
 858  *
 859  * is_open Defines whether or not the session element shall be closed.
 860  *         This should be used carefully and the client
 861  *         must close the pid element.
 862  *         Use case: nested addition information on a domain
 863  *                  ex: channel event.
 864  *
 865  * Returns zero if the element's value could be written.
 866  * Negative values indicate an error.
 867  */
 868 int mi_lttng_pid(struct mi_writer *writer, pid_t pid , const char *name,
 869                 int is_open);
 870
 871 /*
 872  * Machine interface: open a process attribute values element.
 873  *
 874  * writer An instance of a machine interface writer.
 875  *
 876  * Returns zero if the element's value could be written.
 877  * Negative values indicate an error.
 878  */
 879 int mi_lttng_process_attr_values_open(struct mi_writer *writer);
 880
 881 /*
 882  * Machine interface for track/untrack of all process attribute values.
 883  *
 884  * writer An instance of a machine interface writer.
 885  *
 886  * Returns zero if the element's value could be written.
 887  * Negative values indicate an error.
 888  */
 889 int mi_lttng_all_process_attribute_value(struct mi_writer *writer,
 890                 enum lttng_process_attr process_attr,
 891                 bool is_open);
 892
 893 /*
 894  * Machine interface for track/untrack of an integral process attribute value.
 895  *
 896  * writer An instance of a machine interface writer.
 897  *
 898  * Returns zero if the element's value could be written.
 899  * Negative values indicate an error.
 900  */
 901 int mi_lttng_integral_process_attribute_value(struct mi_writer *writer,
 902                 enum lttng_process_attr process_attr,
 903                 int64_t value,
 904                 bool is_open);
 905
 906 /*
 907  * Machine interface for track/untrack of a string process attribute value.
 908  *
 909  * writer An instance of a machine interface writer.
 910  *
 911  * Returns zero if the element's value could be written.
 912  * Negative values indicate an error.
 913  */
 914 int mi_lttng_string_process_attribute_value(struct mi_writer *writer,
 915                 enum lttng_process_attr process_attr,
 916                 const char *value,
 917                 bool is_open);
 918
 919 /*
 920  * Machine interface of a context.
 921  *
 922  * writer An instance of a machine interface writer
 923  *
 924  * context An instance of a lttng_event_context
 925  *
 926  * is_open Define if we close the context element
 927  *         This should be used carefully and the client
 928  *         need to close the context element.
 929  * Returns zero if the element's value could be written.
 930  * Negative values indicate an error.
 931  */
 932 int mi_lttng_context(struct mi_writer *writer,
 933                 struct lttng_event_context *context, int is_open);
 934
 935 /*
 936  * Machine interface of a perf_counter_context.
 937  *
 938  * writer An instance of a machine interface writer
 939  *
 940  * contest An instance of a lttng_event_perf_counter_ctx
 941  *
 942  * Returns zero if the element's value could be written.
 943  * Negative values indicate an error.
 944  */
 945 int mi_lttng_perf_counter_context(struct mi_writer *writer,
 946                 struct lttng_event_perf_counter_ctx  *perf_context);
 947
 948 /*
 949  * Machine interface of the snapshot list_output.
 950  * It specifies the session for which we are listing snapshots,
 951  * and it opens a snapshots element to list a sequence
 952  * of snapshots.
 953  *
 954  * writer An instance of a machine interface writer.
 955  *
 956  * session_name: Snapshot output for session "session_name".
 957  *
 958  * Note: The client has to close the session and the snapshots elements after
 959  * having listed every lttng_snapshot_output.
 960  *
 961  * Returns zero if the element's value could be written.
 962  * Negative values indicate an error.
 963  */
 964 int mi_lttng_snapshot_output_session_name(struct mi_writer *writer,
 965                 const char *session_name);
 966
 967 /*
 968  * Machine interface of the snapshot output.
 969  * The machine interface serializes the following attributes:
 970  * - id: ID of the snapshot output.
 971  * - name: Name of the output.
 972  * - data_url : Destination of the output.
 973  * - ctrl_url: Destination of the output.
 974  * - max_size: total size of all stream combined.
 975  *
 976  * writer An instance of a machine interface writer.
 977  *
 978  * output: A list of snapshot_output.
 979  *
 980  * Returns zero if the element's value could be written.
 981  * Negative values indicate an error.
 982  */
 983 int mi_lttng_snapshot_list_output(struct mi_writer *writer,
 984                 const struct lttng_snapshot_output *output);
 985
 986 /*
 987  * Machine interface of the output of the command snapshot del output
 988  * when deleting a snapshot either by id or by name.
 989  * If the snapshot was found and successfully deleted using its id,
 990  * it return the id of the snapshot and the current session name on which it
 991  * was attached.
 992  *
 993  * Otherwise, it do the same process with the name of the snapshot, if the
 994  * snapshot output id is undefined.
 995  *
 996  * writer An instance of a machine interface writer.
 997  *
 998  * id: ID of the snapshot output.
 999  *
1000  * name: Name of the snapshot.
1001  *
1002  * current_session_name: Session to which the snapshot belongs.
1003  *
1004  * Returns zero if the element's value could be written.
1005  * Negative values indicate an error.
1006  */
1007 int mi_lttng_snapshot_del_output(struct mi_writer *writer, int id,
1008                 const char *name, const char *current_session_name);
1009
1010 /*
1011  * Machine interface of the output of the command snapshot add output
1012  * when adding a snapshot from a user URL.
1013  *
1014  * If the snapshot was successfully added, the machine interface lists
1015  * these information:
1016  * - id: ID of the newly add snapshot output.
1017  * - current_session_name: Name of the session to which the output was added.
1018  * - ctrl_url: Destination of the output.
1019  * - max_size: total size of all stream combined.
1020  *
1021  * writer An instance of a machine interface writer.
1022  *
1023  * current_session_name: Session to which the snapshot belongs.
1024  *
1025  * n_ptr:
1026  *
1027  * output: iterator over a lttng_snapshot_output_list which contain
1028  * the snapshot output informations.
1029  *
1030  * Returns zero if the element's value could be written.
1031  * Negative values indicate an error.
1032  */
1033 int mi_lttng_snapshot_add_output(struct mi_writer *writer,
1034                 const char *current_session_name, const char *n_ptr,
1035                 struct lttng_snapshot_output *output);
1036
1037 /*
1038  * Machine interface of the output of the command snapshot
1039  * record  from a URL (if given).
1040  *
1041  * If the snapshot is successfully recorded from a url, the machine interface
1042  * output the following information:
1043  * - url: Destination of the output stored in the snapshot.
1044  *
1045  * Otherwise, the machine interface output the data and ctrl url received
1046  * from the command-line.
1047  *
1048  * writer An instance of a machine interface writer.
1049  *
1050  * current_session_name: Snapshot record for session "current_session_name".
1051  *
1052  * ctrl_url, data_url: Destination of the output receive from the command-line.
1053  *
1054  * Returns zero if the element's value could be written.
1055  * Negative values indicate an error.
1056  */
1057 int mi_lttng_snapshot_record(struct mi_writer *writer,
1058                 const char *current_session_name, const char *url,
1059                 const char *cmdline_ctrl_url, const char *cmdline_data_url);
1060
1061 /*
1062  * Machine interface representation of a session rotation schedule.
1063  *
1064  * The machine interface serializes the provided schedule as one of the choices
1065  * from 'rotation_schedule_type'.
1066  *
1067  * writer: An instance of a machine interface writer.
1068  *
1069  * schedule: An lttng rotation schedule descriptor object.
1070  *
1071  * Returns zero if the element's value could be written.
1072  * Negative values indicate an error.
1073  */
1074 int mi_lttng_rotation_schedule(struct mi_writer *writer,
1075                 const struct lttng_rotation_schedule *schedule);
1076
1077 /*
1078  * Machine interface of a session rotation schedule result.
1079  * This is an element that is part of the output of the enable-rotation and
1080  * disable-rotation commands.
1081  *
1082  * The machine interface provides the following information:
1083  * - schedule: the session rotation schedule descriptor.
1084  * - success: whether the sub-command succeeded.
1085  *
1086  * writer: An instance of a machine interface writer.
1087  *
1088  * schedule: An lttng rotation schedule descriptor object.
1089  *
1090  * success: Whether the sub-command suceeded.
1091  *
1092  * Returns zero if the element's value could be written.
1093  * Negative values indicate an error.
1094  */
1095 int mi_lttng_rotation_schedule_result(struct mi_writer *writer,
1096                 const struct lttng_rotation_schedule *schedule,
1097                 bool success);
1098
1099 /*
1100  * Machine interface of a session rotation result.
1101  * This is an element that is part of the output of the rotate command.
1102  *
1103  * The machine interface provides the following information:
1104  * - session_name: the session to be rotated.
1105  * - state: the session rotation state.
1106  * - location: the location of the completed chunk archive.
1107  *
1108  * writer: An instance of a machine interface writer.
1109  *
1110  * session_name: The session to which the rotate command applies.
1111  *
1112  * location: A location descriptor object.
1113  *
1114  * success: Whether the sub-command suceeded.
1115  *
1116  * Returns zero if the element's value could be written.
1117  * Negative values indicate an error.
1118  */
1119 int mi_lttng_rotate(struct mi_writer *writer,
1120                 const char *session_name,
1121                 enum lttng_rotation_state rotation_state,
1122                 const struct lttng_trace_archive_location *location);
1123
1124 #if defined(__cplusplus)
1125 }
1126 #endif
1127
1128 #endif /* _MI_LTTNG_H */