LIBTRACECMD(3)

📦
version 3.4 · 14 versions
, in arch rolling

🦋 LIBTRACECMD(3) — the libtracefs manual, bestie edition 🦋

okay so real quick — this is a page from the libtracefs Manual, and it's about the two little functions that let you manage a trace session with multiple trace peers recorded across multiple trace files. host + guests, you know the vibe 💅

✨ NAME ✨

tracecmd_get_traceid, tracecmd_get_guest_cpumap — manage a trace session with multiple trace peers, recorded in multiple trace files. that's the whole thing, no cap 🫶

🌸 SYNOPSIS 🌸

#include <trace-cmd.h>

unsigned long long tracecmd_get_traceid(struct tracecmd_input *handle);
int tracecmd_get_guest_cpumap(struct tracecmd_input *handle, unsigned long long trace_id, const char **name, int *vcpu_count, const int **cpu_pid);

💖 DESCRIPTION 💖

so this little set of APIs is literally for managing a trace session with multiple trace peers — like, imagine you're tracing a host and one or more guest virtual machines at the same time. iconic scenario, honestly. the trace data of each peer from the session gets recorded in separate trace files. and the info about those peers from the session? that's stored in the metadata of each trace file. these APIs use that info to extract and synchronize the trace data. slay 🔥

🎀 tracecmd_get_traceid()

this one returns the trace ID stored in the trace file metadata associated with handle. every peer from a trace session has an ID that's unique — but only for that peer and that trace session, okay? don't go thinking it's universal. this ID is what you use to match multiple trace files recorded in the same trace session. iykyk ⭐

🦋 tracecmd_get_guest_cpumap()

this one gets the mapping of guest virtual CPUs (VCPU) to the host process that represents those VCPUs, and it's stored in the metadata of the trace file associated with handle. this info gets gathered during a host-guest trace session and stored in the host trace file.

the trace_id parameter is the trace ID of the guest in this particular trace session. so if a guest with that ID was part of that session, its VCPU-to-host-process mapping is sitting right there in the host trace file, and the info comes back in the name, vcpu_count and cpu_pid parameters. let me break it down:

  • name — contains the name of the guest 🏷️
  • vcpu_count — contains the count of VCPUs of that guest
  • cpu_pid — the array containing the VCPU to host process mapping

the array is of size vcpu_count, where the index is VCPU and the value is the process ID (PID) of the host process running that VCPU. obsessed with this design ngl.

💀 important bestie: the name, vcpu_count and cpu_pid values must not be freed. don't do it. not your data to free, periodt.

🔥 RETURN VALUE 🔥

  • tracecmd_get_traceid() — returns a 64 bit trace ID. cute and simple 💜
  • tracecmd_get_guest_cpumap() — returns -1 in case of an error, or 0 otherwise. and if 0 is returned, then the name, vcpu_count and cpu_pid parameters contain the requested information. bestie behavior fr fr ✨

🌈 EXAMPLE 🌈

#include <trace-cmd.h>
...
struct tracecmd_input *host = tracecmd_open("trace.dat");
        if (!host) {
                /* Failed to open host trace file */
        }

struct tracecmd_input *guest1 = tracecmd_open_head("trace-Guest1.dat");
        if (!guest1) {
                /* Failed to open guest1 trace file */
        }
struct tracecmd_input *guest2 = tracecmd_open_head("trace-Guest2.dat");
        if (!guest2) {
                /* Failed to open guest2 trace file */
        }

unsigned long long guest_id_1 = tracecmd_get_traceid(guest1);
unsigned long long guest_id_2 = tracecmd_get_traceid(guest2);
int *cpu_pid_1, *cpu_pid_2;
int vcount_1, vcount_2;
char *name_1, *name_2;

        if (!tracecmd_get_guest_cpumap(host, guest_id_1, &name_1, &vcount_1, &cpu_pid_1)) {
                /* The Host and a guest1 with name_1 are part of the same trace session.
                 * Got guest1 VCPU to host PID mapping.
                 */
        }
        if (!tracecmd_get_guest_cpumap(host, guest_id_2, &name_2, &vcount_2, &cpu_pid_2)) {
                /* The Host and a guest2 with name_2 are part of the same trace session.
                 * Got guest2 VCPU to host PID mapping.
                 */
        }
...
        tracecmd_close(guest1);
        tracecmd_close(guest2);
        tracecmd_close(handle);

see how it all comes together? main character energy tbh 👑

🎀 FILES 🎀

  • trace-cmd.h — the header file you include to get access to the library APIs, duh 🫶
  • -ltracecmd — the linker switch you add when building a program that uses the library. don't forget it, that's the whole vibe check

⭐ SEE ALSO ⭐

libtracefs(3), libtraceevent(3), trace-cmd(1) trace-cmd.dat(5)

💜 AUTHOR 💜

  • Steven Rostedt <rostedt@goodmis.org[1]>
  • Tzvetomir Stoyanov <tz.stoyanov@gmail.com[2]>

🙈 REPORTING BUGS 🙈

found a bug? report it to <linux-trace-devel@vger.kernel.org[3]> — they wanna hear it, fr 💌

🌸 LICENSE 🌸

libtracecmd is Free Software licensed under the GNU LGPL 2.1 ✨

🧚 RESOURCES 🧚

https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ — go poke around, the source is right there 🦋

🍓 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

and that's the whole page bestie!! 🎀 this was libtracefs, dated 03/09/2026, and you made it all the way to the end — so proud of you, genuinely 💖✨🦋

📦 where this page comes from