src/common/mi-lttng.hpp

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