HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |SYNOPSIS |DESCRIPTION |RETURN VALUE |EXAMPLE |FILES |SEE ALSO |AUTHOR |REPORTING BUGS |LICENSE |RESOURCES |COPYING |NOTES |COLOPHON | |
LIBTRACEFS(3) libtracefs ManualLIBTRACEFS(3)tracefs_instance_get_stat, tracefs_instance_put_stat, tracefs_buffer_stat_entries, tracefs_buffer_stat_overrun, tracefs_buffer_stat_commit_overrun, tracefs_buffer_stat_bytes, tracefs_buffer_stat_event_timestamp, tracefs_buffer_stat_timestamp, tracefs_buffer_stat_dropped_events, tracefs_buffer_stat_read_events - Handling tracing buffer stats
#include <tracefs.h> struct tracefs_buffer_stat *tracefs_instance_get_stat(struct tracefs_instance *instance, intcpu); voidtracefs_instance_put_stat(struct tracefs_buffer_stat *tstat); ssize_ttracefs_buffer_stat_entries(struct tracefs_buffer_stat *tstat); ssize_ttracefs_buffer_stat_overrun(struct tracefs_buffer_stat *tstat); ssize_ttracefs_buffer_stat_commit_overrun(struct tracefs_buffer_stat *tstat); ssize_ttracefs_buffer_stat_bytes(struct tracefs_buffer_stat *tstat); long longtracefs_buffer_stat_event_timestamp(struct tracefs_buffer_stat *tstat); long longtracefs_buffer_stat_timestamp(struct tracefs_buffer_stat *tstat); ssize_ttracefs_buffer_stat_dropped_events(struct tracefs_buffer_stat *tstat); ssize_ttracefs_buffer_stat_read_events(struct tracefs_buffer_stat *tstat);
This set of functions read and parse the tracefs/per_cpu/cpuX/stats file. These files hold the statistics of the per CPU ring buffer, such as how many events are in the ring buffer, how many have been read and so on. Thetracefs_instance_get_stat()function will read and parse a given statistics file for a giveninstance andcpu. As the ring buffer is split into per_cpu buffers, the information is only associated to the givencpu. The returned tracefs_buffer_stat pointer can be used with the othertracefs_buffer_statfunctions and must be freed withtracefs_instance_put_stat(). Thetracefs_instance_put_stat()will free the resources allocated for the givenstat that was created bytracefs_instance_get_stat(). Thetracefs_buffer_stat_entries()returns the number of events that are currently in the ring buffer associated withtstat. Thetracefs_buffer_stat_overrun()returns the number of events that were lost by the ring buffer writer overrunning the reader. Thetracefs_buffer_stat_commit_overrun()returns the number of events that were lost because the ring buffer was too small and an interrupt interrupted a lower context event being recorded and it added more events than the ring buffer could hold. Note this is not a common occurrence and when it happens it means that something was not set up properly. Thetracefs_buffer_stat_bytes()returns the number of bytes that the current events take up. Note, it includes the meta data for the events, but does not include the meta data for the sub-buffers. Thetracefs_buffer_stat_event_timestamp()returns the timestamp of the last event in the ring buffer. Thetracefs_buffer_stat_timestamp()returns the current timestamp of the ring buffer. Note, it is only read whentracefs_instance_get_stat()is called. It will have the timestamp of the ring buffer when that function was called. Thetracefs_buffer_stat_dropped_events()returns the number of events that were dropped if overwrite mode is disabled. It will show the events that were lost because the writer caught up to the reader and could not write any more events. Thetracefs_buffer_stat_read_events()returns the number of events that were consumed by a reader.
Thetracefs_instance_get_stat()returns a tracefs_buffer_stat structure that can be used to retrieve the statistics via the other functions. It must be freed withtracefs_instance_put_stat(). The other functions that return different values from the tracefs_buffer_stat structure all return the value, or -1 if the value was not found.
#include <stdlib.h> #include <unistd.h> #include <tracefs.h> int main(int argc, char **argv) { char *trace; char buf[1000]; int ret; int i; for (i = 0; i < sizeof(buf) - 1; i++) { buf[i] = '0' + i % 10; } buf[i] = '\0'; tracefs_instance_clear(NULL); for (i = 0; i < 4; i++) { ret = tracefs_printf(NULL, "%s\n", buf); if (ret < 0) perror("write"); } trace = tracefs_instance_file_read(NULL, "trace", NULL); printf("%s\n", trace); free(trace); for (i = 0; i < sysconf(_SC_NPROCESSORS_CONF); i++) { struct tracefs_buffer_stat *tstat; ssize_t entries, eread; tstat = tracefs_instance_get_stat(NULL, i); if (!tstat) continue; entries = tracefs_buffer_stat_entries(tstat); eread = tracefs_buffer_stat_read_events(tstat); if (!entries && !eread) { tracefs_instance_put_stat(tstat); continue; } printf("CPU: %d\n", i);; printf("\tentries: %zd\n", entries); printf("\toverrun: %zd\n", tracefs_buffer_stat_overrun(tstat)); printf("\tcommit_overrun: %zd\n", tracefs_buffer_stat_commit_overrun(tstat)); printf("\tbytes: %zd\n", tracefs_buffer_stat_bytes(tstat)); printf("\tevent_timestamp: %lld\n", tracefs_buffer_stat_event_timestamp(tstat)); printf("\ttimestamp: %lld\n", tracefs_buffer_stat_timestamp(tstat)); printf("\tdropped_events: %zd\n", tracefs_buffer_stat_dropped_events(tstat)); printf("\tread_events: %zd\n", eread); tracefs_instance_put_stat(tstat); } }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.
libtracefs(3),libtraceevent(3),trace-cmd(1)
Steven Rostedt<rostedt@goodmis.org[1]>
Report bugs to <linux-trace-devel@vger.kernel.org[2]>
libtracefs is Free Software licensed under the GNU LGPL 2.1
https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
Copyright (C) 2020 VMware, Inc. Free use of this software is granted under the terms of the GNU Public License (GPL).
1. rostedt@goodmis.org mailto:rostedt@goodmis.org 2. linux-trace-devel@vger.kernel.org mailto:linux-trace-devel@vger.kernel.org
This page is part of thelibtracefs (Linux kernel trace file system library) project. Information about the project can be found at ⟨https://www.trace-cmd.org/⟩. If you have a bug report for this manual page, see ⟨https://www.trace-cmd.org/⟩. This page was obtained from the project's upstream Git repository ⟨https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-06-02.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orglibtracefs 1.8.1 01/02/2025LIBTRACEFS(3)HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |