From: Philippe Proulx Date: Fri, 9 Nov 2018 16:46:38 +0000 (-0500) Subject: lttng-enable-event.1.txt: uprobe: update style and content X-Git-Url: http://git.efficios.com/?p=lttng-tools.git;a=commitdiff_plain;h=fa72991a785e895947a2b947de27e2766fd95279 lttng-enable-event.1.txt: uprobe: update style and content * Better inline styles for option variables. * Option descriptions moved to the OPTIONS section. * Expand SDT acronym. * Add note indicating that SDT probes surrounded by reference counts are not supported. * Use "application" and "library" instead of "executable". Signed-off-by: Philippe Proulx Reviewed-by: Francis Deslauriers Signed-off-by: Jérémie Galarneau --- diff --git a/doc/man/lttng-enable-event.1.txt b/doc/man/lttng-enable-event.1.txt index 3e137a9dc..538a3b96b 100644 --- a/doc/man/lttng-enable-event.1.txt +++ b/doc/man/lttng-enable-event.1.txt @@ -410,8 +410,10 @@ 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 SDT probe's provider and probe -names. +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 @@ -420,12 +422,73 @@ dynamically instrument a user space application or library. As of this version, dynamic probe events do not record any payload field. -The two available option:--userspace-probe option's argument formats -are: -option:--userspace-probe=`[elf:]PATH:SYMBOL`:: +include::common-cmd-options-head.txt[] + + +Domain +~~~~~~ +One of: + +option:-j, option:--jul:: + Create or enable event rules in the `java.util.logging` + (JUL) domain. + +option:-k, option:--kernel:: + Create or enable event rules in the Linux kernel domain. + +option:-l, option:--log4j:: + Create or enable event rules in the Apache log4j domain. + +option:-p, option:--python:: + Create or enable event rules in the Python domain. + +option:-u, option:--userspace:: + Create or enable event rules in the user space domain. + + +Target +~~~~~~ +option:-c 'CHANNEL', option:--channel='CHANNEL':: + Create or enable event rules in the channel named 'CHANNEL' instead + of the default channel name `channel0`. + +option:-s 'SESSION', option:--session='SESSION':: + Create or enable event rules in the tracing session named 'SESSION' + instead of the current tracing session. + + +Event source type +~~~~~~~~~~~~~~~~~ +One of: + +option:--function='SOURCE':: + Dynamic kernel return probe (kretprobe). Only available with the + option:--kernel domain option. 'SOURCE' is one of: ++ +* Function address (`0x` prefix supported) +* Function symbol name +* Function symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format) + +option:--probe='SOURCE':: + Dynamic kernel probe (kprobe). Only available with the + option:--kernel domain option. 'SOURCE' is one of: ++ +* Address (`0x` prefix supported) +* 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 + <> section. ++ +'SOURCE' is one of: ++ +-- +\[++elf:++]__PATH__++:++__SYMBOL__:: Dynamically instrument an available symbol within a user space - executable. + application or library. + -- 'PATH':: @@ -435,7 +498,7 @@ This can be: + * An absolute path. * A relative path. -* An executable's name as found in the directories listed in the +* An application's name as found in the directories listed in the `PATH` environment variable. 'SYMBOL':: @@ -455,8 +518,9 @@ Examples: * `--userspace-probe=./myapp:createUser` * `--userspace-probe=httpd:ap_run_open_htaccess` -option:--userspace-probe=`sdt:PATH:PROVIDER:NAME`:: - Dynamically instrument an SDT probe within a user space executable. +++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__:: + Dynamically instrument an SDT probe within a user space application + or library. + -- 'PATH':: @@ -466,10 +530,10 @@ This can be: + * An absolute path. * A relative path. -* An executable's name as found in the directories listed in the +* An application's name as found in the directories listed in the `PATH` environment variable. -__PROVIDER__:__NAME__:: +__PROVIDER__++:++__NAME__:: SDT provider and probe names. + For example, with the following SDT probe: @@ -486,69 +550,7 @@ The provider/probe name pair is `server:accept_request`. Example: + * `--userspace-probe=sdt:./build/server:server:accept_request` - - -include::common-cmd-options-head.txt[] - - -Domain -~~~~~~ -One of: - -option:-j, option:--jul:: - Create or enable event rules in the `java.util.logging` - (JUL) domain. - -option:-k, option:--kernel:: - Create or enable event rules in the Linux kernel domain. - -option:-l, option:--log4j:: - Create or enable event rules in the Apache log4j domain. - -option:-p, option:--python:: - Create or enable event rules in the Python domain. - -option:-u, option:--userspace:: - Create or enable event rules in the user space domain. - - -Target -~~~~~~ -option:-c 'CHANNEL', option:--channel='CHANNEL':: - Create or enable event rules in the channel named 'CHANNEL' instead - of the default channel name `channel0`. - -option:-s 'SESSION', option:--session='SESSION':: - Create or enable event rules in the tracing session named 'SESSION' - instead of the current tracing session. - - -Event source type -~~~~~~~~~~~~~~~~~ -One of: - -option:--function='SOURCE':: - Linux kernel 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) - -option:--probe='SOURCE':: - Linux kernel kprobe. Only available with the option:--kernel - domain option. 'SOURCE' is one of: -+ -* Address (`0x` prefix supported) -* Symbol -* Symbol and offset (`SYMBOL+OFFSET` format) - -option:--userspace-probe='SOURCE':: - Linux kernel uprobe. Only available with the option:--kernel - domain option. -+ -See the <> section for more -information about the option's argument 'SOURCE'. +-- option:--syscall:: Linux kernel system call. Only available with the option:--kernel