[ust.git] / doc / man / usttrace.1.md

usttrace(1) -- the simplest way to record a trace
=================================================

## SYNOPSIS

`usttrace` [<options>] [<command>]

## DESCRIPTION

The `usttrace` script automatically:

* creates a daemon
* enables all markers
* runs the command specified on the command line
* after the command ends, prints the location where the trace was saved

Each subdirectory of the save location contains the trace of one process that
was generated by the command. The name of a subdirectory consists in the PID of
the process, followed by the timestamp of its creation.

The save location also contains logs of the tracing.

When using usttrace, the early tracing is always active, which means that the
tracing is guaranteed to be started by the time the process enters its main()
function.

Several usttrace's may be run simultaneously without risk of conflict. This
facilitates the use of the tracer by independent users on a system. Each
instance of usttrace starts its own daemon which collects the events of the
processes it creates.

## OPTIONS

These programs follow the usual GNU command line syntax, with long options
starting with two dashes(`-'). A summary of options is included below.

  * `-h`:
    Show summary of options.

  * `-l`:
    Runtime link with UST library. (Needed only if program was not linked at
    compile time with libust.)

  * `-L`:
    Add path to ust libraries to LD_LIBRARY_PATH.

  * `-m`:
    Instrument malloc calls.

  * `-f`:
    Also trace forked processes.

  * `-s`:
    Use system-wide daemon instead of creating one for this session.

  * `-S`:
    Specify the subbuffer size.

  * `-N`:
    Specify the number of subbuffers.

  * `-W`:
    Undocumented option.

## SEE ALSO

ustctl(1), ustd(1)


## AUTHOR

`usttrace` was written by Pierre-Marc Fournier.

This manual page was written by Jon Bernard &lt;jbernard@debian.org&gt;, for
the Debian project (and may be used by others).
Commit	Line	Data
43550d37 JB	1	usttrace(1) -- the simplest way to record a trace
	2	=================================================
	3
	4	## SYNOPSIS
	5
	6	`usttrace` [<options>] [<command>]
	7
	8	## DESCRIPTION
	9
	10	The `usttrace` script automatically:
	11
	12	* creates a daemon
	13	* enables all markers
	14	* runs the command specified on the command line
	15	* after the command ends, prints the location where the trace was saved
	16
	17	Each subdirectory of the save location contains the trace of one process that
	18	was generated by the command. The name of a subdirectory consists in the PID of
	19	the process, followed by the timestamp of its creation.
	20
	21	The save location also contains logs of the tracing.
	22
	23	When using usttrace, the early tracing is always active, which means that the
	24	tracing is guaranteed to be started by the time the process enters its main()
	25	function.
	26
	27	Several usttrace's may be run simultaneously without risk of conflict. This
	28	facilitates the use of the tracer by independent users on a system. Each
	29	instance of usttrace starts its own daemon which collects the events of the
	30	processes it creates.
	31
	32	## OPTIONS
	33
	34	These programs follow the usual GNU command line syntax, with long options
	35	starting with two dashes(`-'). A summary of options is included below.
	36
	37	* `-h`:
	38	Show summary of options.
	39
	40	* `-l`:
	41	Runtime link with UST library. (Needed only if program was not linked at
	42	compile time with libust.)
	43
	44	* `-L`:
	45	Add path to ust libraries to LD_LIBRARY_PATH.
	46
	47	* `-m`:
	48	Instrument malloc calls.
	49
	50	* `-f`:
	51	Also trace forked processes.
	52
	53	* `-s`:
	54	Use system-wide daemon instead of creating one for this session.
	55
235ae2d7 AH	56	* `-S`:
	57	Specify the subbuffer size.
	58
	59	* `-N`:
	60	Specify the number of subbuffers.
	61
43550d37 JB	62	* `-W`:
	63	Undocumented option.
	64
c3947c25 PMF	65	## SEE ALSO
	66
	67	ustctl(1), ustd(1)
	68
	69
43550d37 JB	70	## AUTHOR
	71
	72	`usttrace` was written by Pierre-Marc Fournier.
	73
	74	This manual page was written by Jon Bernard <jbernard@debian.org>, for
	75	the Debian project (and may be used by others).