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