X-Git-Url: https://git.liburcu.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-create.1.txt;h=daac924f7d369cf8e72bbda1841fa3ff3bfc09ba;hb=26f0c7794376456fcb5b13d4eae91c0ccf0dfe66;hp=552e617139c2f70def505f7291565d9c75187670;hpb=7097770edcfe2c6112f5df0af039846b9a7fdbbe;p=lttng-tools.git diff --git a/doc/man/lttng-create.1.txt b/doc/man/lttng-create.1.txt index 552e61713..daac924f7 100644 --- a/doc/man/lttng-create.1.txt +++ b/doc/man/lttng-create.1.txt @@ -1,5 +1,6 @@ lttng-create(1) =============== +:revdate: 3 May 2021 NAME @@ -9,183 +10,353 @@ lttng-create - Create an LTTng tracing session SYNOPSIS -------- -Normal mode: +Create a local mode tracing session: [verse] -*lttng* ['GENERAL OPTIONS'] *create* [option:--output='PATH' | option:--no-output] - [option:--shm-path='PATH'] ['SESSION'] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR'] + [option:--no-output | option:--output='DIR' | option:--set-url=**file://**__DIR__] -Snapshot mode: +Create a network streaming mode tracing session: [verse] -*lttng* ['GENERAL OPTIONS'] *create* option:--snapshot - [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] - [option:--shm-path='PATH'] ['SESSION'] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR'] + (option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL') -Live mode: +Create a snapshot mode tracing session: [verse] -*lttng* ['GENERAL OPTIONS'] *create* option:--live[='DELAYUS'] - [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] - [option:--shm-path='PATH'] ['SESSION'] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--snapshot [option:--shm-path='DIR'] + [option:--no-output | option:--output='DIR' | option:--set-url='URL' | + option:--ctrl-url='URL' option:--data-url='URL'] +Create a live mode tracing session: + +[verse] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--live[='DELAYUS'] + [option:--shm-path='DIR'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] DESCRIPTION ----------- -The `lttng create` command creates a new tracing session. +The `lttng create` command creates a new tracing session for your Unix +user within the connected session daemon (see the ``Session daemon +connection'' section of man:lttng(1) to learn how a user application +connects to a session daemon). -A tracing session is a named container of channels, which in turn -contain event rules. It is domain-agnostic, in that channels and event -rules can be enabled for the user space tracer and/or the Linux -kernel tracer. +See man:lttng-concepts(7) to learn more about tracing sessions. -On execution, an `.lttngrc` file is created, if it does not exist, in the -user's home directory. This file contains the name of the current tracing -session. When creating a new tracing session with `lttng create`, the -current tracing session is set to this new tracing session. The -linklttng:lttng-set-session(1) command can be used to set the current -tracing session without manually editing the `.lttngrc` file. +Without the 'SESSION' argument, LTTng automatically generates a tracing +session name having the ++auto-++__YYYYmmdd__++-++__HHMMSS__ form, where +'YYYYmmdd' and 'HHMMSS' are the creation date and time. 'SESSION' may +:not: contain the character `/`. -If 'SESSION' is omitted, a session name is automatically created having -this form: `auto-YYYYmmdd-HHMMSS`. 'SESSION' *must not* contain the -character `/`. +Specify the path of the directory containing the shared memory files +holding the channel ring buffers with the option:--shm-path option. +Specifying a location on an NVRAM file system makes it possible to +recover the latest recorded trace data when the system reboots after a +crash with the man:lttng-crash(1) utility. -The option:--shm-path option can be used to specify the path to the -shared memory holding the ring buffers. Specifying a location on an -NVRAM file system makes it possible to retrieve the latest recorded -trace data when the system reboots after a crash. To view the events -of ring buffer files after a system crash, use the -linklttng:lttng-crash(1) utility. +By default, the `create` command automatically spawns a session daemon +for your Unix user if none is currently running. Override the path of +the session daemon binary to spawn with the general +genoption:--sessiond-path option. Avoid automatically spawning a session +daemon with the general genoption:--no-sessiond option. -Tracing sessions are destroyed using the linklttng:lttng-destroy(1) -command. +On success, the `create` command sets the current tracing session (see +man:lttng-concepts(7) to learn more) to the created tracing session. +Show the status of the current tracing session with the +man:lttng-status(1) command. -Creation modes -~~~~~~~~~~~~~~ -There are three tracing session modes: - -Normal mode:: - Traces the local system and writes the trace to the local - file system. The option:--output option specifies the trace path. - If omitted, the trace is written in the `$LTTNG_HOME/lttng-traces` - directory (`$LTTNG_HOME` defaults to `$HOME`). The file system - output can be disabled using the option:--no-output option. - -Snapshot mode:: - Traces the local system without writing the trace to the local file - system (implicit option:--no-output option). Channels are automatically - configured to be snapshot-ready on creation (see - linklttng:lttng-enable-channel(1)). The linklttng:lttng-snapshot(1) - command is used to take snapshots of the current ring buffers. - The option:--set-url, or option:--ctrl-url and option:--data-url - options set the default snapshot output destination. - -Live mode:: - Traces the local system, sending trace data to an LTTng relay daemon - over the network (see linklttng:lttng-relayd(8)). The - option:--set-url, or option:--ctrl-url and option:--data-url options - set the trace output destination. The live output URLs cannot use - the `file://` protocol (see URL format below). +List the tracing sessions of your Unix user, or of all users if +your Unix user is `root`, within the connected session daemon with the +man:lttng-list(1) command. + +Start and stop a tracing session with the man:lttng-start(1) and +man:lttng-stop(1) commands. + +Save and load a tracing session with the man:lttng-save(1) and +man:lttng-load(1) commands. + +Allow and disallow specific processes to record events with the +man:lttng-track(1) and man:lttng-untrack(1) commands. + +Archive the current trace chunk of (rotate) a tracing session with the +man:lttng-rotate(1) command. + +Destroy a tracing session with the man:lttng-destroy(1) command. + + +[[modes]] +Tracing session modes +~~~~~~~~~~~~~~~~~~~~~ +As documented in man:lttng-concepts(7), LTTng offers four tracing +session modes: + +[[local-mode]]Local mode:: + Write the trace data to the local file system. ++ +The trace data output directory is: ++ +With the option:--no-output option::: + None: the file system output is disabled. + +With the option:--output='DIR' or option:--set-url=++file://++__DIR__ option::: + The directory 'DIR'. + +Otherwise::: + A subdirectory, under the `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` + defaults to `$HOME`) directory, of which the name contains the + tracing session name and the date/time. + +[[network-streaming-mode]]Network streaming mode:: + Send the trace data over the network to a listening relay daemon + (see man:lttng-relayd(8)). ++ +Set the trace output destination with the option:--set-url option, or +with the option:--ctrl-url and option:--data-url options (see the +<> section below). + +[[snapshot-mode]]Snapshot mode (option:--snapshot option):: + Only write the trace data to the local file system or send it to a + listening relay daemon (man:lttng-relayd(8)) when LTTng takes a + snapshot (see the man:lttng-snapshot(1) command). ++ +With this mode, LTTng: ++ +With the option:--no-output option::: + Does :not: add any snapshot output to the created tracing + session. + +With the option:--output option, the option:--set-url option, or the option:--ctrl-url and option:--data-url options::: + Adds a snapshot output named `snapshot-1` using the provided + path or URL(s) to the created tracing session. + +Otherwise::: + Adds an automatic snapshot output named `snapshot-1` to the created + tracing session. ++ +The automatic snapshot output is a subdirectory, under the +`$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`) +directory, of which the name contains the tracing session name and the +date/time. + +[[live-mode]]Live mode (option:--live option):: + Send the trace data over the network to a listening relay daemon + (see man:lttng-relayd(8)) for live reading. ++ +Set the trace output destination with the option:--set-url='URL' option, +or with the option:--ctrl-url='URL' and option:--data-url='URL' options +(see the <> section below). 'URL' may :not: start +with `file://`. [[url-format]] URL format ~~~~~~~~~~ -The option:--set-url, option:--ctrl-url, and option:--data-url options -specify URLs. +The argument of the option:--set-url='URL', option:--ctrl-url='URL', and +option:--data-url='URL' options is an URL. -The format of those URLs is one of: +There are two available 'URL' formats. +Local format:: ++ [verse] -file://'TRACEPATH' -'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEPATH'] - -The `file://` protocol targets the *local file system*. +file://'TRACEDIR' +{nbsp} ++ +The `file://` protocol targets the *local file system*: you may only use +such an URL with the option:--set-url option when you create the tracing +session in local or snapshot mode (see the <> section above). ++ +'TRACEDIR'::: + Absolute path to the directory containing the trace data on the + local file system. -'TRACEPATH':: - Absolute path to trace files on the local file system. +Network format:: ++ +[verse] +'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEDIR'] +{nbsp} ++ +This format is only available when you create the tracing session in +network streaming, snapshot (option:--snapshot), or live (option:--live) +mode (see the <> section above). ++ +'NETPROTO'::: + Network protocol, amongst: ++ +-- +`net`:: + TCP over IPv4. ++ +The default values of 'CTRLPORT' and 'DATAPORT' +are respectively {default_network_control_port} and +{default_network_data_port}. -The other version is used for *network streaming*. +`net6`:: + TCP over IPv6. ++ +The default values of 'CTRLPORT' and 'DATAPORT' +are respectively {default_network_control_port} and +{default_network_data_port}. -'NETPROTO':: - Network protocol, amongst: +`tcp`:: + Same as the `net` protocol. + -* `net`: TCP over IPv4; the default values of `` and - `` are resp. 5342 and 5343 -* `net6`: TCP over IPv6: same default ports as `net` protocol -* `tcp`: same as `net` protocol; can only be used with the - option:--ctrl-url and option:--data-url options together -* `tcp6`: same as `net6` protocol; can only be used with the - option:--ctrl-url and option:--data-url options together +You may only use this with the option:--ctrl-url and option:--data-url +options together. -('HOST' | 'IPADDR'):: - Hostname or IP address (IPv6 address *must* be enclosed in brackets - (`[` and `]`); see https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]). +`tcp6`:: + Same as the `net6` protocol. ++ +You can only be use this with the option:--ctrl-url and +option:--data-url options together. +-- ++ +('HOST' | 'IPADDR')::: + Hostname or IP address. ++ +IPv6 address must be enclosed in square brackets (`[` and{nbsp}`]`); +see https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732]. -'CTRLPORT':: - Control port. +'CTRLPORT'::: + Control TCP port. -'DATAPORT':: - Data port. +'DATAPORT'::: + Data TCP port. -'TRACEPATH':: - Path of trace files on the remote file system. This path is relative - to the base output directory set on the relay daemon side; - see linklttng:lttng-relayd(8). +'TRACEDIR'::: + Path of the directory containing the trace data on the remote file + system. ++ +This path is relative to the base output directory of the LTTng relay +daemon (see the nloption:--output option of man:lttng-relayd(8)). include::common-cmd-options-head.txt[] -Mode -~~~~ +Mode selection +~~~~~~~~~~~~~~ +See the <> section above. + +At most one of: + option:--live[='DELAYUS']:: - Create the session in live mode. The optional 'DELAYUS' parameter, - given in microseconds, is the maximum time the user can wait for - the data to be flushed. This mode can be set with a network URL - (options option:--set-url, or option:--ctrl-url and option:--data-url) - and must have a relay daemon listening (see linklttng:lttng-relayd(8)). + Create the tracing session in live mode. ++ +The optional 'DELAYUS' argument is the maximum time (in µs) you can wait +for the data to be flushed (sent to the connected LTTng relay daemon). +The default value of 'DELAYUS' is {default_lttng_live_timer}. + -By default, 'DELAYUS' is 1000000 and the network URL is set to -`net://127.0.0.1`. +Set the URL of the relay daemon to connect to with the option:--set-url +option, or with the option:--ctrl-url and option:--data-url options, +instead of using `net://127.0.0.1`. ++ +The session daemon must be able to connect to a listening relay daemon +(see man:lttng-relayd(8)). option:--snapshot:: - Create the session in snapshot mode. This is the equivalent of using - the option:--no-output option and creating all the channels of this - new tracing session in overwrite mode with an `mmap` output type. + Create the tracing session in snapshot mode. ++ +This is equivalent to: ++ +* One of: ++ +-- +With the option:--no-output option:: + Not adding any snapshot output after LTTng creates the tracing + session. + +With the option:--output option, the option:--set-url option, or the option:--ctrl-url and option:--data-url options:: + Adding a snapshot output named `snapshot-1` using the provided path + or URL(s) immediately after LTTng creates the tracing session. + +Otherwise:: + Adding an automatic snapshot output named `snapshot-1` immediately + after LTTng creates the tracing session. ++ +The automatic snapshot output is a subdirectory, under the +`$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`) +directory, of which the name contains the tracing session name and the +date/time. +-- + +* Forcing all the channels to be created for the tracing session to be + configured with the nloption:--override and nloption:--output=++mmap++ + options (see man:lttng-enable-channel(1)). Output ~~~~~~ option:--no-output:: - Do not output any trace data. + Depending on the tracing session mode (see the <> section above): ++ +Local mode::: + Disable the file system output. + +Snapshot mode (option:--snapshot option)::: + Do :not: add a snapshot output after creating the tracing session. -option:-o, option:--output='PATH':: - Set trace output path to 'PATH'. +option:-o 'DIR', option:--output='DIR':: + Equivalent to option:--set-url=++file://++__DIR__. -option:--shm-path='PATH':: - Create shared memory holding buffers at 'PATH'. +option:--shm-path='DIR':: + Set the path of the directory containing the shared memory files + holding the channel ring buffers to 'DIR' on the local file sytem. URL ~~~ -See the <> section above for more information -about the syntax of the following options' 'URL' argument. +See the <> section above to learn more about the +syntax of the 'URL' argument of the following options. + +option:-C 'URL', option:--ctrl-url='URL':: + Set the control path URL to 'URL'. ++ +You must also use the option:--data-url option. ++ +Not available in local mode (see the <> +section above). ++ +In snapshot mode, this is equivalent to using the nloption:--ctrl-url +option of the `add-output` action of the man:lttng-snapshot(1) command +immediately after creating the tracing session. -option:-C, option:--ctrl-url='URL':: - Set control path URL to 'URL' (must use option:--data-url option - also). +option:-D 'URL', option:--data-url='URL':: + Set the trace data path URL to 'URL'. ++ +You must also use the option:--ctrl-url option. ++ +Not available in local mode (see the <> +section above). ++ +In snapshot mode, this is equivalent to using the nloption:--data-url +option of the `add-output` action of the man:lttng-snapshot(1) command +immediately after creating the tracing session. + +option:-U 'URL', option:--set-url='URL':: + Set the destination URL of the control path and trace data to 'URL'. ++ +This URL remains unchanged as long as the tracing session exists. ++ +Depending on the tracing session mode (see the <> section above): ++ +Local mode::: + 'URL' must start with `file://`, followed with the destination + directory path on the local file system. -option:-D, option:--data-url='URL':: - Set data path URL to 'URL' (must use option:--ctrl-url option - also). +Network streaming and live modes::: + Equivalent to using both the option:--ctrl-url and option:--data-url + options. -option:-U, option:--set-url='URL':: - Set URL destination of the trace data to 'URL'. It is persistent for - the session lifetime. This option sets both data - (option:--data-url option) and control (option:--ctrl-url option) - URLs at the same time. +Snapshot mode (option:--snapshot option)::: + Equivalent to using the 'URL' non-option argument of the + `add-output` action of the man:lttng-snapshot(1) command immediately + after creating the tracing session. include::common-cmd-help-options.txt[] @@ -196,6 +367,16 @@ include::common-cmd-footer.txt[] SEE ALSO -------- -linklttng:lttng-destroy(1), -linklttng:lttng-set-session(1), -linklttng:lttng(1) +man:lttng(1), +man:lttng-concepts(7), +man:lttng-destroy(1), +man:lttng-enable-channel(1), +man:lttng-list(8), +man:lttng-relayd(8), +man:lttng-rotate(1), +man:lttng-save(1), +man:lttng-sessiond(8), +man:lttng-set-session(1), +man:lttng-start(1), +man:lttng-status(8), +man:lttng-track(1)