1LIBTRACECMD(3)                 libtracefs Manual                LIBTRACECMD(3)
2
3
4

NAME

6       tracecmd_get_traceid, tracecmd_get_guest_cpumap - Manage trace session
7       with multiple trace peers, recorded in multiple trace files.
8

SYNOPSIS

10       #include <trace-cmd.h>
11
12       unsigned long long tracecmd_get_traceid(struct tracecmd_input *handle);
13       int tracecmd_get_guest_cpumap(struct tracecmd_input *handle, unsigned long long trace_id, const char **name, int *vcpu_count, const int **cpu_pid);
14

DESCRIPTION

16       This set of APIs can be used to manage a trace session with multiple
17       trace peers, for example, tracing both a host and one or more guest
18       virtual machines. The trace data of each peer from the session is
19       recorded in separate trace files. Information about peers from the
20       session is stored in the metadata of each trace file. These APIs use
21       that information to extract and synchronize the trace data.
22
23       The tracecmd_get_traceid() function returns the trace ID stored in the
24       trace file metadata associated with handle. Each peer from a trace
25       session has an ID unique for that peer and that trace session only.
26       This ID is used to match multiple trace files recorded in a same trace
27       session.
28
29       The tracecmd_get_guest_cpumap() function gets the mapping of guest
30       virtual CPUs (VCPU) to the host process that represents those VCPUs and
31       is stored in the metadata of the trace file associated with handle.
32       This information is gathered during a host-guest trace session and is
33       stored in the host trace file. The trace_id parameter is the trace ID
34       of the guest in this particular trace session. If a guest with that ID
35       was part of that session, its VCPU to host process mapping is in the
36       host trace file and the information is returned in name, vcpu_count and
37       cpu_pid parameters. The name parameter contains the name of the guest,
38       the vcpu_count contains the count of VCPUs of that guest and the
39       cpu_pid array contains the VCPU to host process mapping. The array is
40       of size vcpu_count where the index is VCPU and the value is the process
41       ID (PID) of the host process, running that VCPU. The name, vcpu_count
42       and cpu_pid values must not be freed.
43

RETURN VALUE

45       The tracecmd_get_traceid() function returns a 64 bit trace ID.
46
47       The tracecmd_get_guest_cpumap() function returns -1 in case of an error
48       or 0 otherwise. If 0 is returned, then the name, vcpu_count and cpu_pid
49       parameters contain the requested information.
50

EXAMPLE

52           #include <trace-cmd.h>
53           ...
54           struct tracecmd_input *host = tracecmd_open("trace.dat");
55                   if (!host) {
56                           /* Failed to open host trace file */
57                   }
58
59           struct tracecmd_input *guest1 = tracecmd_open_head("trace-Guest1.dat");
60                   if (!guest1) {
61                           /* Failed to open guest1 trace file */
62                   }
63           struct tracecmd_input *guest2 = tracecmd_open_head("trace-Guest2.dat");
64                   if (!guest2) {
65                           /* Failed to open guest2 trace file */
66                   }
67
68           unsigned long long guest_id_1 = tracecmd_get_traceid(guest1);
69           unsigned long long guest_id_2 = tracecmd_get_traceid(guest2);
70           int *cpu_pid_1, *cpu_pid_2;
71           int vcount_1, vcount_2;
72           char *name_1, *name_2;
73
74                   if (!tracecmd_get_guest_cpumap(host, guest_id_1, &name_1, &vcount_1, &cpu_pid_1)) {
75                           /* The Host and a guest1 with name_1 are part of the same trace session.
76                            * Got guest1 VCPU to host PID mapping.
77                            */
78                   }
79                   if (!tracecmd_get_guest_cpumap(host, guest_id_2, &name_2, &vcount_2, &cpu_pid_2)) {
80                           /* The Host and a guest2 with name_2 are part of the same trace session.
81                            * Got guest2 VCPU to host PID mapping.
82                            */
83                   }
84           ...
85                   tracecmd_close(guest1);
86                   tracecmd_close(guest2);
87                   tracecmd_close(handle);
88

FILES

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

SEE ALSO

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

AUTHOR

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

REPORTING BUGS

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

LICENSE

106       libtracecmd is Free Software licensed under the GNU LGPL 2.1
107

RESOURCES

109       https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
110

COPYING

112       Copyright (C) 2020 VMware, Inc. Free use of this software is granted
113       under the terms of the GNU Public License (GPL).
114

NOTES

116        1. rostedt@goodmis.org
117           mailto:rostedt@goodmis.org
118
119        2. tz.stoyanov@gmail.com
120           mailto:tz.stoyanov@gmail.com
121
122        3. linux-trace-devel@vger.kernel.org
123           mailto:linux-trace-devel@vger.kernel.org
124
125
126
127libtracefs                        03/29/2021                    LIBTRACECMD(3)
Impressum