X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-create.1.txt;h=4e997e1d10a0720ca3dbaebca0fa35b592c55d13;hb=da39b67ce2828bfc63a02db969048bfe1abd4ca0;hp=5b5f7b62eebecd3f2545a543acf58c731063548b;hpb=f5511eeafdb40b9589306519633566c3be48756c;p=lttng-tools.git diff --git a/doc/man/lttng-create.1.txt b/doc/man/lttng-create.1.txt index 5b5f7b62e..4e997e1d1 100644 --- a/doc/man/lttng-create.1.txt +++ b/doc/man/lttng-create.1.txt @@ -1,6 +1,6 @@ lttng-create(1) =============== -:revdate: 3 May 2021 +:revdate: 17 May 2021 NAME @@ -55,15 +55,44 @@ 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. -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. +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. + +* A relay daemon (see man:lttng-relayd(8)) if all the following + statements are true: ++ +-- +* You specify the option:--live option. + +* You don't specify any of the option:--set-url, option:--ctrl-url, or + option:--data-url options. + +* 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. On success, the `create` command sets the current tracing session (see man:lttng-concepts(7) to learn more) to the created tracing session. +See the ``<>'' section below for usage examples. + Show the status of the current tracing session with the man:lttng-status(1) command. @@ -114,7 +143,7 @@ Otherwise::: + 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):: Only write the trace data to the local file system or send it to a @@ -146,8 +175,8 @@ date/time. + 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]] @@ -166,8 +195,8 @@ file://'TRACEDIR' + 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). +session in local or snapshot mode (see the ``<>'' section above). + 'TRACEDIR'::: Absolute path to the directory containing the trace data on the @@ -181,7 +210,7 @@ Network format:: + 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). +mode (see the ``<>'' section above). + 'NETPROTO'::: Network protocol, amongst: @@ -239,7 +268,7 @@ include::common-lttng-cmd-options-head.txt[] Mode selection ~~~~~~~~~~~~~~ -See the <> section above. +See the ``<>'' section above. At most one of: @@ -291,8 +320,8 @@ date/time. Output ~~~~~~ option:--no-output:: - Depending on the tracing session mode (see the <> section above): + Depending on the tracing session mode (see the ``<>'' section above): + Local mode::: Disable the file system output. @@ -310,15 +339,15 @@ option:--shm-path='DIR':: 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 <> +Not available in local mode (see the ``<>'' section above). + In snapshot mode, this is equivalent to using the nloption:--ctrl-url @@ -330,7 +359,7 @@ option:-D 'URL', option:--data-url='URL':: + You must also use the option:--ctrl-url option. + -Not available in local mode (see the <> +Not available in local mode (see the ``<>'' section above). + In snapshot mode, this is equivalent to using the nloption:--data-url @@ -342,8 +371,8 @@ option:-U 'URL', option:--set-url='URL':: + This URL remains unchanged as long as the tracing session exists. + -Depending on the tracing session mode (see the <> section above): +Depending on the tracing session mode (see the ``<>'' section above): + Local mode::: 'URL' must start with `file://`, followed with the destination @@ -365,6 +394,112 @@ include::common-lttng-cmd-help-options.txt[] include::common-lttng-cmd-after-options.txt[] +[[examples]] +EXAMPLES +-------- +.Create a normal mode tracing session with a generated name. +==== +[role="term"] +---- +$ lttng create +---- +==== + +.Create a normal mode tracing session with a custom name. +==== +[role="term"] +---- +$ lttng create my-session +---- +==== + +.Create a normal mode tracing session with a specific output directory. +==== +See the option:--output option. + +[role="term"] +---- +$ lttng create --output=/path/to/traces +---- +==== + +.Create a network streaming mode tracing 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 tracing session with a default snapshot output. +==== +See the option:--snapshot option. + +[role="term"] +---- +$ lttng create --snapshot +---- +==== + +.Create a snapshot mode tracing 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 tracing 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 tracing session with a default relay daemon URL. +==== +See the option:--live option. + +[role="term"] +---- +$ lttng create --live +---- +==== + +.Create an LTTng live mode tracing 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 tracing 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[]