[lttng-dev] [PATCH] baddr: Added ust_baddr & ust_baddr_statedump docu
mathieu.desnoyers at efficios.com
Wed Jan 8 10:14:11 EST 2014
Merged and pushed, along with a follow up cleanup commit.
----- Original Message -----
> From: "Paul Woegerer" <paul_woegerer at mentor.com>
> To: "mathieu desnoyers" <mathieu.desnoyers at efficios.com>, lttng-dev at lists.lttng.org
> Sent: Thursday, December 19, 2013 10:21:19 AM
> Subject: [PATCH] baddr: Added ust_baddr & ust_baddr_statedump docu
> Signed-off-by: Paul Woegerer <paul_woegerer at mentor.com>
> doc/Makefile.am | 1 +
> doc/man/lttng-ust-dl.3 | 47 +++++++++++++++++++++++++++++++++++++++++++++++
> doc/man/lttng-ust.3 | 34 +++++++++++++++++++++++++++++++++-
> 3 files changed, 81 insertions(+), 1 deletion(-)
> create mode 100644 doc/man/lttng-ust-dl.3
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index 4349713..72dcde2 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -2,6 +2,7 @@ SUBDIRS = . examples
> dist_man_MANS = man/lttng-gen-tp.1 \
> man/lttng-ust.3 \
> + man/lttng-ust-dl.3 \
> dist_doc_DATA = java-util-logging.txt
> diff --git a/doc/man/lttng-ust-dl.3 b/doc/man/lttng-ust-dl.3
> new file mode 100644
> index 0000000..ff46f6b
> --- /dev/null
> +++ b/doc/man/lttng-ust-dl.3
> @@ -0,0 +1,47 @@
> +.TH "LTTNG-UST-DL" "3" "December 19, 2013" "" ""
> +.SH "NAME"
> +lttng-ust-dl \(em LTTng UST 2.x Dynamic Linker Tracing
> +.SH "SYNOPSIS"
> +Launch your application with:
> +\fBLD_PRELOAD=liblttng-ust-dl.so\fP appname
> +This LD_PRELOAD library causes all calls to dlopen and dlclose in the
> +application to be traced with LTTng. The following two events need to be
> +enabled: ust_baddr:push and ust_baddr:pop.
> +.SH "DESCRIPTION"
> +The events have the following detailed definitions:
> +.IP "ust_baddr:push"
> +This event is used to trace dlopen calls. The base address (where the
> +linker has placed the shared object) is recorded in the baddr-field. The
> +to the shared object gets recorded in the sopath-field (as string). The file
> +size of the loaded object (in bytes) is recorded to the size-field and its
> +of last modification (in seconds since Epoch) is recorded in the
> +.IP "ust_baddr:pop"
> +This event is used to trace dlclose calls. The base address of the shared
> +object that got closed is recorded in the baddr-field.
> +.SH "SEE ALSO"
> +lttng-ust(3), dlopen(3), lttng(1)
> +.SH "BUGS"
> +If you encounter any issues or usability problem, please report it on
> +our mailing list <lttng-dev at lists.lttng.org> to help improve this
> +.SH "CREDITS"
> +liblttng-ust is distributed under the GNU Lesser General Public License
> +version 2.1. The headers are distributed under the MIT license.
> +See http://lttng.org for more information on the LTTng project.
> +Mailing list for support and development: <lttng-dev at lists.lttng.org>.
> +You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
> +.SH "AUTHORS"
> +liblttng-ust was originally written by Mathieu Desnoyers, with additional
> +contributions from various other people. It is currently maintained by
> +Mathieu Desnoyers <mathieu.desnoyers at efficios.com>.
> diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3
> index 7624e88..55de9fd 100644
> --- a/doc/man/lttng-ust.3
> +++ b/doc/man/lttng-ust.3
> @@ -347,6 +347,13 @@ process namespace.
> +.IP "ip"
> +Instruction pointer: Enables recording of the exact location where a
> +was emitted. Can be used to reverse-lookup the source location that caused
> +event to be emitted.
> .IP "procname"
> Thread name, as set by exec() or prctl(). It is recommended that
> programs set their thread name with prctl() before hitting the first
> @@ -359,6 +366,28 @@ Pthread identifier. Can be used on architectures where
> pthread_t maps
> nicely to an unsigned long type.
> +.SH "BASE ADDRESS STATEDUMP"
> +If an application that uses liblttng-ust.so becomes part of a session,
> +information about its currently loaded shared objects will be traced to the
> +session at session-enable time. To record this information, the following
> +needs to be enabled:
> +.IP "ust_baddr_statedump:soinfo"
> +This event is used to trace a currently loaded shared object. The base
> +(where the dynamic linker has placed the shared object) is recorded in the
> +baddr-field. The path to the shared object gets recorded in the sopath-field
> +(as string). The file size of the loaded object (in bytes) is recorded to
> +size-field and its time of last modification (in seconds since Epoch) is
> +recorded in the mtime-field.
> +If the event above is enabled, a series of ust_baddr_statedump:soinfo events
> +recorded at session-enable time, that represents the state of currently
> +shared objects (of the traced application). If this information gets
> +with the lttng-ust-dl(3) instrumentation, all aspects of dynamic loading
> +are relevant for symbol and linenumber-lookup are traced by LTTng.
> .SH "ENVIRONMENT VARIABLES"
> @@ -375,12 +404,15 @@ specified in milliseconds. The value 0 means "don't
> wait". The value
> recommended for applications with time constraints on the process
> startup time.
> +.IP "LTTNG_UST_WITHOUT_BADDR_STATEDUMP"
> +Prevent liblttng-ust to perform a base-address statedump on session-enable.
> .SH "SEE ALSO"
> lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-ust-cyg-profile(3),
> +lttng-ust-dl(3), lttng-sessiond(8)
> .SH "COMPATIBILITY"
More information about the lttng-dev