1libtracefs(3) 2============= 3 4NAME 5---- 6tracefs_instance_get_stat, tracefs_instance_put_stat, tracefs_buffer_stat_entries, tracefs_buffer_stat_overrun, 7tracefs_buffer_stat_commit_overrun, tracefs_buffer_stat_bytes, tracefs_buffer_stat_event_timestamp, 8tracefs_buffer_stat_timestamp, tracefs_buffer_stat_dropped_events, tracefs_buffer_stat_read_events 9- Handling tracing buffer stats 10 11SYNOPSIS 12-------- 13[verse] 14-- 15*#include <tracefs.h>* 16 17struct tracefs_buffer_stat pass:[*]*tracefs_instance_get_stat*(struct tracefs_instance pass:[*]_instance_, int _cpu_); 18void *tracefs_instance_put_stat*(struct tracefs_buffer_stat pass:[*]_tstat_); 19ssize_t *tracefs_buffer_stat_entries*(struct tracefs_buffer_stat pass:[*]_tstat_); 20ssize_t *tracefs_buffer_stat_overrun*(struct tracefs_buffer_stat pass:[*]_tstat_); 21ssize_t *tracefs_buffer_stat_commit_overrun*(struct tracefs_buffer_stat pass:[*]_tstat_); 22ssize_t *tracefs_buffer_stat_bytes*(struct tracefs_buffer_stat pass:[*]_tstat_); 23long long *tracefs_buffer_stat_event_timestamp*(struct tracefs_buffer_stat pass:[*]_tstat_); 24long long *tracefs_buffer_stat_timestamp*(struct tracefs_buffer_stat pass:[*]_tstat_); 25ssize_t *tracefs_buffer_stat_dropped_events*(struct tracefs_buffer_stat pass:[*]_tstat_); 26ssize_t *tracefs_buffer_stat_read_events*(struct tracefs_buffer_stat pass:[*]_tstat_); 27-- 28 29DESCRIPTION 30----------- 31This set of functions read and parse the tracefs/per_cpu/cpuX/stats file. 32These files hold the statistics of the per CPU ring buffer, such as how 33many events are in the ring buffer, how many have been read and so on. 34 35The *tracefs_instance_get_stat()* function will read and parse a given statistics 36file for a given _instance_ and _cpu_. As the ring buffer is split into per_cpu buffers, 37the information is only associated to the given _cpu_. The returned tracefs_buffer_stat 38pointer can be used with the other *tracefs_buffer_stat* functions and must be freed with 39*tracefs_instance_put_stat()*. 40 41The *tracefs_instance_put_stat()* will free the resources allocated for the given _stat_ 42that was created by *tracefs_instance_get_stat()*. 43 44The *tracefs_buffer_stat_entries()* returns the number of events that are currently 45in the ring buffer associated with _tstat_. 46 47The *tracefs_buffer_stat_overrun()* returns the number of events that were lost by 48the ring buffer writer overrunning the reader. 49 50The *tracefs_buffer_stat_commit_overrun()* returns the number of events that were 51lost because the ring buffer was too small and an interrupt interrupted a lower 52context event being recorded and it added more events than the ring buffer could 53hold. Note this is not a common occurrence and when it happens it means that 54something was not set up properly. 55 56The *tracefs_buffer_stat_bytes()* returns the number of bytes that the current events 57take up. Note, it includes the meta data for the events, but does not include the 58meta data for the sub-buffers. 59 60The *tracefs_buffer_stat_event_timestamp()* returns the timestamp of the last event in the 61ring buffer. 62 63The *tracefs_buffer_stat_timestamp()* returns the current timestamp of the ring buffer. 64Note, it is only read when *tracefs_instance_get_stat()* is called. It will have the 65timestamp of the ring buffer when that function was called. 66 67The *tracefs_buffer_stat_dropped_events()* returns the number of events that were 68dropped if overwrite mode is disabled. It will show the events that were lost because 69the writer caught up to the reader and could not write any more events. 70 71The *tracefs_buffer_stat_read_events()* returns the number of events that were consumed 72by a reader. 73 74 75RETURN VALUE 76------------ 77The *tracefs_instance_get_stat()* returns a tracefs_buffer_stat structure that can 78be used to retrieve the statistics via the other functions. It must be freed with 79*tracefs_instance_put_stat()*. 80 81The other functions that return different values from the tracefs_buffer_stat structure 82all return the value, or -1 if the value was not found. 83 84 85EXAMPLE 86------- 87[source,c] 88-- 89#include <stdlib.h> 90#include <unistd.h> 91#include <tracefs.h> 92 93int main(int argc, char **argv) 94{ 95 char *trace; 96 char buf[1000]; 97 int ret; 98 int i; 99 100 for (i = 0; i < sizeof(buf) - 1; i++) { 101 buf[i] = '0' + i % 10; 102 } 103 buf[i] = '\0'; 104 105 tracefs_instance_clear(NULL); 106 107 for (i = 0; i < 4; i++) { 108 ret = tracefs_printf(NULL, "%s\n", buf); 109 if (ret < 0) 110 perror("write"); 111 } 112 113 trace = tracefs_instance_file_read(NULL, "trace", NULL); 114 printf("%s\n", trace); 115 free(trace); 116 117 for (i = 0; i < sysconf(_SC_NPROCESSORS_CONF); i++) { 118 struct tracefs_buffer_stat *tstat; 119 ssize_t entries, eread; 120 121 tstat = tracefs_instance_get_stat(NULL, i); 122 if (!tstat) 123 continue; 124 125 entries = tracefs_buffer_stat_entries(tstat); 126 eread = tracefs_buffer_stat_read_events(tstat); 127 if (!entries && !eread) { 128 tracefs_instance_put_stat(tstat); 129 continue; 130 } 131 132 printf("CPU: %d\n", i);; 133 printf("\tentries: %zd\n", entries); 134 printf("\toverrun: %zd\n", tracefs_buffer_stat_overrun(tstat)); 135 printf("\tcommit_overrun: %zd\n", tracefs_buffer_stat_commit_overrun(tstat)); 136 printf("\tbytes: %zd\n", tracefs_buffer_stat_bytes(tstat)); 137 printf("\tevent_timestamp: %lld\n", tracefs_buffer_stat_event_timestamp(tstat)); 138 printf("\ttimestamp: %lld\n", tracefs_buffer_stat_timestamp(tstat)); 139 printf("\tdropped_events: %zd\n", tracefs_buffer_stat_dropped_events(tstat)); 140 printf("\tread_events: %zd\n", eread); 141 142 tracefs_instance_put_stat(tstat); 143 } 144} 145-- 146FILES 147----- 148[verse] 149-- 150*tracefs.h* 151 Header file to include in order to have access to the library APIs. 152*-ltracefs* 153 Linker switch to add when building a program that uses the library. 154-- 155 156SEE ALSO 157-------- 158*libtracefs*(3), 159*libtraceevent*(3), 160*trace-cmd*(1) 161 162AUTHOR 163------ 164[verse] 165-- 166*Steven Rostedt* <rostedt@goodmis.org> 167-- 168REPORTING BUGS 169-------------- 170Report bugs to <linux-trace-devel@vger.kernel.org> 171 172LICENSE 173------- 174libtracefs is Free Software licensed under the GNU LGPL 2.1 175 176RESOURCES 177--------- 178https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ 179 180COPYING 181------- 182Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under 183the terms of the GNU Public License (GPL). 184