X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng-concepts.7.txt;h=a1bea3b9c522e75798821617581ff65c948520c4;hp=54718afd2d67eee93ed8dab4b41f885aac251f59;hb=e971184584781f70bbbfc52bbede8b9abf0436e5;hpb=7013e16714631ec4798f8700866e206239d83eb8 diff --git a/doc/man/lttng-concepts.7.txt b/doc/man/lttng-concepts.7.txt index 54718afd2..a1bea3b9c 100644 --- a/doc/man/lttng-concepts.7.txt +++ b/doc/man/lttng-concepts.7.txt @@ -1,8 +1,8 @@ lttng-concepts(7) ================= -:revdate: 3 May 2021 +:revdate: 14 June 2021 :sect-event-rule: INSTRUMENTATION POINT, EVENT RULE, AND EVENT -:sect-session: TRACING SESSION +:sect-session: RECORDING SESSION :sect-domain: TRACING DOMAIN :sect-channel: CHANNEL AND RING BUFFER :sect-recording-event-rule: RECORDING EVENT RULE AND EVENT RECORD @@ -25,7 +25,7 @@ The concepts of LTTng{nbsp}{lttng_version} are: * Instrumentation point, event rule, and event * Trigger -* Tracing session +* Recording session * Tracing domain * Channel and ring buffer * Recording event rule and event record @@ -38,8 +38,8 @@ An _instrumentation point_ is a point, within a piece of software, which, when executed, creates an LTTng _event_. LTTng offers various types of instrumentation; see the -<> section below to learn -about them. +``<>'' section below to +learn about them. An _event rule_ is a set of conditions to match a set of events. @@ -58,30 +58,30 @@ help understand the journey from an instrumentation point to the execution of actions. The actual creation of an event can be costly because LTTng needs to -evalute the arguments of the instrumentation point. +evaluate the arguments of the instrumentation point. In practice, LTTng implements various optimizations for the Linux kernel -and user space tracing domains (see the <> section -below) to avoid actually creating an event -when the tracer knows, thanks to properties which are independent from -the event payload and current context, that it would never emit such an -event. Those properties are: +and user space tracing domains (see the ``<>'' +section below) to avoid actually creating an event when the tracer +knows, thanks to properties which are independent from the event payload +and current context, that it would never emit such an event. Those +properties are: * The instrumentation point type (see the - <> section below). + ``<>'' section below). * The instrumentation point name. * The instrumentation point log level. * For a recording event rule (see the - <> section + ``<>'' section below): ** The status of the rule itself. -** The status of the channel (see the <> section - below). -** The activity of the tracing session (started or stopped; see - the <> section below). +** The status of the channel (see the ``<>'' + section below). +** The activity of the recording session (started or stopped; see + the ``<>'' section below). ** Whether or not the process for which LTTng would create the event is allowed to record events (see man:lttng-track(1)). @@ -98,20 +98,20 @@ Recording event rule:: A specific type of event rule of which the action is to record the matched event as an event record. + -See the <> section +See the ``<>'' section below. + Create or enable a recording event rule with the man:lttng-enable-event(1) command. + -List the recording event rules of a specific tracing session +List the recording event rules of a specific recording session and/or channel with the man:lttng-list(1) and man:lttng-status(1) commands. ``Event rule matches'' <> condition (since LTTng{nbsp}2.13):: When the event rule of the trigger condition matches an event, LTTng can execute user-defined actions such as sending an LTTng - notification, starting a tracing session, and more. + notification, starting a recording session, and more. + See man:lttng-add-trigger(1) and man:lttng-event-rule(7). @@ -121,7 +121,8 @@ basic conditions of an event rule{nbsp}__ER__, that is: * The instrumentation point from which LTTng creates{nbsp}__E__ has a specific type. + -See the <> section below. +See the ``<>'' section +below. * A pattern matches the name of{nbsp}__E__ while another pattern doesn't. @@ -134,7 +135,7 @@ See the <> section below. satisfy a filter expression. A recording event rule has additional, implicit conditions to satisfy. -See the <> section +See the ``<>'' section below to learn more. @@ -143,7 +144,7 @@ Instrumentation point types ~~~~~~~~~~~~~~~~~~~~~~~~~~~ As of LTTng{nbsp}{lttng_version}, the available instrumentation point types are, depending on the tracing domain (see the -<> section below): +``<>'' section below): Linux kernel:: LTTng tracepoint::: @@ -222,20 +223,20 @@ actions are: Conditions:: + -* The consumed buffer size of a given tracing - session (see the <> section below) +* The consumed buffer size of a given recording + session (see the ``<>'' section below) becomes greater than some value. * The buffer usage of a given channel (see the - <> section below) becomes greater than some - value. + ``<>'' section below) becomes greater than + some value. * The buffer usage of a given channel becomes less than some value. -* There's an ongoing tracing session rotation (see the - <> section below). +* There's an ongoing recording session rotation (see the + ``<>'' section below). -* A tracing session rotation becomes completed. +* A recording session rotation becomes completed. * An event rule matches an event. + @@ -246,15 +247,15 @@ other ones are available through the liblttng-ctl C{nbsp}API. Actions:: + * Send a notification to a user application. -* Start a given tracing session, like man:lttng-start(1) would do. -* Stop a given tracing session, like man:lttng-stop(1) would do. -* Archive the current trace chunk of a given tracing session (rotate), +* Start a given recording session, like man:lttng-start(1) would do. +* Stop a given recording session, like man:lttng-stop(1) would do. +* Archive the current trace chunk of a given recording session (rotate), like man:lttng-rotate(1) would do. -* Take a snapshot of a given tracing session, like man:lttng-snapshot(1) - would do. +* Take a snapshot of a given recording session, like + man:lttng-snapshot(1) would do. A trigger belongs to a session daemon (see man:lttng-sessiond(8)), not -to a specific tracing session. For a given session daemon, each Unix +to a specific recording session. For a given session daemon, each Unix user has its own, private triggers. Note, however, that the `root` Unix user may, for the root session daemon: @@ -278,12 +279,12 @@ Remove a trigger with the man:lttng-remove-trigger(1) command. [[session]] {sect-session} -------------- -A _tracing session_ is a stateful dialogue between you and a session -daemon (see man:lttng-sessiond(8)) for everything related to event -recording. +A _recording session_ (named ``tracing session'' prior to +LTTng{nbsp}2.13) is a stateful dialogue between you and a session daemon +(see man:lttng-sessiond(8)) for everything related to event recording. Everything that you do when you control LTTng tracers to record events -happens within a tracing session. In particular, a tracing session: +happens within a recording session. In particular, a recording session: * Has its own name, unique for a given session daemon. @@ -291,64 +292,64 @@ happens within a tracing session. In particular, a tracing session: * Has its own state of activity (started or stopped). + -An active tracing session is an implicit recording event rule condition -(see the <> section -below). +An active recording session is an implicit recording event rule +condition (see the +``<>'' section below). * Has its own mode (local, network streaming, snapshot, or live). + -See the <> section below to learn -more. +See the ``<>'' section below to +learn more. -* Has its own channels (see the <> section +* Has its own channels (see the ``<>'' section below) to which are attached their own recording event rules. * Has its own process attribute inclusion sets (see man:lttng-track(1)). Those attributes and objects are completely isolated between different -tracing sessions. +recording sessions. -A tracing session is like an ATM session: the operations you do on the +A recording session is like an ATM session: the operations you do on the banking system through the ATM don't alter the data of other users of the same system. In the case of the ATM, a session lasts as long as your -bank card is inside. In the case of LTTng, a tracing session lasts from +bank card is inside. In the case of LTTng, a recording session lasts from the man:lttng-create(1) command to the man:lttng-destroy(1) command. -A tracing session belongs to a session daemon (see +A recording session belongs to a session daemon (see man:lttng-sessiond(8)). For a given session daemon, each Unix user has -its own, private tracing sessions. Note, however, that the `root` Unix -user may operate on or destroy another user's tracing session. +its own, private recording sessions. Note, however, that the `root` Unix +user may operate on or destroy another user's recording session. -Create a tracing session with the man:lttng-create(1) command. +Create a recording session with the man:lttng-create(1) command. -List the tracing sessions of the connected session daemon with +List the recording sessions of 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 of (rotate) a tracing session with the +Archive the current trace chunk of (rotate) a recording session with the man:lttng-rotate(1) command. -Destroy a tracing session with the man:lttng-destroy(1) command. +Destroy a recording session with the man:lttng-destroy(1) command. -Current tracing session +Current recording session ~~~~~~~~~~~~~~~~~~~~~~~ When you run the man:lttng-create(1) 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 +`$LTTNG_HOME/.lttngrc` contains the name of the _current recording session_. -When you create a new tracing session with the `create` command, LTTng -updates the current tracing session. +When you create a new recording session with the `create` command, LTTng +updates the current recording session. -The following man:lttng(1) commands select the current tracing session +The following man:lttng(1) commands select the current recording session if you don't specify one: * man:lttng-add-context(1) @@ -371,15 +372,15 @@ if you don't specify one: * man:lttng-untrack(1) * man:lttng-view(1) -Set the current tracing session manually with the +Set the current recording session manually with the man:lttng-set-session(1) command, without having to edit the `.lttngrc` file. [[session-modes]] -Tracing session modes -~~~~~~~~~~~~~~~~~~~~~ -LTTng offers four tracing session modes: +Recording session modes +~~~~~~~~~~~~~~~~~~~~~~~ +LTTng offers four recording session modes: Local mode:: Write the trace data to the local file system. @@ -393,16 +394,16 @@ Snapshot mode:: listening relay daemon (man:lttng-relayd(8)) when LTTng takes a snapshot. + -LTTng forces all the channels (see the <> +LTTng forces all the channels (see the ``<>'' section below) to be created to be configured to be snapshot-ready. + -LTTng takes a snapshot of such a tracing session when: +LTTng takes a snapshot of such a recording session when: + -- * You run the man:lttng-snapshot(1) command. * LTTng executes a `snapshot-session` trigger action (see the - <> section above). + ``<>'' section above). -- Live mode:: @@ -410,33 +411,33 @@ Live mode:: (see man:lttng-relayd(8)) for live reading. + An LTTng live reader (for example, man:babeltrace2(1)) can connect to -the same relay daemon to receive trace data while the tracing session is +the same relay daemon to receive trace data while the recording session is active. [[rotation]] -Tracing session rotation -~~~~~~~~~~~~~~~~~~~~~~~~ -A _tracing session rotation_ is the action of archiving the current -trace chunk of the tracing session to the file system. +Recording session rotation +~~~~~~~~~~~~~~~~~~~~~~~~~~ +A _recording session rotation_ is the action of archiving the current +trace chunk of the recording session to the file system. Once LTTng archives a trace chunk, it does :not: manage it anymore: you can read it, modify it, move it, or remove it. An _archived trace chunk_ is a collection of metadata and data stream files which form a self-contained LTTng trace. See the -<> section below to learn how +``<>'' section below to learn how LTTng names a trace chunk archive directory. -The _current trace chunk_ of a given tracing session includes: +The _current trace chunk_ of a given recording session includes: * The stream files which LTTng already wrote to the file system, and which are not part of a previously archived trace chunk, since the most recent event amongst: -** The first time the tracing session was started, either with the +** The first time the recording session was started, either with the man:lttng-start(1) command or with a `start-session` trigger action - (see the <> section above). + (see the ``<>'' section above). ** The last rotation, performed with: @@ -446,17 +447,17 @@ The _current trace chunk_ of a given tracing session includes: man:lttng-enable-rotation(1). *** An executed `rotate-session` trigger action (see the - <> section above). + ``<>'' section above). * The content of all the non-flushed sub-buffers of the channels of the - tracing session. + recording session. [[trace-chunk-naming]] Trace chunk archive naming ~~~~~~~~~~~~~~~~~~~~~~~~~~ A trace chunk archive is a subdirectory of the `archives` subdirectory -within the output directory of a tracing session (see the +within the output directory of a recording session (see the nloption:--output option of the man:lttng-create(1) command and of man:lttng-relayd(8)). @@ -468,15 +469,15 @@ A trace chunk archive is, at the same time: * A self-contained LTTng trace. * A member of a set of trace chunk archives which form the complete - trace of a tracing session. + trace of a recording session. -In other words, an LTTng trace reader can read both the tracing +In other words, an LTTng trace reader can read both the recording session output directory (all the trace chunk archives), or a single trace chunk archive. -When LTTng performs a tracing session rotation, it names the resulting +When LTTng performs a recording session rotation, it names the resulting trace chunk archive as such, relative to the output directory of the -tracing session: +recording session: [verse] archives/__BEGIN__-__END__-__ID__ @@ -498,7 +499,7 @@ __END__:: Example: `20180118T152407+0930` __ID__:: - Unique numeric identifier of the trace chunk within its tracing + Unique numeric identifier of the trace chunk within its recording session. Trace chunk archive name example: @@ -522,23 +523,23 @@ There are currently five available tracing domains: |Tracing domain |``Event rule matches'' trigger condition option |Option for other CLI commands |Linux kernel -|nloption:--domain=++kernel++ +|nloption:--type option starts with `kernel:` |nloption:--kernel |User space -|nloption:--domain=++user++ +|nloption:--type option starts with `user:` |nloption:--userspace |`java.util.logging` (JUL) -|nloption:--domain=++jul++ +|nloption:--type option starts with `jul:` |nloption:--jul |Apache log4j -|nloption:--domain=++log4j++ +|nloption:--type option starts with `log4j:` |nloption:--log4j |Python -|nloption:--domain=++python++ +|nloption:--type option starts with `python:` |nloption:--python |=== @@ -546,11 +547,11 @@ You must specify a tracing domain to target a type of LTTng tracer when using some man:lttng(1) commands to avoid ambiguity. For example, because the Linux kernel and user space tracing domains support named tracepoints as instrumentation points (see the -<<"event-rule","{sect-event-rule}">> section above), you need to specify -a tracing domain when you create an event rule because both tracing -domains could have tracepoints sharing the same name. +``<<"event-rule","{sect-event-rule}">>'' section above), you need to +specify a tracing domain when you create an event rule because both +tracing domains could have tracepoints sharing the same name. -You can create channels (see the <> section +You can create channels (see the ``<>'' section below) in the Linux kernel and user space tracing domains. The other tracing domains have a single, default channel. @@ -562,7 +563,7 @@ A _channel_ is an object which is responsible for a set of ring buffers. Each ring buffer is divided into multiple _sub-buffers_. When a recording event rule (see the -<>'' section below) matches an event, LTTng can record it to one or more sub-buffers of one or more channels. @@ -571,28 +572,29 @@ you set its final attributes, that is: * Its buffering scheme. + -See the <> section below. +See the ``<>'' section below. * What to do when there's no space left for a new event record because all sub-buffers are full. + -See the <> section below. +See the ``<>'' section +below. * The size of each ring buffer and how many sub-buffers a ring buffer has. + -See the <> section -below. +See the ``<>'' +section below. * The size of each trace file LTTng writes for this channel and the maximum count of trace files. + -See the <> section below. +See the ``<>'' section below. * The periods of its read, switch, and monitor timers. + -See the <> section below. +See the ``<>'' section below. * For a Linux kernel channel: its output type (man:mmap(2) or man:splice(2)). @@ -610,13 +612,13 @@ a default channel with sane defaults when no channel exists for the provided tracing domain. A channel is always associated to a tracing domain (see the -<> section below). The `java.util.logging` (JUL), -log4j, and Python tracing domains each have a default channel which you -can't configure. +``<>'' section below). The `java.util.logging` +(JUL), log4j, and Python tracing domains each have a default channel +which you can't configure. A channel owns recording event rules. -List the channels of a given tracing session with the +List the channels of a given recording session with the man:lttng-list(1) and man:lttng-status(1) commands. Disable an enabled channel with the man:lttng-disable-channel(1) @@ -716,11 +718,12 @@ similar to the roll mode of an oscilloscope. + Since LTTng{nbsp}2.8, with this mode, LTTng writes to a given sub-buffer its sequence number within its data stream. With a local, network -streaming, or live tracing session (see the <> section above), a trace reader can use such sequence -numbers to report lost packets. A trace reader can use the saved -discarded sub-buffer (packet) count of the trace to decide whether or -not to perform some analysis even if trace data is known to be missing. +streaming, or live recording session (see the +``<>'' section above), a trace +reader can use such sequence numbers to report lost packets. A trace +reader can use the saved discarded sub-buffer (packet) count of the +trace to decide whether or not to perform some analysis even if trace +data is known to be missing. + With this mode, LTTng doesn't write to the trace the exact number of lost event records in the lost sub-buffers. @@ -738,10 +741,10 @@ and nloption:--overwrite options of the man:lttng-enable-channel(1) command. There are a few ways to decrease your probability of losing event -records. The <> -section below shows how to fine-tune the sub-buffer size and count of a -channel to virtually stop losing event records, though at the cost of -greater memory usage. +records. The ``<>'' section below shows how to fine-tune the sub-buffer size and +count of a channel to virtually stop losing event records, though at the +cost of greater memory usage. [[channel-sub-buf-size-count]] @@ -749,8 +752,8 @@ Sub-buffer size and count ~~~~~~~~~~~~~~~~~~~~~~~~~ A channel has one or more ring buffer for each CPU of the target system. -See the <> section above to learn -how many ring buffers of a given channel are dedicated to each CPU +See the ``<>'' section above to +learn how many ring buffers of a given channel are dedicated to each CPU depending on its buffering scheme. Set the size of each sub-buffer the ring buffers of a channel contain @@ -772,12 +775,12 @@ High event throughput:: event records. + Having larger sub-buffers also ensures a lower sub-buffer switching -frequency (see the <> section below). +frequency (see the ``<>'' section below). + The sub-buffer count is only meaningful if you create the channel in -overwrite mode (see the <> -section above): in this case, if LTTng overwrites a sub-buffer, then the -other sub-buffers are left unaltered. +overwrite mode (see the ``<>'' section above): in this case, if LTTng overwrites a sub-buffer, +then the other sub-buffers are left unaltered. Low event throughput:: In general, prefer smaller sub-buffers since the risk of losing @@ -843,15 +846,15 @@ file. This mechanism is called _trace file rotation_. [IMPORTANT] ==== Even if you don't limit the trace file count, always assume that LTTng -manages all the trace files of the tracing session. +manages all the trace files of the recording session. In other words, there's no safe way to know if LTTng still holds a given trace file open with the trace file rotation feature. The only way to obtain an unmanaged, self-contained LTTng trace before -you destroy the tracing session is with the tracing session rotation -feature (see the <> section above), -which is available since LTTng{nbsp}2.11. +you destroy the recording session is with the recording session rotation +feature (see the ``<>'' section +above), which is available since LTTng{nbsp}2.11. ==== @@ -871,9 +874,9 @@ data to trace files or to a distant relay daemon (man:lttng-relayd(8)) periodically in case of a low event throughput. + Such a timer is also convenient when you use large sub-buffers (see the -<> section above) -to cope with a sporadic high event throughput, even if the throughput is -otherwise low. +``<>'' section +above) to cope with a sporadic high event throughput, even if the +throughput is otherwise low. + Set the period of the switch timer of a channel, or disable the timer altogether, with the nloption:--switch-timer option of the @@ -895,11 +898,10 @@ man:lttng-enable-channel(1) command. Monitor timer:: When this timer expires, the consumer daemon samples some channel - (see the <> section above) statistics to evaluate the following trigger conditions: + -- -. The consumed buffer size of a given tracing session becomes greater +. The consumed buffer size of a given recording session becomes greater than some value. . The buffer usage of a given channel becomes greater than some value. . The buffer usage of a given channel becomes less than some value. @@ -908,7 +910,7 @@ Monitor timer:: If you disable the monitor timer of a channel{nbsp}__C__: + -- -* The consumed buffer size value of the tracing session of{nbsp}__C__ +* The consumed buffer size value of the recording session of{nbsp}__C__ could be wrong for trigger condition type{nbsp}1: the consumed buffer size of{nbsp}__C__ won't be part of the grand total. @@ -916,7 +918,8 @@ If you disable the monitor timer of a channel{nbsp}__C__: for{nbsp}__C__ will never be satisfied. -- + -See the <> section above to learn more about triggers. +See the ``<>'' section above to learn more about +triggers. + Set the period of the monitor timer of a channel, or disable the timer altogether, with the nloption:--monitor-timer option of the @@ -927,8 +930,9 @@ man:lttng-enable-channel(1) command. {sect-recording-event-rule} --------------------------- A _recording event rule_ is a specific type of event rule (see the -<<"event-rule","{sect-event-rule}">> section above) of which the action is -to serialize and record the matched event as an _event record_. +``<<"event-rule","{sect-event-rule}">>'' section above) of which the +action is to serialize and record the matched event as an _event +record_. Set the explicit conditions of a recording event rule when you create it with the man:lttng-enable-event(1) command. A recording event rule also @@ -942,18 +946,18 @@ A recording event rule is enabled on creation. + A channel is enabled on creation. + -See the <> section above. +See the ``<>'' section above. -* The tracing session of the recording event rule is active (started). +* The recording session of the recording event rule is active (started). + -A tracing session is inactive (stopped) on creation. +A recording session is inactive (stopped) on creation. + -See the <> section above. +See the ``<>'' section above. * The process for which LTTng creates an event to match is allowed to record events. + -All processes are allowed to record events on tracing session +All processes are allowed to record events on recording session creation. + Use the man:lttng-track(1) and man:lttng-untrack(1) commands to select @@ -961,7 +965,7 @@ which processes are allowed to record events based on specific process attributes. You always attach a recording event rule to a channel, which belongs to -a tracing session, when you create it. +a recording session, when you create it. When a recording event rule{nbsp}__ER__ matches an event{nbsp}__E__, LTTng attempts to serialize and record{nbsp}__E__ to one of the @@ -978,7 +982,7 @@ $ lttng enable-event --userspace hello:world $ lttng enable-event --userspace hello:world --loglevel=INFO ---- -List the recording event rules of a specific tracing session +List the recording event rules of a specific recording session and/or channel with the man:lttng-list(1) and man:lttng-status(1) commands. @@ -986,7 +990,7 @@ Disable a recording event rule with the man:lttng-disable-event(1) command. As of LTTng{nbsp}{lttng_version}, you cannot remove a recording event -rule: it exists as long as its tracing session exists. +rule: it exists as long as its recording session exists. include::common-footer.txt[]