[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel
- [option:--probe='SOURCE' | option:--function='SOURCE' | option:--syscall]
+ [option:--probe='SOURCE' | option:--function='SOURCE' | option:--syscall |
+ option:--userspace-probe='SOURCE']
[option:--filter='EXPR'] [option:--session='SESSION']
[option:--channel='CHANNEL'] 'EVENT'[,'EVENT']...
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel option:--all [option:--syscall]
[option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL']
-Create or enable application event rules:
+Create or enable application/library event rules:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event*
one or more existing and disabled ones.
An event rule created by `lttng enable-event` is a set of conditions
-that must be satisfied in order for an actual event to be emitted by
-an LTTng tracer when the execution of an application or the Linux kernel
-reaches an event source (tracepoint, system call, dynamic probe).
-Event sources can be listed with the man:lttng-list(1) command.
+that must be satisfied in order for an actual event to be emitted by an
+LTTng tracer when the execution of an application or a library or the
+Linux kernel reaches an event source (tracepoint, system call, dynamic
+probe). Event sources can be listed with the man:lttng-list(1) command.
The man:lttng-disable-event(1) command can be used to disable
existing event rules.
Event source types
~~~~~~~~~~~~~~~~~~
-Four types of event sources are available in the Linux kernel tracing
+Five types of event sources are available in the Linux kernel tracing
domain (option:--kernel option):
Tracepoint (option:--tracepoint option; default)::
and placed in the source code by developers and record useful
payload fields.
-Dynamic probe (option:--probe option)::
+Dynamic kernel probe (option:--probe option)::
A Linux kernel kprobe, that is, an instrumentation point placed
dynamically in the compiled kernel code. Dynamic probe events do not
record any payload field.
+Dynamic user space probe (option:--userspace-probe option)::
+ A Linux kernel uprobe, that is, an instrumentation point placed
+ dynamically in the compiled user space application/library through
+ the kernel. Dynamic user space probe events do not record any
+ payload field.
++
+See the <<userspace-probe,Dynamic user space probes>> section for more
+information.
+
Function probe (option:--function option)::
A Linux kernel kretprobe, that is, two instrumentation points placed
dynamically where a function is entered and where it returns in the
The available conditions for the Linux kernel domain are:
-* Tracepoint/system call name ('EVENT' argument with
- option:--tracepoint or option:--syscall options) or
- dynamic probe/function name/address
- (option:--probe or option:--function option's argument) which must
- match event source's equivalent.
+* Tracepoint/system call name ('EVENT' argument with option:--tracepoint
+ or option:--syscall options) or dynamic probe/function name/address
+ (option:--probe, option:--userspace-probe, and option:--function
+ option's argument) which must match event source's equivalent.
+
You can use `*` characters at any place in the tracepoint or system
call name as wildcards to match zero or more characters. To use a
* `PYTHON_NOTSET` (0)
+[[userspace-probe]]
+Dynamic user space probes
+~~~~~~~~~~~~~~~~~~~~~~~~~
+With the option:--userspace-probe option, you can instrument function
+entries of any user space binary (application or library) using either
+an available symbol name or a SystemTap Statically Defined Tracepoints
+(SDT, a DTrace-style marker) probe's provider and probe names. As of
+this version, only SDT probes that are :not: surrounded by a reference
+counter (semaphore).
+
+The option:--userspace-probe option must be specified with the
+option:--kernel option because it uses Linux's uprobe feature to
+dynamically instrument a user space application or library.
+
+As of this version, dynamic probe events do not record any payload
+field.
+
+
include::common-cmd-options-head.txt[]
One of:
option:--function='SOURCE'::
- Linux kernel kretprobe. Only available with the option:--kernel
- domain option. 'SOURCE' is one of:
+ Dynamic kernel return probe (kretprobe). Only available with the
+ option:--kernel domain option. 'SOURCE' is one of:
+
* Function address (`0x` prefix supported)
-* Function symbol
-* Function symbol and offset (`SYMBOL+OFFSET` format)
+* Function symbol name
+* Function symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format)
option:--probe='SOURCE'::
- Linux kernel kprobe. Only available with the option:--kernel
- domain option. 'SOURCE' is one of:
+ Dynamic kernel probe (kprobe). Only available with the
+ option:--kernel domain option. 'SOURCE' is one of:
+
* Address (`0x` prefix supported)
-* Symbol
-* Symbol and offset (`SYMBOL+OFFSET` format)
+* Symbol nane
+* Symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format)
+
+option:--userspace-probe='SOURCE'::
+ Dynamic user space probe (uprobe). Only available with the
+ option:--kernel domain option. See the
+ <<userspace-probe,Dynamic user space probes>> section.
++
+'SOURCE' is one of:
++
+--
+\[++elf:++]__PATH__++:++__SYMBOL__::
+ Dynamically instrument an available symbol within a user space
+ application or library.
++
+--
+'PATH'::
+ Application or library path.
++
+This can be:
++
+* An absolute path.
+* A relative path.
+* An application's name as found in the directories listed in the
+ `PATH` environment variable.
+
+'SYMBOL'::
+ Symbol name of the function of which to instrument the entry.
++
+This can be any defined code symbol listed by the man:nm(1) command
+(including with its nloption:--dynamic option which lists dynamic
+symbols).
+--
++
+As of this version, not specifying `elf:` is equivalent to specifying
+it.
++
+Examples:
++
+* `--userspace-probe=/usr/lib/libc.so.6:malloc`
+* `--userspace-probe=./myapp:createUser`
+* `--userspace-probe=httpd:ap_run_open_htaccess`
+
+++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__::
+ Dynamically instrument an SDT probe within a user space application
+ or library.
++
+--
+'PATH'::
+ Application or library path.
++
+This can be:
++
+* An absolute path.
+* A relative path.
+* An application's name as found in the directories listed in the
+ `PATH` environment variable.
+
+__PROVIDER__++:++__NAME__::
+ SDT provider and probe names.
++
+For example, with the following SDT probe:
++
+[source,c]
+----
+DTRACE_PROBE2("server", "accept_request",
+ request_id, ip_addr);
+----
++
+The provider/probe name pair is `server:accept_request`.
+--
++
+Example:
++
+* `--userspace-probe=sdt:./build/server:server:accept_request`
+--
option:--syscall::
Linux kernel system call. Only available with the option:--kernel
projects / lttng-tools.git / blobdiff