LIBTRACEFS(3) libtracefs Manual LIBTRACEFS(3) NAME libtracefs - Linux kernel trace file system library SYNOPSIS #include Locations of tracing files and directories: char *tracefs_get_tracing_file(const char *name); void tracefs_put_tracing_file(char *name); const char *tracefs_tracing_dir(void); const char *tracefs_debug_dir(void); int tracefs_set_tracing_dir(char *tracing_dir) int tracefs_tracing_dir_is_mounted(bool mount, const char **path); Trace instances: struct tracefs_instance *tracefs_instance_create(const char *name); int tracefs_instance_destroy(struct tracefs_instance *instance); struct tracefs_instance *tracefs_instance_alloc(const char *tracing_dir, const char *name); void tracefs_instance_free(struct tracefs_instance *instance); char **tracefs_instances(const char *regex); void tracefs_instance_clear(struct tracefs_instance *instance); void tracefs_instance_reset(struct tracefs_instance *instance); bool tracefs_instance_is_new(struct tracefs_instance *instance); bool tracefs_file_exists(struct tracefs_instance *instance, char *name); bool tracefs_dir_exists(struct tracefs_instance *instance, char *name); char *tracefs_instance_get_file(struct tracefs_instance *instance, const char *file); char *tracefs_instance_get_dir(struct tracefs_instance *instance); int tracefs_instance_file_open(struct tracefs_instance *instance, const char *file, int mode); int tracefs_instance_file_write(struct tracefs_instance *instance, const char *file, const char *str); int tracefs_instance_file_write_number(struct tracefs_instance *instance, const char *file, size_t val); int tracefs_instance_file_append(struct tracefs_instance *instance, const char *file, const char *str); int tracefs_instance_file_clear(struct tracefs_instance *instance, const char *file); char *tracefs_instance_file_read(struct tracefs_instance *instance, const char *file, int *psize); int tracefs_instance_file_read_number(struct tracefs_instance *instance, const char *file, long long int *res); const char *tracefs_instance_get_name(struct tracefs_instance *instance); const char *tracefs_instance_get_trace_dir(struct tracefs_instance *instance); int tracefs_instances_walk(int (*callback)(const char *, void *), void *context); bool tracefs_instance_exists(const char *name); int tracefs_instance_set_affinity(struct tracefs_instance *instance, const char *cpu_str); int tracefs_instance_set_affinity_set(struct tracefs_instance *instance, cpu_set_t *set, size_t set_size); int tracefs_instance_set_affinity_raw(struct tracefs_instance *instance, const char *mask); char *tracefs_instance_get_affinity(struct tracefs_instance *instance); int tracefs_instance_get_affinity_set(struct tracefs_instance *instance, cpu_set_t *set, size_t set_size); char *tracefs_instance_get_affinity_raw(struct tracefs_instance *instance); size_t tracefs_instance_get_buffer_size(struct tracefs_instance *instance, int cpu); int tracefs_instance_set_buffer_size(struct tracefs_instance *instance, size_t size, int cpu); int tracefs_instance_get_buffer_percent(struct tracefs_instance *instance); int tracefs_instance_set_buffer_percent(struct tracefs_instance *instance, int val); Trace events: char **tracefs_event_systems(const char *tracing_dir); char **tracefs_system_events(const char *tracing_dir, const char *system); int tracefs_event_enable(struct tracefs_instance *instance, const char *system, const char *event); int tracefs_event_disable(struct tracefs_instance *instance, const char *system, const char *event); enum tracefs_enable_state tracefs_event_is_enabled(struct tracefs_instance *instance, const char *system, const char *event); int tracefs_iterate_raw_events(struct tep_handle *tep, struct tracefs_instance *instance, cpu_set_t *cpus, int cpu_size, int (*callback)(struct tep_event *, struct tep_record *, int, void *), void *callback_context); void tracefs_iterate_stop(struct tracefs_instance *instance); int tracefs_follow_event(struct tep_handle *tep, struct tracefs_instance *instance, const char *system, const char *event_name, int (*callback)(struct tep_event *, struct tep_record *, int, void *), void *callback_data); int tracefs_follow_missed_events(struct tracefs_instance *instance, int (*callback)(struct tep_event *, struct tep_record *, int, void *), void *callback_data); int tracefs_follow_event_clear(struct tracefs_instance *instance, const char *system, const char *event_name); int tracefs_follow_missed_events_clear(struct tracefs_instance *instance); struct tep_handle *tracefs_local_events(const char *tracing_dir); struct tep_handle *tracefs_local_events_system(const char *tracing_dir, const char * const *sys_names); int tracefs_fill_local_events(const char *tracing_dir, struct tep_handle *tep, int *parsing_failures); int tracefs_load_cmdlines(const char *tracing_dir, struct tep_handle *tep); int tracefs_load_headers(const char *tracing_dir, struct tep_handle *tep); char *tracefs_event_get_file(struct tracefs_instance *instance, const char *system, const char *event, const char *file); char *tracefs_event_file_read(struct tracefs_instance *instance, const char *system, const char *event, const char *file, int *psize); int tracefs_event_file_write(struct tracefs_instance *instance, const char *system, const char *event, const char *file, const char *str); int tracefs_event_file_append(struct tracefs_instance *instance, const char *system, const char *event, const char *file, const char *str); int tracefs_event_file_clear(struct tracefs_instance *instance, const char *system, const char *event, const char *file); bool tracefs_event_file_exists(struct tracefs_instance *instance, const char *system, const char *event, const char *file); Snapshot buffer: int tracefs_snapshot_snap(struct tracefs_instance *instance); int tracefs_snapshot_clear(struct tracefs_instance *instance); int tracefs_snapshot_free(struct tracefs_instance *instance); int tracefs_iterate_snapshot_events(struct tep_handle *tep, struct tracefs_instance *instance, cpu_set_t *cpus, int cpu_size, int (*callback)(struct tep_event *, struct tep_record *, int, void *), void *callback_context); struct tracefs_cpu *tracefs_cpu_snapshot_open(struct tracefs_instance *instance, int cpu, bool nonblock); Event filters: int tracefs_filter_string_append(struct tep_event *event, char **filter, struct tracefs_filter type, const char *field, enum tracefs_synth_compare compare, const char *val); int tracefs_filter_string_verify(struct tep_event *event, const char *filter, char **err); int tracefs_event_filter_apply(struct tracefs_instance *instance, struct tep_event *event, const char *filter); int tracefs_event_filter_clear(struct tracefs_instance *instance, struct tep_event *event); Function filters: int tracefs_function_filter(struct tracefs_instance *instance, const char *filter, const char *module, int flags); int tracefs_function_notrace(struct tracefs_instance *instance, const char *filter, const char *module, int flags); int tracefs_filter_functions(const char *filter, const char *module, char ***list); PID filters: int tracefs_filter_pid_function(struct tracefs_instance *instance, int pid, bool reset, bool notrace); int tracefs_filter_pid_function_clear(struct tracefs_instance *instance, bool notrace); int tracefs_filter_pid_events(struct tracefs_instance *instance, int pid, bool reset, bool notrace); int tracefs_filter_pid_events_clear(struct tracefs_instance *instance, bool notrace); Trace helper functions: void tracefs_list_free(char **list); char **tracefs_list_add(char *list, const char *string); int *tracefs_list_size(char **list); char *tracefs_get_clock(struct tracefs_instance *instance); int tracefs_trace_is_on(struct tracefs_instance *instance); int tracefs_trace_on(struct tracefs_instance *instance); int tracefs_trace_off(struct tracefs_instance *instance); int tracefs_trace_on_get_fd(struct tracefs_instance *instance); int tracefs_trace_on_fd(int fd); int tracefs_trace_off_fd(int fd); Trace stream: ssize_t tracefs_trace_pipe_stream(int fd, struct tracefs_instance *instance, int flags); ssize_t tracefs_trace_pipe_print(struct tracefs_instance *instance, int flags); void tracefs_trace_pipe_stop(struct tracefs_instance *instance); Memory mapping the ring buffer: bool tracefs_cpu_is_mapped(struct tracefs_cpu *tcpu); bool tracefs_mapped_is_supported(void); int tracefs_cpu_map(struct tracefs_cpu *tcpu); void tracefs_cpu_unmap(struct tracefs_cpu *tcpu); struct tracefs_cpu *tracefs_cpu_open_mapped(struct tracefs_instance *instance, int cpu, bool nonblock); Trace options: const struct tracefs_options_mask *tracefs_options_get_supported(struct tracefs_instance *instance); bool tracefs_option_is_supported(struct tracefs_instance *instance, enum tracefs_option_id id); const struct tracefs_options_mask *tracefs_options_get_enabled(struct tracefs_instance *instance); bool tracefs_option_is_enabled(struct tracefs_instance *instance, enum tracefs_option_id id); bool tracefs_option_mask_is_set(const struct tracefs_options_mask options, enum tracefs_option_id id); int *tracefs_option_enable(struct tracefs_instance *instance, enum tracefs_option_id id); int tracefs_option_disable(struct tracefs_instance *instance, enum tracefs_option_id id); const char *tracefs_option_name(enum tracefs_option_id id); enum tracefs_option_id tracefs_option_id(const char *name); Ftrace tracers: char **tracefs_tracers(const char *tracing_dir); char ** tracefs_instance_tracers(struct tracefs_instance *instance); bool tracefs_tracer_available(const char *tracing_dir, const char *tracer); int tracefs_tracer_set(struct tracefs_instance *instance, enum tracefs_tracers tracer); int tracefs_tracer_set(struct tracefs_instance *instance, enum tracefs_tracers tracer, const char *name); int tracefs_tracer_clear(struct tracefs_instance *instance); Writing data in the trace buffer: int tracefs_print_init(struct tracefs_instance *instance); int tracefs_printf(struct tracefs_instance *instance, const char *fmt, ...); int tracefs_vprintf(struct tracefs_instance *instance, const char *fmt, va_list ap); void tracefs_print_close(struct tracefs_instance *instance); int tracefs_binary_init(struct tracefs_instance *instance); int tracefs_binary_write(struct tracefs_instance *instance, void *data, int len); void tracefs_binary_close(struct tracefs_instance *instance); Control library logs: int tracefs_set_loglevel(enum tep_loglevel level); Read the ring buffer statistics: struct tracefs_buffer_stat *tracefs_instance_get_stat(struct tracefs_instance *instance, int cpu); void tracefs_instance_put_stat(struct tracefs_buffer_stat *tstat); ssize_t tracefs_buffer_stat_entries(struct tracefs_buffer_stat *tstat); ssize_t tracefs_buffer_stat_overrun(struct tracefs_buffer_stat *tstat); ssize_t tracefs_buffer_stat_commit_overrun(struct tracefs_buffer_stat *tstat); ssize_t tracefs_buffer_stat_bytes(struct tracefs_buffer_stat *tstat); long long tracefs_buffer_stat_event_timestamp(struct tracefs_buffer_stat *tstat); long long tracefs_buffer_stat_timestamp(struct tracefs_buffer_stat *tstat); ssize_t tracefs_buffer_stat_dropped_events(struct tracefs_buffer_stat *tstat); ssize_t tracefs_buffer_stat_read_events(struct tracefs_buffer_stat *tstat); Dynamic event generic APIs: struct tracefs_dynevent; enum tracefs_dynevent_type; int tracefs_dynevent_create(struct tracefs_dynevent *devent); int tracefs_dynevent_destroy(struct tracefs_dynevent *devent, bool force); int tracefs_dynevent_destroy_all(unsigned int types, bool force); void tracefs_dynevent_free(struct tracefs_dynevent *devent); void tracefs_dynevent_list_free(struct tracefs_dynevent **events); struct tracefs_dynevent *tracefs_dynevent_get(enum tracefs_dynevent_type type, const char *system, const char *event); struct tracefs_dynevent **tracefs_dynevent_get_all(unsigned int types, const char *system); enum tracefs_dynevent_type tracefs_dynevent_info(struct tracefs_dynevent *dynevent, char **system, char **event, char **prefix, char **addr, char **format); struct tep_event *tracefs_dynevent_get_event(struct tep_handle *tep, struct tracefs_dynevent *dynevent); Even probes (eprobes): struct tracefs_dynevent * tracefs_eprobe_alloc(const char *system, const char *event, const char *target_system, const char *target_event, const char *fetchargs); Uprobes, Kprobes and Kretprobes: struct tracefs_dynevent * tracefs_kprobe_alloc(const char *system, const char *event, const char *addr, const char *format); struct tracefs_dynevent * tracefs_kretprobe_alloc(const char *system, const char *event, const char *addr, const char *format, unsigned int max); int tracefs_kprobe_raw(const char *system, const char *event, const char *addr, const char *format); int tracefs_kretprobe_raw(const char *system, const char *event, const char *addr, const char *format); tracefs_uprobe_alloc(const char *system, const char *event, const char *file, unsigned long long offset, const char *fetchargs) tracefs_uretprobe_alloc(const char *system, const char *event, const char *file, unsigned long long offset, const char *fetchargs); int tracefs_kprobe_destroy(const char *system, const char *event, const char *addr, const char *format, bool force); Synthetic events: struct tracefs_synth *tracefs_sql(struct tep_handle *tep, const char *name, const char *sql_buffer, char **err); struct tracefs_synth *tracefs_synth_alloc(struct tep_handle *tep, const char *name, const char *start_system, const char *start_event, const char *end_system, const char *end_event, const char *start_match_field, const char *end_match_field, const char *match_name); int tracefs_synth_add_match_field(struct tracefs_synth *synth, const char *start_match_field, const char *end_match_field, const char *name); int tracefs_synth_add_compare_field(struct tracefs_synth *synth, const char *start_compare_field, const char *end_compare_field, enum tracefs_synth_calc calc, const char *name); int tracefs_synth_add_start_field(struct tracefs_synth *synth, const char *start_field, const char *name); int tracefs_synth_add_end_field(struct tracefs_synth *synth, const char *end_field, const char *name); int tracefs_synth_append_start_filter(struct tracefs_synth *synth, struct tracefs_filter type, const char *field, enum tracefs_synth_compare compare, const char *val); int tracefs_synth_append_end_filter(struct tracefs_synth *synth, struct tracefs_filter type, const char *field, enum tracefs_synth_compare compare, const char *val); void tracefs_synth_free(struct tracefs_synth *synth); int tracefs_synth_create(struct tracefs_synth *synth); int tracefs_synth_destroy(struct tracefs_synth *synth); int tracefs_synth_set_instance(struct tracefs_synth *synth, struct tracefs_instance *instance); int tracefs_synth_echo_cmd(struct trace_seq *seq, struct tracefs_synth *synth); bool tracefs_synth_complete(struct tracefs_synth *synth); struct tracefs_hist *tracefs_synth_get_start_hist(struct tracefs_synth *synth); int tracefs_synth_trace(struct tracefs_synth *synth, enum tracefs_synth_handler type, const char *var); int tracefs_synth_snapshot(struct tracefs_synth *synth, enum tracefs_synth_handler type, const char *var); int tracefs_synth_save(struct tracefs_synth *synth, enum tracefs_synth_handler type, const char *var, char **save_fields); const char *tracefs_synth_get_name(struct tracefs_synth *synth); int tracefs_synth_raw_fmt(struct trace_seq *seq, struct tracefs_synth *synth); const char *tracefs_synth_show_event(struct tracefs_synth *synth); const char *tracefs_synth_show_start_hist(struct tracefs_synth *synth); const char *tracefs_synth_show_end_hist(struct tracefs_synth *synth); struct tep_event *tracefs_synth_get_event(struct tep_handle *tep, struct tracefs_synth *synth); Ftrace errors reporting: char *tracefs_error_last(struct tracefs_instance *instance); char *tracefs_error_all(struct tracefs_instance *instance); int tracefs_error_clear(struct tracefs_instance *instance); Histograms: struct tracefs_hist *tracefs_hist_alloc(struct tracefs_tep * tep, const char *system, const char *event, const char *key, enum tracefs_hist_key_type type); struct tracefs_hist *tracefs_hist_alloc_2d(struct tracefs_tep * tep, const char *system, const char *event, const char *key1, enum tracefs_hist_key_type type1, const char *key2, enum tracefs_hist_key_type type2)); struct tracefs_hist *tracefs_hist_alloc_nd(struct tracefs_tep * tep, const char *system, const char *event, struct tracefs_hist_axis *axes); struct tracefs_hist *tracefs_hist_alloc_nd_cnt(struct tep_handle *tep, const char *system, const char *event_name, struct tracefs_hist_axis_cnt *axes); void tracefs_hist_free(struct tracefs_hist *hist); int tracefs_hist_add_key(struct tracefs_hist *hist, const char *key, enum tracefs_hist_key_type type); int tracefs_hist_add_key_cnt(struct tracefs_hist *hist, const char *key, enum tracefs_hist_key_type type, int cnt); int tracefs_hist_add_value(struct tracefs_hist *hist, const char *value); int tracefs_hist_add_sort_key(struct tracefs_hist *hist, const char *sort_key); int tracefs_hist_set_sort_key(struct tracefs_hist *hist, const char *sort_key, ...); int tracefs_hist_sort_key_direction(struct tracefs_hist *hist, const char *sort_key, enum tracefs_hist_sort_direction dir); int tracefs_hist_add_name(struct tracefs_hist *hist, const char *name); int tracefs_hist_append_filter(struct tracefs_hist *hist, enum tracefs_filter type, const char *field, enum tracefs_compare compare, const char *val); int tracefs_hist_echo_cmd(struct trace_seq *s, struct tracefs_instance *instance, struct tracefs_hist *hist, enum tracefs_hist_command command); int tracefs_hist_command(struct tracefs_instance *instance, struct tracefs_hist *hist, enum tracefs_hist_command command); const char *tracefs_hist_get_name(struct tracefs_hist *hist); const char *tracefs_hist_get_event(struct tracefs_hist *hist); const char *tracefs_hist_get_system(struct tracefs_hist *hist); int tracefs_hist_start(struct tracefs_instance *instance, struct tracefs_hist *hist); int tracefs_hist_destroy(struct tracefs_instance *instance, struct tracefs_hist *hist); int tracefs_hist_pause(struct tracefs_instance *instance, struct tracefs_hist *hist); int tracefs_hist_continue(struct tracefs_instance *instance, struct tracefs_hist *hist); int tracefs_hist_reset(struct tracefs_instance *instance, struct tracefs_hist *hist); Recording of trace_pipe_raw files: struct tracefs_cpu *tracefs_cpu_open(struct tracefs_instance *instance, int cpu, bool nonblock); struct tracefs_cpu *tracefs_cpu_alloc_fd(int fd, int subbuf_size, bool nonblock); void tracefs_cpu_close(struct tracefs_cpu *tcpu); void tracefs_cpu_free_fd(struct tracefs_cpu *tcpu); int tracefs_cpu_read_size(struct tracefs_cpu *tcpu); int tracefs_cpu_read(struct tracefs_cpu *tcpu, void *buffer, bool nonblock); int tracefs_cpu_buffered_read(struct tracefs_cpu *tcpu, void *buffer, bool nonblock); int tracefs_cpu_write(struct tracefs_cpu *tcpu, int wfd, bool nonblock); int tracefs_cpu_stop(struct tracefs_cpu *tcpu); int tracefs_cpu_flush(struct tracefs_cpu *tcpu, void *buffer); int tracefs_cpu_flush_write(struct tracefs_cpu *tcpu, int wfd); int tracefs_cpu_pipe(struct tracefs_cpu *tcpu, int wfd, bool nonblock); struct kbuffer *tracefs_cpu_read_buf(struct tracefs_cpu *tcpu, bool nonblock); struct kbuffer *tracefs_cpu_buffered_read_buf(struct tracefs_cpu *tcpu, bool nonblock); struct kbuffer *tracefs_cpu_flush_buf(struct tracefs_cpu *tcpu); Helper functions for modifying the ring buffer sub-buffers: size_t tracefs_instance_get_subbuf_size(struct tracefs_instance *instance); int tracefs_instance_set_subbuf_size(struct tracefs_instance *instance, size_t size); Helper functions for guest tracing: char *tracefs_find_cid_pid(int cid); char *tracefs_instance_find_cid_pid(struct tracefs_instance *instance, int cid); int tracefs_time_conversion(int cpu, int *shift, int *multi, long long *offset); DESCRIPTION The libtracefs(3) library provides APIs to access kernel trace file system. FILES tracefs.h Header file to include in order to have access to the library APIs. -ltracefs Linker switch to add when building a program that uses the library. SEE ALSO libtraceevent(3), trace-cmd(1) AUTHOR Steven Rostedt Tzvetomir Stoyanov REPORTING BUGS Report bugs to LICENSE libtracefs is Free Software licensed under the GNU LGPL 2.1 RESOURCES https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ COPYING Copyright (C) 2020 VMware, Inc. Free use of this software is granted under the terms of the GNU Public License (GPL). NOTES 1. rostedt@goodmis.org mailto:rostedt@goodmis.org 2. tz.stoyanov@gmail.com mailto:tz.stoyanov@gmail.com 3. linux-trace-devel@vger.kernel.org mailto:linux-trace-devel@vger.kernel.org libtracefs 1.8.0 01/13/2024 LIBTRACEFS(3)