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