---
name: "tracecmd_get_traceid"
section: "3"
platform: "linux"
package: "trace-cmd"
version: "3.4-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/tracecmd_get_traceid"
---

# tracecmd\_get\_traceid(3)

Manage trace session with multiple trace peers, recorded in multiple trace files.

## NAME

tracecmd\_get\_traceid, tracecmd\_get\_guest\_cpumap - Manage trace session with multiple trace peers, recorded in multiple trace files.

## 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

This set of APIs can be used to manage a trace session with multiple trace peers, for example, tracing both a host and one or more guest virtual machines. The trace data of each peer from the session is recorded in separate trace files. Information about peers from the session is stored in the metadata of each trace file. These APIs use that information to extract and synchronize the trace data.

The **tracecmd\_get\_traceid()** function returns the trace ID stored in the trace file metadata associated with *handle*. Each peer from a trace session has an ID unique for that peer and that trace session only. This ID is used to match multiple trace files recorded in a same trace session.

The **tracecmd\_get\_guest\_cpumap()** function gets the mapping of guest virtual CPUs (VCPU) to the host process that represents those VCPUs and is stored in the metadata of the trace file associated with *handle*. This information is gathered during a host-guest trace session and is stored in the host trace file. The *trace\_id* parameter is the trace ID of the guest in this particular trace session. If a guest with that ID was part of that session, its VCPU to host process mapping is in the host trace file and the information is returned in *name*, *vcpu\_count* and *cpu\_pid* parameters. The *name* parameter contains the name of the guest, the *vcpu\_count* contains the count of VCPUs of that guest and the *cpu\_pid* array contains 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. The *name*, *vcpu\_count* and *cpu\_pid* values must **not** be freed.

## RETURN VALUE

The **tracecmd\_get\_traceid()** function returns a 64 bit trace ID.

The **tracecmd\_get\_guest\_cpumap()** function returns -1 in case of an error or 0 otherwise. If 0 is returned, then the *name*, *vcpu\_count* and *cpu\_pid* parameters contain the requested information.

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

## FILES

```
trace-cmd.h
        Header file to include in order to have access to the library APIs.
-ltracecmd
        Linker switch to add when building a program that uses the library.
```

## SEE ALSO

**[libtracefs(3)](/libtracefs/3.md)**, **[libtraceevent(3)](/libtraceevent/3.md)**, **[trace-cmd(1)](/trace-cmd/1.md)** **[trace-cmd.dat(5)](/trace-cmd.dat/5.md)**

## AUTHOR

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

## REPORTING BUGS

Report bugs to \<**linux-trace-devel@vger.kernel.org**\[3\]\>

## 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/**

## 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