LIBTRACEFS(3)

📦
version 1.8.4 · 10 versions
, in arch rolling

💅 LIBTRACEFS(3) — the libtracefs manual page, bestie edition ✨

okay so this is a page straight out of the libtracefs manual, and it's all about handling tracing buffer stats 🎀 like, reading the per-CPU ring buffer tea. stay with me, it's honestly so good.

🦋 NAME 🦋

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 👑

✨ SYNOPSIS ✨

#include <tracefs.h>

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);

🌸 DESCRIPTION 🌸

okay so this whole little squad of functions reads and parses the tracefs/per_cpu/cpuX/stats file 📖. those files hold the statistics of the per CPU ring buffer — like how many events are chilling in the ring buffer, how many have been read, all that. it's giving receipts for your buffer, ngl.

tracefs_instance_get_stat() will read and parse a given statistics file for a given instance and cpu 🔍. and because the ring buffer is split into per_cpu buffers, the information is only associated with the given cpu. periodt. the returned tracefs_buffer_stat pointer can be used with the other tracefs_buffer_stat functions and must be freed with tracefs_instance_put_stat() — like, please don't leave it hanging 🙈.

tracefs_instance_put_stat() will free the resources allocated for the given stat that was created by tracefs_instance_get_stat() 🧹. cleanup queen behavior.

tracefs_buffer_stat_entries() returns the number of events that are currently in the ring buffer associated with tstat 📥.

tracefs_buffer_stat_overrun() returns the number of events that were lost by the ring buffer writer overrunning the reader 💀. yeah. the writer just ran straight past the reader and events got left behind.

tracefs_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 😭. > heads up bestie: this is not a common occurrence, and when it happens it means that something was not set up properly. so if you see this, go fix your setup, fr fr.

tracefs_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. important distinction, don't @ me.

tracefs_buffer_stat_event_timestamp() returns the timestamp of the last event in the ring buffer ⏰.

tracefs_buffer_stat_timestamp() returns the current timestamp of the ring buffer. note: it is only read when tracefs_instance_get_stat() is called 🫶. so it'll have the timestamp of the ring buffer when that function was called — it's a snapshot, not a live feed, iykyk.

tracefs_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.

tracefs_buffer_stat_read_events() returns the number of events that were consumed by a reader 👀.

🎀 RETURN VALUE 🎀

tracefs_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 with tracefs_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 🫠.

🔥 EXAMPLE 🔥

this is the whole main character demo right here, verbatim, no cap:

#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);
        }
}

🧚 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 💜

libtracefs(3), libtraceevent(3), trace-cmd(1) — go read those too, bestie, they're all part of the lore 🌈

👑 AUTHOR 👑

Steven Rostedt <rostedt@goodmis.org[1]> — the icon himself 🫶

💀 REPORTING BUGS 💀

report bugs to <linux-trace-devel@vger.kernel.org[2]> 🐛 — they actually wanna hear about it, so don't be shy.

⭐ LICENSE ⭐

libtracefs is Free Software licensed under the GNU LGPL 2.1 📜

🌈 RESOURCES 🌈

https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ — the source, go touch grass (the git kind) 🌱

🍓 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. linux-trace-devel@vger.kernel.org mailto:linux-trace-devel@vger.kernel.org

and that's the page!! 💅 this was libtracefs 1.8.4, dated 10/21/2026, and honestly she ate. go read your buffer stats, bestie — you're gonna slay 🎀✨🦋

📦 where this page comes from