X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-create.1.txt;h=42fdf651e4f807deb0b685de8389f60dd0236094;hb=bc13dc0f9eaa7742a589ce6d8faece4990f77f75;hp=b1032fb5e9aca52fa1d6334c753c7433ac83708c;hpb=484b2a0cbefcf0c7072622a5a411ea5ed849da28;p=lttng-tools.git diff --git a/doc/man/lttng-create.1.txt b/doc/man/lttng-create.1.txt index b1032fb5e..42fdf651e 100644 --- a/doc/man/lttng-create.1.txt +++ b/doc/man/lttng-create.1.txt @@ -1,34 +1,35 @@ lttng-create(1) =============== -:revdate: 8 April 2021 +:revdate: 7 December 2021 NAME ---- -lttng-create - Create an LTTng tracing session +lttng-create - Create an LTTng recording session SYNOPSIS -------- -Create a local mode tracing session: +Create a local mode recording session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR'] - [option:--no-output | option:--output='DIR' | option:--set-url=file://'DIR'] + [option:--no-output | option:--output='DIR' | option:--set-url=**file://**__DIR__] -Create a network streaming mode tracing session: +Create a network streaming mode recording session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR'] (option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL') -Create a snapshot mode tracing session: +Create a snapshot mode recording session: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--snapshot - [option:--shm-path='DIR'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] +*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: +Create a live mode recording session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--live[='DELAYUS'] @@ -36,125 +37,107 @@ Create a live mode tracing session: DESCRIPTION ----------- -The `lttng create` command creates a new tracing session for your Unix -user. +The `lttng create` command creates a new recording 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 stateful dialogue between you and a -session daemon (see man:lttng-sessiond(8)) for everything related to -event recording. +See man:lttng-concepts(7) to learn more about recording sessions. -Everything that you do when you control LTTng tracers to record events -happens within a tracing session. In particular, a tracing session: +Without the 'SESSION' argument, LTTng automatically generates a recording +session name having the ++auto-++__YYYYmmdd__++-++__HHMMSS__ form, where +'YYYYmmdd' and 'HHMMSS' are the creation date and time. 'SESSION' may +:not: contain the character `/`. -* Has its own name. +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. Note that, as of +LTTng{nbsp}{lttng_version}, this feature is only available for user +space channels. -* Has its own set of trace files, if any. +By default, the `create` command automatically spawns: -* Has its own state of activity (started or stopped). +* 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. -* Has its own mode (local, network streaming, - snapshot, or live). +* A relay daemon (see man:lttng-relayd(8)) if all the following + statements are true: + -See the <> section below to learn more. +-- +* You specify the option:--live option. -* Has its own channels (see man:lttng-enable-channel(1)) to which are - attached their own recording event rules (see - man:lttng-enable-event(1)). +* You don't specify any of the option:--set-url, option:--ctrl-url, or + option:--data-url options. -* Has its own process attribute tracking inclusion sets (see - man:lttng-track(1)). +* No relay daemon is currently listening for TCP connections on + +127.0.0.1:{default_network_viewer_port}+ (default LTTng live reader + connection address and port). +-- ++ +In this case, the `create` command spawns a relay daemon as such: ++ +[verse] +*lttng-relayd* nloption:--live-port=**tcp://localhost:{default_network_viewer_port}** +{nbsp} ++ +Override the path of the relay daemon binary to spawn with the general +genoption:--relayd-path option. -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 `/`. +On success, the `create` command sets the current recording session (see +man:lttng-concepts(7) to learn more) to the created recording session. -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. +See the ``<>'' section below for usage examples. -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. +Show the status of the current recording session with the +man:lttng-status(1) command. -List the tracing sessions of your Unix user with the man:lttng-list(1) -command. +List the recording 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 +Start and stop a recording 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 +Save and load a recording session with the man:lttng-save(1) and man:lttng-load(1) commands. -Archive the current trace chunk (rotate) a tracing session with the -man:lttng-rotate(1) command. - -Destroy a tracing session with the man:lttng-destroy(1) command. +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 recording session with the +man:lttng-rotate(1) command. -Current tracing session -~~~~~~~~~~~~~~~~~~~~~~~ -When you run the `create` command, LTTng creates the -`$LTTNG_HOME/.lttngrc` file if it doesn't exist (`$LTTNG_HOME` defaults -to `$HOME`). - -`$LTTNG_HOME/.lttngrc` contains the name of the _current tracing -session_. - -When you create a new tracing session with the `create` command, LTTng -updates the current tracing session. - -The following man:lttng(1) commands select the current tracing session -if you don't specify one: - -* man:lttng-add-context(1) -* man:lttng-clear(1) -* man:lttng-destroy(1) -* man:lttng-disable-channel(1) -* man:lttng-disable-event(1) -* man:lttng-disable-rotation(1) -* man:lttng-enable-channel(1) -* man:lttng-enable-event(1) -* man:lttng-enable-rotation(1) -* man:lttng-regenerate(1) -* man:lttng-rotate(1) -* man:lttng-save(1) -* man:lttng-snapshot(1) -* man:lttng-start(1) -* man:lttng-status(1) -* man:lttng-stop(1) -* man:lttng-track(1) -* man:lttng-untrack(1) -* man:lttng-view(1) - -Set the current tracing session manually with the -man:lttng-set-session(1) command, without having to edit the `.lttngrc` -file. +Destroy a recording session with the man:lttng-destroy(1) command. [[modes]] -Tracing session modes -~~~~~~~~~~~~~~~~~~~~~ -LTTng offers four tracing session modes: +Recording session modes +~~~~~~~~~~~~~~~~~~~~~~~ +As documented in man:lttng-concepts(7), LTTng offers four recording +session modes: [[local-mode]]Local mode:: Write the trace data to the local file system. + -The option:--output option specifies the trace path. Using -option:--set-url=++file://++__DIR__ is equivalent to using -option:--output='DIR'. -+ -Disable the file system output with the -option:--no-output option. +The trace data output directory is: + -If you don't use any of the option:--output, option:--set-url, or -option:--no-output options, then LTTng writes the trace data locally to -the `$LTTNG_HOME/lttng-traces` directory (`$LTTNG_HOME` defaults to -`$HOME`). +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 + recording session name and the date/time. [[network-streaming-mode]]Network streaming mode:: Send the trace data over the network to a listening relay daemon @@ -162,29 +145,31 @@ the `$LTTNG_HOME/lttng-traces` directory (`$LTTNG_HOME` defaults to + 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). +``<>'' section below). [[snapshot-mode]]Snapshot mode (option:--snapshot option):: - Don't write the trace data to the local file system by default - (implicit option:--no-output 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. -+ -LTTng automatically configures the channels of such a tracing session to -be snapshot-ready on creation (see man:lttng-enable-channel(1)). + 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). + -LTTng takes a snapshot of such a tracing session when: +With this mode, LTTng: + --- -* You run the man:lttng-snapshot(1) command. -* LTTng executes a `snapshot-session` trigger action (see - man:lttng-add-trigger(1)). --- +With the option:--no-output option::: + Does :not: add any snapshot output to the created recording + 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 recording session. + +Otherwise::: + Adds an automatic snapshot output named `snapshot-1` to the created + recording session. + -Set the default snapshot output destination with the -option:--set-url option, or with the option:--ctrl-url and -option:--data-url options (see the <> section -below). +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 recording 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 @@ -192,17 +177,17 @@ below). + 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://`. +(see the ``<>'' section below). 'URL' may :not: +start with `file://`. [[url-format]] URL format ~~~~~~~~~~ -The argument of the option:--set-url, option:--ctrl-url, and -option:--data-url options is an URL. +The argument of the option:--set-url='URL', option:--ctrl-url='URL', and +option:--data-url='URL' options is an URL. -There are two available URL formats. +There are two available 'URL' formats. Local format:: + @@ -211,9 +196,9 @@ 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). +such an URL with the option:--set-url option when you create the +recording session in local or snapshot mode (see the ``<>'' section above). + 'TRACEDIR'::: Absolute path to the directory containing the trace data on the @@ -225,9 +210,9 @@ Network format:: 'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEDIR'] {nbsp} + -This format is only available when you create the tracing session in -network streaming, snapshot, or live mode (see the <> section above). +This format is only available when you create the recording session in +network streaming, snapshot (option:--snapshot), or live (option:--live) +mode (see the ``<>'' section above). + 'NETPROTO'::: Network protocol, amongst: @@ -261,9 +246,10 @@ 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]). + 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 TCP port. @@ -279,17 +265,17 @@ 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[] +include::common-lttng-cmd-options-head.txt[] Mode selection ~~~~~~~~~~~~~~ -See the <> section above. +See the ``<>'' section above. At most one of: option:--live[='DELAYUS']:: - Create the tracing session in live mode. + Create the recording 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). @@ -303,61 +289,224 @@ The session daemon must be able to connect to a listening relay daemon (see man:lttng-relayd(8)). option:--snapshot:: - Create the tracing session in snapshot mode. + Create the recording session in snapshot mode. ++ +This is equivalent to: ++ +* One of: + -This is equivalent to using the option:--no-output option and creating -all the channels of this new tracing session with the -nloption:--override and nloption:--output=++mmap++ options (see -man:lttng-enable-channel(1)). +-- +With the option:--no-output option:: + Not adding any snapshot output after LTTng creates the recording + 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 recording session. + +Otherwise:: + Adding an automatic snapshot output named `snapshot-1` immediately + after LTTng creates the recording 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 recording session name and the +date/time. +-- + +* Forcing all the channels to be created for the recording session to be + configured with the nloption:--override and nloption:--output=++mmap++ + options (see man:lttng-enable-channel(1)). Output ~~~~~~ option:--no-output:: - In local mode (see the <> section - above), do :not: write any trace data. + Depending on the recording session mode (see the ``<>'' section above): + -You may :not: use this option with the option:--output option. +Local mode::: + Disable the file system output. + +Snapshot mode (option:--snapshot option)::: + Do :not: add a snapshot output after creating the recording session. option:-o 'DIR', option:--output='DIR':: - In local mode, set the trace output path to 'DIR'. -+ -You may :not: use this option with the option:--no-output option. + Equivalent to option:--set-url=++file://++__DIR__. 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. ++ +NOTE: As of LTTng{nbsp}{lttng_version}, LTTng only considers this option +for user space (including Java and Python) channels, but this may change +in the future. URL ~~~ -See the <> section above to learn more about the -syntax of the 'URL' argument of the following options. +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 recording session. 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 recording session. option:-U 'URL', option:--set-url='URL':: Set the destination URL of the control path and trace data to 'URL'. + -This URL stays the same as long as the tracing session exists. +This URL remains unchanged as long as the recording session exists. ++ +Depending on the recording session mode (see the ``<>'' section above): + -In local mode (see the <> section above), -'URL' must start with `file://`, followed with the destination directory -path on the local file system. +Local mode::: + 'URL' must start with `file://`, followed with the destination + directory path on the local file system. + +Network streaming and live modes::: + Equivalent to using both the option:--ctrl-url and option:--data-url + options. + +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 recording session. + + +include::common-lttng-cmd-help-options.txt[] + +include::common-lttng-cmd-after-options.txt[] -include::common-cmd-help-options.txt[] +[[examples]] +EXAMPLES +-------- +.Create a normal mode recording session with a generated name. +==== +[role="term"] +---- +$ lttng create +---- +==== + +.Create a normal mode recording session with a custom name. +==== +[role="term"] +---- +$ lttng create my-session +---- +==== -include::common-cmd-footer.txt[] +.Create a normal mode recording session with a specific output directory. +==== +See the option:--output option. + +[role="term"] +---- +$ lttng create --output=/path/to/traces +---- +==== + +.Create a network streaming mode recording session. +==== +See the ``Output directory'' section of man:lttng-relayd(8) to +understand where the relay daemon to connect to (`10.0.0.242`) writes +the received traces. + +See the option:--set-url option. + +[role="term"] +---- +$ lttng create --set-url=net://10.0.0.242/inv4 +---- +==== + +.Create a snapshot mode recording session with a default snapshot output. +==== +See the option:--snapshot option. + +[role="term"] +---- +$ lttng create --snapshot +---- +==== + +.Create a snapshot mode recording session with a custom snapshot output. +==== +See the option:--snapshot and option:--set-url options. + +[role="term"] +---- +$ lttng create --snapshot \ + --set-url=tcp://192.168.1.102:1234:5678/my-snapshots +---- +==== + +.Create a snapshot mode recording session with no snapshot output. +==== +See the option:--snapshot and option:--no-output options. + +[role="term"] +---- +$ lttng create --snapshot --no-output +---- +==== + +.Create an LTTng live mode recording session with a default relay daemon URL. +==== +See the option:--live option. + +[role="term"] +---- +$ lttng create --live +---- +==== + +.Create an LTTng live mode recording session with a custom live timer period and relay daemon URL. +==== +See the option:--live and option:--set-url options. + +[role="term"] +---- +$ lttng create --live=250000 \ + --set-url=tcp://relayd34:4885:4886 +---- +==== + +.Create a normal mode recording session with a custom directory containing the ring buffer shared memory files. +==== +See the option:--shm-path option. + +[role="term"] +---- +$ lttng create my-session --shm-path=/mnt/nvram2/lttng +---- +==== + + +include::common-footer.txt[] SEE ALSO @@ -365,10 +514,13 @@ SEE ALSO man:lttng(1), man:lttng-destroy(1), man:lttng-enable-channel(1), -man:lttng-relayd(8), +man:lttng-list(1), man:lttng-rotate(1), -man:lttng-sessiond(8), +man:lttng-save(1), man:lttng-set-session(1), man:lttng-start(1), -man:lttng-stop(1), -man:lttng-track(1) +man:lttng-status(1), +man:lttng-track(1), +man:lttng-concepts(7), +man:lttng-relayd(8), +man:lttng-sessiond(8)