LIBTRACEFS(3)

📦
version 1.8.4 · 12 versions
, in arch rolling

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

okay so real quick: this is a page from the libtracefs manual, and it's literally all about turning tracers on and off — either in a specific instance or at the top level. no cap, it's more fun than it sounds. ✨

🌸 NAME 🌸

tracefs_instance_tracers, tracefs_tracer_set, tracefs_tracer_clear — enable or disable a tracer in an instance or the top level. that's the whole vibe 🦋

✨ SYNOPSIS ✨

#include <tracefs.h>

char ** tracefs_instance_tracers(struct tracefs_instance *instance);
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);

yes there are two tracefs_tracer_set signatures up there — that's not a typo, it's giving overloaded-girlie energy 👑

💖 DESCRIPTION 💖

tracefs_instance_tracers</p> hands you back a list of the tracers that are available for a given instance. heads up though — an instance might not have the same set of available tracers as the top level, so don't assume, okay? 🙈 if instance is NULL, then the list of available tracers you get back is for the top level. easy.

tracefs_tracer_set</p> enables a tracer in the given instance, defined by the instance parameter. if instance is NULL, the top level instance is what gets changed. and if tracer is set to TRACFES_TRACER_CUSTOM then you must pass a name string in as the third parameter, and that string gets written into the instance to enable the tracer with that name. this one's for the newer or custom kernels that have tracers the tracefs_tracers enum hasn't identified yet — main character tracers that haven't been introduced to the group chat 💅

tracefs_tracer_clear</p> disables the tracer for the given instance defined by the instance variable, or the top level instance if it's NULL. it's literally the same as calling tracefs_tracer_set with TRACEFS_TRACER_NOP as the tracer parameter. same thing, cuter name 🎀

🔥 TRACEFS_TRACER ENUMS 🔥

the currently defined enums that are accepted are, bestie, as follows:

  • TRACEFS_TRACER_NOP — this is the idle tracer. it does nothing and is used to clear any active tracer. the "no thoughts, head empty" of tracers 😌
  • TRACEFS_TRACER_FUNCTION — enables most functions in the kernel to be traced.
  • TRACEFS_TRACER_FUNCTION_GRAPH — enables most functions in the kernel to be traced, and also the return of the function. matching set, slay.
  • TRACEFS_TRACER_IRQSOFF — tracers the latency of interrupts disabled.
  • TRACEFS_TRACER_PREEMPTOFF — tracers the latency of preemption disabled (that's the time in the kernel that tasks can not be scheduled from the CPU).
  • TRACEFS_TRACER_PREEMPTIRQSOFF — traces the combined total latency of when interrupts are disabled as well as when preemption is disabled. combo deal 💜
  • TRACEFS_TRACER_WAKEUP — traces the latency of when the highest priority task takes to wake up.
  • TRACEFS_TRACER_WAKEUP_RT — traces the latency of when the highest priority real-time task takes to wake up. all other tasks are ignored, sorry to them 💀
  • TRACEFS_TRACER_WAKEUP_DL — traces the latency of when the highest priority DEADLINE task takes to wake up. all other tasks are ignored too. rude but valid.
  • TRACEFS_TRACER_MMIOTRACE — traces the interaction of devices with the kernel.
  • TRACEFS_TRACER_HWLAT — detects latency caused by the hardware that is outside the scope of the kernel.
  • TRACEFS_TRACER_BRANCH — traces when likely or unlikely branches are taken.
  • TRACEFS_TRACER_BLOCK — special tracer for the block devices. special girlie 💅
⚠️ heads up: the above tracers may not be available in the kernel! and tracefs_tracer_set() will return an error with errno set to ENODEV if the kernel doesn't support the tracer option — or the custom one if TRACEFS_TRACER_CUSTOM is used. so yeah, vibe check your kernel first, fr fr 😭

🫶 RETURN VALUE 🫶

returns 0 on success, or -1 on error. short and sweet, periodt.

🌈 ERRORS 🌈

tracefs_tracer_set() can fail with the following errors:

  • EINVAL — the tracer parameter is outside the scope of what is defined. not a real tracer, babe.
  • ENOMEM — memory allocation error.
  • ENOENT — tracers are not supported on the running kernel. 💀
  • ENODEV — the specified tracer is not supported on the running kernel.

other errors may also happen, caused by internal system calls — not us, it's the system calls 🙈

🌟 EXAMPLE 🌟

okay this is the whole thing, and yes it's a full program, and yes it ATE:

#include <stdlib.h>
#include <stdio.h>
#include <getopt.h>
#include <errno.h>
#include <tracefs.h>

int main(int argc, char *argv[])
{
    struct tracefs_instance *inst = NULL;
    enum tracefs_tracers t = TRACEFS_TRACER_NOP;
    const char *cust = NULL;
    const char *buf = NULL;
    char **tracers;
    int ret;
    int ch;
    int i;

    while ((ch = getopt(argc, argv, "nfgiwdc:B:")) > 0) {
        switch (ch) {
        case 'f': t = TRACEFS_TRACER_FUNCTION; break;
        case 'g': t = TRACEFS_TRACER_FUNCTION_GRAPH; break;
        case 'i': t = TRACEFS_TRACER_PREEMPTIRQSOFF; break;
        case 'w': t = TRACEFS_TRACER_WAKEUP_RT; break;
        case 'd': t = TRACEFS_TRACER_WAKEUP_DL; break;
        case 'c':
            t = TRACEFS_TRACER_CUSTOM;
            cust = optarg;
            break;
        case 'B':
            buf = optarg;
            break;
        case 'n':
            /* nop */
            break;
        default:
            printf("Unknow arg %c\n", ch);
            exit(-1);
        }
    }

    if (buf) {
        inst = tracefs_instance_create(buf);
        if (!inst) {
            printf("failed to create instance\n");
            exit(-1);
        }
    }

    if (t == TRACEFS_TRACER_CUSTOM)
        ret = tracefs_tracer_set(inst, t, cust);
    else
        ret = tracefs_tracer_set(inst, t);

    if (ret < 0) {
        if (errno == ENODEV) {
            if (cust)
                printf("Tracer '%s' not supported by kernel\n", cust);
            else
                printf("Tracer not supported by kernel\n");
            tracers = tracefs_instance_tracers(inst);
            printf("Available tracers:");
            for (i = 0; tracers && tracers[i]; i++)
                printf(" %s", tracers[i]);
            tracefs_list_free(tracers);
            printf("\n");
        } else
            perror("Error");
        if (inst) {
            tracefs_instance_destroy(inst);
            tracefs_instance_free(inst);
        }
        exit(-1);
    }

    tracefs_instance_free(inst);

    exit(0);
}

🎀 FILES 🎀

  • tracefs.h — header file to include in order to have access to the library APIs. include her or you get nothing 💅
  • -ltracefs — linker switch to add when building a program that uses the library. don't forget her!!

🦋 SEE ALSO 🦋

libtracefs(3), libtraceevent(3), trace-cmd(1) — go read those too, iykyk 📚

👑 AUTHOR 👑

  • Steven Rostedt <rostedt@goodmis.org<sup>1</sup>>
  • Tzvetomir Stoyanov <tz.stoyanov@gmail.com<sup>2</sup>>
  • sameeruddin shaik <sameeruddin.shaik8@gmail.com<sup>3</sup>>

legends, honestly 🫶

💀 REPORTING BUGS 💀

report bugs to <linux-trace-devel@vger.kernel.org<sup>4</sup>>. be nice about it pls 🙏

💜 LICENSE 💜

libtracefs is Free Software licensed under the GNU LGPL 2.1.

⭐ RESOURCES ⭐

https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ — go snoop 🧚

🌸 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. sameeruddin.shaik8@gmail.com — mailto:sameeruddin.shaik8@gmail.com
  4. linux-trace-devel@vger.kernel.org — mailto:linux-trace-devel@vger.kernel.org
✨ that's the whole page bestie! this was libtracefs 1.8.4, dated 10/21/2026 — screenshot it, cite it, cite me, whatever, just don't @ me. love u, go trace something iconic 💖🎀🦋
📦 where this page comes from