1 // SPDX-License-Identifier: GPL-2.0
2 #include <stdio.h>
3 #include <stdlib.h>
4 #include <string.h>
5 #include <libgen.h>
6
7 #include "trace-local.h"
8 #include "version.h"
9
10 struct usage_help {
11 char *name;
12 char *short_help;
13 char *long_help;
14 };
15
16 static struct usage_help usage_help[] = {
17 {
18 "record",
19 "record a trace into a trace.dat file",
20 " %s record [-v][-e event [-f filter]][-p plugin][-F][-d][-D][-o file] \\\n"
21 " [-q][-s usecs][-O option ][-l func][-g func][-n func] \\\n"
22 " [-P pid][-N host:port][-t][-r prio][-b size][-B buf] \\\n"
23 " [--proxy vsock][command ...]\n"
24 " [-m max][-C clock]\n"
25 " -e run command with event enabled\n"
26 " -f filter for previous -e event\n"
27 " -R trigger for previous -e event\n"
28 " -p run command with plugin enabled\n"
29 " -F filter only on the given process\n"
30 " -P trace the given pid like -F for the command\n"
31 " -c also trace the children of -F (or -P if kernel supports it)\n"
32 " -C set the trace clock\n"
33 " -T do a stacktrace on all events\n"
34 " -l filter function name\n"
35 " -g set graph function\n"
36 " -n do not trace function\n"
37 " -m max size per CPU in kilobytes\n"
38 " -M set CPU mask to trace\n"
39 " -v will negate all -e (disable those events) and -B (delete those instances) after it\n"
40 " -d disable function tracer when running\n"
41 " -D Full disable of function tracing (for all users)\n"
42 " -o data output file [default trace.dat]\n"
43 " -O option to enable (or disable)\n"
44 " -r real time priority to run the capture threads\n"
45 " -s sleep interval between recording (in usecs) [default: 1000]\n"
46 " -S used with --profile, to enable only events in command line\n"
47 " -N host:port to connect to (see listen)\n"
48 " -V cid:port to connect to via vsocket (see listen)\n"
49 " -t used with -N, forces use of tcp in live trace\n"
50 " -b change kernel buffersize (in kilobytes per CPU)\n"
51 " -B create sub buffer and following events will be enabled here\n"
52 " -k do not reset the buffers after tracing.\n"
53 " -i do not fail if an event is not found\n"
54 " -q print no output to the screen\n"
55 " -G when profiling, set soft and hard irqs as global\n"
56 " --quiet print no output to the screen\n"
57 " --temp specify a directory to store the temp files used to create trace.dat\n"
58 " --subbuf-size to specify the sub-buffer size in kilobytes\n"
59 " --module filter module name\n"
60 " --by-comm used with --profile, merge events for related comms\n"
61 " --profile enable tracing options needed for report --profile\n"
62 " --func-stack perform a stack trace for function tracer\n"
63 " (use with caution)\n"
64 " --max-graph-depth limit function_graph depth\n"
65 " --cmdlines-size change kernel saved_cmdlines_size\n"
66 " --no-filter include trace-cmd threads in the trace\n"
67 " --proc-map save the traced processes address map into the trace.dat file\n"
68 " --user execute the specified [command ...] as given user\n"
69 " --tsc2nsec Convert the current clock to nanoseconds, using tsc multiplier and shift from the Linux"
70 " kernel's perf interface\n"
71 " --tsync-interval set the loop interval, in ms, for timestamps synchronization with guests:"
72 " If a negative number is specified, timestamps synchronization is disabled"
73 " If 0 is specified, no loop is performed - timestamps offset is calculated only twice,"
74 " at the beginnig and at the end of the trace\n"
75 " --poll don't block while reading from the trace buffer\n"
76 " --name used with -A to give the agent a specific name\n"
77 " --file-version set the desired trace file version\n"
78 " --compression compress the trace output file, one of these strings can be passed:\n"
79 " any - auto select the best available compression algorithm\n"
80 " none - do not compress the trace file\n"
81 " name - the name of the desired compression algorithms\n"
82 " available algorithms can be listed with trace-cmd list -c\n"
83 " --proxy vsocket to reach the agent. Acts the same as -A (for an agent)\n"
84 " but will send the proxy connection to the agent.\n"
85 " --daemonize run trace-cmd in the background as a daemon after recording has started.\n"
86 " creates a pidfile at /var/run/trace-cmd-record.pid with the pid of trace-cmd\n"
87 " during the recording.\n"
88 },
89 {
90 "set",
91 "set a ftrace configuration parameter",
92 " %s set [-v][-e event [-f filter]][-p plugin][-F][-d][-D] \\\n"
93 " [-q][-s usecs][-O option ][-l func][-g func][-n func] \\\n"
94 " [-P pid][-b size][-B buf][-m max][-C clock][command ...]\n"
95 " -e enable event\n"
96 " -f filter for previous -e event\n"
97 " -R trigger for previous -e event\n"
98 " -p set ftrace plugin\n"
99 " -P set PIDs to be traced\n"
100 " -c also trace the children of -F (or -P if kernel supports it)\n"
101 " -C set the trace clock\n"
102 " -T do a stacktrace on all events\n"
103 " -l filter function name\n"
104 " -g set graph function\n"
105 " -n do not trace function\n"
106 " -m max size per CPU in kilobytes\n"
107 " -M set CPU mask to trace\n"
108 " -v will negate all -e (disable those events) and -B (delete those instances) after it\n"
109 " -d disable function tracer when running\n"
110 " -D Full disable of function tracing (for all users)\n"
111 " -O option to enable (or disable)\n"
112 " -b change kernel buffersize (in kilobytes per CPU)\n"
113 " -B create sub buffer and following events will be enabled here\n"
114 " -i do not fail if an event is not found\n"
115 " -q print no output to the screen\n"
116 " --quiet print no output to the screen\n"
117 " --module filter module name\n"
118 " --func-stack perform a stack trace for function tracer\n"
119 " (use with caution)\n"
120 " --max-graph-depth limit function_graph depth\n"
121 " --cmdlines-size change kernel saved_cmdlines_size\n"
122 " --user execute the specified [command ...] as given user\n"
123 " --fork return immediately if a command is specified\n"
124 " --verbose 'level' Set the desired log level\n"
125 },
126 {
127 "start",
128 "start tracing without recording into a file",
129 " %s start [-e event][-p plugin][-d][-O option ][-P pid]\n"
130 " Uses same options as record.\n"
131 " It only enables the tracing and exits\n"
132 "\n"
133 " --fork: If a command is specified, then return right after it forks\n"
134 " --verbose 'level' Set the desired log level\n"
135 },
136 {
137 "extract",
138 "extract a trace from the kernel",
139 " %s extract [-p plugin][-O option][-o file][-B buf][-s][-a][-t]\n"
140 " Uses similar options as record, but only reads an existing trace.\n"
141 " -s : extract the snapshot instead of the main buffer\n"
142 " -B : extract a given buffer (more than one may be specified)\n"
143 " -a : extract all buffers (except top one)\n"
144 " -t : extract the top level buffer (useful with -B and -a)\n"
145 " --verbose 'level' Set the desired log level\n"
146 },
147 {
148 "stop",
149 "stop the kernel from recording trace data",
150 " %s stop [-B buf [-B buf]..] [-a] [-t]\n"
151 " Stops the tracer from recording more data.\n"
152 " Used in conjunction with start\n"
153 " -B stop a given buffer (more than one may be specified)\n"
154 " -a stop all buffers (except top one)\n"
155 " -t stop the top level buffer (useful with -B or -a)\n"
156 },
157 {
158 "restart",
159 "restart the kernel trace data recording",
160 " %s restart [-B buf [-B buf]..] [-a] [-t]\n"
161 " Restarts recording after a trace-cmd stop.\n"
162 " Used in conjunction with stop\n"
163 " -B restart a given buffer (more than one may be specified)\n"
164 " -a restart all buffers (except top one)\n"
165 " -t restart the top level buffer (useful with -B or -a)\n"
166 },
167 {
168 "show",
169 "show the contents of the kernel tracing buffer",
170 " %s show [-p|-s][-c cpu][-B buf][options]\n"
171 " Basically, this is a cat of the trace file.\n"
172 " -p read the trace_pipe file instead\n"
173 " -s read the snapshot file instance\n"
174 " (Can't have both -p and -s)\n"
175 " -c just show the file associated with a given CPU\n"
176 " -B read from a tracing buffer instance.\n"
177 " -f display the file path that is being dumped\n"
178 " The following options shows the corresponding file name\n"
179 " and then exits.\n"
180 " --tracing_on\n"
181 " --current_tracer\n"
182 " --buffer_size (for buffer_size_kb)\n"
183 " --buffer_total_size (for buffer_total_size_kb)\n"
184 " --buffer_subbuf_size (for buffer_subbuf_size_kb)\n"
185 " --buffer_percent (for buffer_percent)\n"
186 " --ftrace_filter (for set_ftrace_filter)\n"
187 " --ftrace_notrace (for set_ftrace_notrace)\n"
188 " --ftrace_pid (for set_ftrace_pid)\n"
189 " --graph_function (for set_graph_function)\n"
190 " --graph_notrace (for set_graph_notrace)\n"
191 " --cpumask (for tracing_cpumask)\n"
192 },
193 {
194 "reset",
195 "disable all kernel tracing and clear the trace buffers",
196 " %s reset [-b size][-B buf][-a][-d][-t]\n"
197 " Disables the tracer (may reset trace file)\n"
198 " Used in conjunction with start\n"
199 " -b change the kernel buffer size (in kilobytes per CPU)\n"
200 " -d delete the previous specified instance\n"
201 " -B reset the given buffer instance (may specify multiple -B)\n"
202 " -a reset all instances (except top one)\n"
203 " -t reset the top level instance (useful with -B or -a)\n"
204 },
205 {
206 "clear",
207 "clear the trace buffers",
208 " %s clear [-B buf][-a]\n"
209 " -B clear the given buffer (may specify multiple -B)\n"
210 " -a clear all existing buffers, including the top level one\n"
211 },
212 {
213 "report",
214 "read out the trace stored in a trace.dat file",
215 " %s report [-i file] [--cpu cpu] [-e][-f][-l][-P][-L][-N][-R][-E]\\\n"
216 " [-r events][-n events][-F filter][-v][-V[1-6]][-T][-O option]\n"
217 " [-H [start_system:]start_event,start_match[,pid]/[end_system:]end_event,end_match[,flags]\n"
218 " [-G]\n"
219 " -i input file [default trace.dat]\n"
220 " -e show file endianess\n"
221 " -f show function mapping list\n"
222 " -P show printk list\n"
223 " -E show event files stored\n"
224 " -F filter to filter output on\n"
225 " -I filter out events with the HARDIRQ flag set\n"
226 " -S filter out events with the SOFTIRQ flag set\n"
227 " -t print out full timestamp. Do not truncate to 6 places.\n"
228 " -R raw format: ignore print format and only show field data\n"
229 " -r raw format the events that match the option\n"
230 " -v will negate all -F after it (Not show matches)\n"
231 " -T print out the filter strings created and exit\n"
232 " -V[level] verbose (shows plugins being loaded)\n"
233 " With optional level (see --verbose numbers)\n"
234 " -L load only local (~/.trace-cmd/plugins) plugins\n"
235 " -N do not load any plugins\n"
236 " -n ignore plugin handlers for events that match the option\n"
237 " -w show wakeup latencies\n"
238 " -l show latency format (default with latency tracers)\n"
239 " -O plugin option -O [plugin:]var[=val]\n"
240 " --cpu <cpu1,cpu2,...> - filter events according to the given cpu list.\n"
241 " A range of CPUs can be specified using 'cpuX-cpuY' notation.\n"
242 " --cpus - List the CPUs that have content in it then exit.\n"
243 " --first-event - Show the timestamp of the first event for all CPUs.\n"
244 " --last-event - Show the timestamp of the last event for all CPUs.\n"
245 " --check-events return whether all event formats can be parsed\n"
246 " --stat - show the buffer stats that were reported at the end of the record.\n"
247 " --uname - show uname of the record, if it was saved\n"
248 " --version - show version used to build the trace-cmd exec that created the file\n"
249 " --profile report stats on where tasks are blocked and such\n"
250 " -G when profiling, set soft and hard irqs as global\n"
251 " -H Allows users to hook two events together for timings\n"
252 " (used with --profile)\n"
253 " --by-comm used with --profile, merge events for related comms\n"
254 " --ts-offset will add amount to timestamp of all events of the\n"
255 " previous data file.\n"
256 " --ts2secs HZ, pass in the timestamp frequency (per second)\n"
257 " to convert the displayed timestamps to seconds\n"
258 " Affects the previous data file, unless there was no\n"
259 " previous data file, in which case it becomes default\n"
260 " --ts-diff Show the delta timestamp between events.\n"
261 " --ts-check Check to make sure no time stamp on any CPU goes backwards.\n"
262 " --nodate Ignore the --date processing of trace-cmd record.\n"
263 " --raw-ts Display raw timestamps, without any corrections.\n"
264 " --align-ts Display timestamps aligned to the first event.\n"
265 " --verbose[=level] Set the desired log level\n"
266 " 0 or none - no error messages\n"
267 " 1 or crit - only critical messages\n"
268 " 2 or err - 'crit' and error messages\n"
269 " 3 or warn - 'err' and warning messages\n"
270 " 4 or info - 'warn' and informational messages\n"
271 " 5 or debug - 'info' and debugging messages\n"
272 " 6 or all - same as debug\n"
273 },
274 {
275 "stream",
276 "Start tracing and read the output directly",
277 " %s stream [-e event][-p plugin][-d][-O option ][-P pid]\n"
278 " Uses same options as record but does not write to files or the network.\n"
279 " --verbose 'level' Set the desired log level\n"
280 },
281 {
282 "profile",
283 "Start profiling and read the output directly",
284 " %s profile [-e event][-p plugin][-d][-O option ][-P pid][-G][-S][-o output]\n"
285 " [-H [start_system:]start_event,start_match[,pid]/[end_system:]end_event,end_match[,flags]\n\n"
286 " Uses same options as record --profile.\n"
287 " -H Allows users to hook two events together for timings\n"
288 " --verbose 'level' Set the desired log level\n"
289 },
290 {
291 "hist",
292 "show a histogram of the trace.dat information",
293 " %s hist [-i file][-P] [file]"
294 " -P ignore pids (compact all functions)\n"
295 },
296 {
297 "stat",
298 "show the status of the running tracing (ftrace) system",
299 " %s stat [-B buf][-t][-o]"
300 " -B show the status of a instance buffer\n"
301 " -t show the top level status along with buffer specified by -B\n"
302 " -o list tracing options\n"
303 },
304 {
305 "split",
306 "parse a trace.dat file into smaller file(s)",
307 " %s split [options] -o file [start [end]]\n"
308 " -o output file to write to (file.1, file.2, etc)\n"
309 " -s n split file up by n seconds\n"
310 " -m n split file up by n milliseconds\n"
311 " -u n split file up by n microseconds\n"
312 " -e n split file up by n events\n"
313 " -p n split file up by n pages\n"
314 " -C n select CPU n\n"
315 " -B buffer keep buffer in resulting .dat file\n"
316 " Use -t to promote the buffer to the top instance.\n"
317 " -t promote preceding buffer to the top instance.\n"
318 " Must follow -B.\n"
319 " --top keep top buffer in resulting .dat file.\n"
320 " -b new name of the top instance. Must follow --top.\n"
321 " -r repeat from start to end\n"
322 " -c per cpu, that is -p 2 will be 2 pages for each CPU\n"
323 " if option is specified, it will split the file\n"
324 " up starting at start, and ending at end\n"
325 " start - decimal start time in seconds (ex: 75678.923853)\n"
326 " if left out, will start at beginning of file\n"
327 " end - decimal end time in seconds\n"
328 },
329 {
330 "options",
331 "list the plugin options available for trace-cmd report",
332 " %s options\n"
333 },
334 {
335 "listen",
336 "listen on a network socket for trace clients",
337 " %s listen -p port[-D][-o file][-d dir][-l logfile]\n"
338 " Creates a socket to listen for clients.\n"
339 " -p port number to listen on.\n"
340 " -D run in daemon mode.\n"
341 " -V listen on a vsocket instead.\n"
342 " -o file name to use for clients.\n"
343 " -d directory to store client files.\n"
344 " -l logfile to write messages to.\n"
345 " --verbose 'level' Set the desired log level\n"
346 },
347 {
348 "agent",
349 "listen on a vsocket for trace clients",
350 " %s agent -p port[-D][-N IP][-P cid]\n"
351 " Creates a vsocket to listen for clients.\n"
352 " -N Connect to IP via TCP instead of vsockets\n"
353 " *** Insecure setting, only use on a trusted network ***\n"
354 " *** Only use if the client is totally trusted. ***\n"
355 " -p port number to listen on.\n"
356 " -D run in daemon mode.\n"
357 " -P Also act as a proxy server, with a single client denoted\n"
358 " by a context ID (cid).\n"
359 " --verbose 'level' Set the desired log level\n"
360 },
361 {
362 "setup-guest",
363 "create FIFOs for tracing guest VMs",
364 " %s setup-guest [-c cpus][-p perm][-g group][-a] guest\n"
365 " -c number of guest virtual CPUs\n"
366 " -p FIFOs permissions (default: 0660)\n"
367 " -g FIFOs group owner\n"
368 " -a Attach FIFOs to guest VM config\n"
369 },
370 {
371 "list",
372 "list the available events, plugins or options",
373 " %s list [-e [regex]][-t][-o][-f [regex]]\n"
374 " -e list available events\n"
375 " -F show event format\n"
376 " --full show the print fmt with -F\n"
377 " -R show event triggers\n"
378 " -l show event filters\n"
379 " -t list available tracers\n"
380 " -o list available options\n"
381 " -f [regex] list available functions to filter on\n"
382 " -P list loaded plugin files (by path)\n"
383 " -O list plugin options\n"
384 " -B list defined buffer instances\n"
385 " -C list the defined clocks (and active one)\n"
386 " -c list the supported trace file compression algorithms\n"
387 },
388 {
389 "restore",
390 "restore a crashed record",
391 " %s restore [-c][-o file][-i file] cpu-file [cpu-file ...]\n"
392 " -c create a partial trace.dat file only\n"
393 " -o output file\n"
394 " -i partial trace.dat file for input\n"
395 },
396 {
397 "snapshot",
398 "take snapshot of running trace",
399 " %s snapshot [-s][-r][-f][-B buf][-c cpu]\n"
400 " -s take a snapshot of the trace buffer\n"
401 " -r reset current snapshot\n"
402 " -f free the snapshot buffer\n"
403 " without the above three options, display snapshot\n"
404 " -c operate on the snapshot buffer for the given CPU\n"
405 " -B operate on the snapshot buffer for a tracing buffer instance.\n"
406 },
407 {
408 "stack",
409 "output, enable or disable kernel stack tracing",
410 " %s stack [--start][--stop][--reset]\n"
411 " --start enable the stack tracer\n"
412 " --stop disable the stack tracer\n"
413 " --reset reset the maximum stack found\n"
414 " --verbose 'level' Set the desired log level\n"
415 },
416 {
417 "check-events",
418 "parse trace event formats",
419 " %s check-events [-N]\n"
420 " -N do not load any plugins\n"
421 " --verbose 'level' Set the desired log level\n"
422 },
423 {
424 "dump",
425 "read out the meta data from a trace file",
426 " %s dump [options]\n"
427 " -i input file, default is trace.dat\n"
428 " -v validate a trace file\n"
429 " --all print all meta data from a trace file\n"
430 " --summary print a meta data summary\n"
431 " --head-page print header page information\n"
432 " --head-event print header event information\n"
433 " --ftrace-events print ftrace events format\n"
434 " --systems print recorded event systems\n"
435 " --events print format of recorded events\n"
436 " --kallsyms print information of the mapping of function addresses to the function names\n"
437 " --printk print trace_printk() format strings\n"
438 " --cmd-lines print information mapping a PID to a process name\n"
439 " --options print options\n"
440 " --flyrecord information of offset and count of recorded events per CPU\n"
441 " --clock trace clock, saved in the file\n"
442 " -h, --help show usage information\n"
443 " --verbose 'level' Set the desired log level\n"
444 },
445 {
446 "attach",
447 "Attach a host and guest trace.dat file",
448 " %s attach [options] host_file guest_file vcpu_pid,...\n"
449 " -s offset,scale,fraction[,timestamp] conversion to sync guest timestamp\n"
450 " host_file The trace.dat file from the host\n"
451 " guest_file The trace.dat file from the guest\n"
452 " vcpu_pid list of process ids from the host that represent the vCPUs of the guest\n"
453 },
454 {
455 "convert",
456 "convert trace file to different version",
457 " %s convert [options]\n"
458 " -i input file, default is trace.dat\n"
459 " -o output file, mandatory parameter.\n"
460 " The output file can be specified also as last argument of the command\n"
461 " --file-version set the desired trace file version\n"
462 " --compression compress the trace output file, one of these strings can be passed:\n"
463 " any - auto select the best available compression algorithm\n"
464 " none - do not compress the trace file\n"
465 " name - the name of the desired compression algorithms\n"
466 " available algorithms can be listed with trace-cmd list -c\n"
467 },
468 {
469 "sqlhist",
470 "Run a SQL like query to create histogram or synthetic events (see man tracefs_sql(3))\n",
471 "%s sql [-n name][-e][-s][-S fields][-m var][-c var][-T][-t dir][-f file | 'sql-command-line']\n"
472 " -n name - name of synthetic event 'Anonymous' if left off\n"
473 " -t dir - use dir instead of /sys/kernel/tracing\n"
474 " -e - execute the commands to create the synthetic event\n"
475 " -m - trigger the action when var is a new max.\n"
476 " -c - trigger the action when var changes.\n"
477 " -s - used with -m or -c to do a snapshot of the tracing buffer\n"
478 " -S - used with -m or -c to save fields of the end event (comma deliminated)\n"
479 " -T - used with -m or -c to do both a snapshot and a trace\n"
480 " -f file - read sql lines from file otherwise from the command line\n"
481 " if file is '-' then read from standard input.\n\n"
482 " See man tracefs_sql(3) for sql-command-line\n"
483 },
484
485 {
486 NULL, NULL, NULL
487 }
488 };
489
find_help(char * cmd)490 static struct usage_help *find_help(char *cmd)
491 {
492 struct usage_help *help;
493
494 help = usage_help;
495 while (help->name) {
496 if (strcmp(cmd, help->name) == 0)
497 return help;
498 help++;
499 }
500 return NULL;
501 }
502
usage(char ** argv)503 void usage(char **argv)
504 {
505 struct usage_help *help = NULL;
506 char *arg = argv[0];
507 char *p;
508
509 p = basename(arg);
510
511 printf("\n"
512 "%s version %s (%s)\n\n"
513 "usage:\n", p, VERSION_STRING, VERSION_GIT);
514
515 if (argv[1])
516 help = find_help(argv[1]);
517
518 if (help) {
519 printf(help->long_help, p);
520 goto out;
521 }
522
523 printf(" %s [COMMAND] ...\n\n"
524 " commands:\n", p);
525
526 help = usage_help;
527 while (help->name) {
528 printf(" %s - %s\n", help->name, help->short_help);
529 help++;
530 }
531 out:
532 printf("\n");
533 exit(-1);
534 }
535
536
trace_usage(int argc,char ** argv)537 void trace_usage(int argc, char **argv)
538 {
539 usage(argv);
540 }
541