src/common/mi-lttng.h

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