instance, \-C does not enable the consumer automatically. You'll need the \-e
option for that.
-\-U, \-\-set-uri=URL
- Set URL for the enable-consumer destination. It is persistent for the
+\-U, \-\-set-url=URL
+ Set URL for the consumer output destination. It is persistent for the
session lifetime. Redo the command to change it. This will set both
data and control URL for network.
\-C, \-\-ctrl-url=URL
Set control path URL. (Must use -D also)
\-D, \-\-data-url=URL
Set data path URL. (Must use -C also)
- \-\-no-consumer
- Don't activate a consumer for this session.
- \-\-disable-consumer
- Disable consumer for this session.
-See \fBenable-consumer\fP command below for the supported URL format.
+.B URL FORMAT:
+
+proto://[HOST|IP][:PORT1[:PORT2]][/TRACE_PATH]
+
+Supported protocols are (proto):
+> file://...
+ Local filesystem full path.
+
+> net://...
+ This will use the default network transport layer which is TCP for both
+ control (PORT1) and data port (PORT2). The default ports are
+ respectively 5342 and 5343. Note that net[6]:// is not yet supported.
+
+> tcp[6]://...
+ Can only be used with -C and -D together
+
+NOTE: IPv6 address MUST be enclosed in brackets '[]' (rfc2732)
.B EXAMPLES:
.nf
Enable tracing channel
-To enable event, you must first enable a channel which contains event(s).
+To enable an event, you must enable both the event and the channel that
+contains it.
If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
file.
+
+It is important to note that if a certain type of buffers is used, the session
+will be set with that type and all other subsequent channel need to have the
+same type.
.fi
.B OPTIONS:
\-\-overwrite
Flight recorder mode : overwrites events when subbuffers are full
\-\-subbuf-size SIZE
- Subbuffer size in bytes (default: 4096, kernel default: 262144)
+ Subbuffer size in bytes {+k,+M,+G} (default: 4096, kernel default: 262144)
+ Needs to be a power of 2 for both tracers
\-\-num-subbuf NUM
Number of subbuffers (default: 4)
- Needs to be a power of 2 for kernel and ust tracers
+ Needs to be a power of 2 for both tracers
\-\-switch-timer USEC
- Switch subbuffer timer interval in usec (default: 0)
- Needs to be a power of 2 for kernel and ust tracers
+ Switch subbuffer timer interval in µsec (default: 0)
\-\-read-timer USEC
- Read timer interval in usec (default: 200)
+ Read timer interval in µsec (UST default: 0, kernel default: 200000)
\-\-output TYPE
Channel output type. Possible values: mmap, splice
-.fi
-
-.IP
+\-\-buffers-uid
+ Use per UID buffer (\-u only). Buffers are shared between applications
+ that have the same UID.
+\-\-buffers-pid
+ Use per PID buffer (\-u only). Each application has its own buffers.
+\-\-buffers-global
+ Use shared buffer for the whole system (\-k only)
+\-C, \-\-tracefile-size SIZE
+ Maximum size of each tracefile within a stream (in bytes).
+\-W, \-\-tracefile-count COUNT
+ Used in conjunction with \-C option, this will limit the number
+ of files created to the specified count.
-.IP "\fBenable-consumer\fP [-u|-k] [URL] [OPTIONS]"
-.nf
-Enable a consumer for the tracing session and domain.
+.B EXAMPLES:
-By default, every tracing session has a consumer attached to it using the local
-filesystem as output. The trace is written in $HOME/lttng-traces. This command
-allows the user to specify a specific URL after the session was created for a
-specific domain. If no domain is specified, the consumer is applied on all
-domains.
+$ lttng enable-channel -C 4096 -W 32 chan1
+For each stream, the maximum size of a trace file will be 4096 bytes divided
+over a \fBmaximum\fP of 32 different files. The file count is appended after
+the stream number as seen in the following example. The last trace file is
+smaller than 4096 since it was not completely filled.
-Without options, the behavior is to enable a consumer to the current URL. The
-default URL is the local filesystem at the path of the session mentioned above.
+ ~/lttng-traces/[...]/chan1_0_0 (4096)
+ ~/lttng-traces/[...]/chan1_0_1 (4096)
+ ~/lttng-traces/[...]/chan1_0_2 (3245)
+ ~/lttng-traces/[...]/chan1_1_0 (4096)
+ ...
-The enable-consumer feature supports both local and network transport. You must
-have a running \fBlttng-relayd(8)\fP for network transmission or any other daemon
-that can understand the streaming protocol of LTTng.
+$ lttng enable-channel -C 4096
+This will create trace files of 4096 bytes and will create new ones as long as
+there is data available.
.fi
-.B OPTIONS:
-
-.nf
-\-h, \-\-help
- Show summary of possible options and commands.
-\-\-list-options
- Simple listing of options
-\-s, \-\-session NAME
- Apply on session name
-\-k, \-\-kernel
- Apply for the kernel tracer
-\-u, \-\-userspace
- Apply for the user-space tracer
-
-Using these options, each API call can be controlled individually. For
-instance, \-C does not enable the consumer automatically. You'll need the \-e
-option for that.
-
-\-U, \-\-set-uri=URL
- Set URL for the enable-consumer destination. It is persistent for the
- session lifetime. Redo the command to change it. This will set both
- data and control URL for network.
-\-C, \-\-ctrl-url=URL
- Set control path URL. (Must use -D also)
-\-D, \-\-data-url=URL
- Set data path URL. (Must use -C also)
-\-e, \-\-enable
- Enable consumer
-
-.B URL FORMAT:
-
-proto://[HOST|IP][:PORT1[:PORT2]][/TRACE_PATH]
-
-Supported protocols are (proto):
-> file://...
- Local filesystem full path.
-
-> net://...
- This will use the default network transport layer which is TCP for both
- control (PORT1) and data port (PORT2). The default ports are
- respectively 5342 and 5343. Note that net[6]:// is not yet supported.
-
-> tcp[6]://...
- Can only be used with -C and -D together
-
-NOTE: IPv6 address MUST be enclosed in brackets '[]' (rfc2732)
-
-.B EXAMPLES:
-
-$ lttng enable-consumer -u net://192.168.1.42
-
-Uses TCP and default ports for user space tracing (-u) where the IP address
-above is the destination machine where the traces will be streamed and a
-\fBlttng-relayd(8)\fP is listening.
-.fi
+.IP
.IP "\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]"
.nf
\-c, \-\-channel NAME
Apply on channel name
\-a, \-\-all
- Enable all tracepoints and syscalls
+ Enable all tracepoints and syscalls. This actually enable a single
+ wildcard event "*".
\-k, \-\-kernel
Apply for the kernel tracer
\-u, \-\-userspace
\-\-filter 'expression'
Set a filter on a newly enabled event. Filter expression on event
- fields, event recording depends on evaluation. Only specify on first
- activation of a given event within a session. Filter only allowed when
- enabling events within a session before tracing is started. If the
- filter fails to link with the event within the traced domain, the event
- will be discarded. Currently, filter is only implemented for the
- user-space tracer.
+ fields and context. Event recording depends on evaluation. Only
+ specify on first activation of a given event within a session.
+ Filter only allowed when enabling events within a session before
+ tracing is started. If the filter fails to link with the event
+ within the traced domain, the event will be discarded.
+ Currently, filter is only implemented for the user-space tracer.
Expression examples:
Wildcards are allowed at the end of strings:
'seqfield1 == "te*"'
In string literals, the escape character is a '\\'. Use '\\*' for
- the '*' character, and '\\\\' for the '\\' character.
+ the '*' character, and '\\\\' for the '\\' character. Wildcard
+ match any sequence of characters, including an empty sub-string
+ (match 0 or more characters).
+
+ Context information can be used for filtering. The examples
+ below show usage of context filtering on process name (with a
+ wildcard), process ID range, and unique thread ID for filtering.
+ The process and thread ID of running applications can be found
+ under columns "PID" and "LWP" of the "ps -eLf" command.
+
+ '$ctx.procname == "demo*"'
+ '$ctx.vpid >= 4433 && $ctx.vpid < 4455'
+ '$ctx.vtid == 1234'
.fi
.IP "\fBdisable-channel\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]"
Apply for the user-space tracer
.fi
-.IP "\fBdisable-consumer\fP [\-k|\-u] [OPTIONS]"
-.nf
-Disable the consumer of a tracing session.
-
-This call MUST be done BEFORE tracing has started.
-.fi
-
-.B OPTIONS:
-
-.nf
-\-h, \-\-help
- Show summary of possible options and commands.
-\-\-list-options
- Simple listing of options
-\-s, \-\-session NAME
- Apply on session name
-\-k, \-\-kernel
- Apply for the kernel tracer
-\-u, \-\-userspace
- Apply for the user-space tracer
-.fi
-
.IP "\fBdisable-event\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]"
.nf
Disable tracing event
Simple listing of options
\-s, \-\-session NAME
Apply on session name
+\-a, \-\-all-events
+ Disable all events. This does NOT disable "*" but rather
+ every known events of the session.
\-k, \-\-kernel
Apply for the kernel tracer
\-u, \-\-userspace
projects / lttng-tools.git / blobdiff