From: Philippe Proulx Date: Tue, 5 Apr 2016 14:50:34 +0000 (-0400) Subject: Convert man pages to AsciiDoc X-Git-Tag: v2.8.0-rc2~22 X-Git-Url: https://git.lttng.org./?a=commitdiff_plain;h=cfeef37a815d520888bd5a3435401b2bb3315fbd;p=lttng-ust.git Convert man pages to AsciiDoc This patch adds a new "enable" option to the configure script, --enable-man-pages (default) and --disable-man-pages. When man pages are enabled, they are built and installed. The man pages are built from their AsciiDoc sources in this way: AsciiDoc source -> asciidoc -> DocBook XML -> xmlto -> troff ^ ^ included DocBook XSLs AsciiDoc + files custom XSLs The built troff man pages should be distributed in a release tarball. When building from a release tarball, the tools (asciidoc and xmlto) are not strictly needed, unless a man page source is modified/removed, in which case: if the tools existed at configure time: rebuild/update man page otherwise: show an error message which indicates why the target cannot be built because the tools are missing When building from the Git repository, and when --enable-man-pages is used, the tools are required at configure time. The incentive for this change is to make the man pages easier to write and maintain, AsciiDoc being far more easy to read and write than pure troff, as well as enable rich HTML man page generation from the intermediate DocBook XML file to publish man pages with working internal/external links and style improvements on the LTTng website. This also makes LTTng-UST man pages conform to the LTTng-tools ones which use the same mechanism. The following "redirection" man pages are also added: * do_tracepoint(3) * tracepoint(3) * tracepoint_enabled(3) They all redirect to lttng-ust(3). They are always distributed, but only installed when lttng-ust(3) is also installed (which is when --enable-man-page exists at configure time). See the new doc/man/README.md file for more details about the new files and macros to use in the AsciiDoc man page source files. This patch also contains various content fixes and updates of the LTTng-UST man pages. Some new content is based on the online LTTng documentation. Signed-off-by: Philippe Proulx Signed-off-by: Mathieu Desnoyers --- diff --git a/.gitignore b/.gitignore index 87d55d9c..78cba0dc 100644 --- a/.gitignore +++ b/.gitignore @@ -40,6 +40,14 @@ doc/examples/gen-tp/sample_tracepoint.h doc/examples/demo-tracef/demo-tracef doc/examples/demo-tracelog/demo-tracelog +doc/man/*.xml +doc/man/lttng-gen-tp.1 +doc/man/lttng-ust-cyg-profile.3 +doc/man/lttng-ust-dl.3 +doc/man/lttng-ust.3 +doc/man/tracef.3 +doc/man/tracelog.3 + tests/hello/hello tests/hello.cxx/hello tests/same_line_tracepoint/same_line_tracepoint diff --git a/README.md b/README.md index 2c61d339..c447939b 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,17 @@ compile the Git repository tree: - [GNU Libtool](http://www.gnu.org/software/autoconf/) >= 2.2 - Perl (optional: needed for `make check` and tests) +Optional packages to build LTTng-tools man pages: + + - **[AsciiDoc](http://www.methods.co.nz/asciidoc/) >= 8.4.5** + (previous versions may work, but were not tested) + - **[xmlto](https://fedorahosted.org/xmlto/) >= 0.0.21** (previous + versions may work, but were not tested) + +Note that the man pages are already built in a distribution tarball. +In this case, you only need AsciiDoc and xmlto if you indend to modify +the AsciiDoc man page sources. + If you get the tree from the Git repository, you will need to run ./bootstrap diff --git a/configure.ac b/configure.ac index 19e4b746..6850489a 100644 --- a/configure.ac +++ b/configure.ac @@ -368,10 +368,67 @@ AC_DEFINE_UNQUOTED([LTTNG_SYSTEM_RUNDIR], ["$lttng_system_rundir"], AC_CHECK_PROG([BUILD_GEN_TP_EXAMPLES], [python], ["yes"]) AM_CONDITIONAL([BUILD_GEN_TP_EXAMPLES], [test "x$BUILD_GEN_TP_EXAMPLES" = "xyes"]) +# Set $IN_GIT_REPO if we're in the Git repository; the `bootstrap` file +# is not distributed in tarballs. +AS_IF([test -f "$srcdir/bootstrap"], [in_git_repo=yes], [in_git_repo=no]) +AM_CONDITIONAL([IN_GIT_REPO], [test "x$in_git_repo" = "xyes"]) + +# Enable building man pages (user's intention). +AC_ARG_ENABLE( + man-pages, + AS_HELP_STRING( + [--disable-man-pages], + [Do not build and install man pages (already built in a distributed tarball)] + ), + [man_pages_opt=$enableval], + [man_pages_opt=yes] +) + +# Check for asciidoc and xmlto if we enabled building the man pages. +have_asciidoc_xmlto=no + +AS_IF([test "x$man_pages_opt" = "xyes"], [ + AC_PATH_PROG([ASCIIDOC], [asciidoc], [no]) + AC_PATH_PROG([XMLTO], [xmlto], [no]) + + AS_IF([test "x$ASCIIDOC" = "xno" || test "x$XMLTO" = "xno"], [ + AS_IF([test "x$in_git_repo" = "xyes"], [ + # This is an error because we're in the Git repo, which + # means the man pages are not already generated for us, + # thus asciidoc/xmlto are required because we were asked + # to build the man pages. + AC_MSG_ERROR([ +Both asciidoc and xmlto are needed to build the LTTng-UST man pages. Use +--disable-man-pages to disable building the man pages, in which case +they will not be installed. + ]) + ], [ + # Only warn here: since we're in the tarball, the man + # pages should already be generated at this point, thus + # asciidoc/xmlto are not strictly required. + AC_MSG_WARN([ +Both asciidoc and xmlto are needed to build the LTTng-UST man pages. +Note that the man pages are already built in this distribution tarball, +so asciidoc and xmlto are only needed if you intend to modify their +sources. Use --disable-man-pages to completely disable building +and installing the man pages. + ]) + ]) + ], [ + have_asciidoc_xmlto=yes + ]) +]) + +# Export man page build condition: build the man pages if the user +# asked for it, and if the tools are available. +AM_CONDITIONAL([MAN_PAGES_OPT], [test "x$man_pages_opt" != "xno"]) +AM_CONDITIONAL([HAVE_ASCIIDOC_XMLTO], [test "x$have_asciidoc_xmlto" = "xyes"]) + AC_CONFIG_FILES([ Makefile doc/Makefile doc/examples/Makefile + doc/man/Makefile include/Makefile include/lttng/ust-version.h snprintf/Makefile diff --git a/doc/Makefile.am b/doc/Makefile.am index ba21e9fb..e110ed85 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,8 +1,3 @@ -SUBDIRS = . examples - -dist_man_MANS = man/lttng-gen-tp.1 \ - man/lttng-ust.3 \ - man/lttng-ust-dl.3 \ - man/lttng-ust-cyg-profile.3 +SUBDIRS = . man examples dist_doc_DATA = java-agent.txt diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am new file mode 100644 index 00000000..20362045 --- /dev/null +++ b/doc/man/Makefile.am @@ -0,0 +1,115 @@ +# Man pages are only built if they are enabled at configure time. +# +# They should always be built before creating a distribution tarball. + +# Function which adds the source directory prefix and adds a given suffix: +manaddsuffix = $(addsuffix $(1),$(addprefix $(srcdir)/,$(2))) + +# List only the names without the .*.txt extension here: +MAN1_NAMES = \ + lttng-gen-tp +MAN3_NAMES = \ + lttng-ust \ + tracef \ + tracelog \ + lttng-ust-dl \ + lttng-ust-cyg-profile + +# troff man pages: +MAN3_TROFF = do_tracepoint.3 tracepoint.3 tracepoint_enabled.3 + +# AsciiDoc sources and outputs: +MAN1_TXT = $(call manaddsuffix,.1.txt,$(MAN1_NAMES)) +MAN3_TXT = $(call manaddsuffix,.3.txt,$(MAN3_NAMES)) +MAN_TXT = $(MAN1_TXT) $(MAN3_TXT) $(MAN8_TXT) +MAN_XML = $(patsubst $(srcdir)/%.txt,%.xml,$(MAN_TXT)) + +# Common AsciiDoc source files: +COMMON_TXT = \ + $(srcdir)/common-footer.txt \ + $(srcdir)/common-authors.txt \ + $(srcdir)/common-copyrights.txt \ + $(srcdir)/log-levels.txt \ + $(srcdir)/tracef-tracelog-limitations.txt + +# AsciiDoc configuration and XSL files: +ASCIIDOC_CONF = $(srcdir)/asciidoc.conf +XSL_FILES = \ + manpage.xsl \ + manpage-callouts.xsl \ + manpage-bold-literal.xsl \ + manpage-links.xsl \ + manpage-headings.xsl +XSL_SRC_FILES = $(addprefix $(srcdir)/xsl/,$(XSL_FILES)) + +# Common dependencies: +COMMON_DEPS = $(ASCIIDOC_CONF) $(COMMON_TXT) + +# Man pages destinations: +MAN1 = $(addsuffix .1,$(MAN1_NAMES)) +MAN3 = $(addsuffix .3,$(MAN3_NAMES)) +MAN = $(MAN1) $(MAN3) + +if MAN_PAGES_OPT +# At this point, we know the user asked to build the man pages. +if HAVE_ASCIIDOC_XMLTO +# Tools to execute: +ADOC = $(ASCIIDOC) -f $(ASCIIDOC_CONF) -d manpage \ + -a lttng_version="$(PACKAGE_VERSION)" +ADOC_DOCBOOK = $(ADOC) -b docbook +XTO = $(XMLTO) -m $(firstword $(XSL_SRC_FILES)) man + +# Recipes: +%.1.xml: $(srcdir)/%.1.txt $(COMMON_DEPS) + $(ADOC_DOCBOOK) -o $@ $< + +%.1: %.1.xml $(XSL_SRC_FILES) + $(XTO) $< + +%.3.xml: $(srcdir)/%.3.txt $(COMMON_DEPS) + $(ADOC_DOCBOOK) -o $@ $< + +%.3: %.3.xml $(XSL_SRC_FILES) + $(XTO) $< + +# Only clean the generated files if we have the tools to generate them again. +CLEANFILES = $(MAN_XML) $(MAN) +else # HAVE_ASCIIDOC_XMLTO +# Create man page targets used to stop the build if we want to +# build the man pages, but we don't have the necessary tools to do so. +ERR_MSG = "Error: Cannot build target because asciidoc or xmlto tool is missing." +ERR_MSG += "Make sure both tools are installed and run the configure script again." + +%.1: $(srcdir)/%.1.txt $(COMMON_DEPS) + @echo $(ERR_MSG) + @false + +%.3: $(srcdir)/%.3.txt $(COMMON_DEPS) + @echo $(ERR_MSG) + @false +endif # HAVE_ASCIIDOC_XMLTO +endif # MAN_PAGES_OPT + +# Start with empty distributed/installed man pages: +dist_man1_MANS = +dist_man3_MANS = +EXTRA_DIST = + +if MAN_PAGES_OPT +# Building man pages: we can install and distribute them. +dist_man1_MANS += $(MAN1) +dist_man3_MANS += $(MAN3) $(MAN3_TROFF) +else # MAN_PAGES_OPT +# Those are not known by automake yet because dist_man3_MANS is empty +# at this point, so make sure they are distributed. +EXTRA_DIST += $(MAN3_TROFF) +endif # MAN_PAGES_OPT + +if !MAN_PAGES_OPT +dist-hook: + @echo "Error: Please enable the man pages before creating a distribution tarball." + @false +endif # !MAN_PAGES_OPT + +# Always distribute the source files. +EXTRA_DIST += $(MAN_TXT) $(COMMON_TXT) $(XSL_SRC_FILES) $(ASCIIDOC_CONF) diff --git a/doc/man/README.md b/doc/man/README.md new file mode 100644 index 00000000..b895f22f --- /dev/null +++ b/doc/man/README.md @@ -0,0 +1,100 @@ +LTTng-UST man pages +=================== + +This directory contains the sources of the LTTng-UST man pages. + +LTTng-UST man pages are written in +[AsciiDoc](http://www.methods.co.nz/asciidoc/), and then converted to +DocBook (XML) using the `asciidoc` command, and finally to troff using +the appropriate DocBook XSL stylesheet (using the `xmlto` command). + + +Custom XSL stylesheets +---------------------- + +There are a few custom XSL stylesheets applied for customizing the +generated man pages in the `xsl` directory. + + +Macros +------ + +AsciiDoc is configured with `asciidoc.conf` which contains a few +macro definitions used everywhere in the man page sources. + + +### `man` + +The `man` macro is used to specify a reference to another man page. +Using the provided `asciidoc.conf` configuration file, the man page +name is rendered in bold and the section is normal. + +Usage example: `man:lttng-enable-channel(1)`, `man:dlopen(3)` + + +### `option` + +The option macro is used to write a command-line option which is +**defined in the same man page**. + +Usage example: `option:--output`, `option:--verbose` + + +### `nloption` + +Command-line option generating no link. This is used when writing +about an option which is **not defined in the same man page**. + +Usage example: `nloption:-finstrument-functions` + + +### `not` + +The `:not:` macro is used to emphasize on _not_. + + +Includes +-------- + + * `common-authors.txt`: common authors section of the LTTng-UST + project. Only use this for man pages which describe + a command/library/function written by the main authors of LTTng-UST. + * `common-copyright.txt`: common copyrights section of the LTTng-UST + project. Only use this for man pages which describe + a command/library/function having the common LTTng-UST license. + * `common-footer.txt`: common footer for all man pages. This goes + before the copyrights section. + * `log-levels.txt`: definition list of LTTng-UST log levels. + * `tracef-tracelog-limitations.txt`: limitations that apply to both + the `tracef(3)` and `tracelog(3)` man pages. + + +Convention +---------- + +Please follow those rules when updating the current man pages or writing +new ones: + + * Always use macros when possible (man page references, command-line + options, _not_, etc.). + * Use callouts with the `term` role for command-line examples. + * Use a verse, possibly with the `term` role, in the synopsis section. + * Always refer to _long_ options in the text. + * Use the `option:--option='PARAM'` format (with `=`) when providing a + parameter to long options. + * Prefer writing _user space_ rather than _userspace_, _user-space_, + or _user land_. + * Write _file system_, not _filesystem_. + * Prefer writing _use case_ rather than _use-case_ or _usecase_. + * Write _log level_, not _loglevel_. + * Write complete LTTng project names: _LTTng-modules_, _LTTng-UST_, + and _LTTng-tools_, not _modules_, _UST_ and _tools_. + * Prefer simple emphasis to strong emphasis for emphasizing text. + * Try to stay behind the 72th column mark if possible, and behind the + 80th column otherwise. + * Do not end directory paths with a forward slash (good: + `include/trace/events`, bad: `include/trace/events/`). + * Minimize the use of the future tense (_will_). + * Use an active voice, and prefer using the second person (_you_) when + referring to the user. + * Avoid using Latin abbreviations (_e.g._, _i.e._, _etc._). diff --git a/doc/man/asciidoc.conf b/doc/man/asciidoc.conf new file mode 100644 index 00000000..e3c8016d --- /dev/null +++ b/doc/man/asciidoc.conf @@ -0,0 +1,79 @@ +[macros] + +# man macro +# +# Inspired by linkgit macro: +# +# +# Usage: man:command(manpage-section) +(?su)[\\]?(?Pman):(?P\S*?)\((?P.*?)\)= + +# no link option macro +# +# Usage: nloption:--option-name +(?su)[\\]?(?Pnloption):(?P--?[a-zA-Z0-9-]*)= + +# option macro +# +# Usage: option:--option-name +(?su)[\\]?(?Poption):(?P--?[a-zA-Z0-9-]*)= + +# not macro +# +# Usage: :not: +:not:=not + +# man macro expansions +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[man-inlinemacro] +{0%{target}} +{0#} +{0#{target}{0}} +{0#} +endif::backend-docbook[] +endif::doctype-manpage[] + +# option macro expansions +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[option-inlinemacro] +{opt} +endif::backend-docbook[] +endif::doctype-manpage[] + +# no link option macro expansions +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[nloption-inlinemacro] +{opt} +endif::backend-docbook[] +endif::doctype-manpage[] + +# not macro expansions +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[not-inlinemacro] +NOT +endif::backend-docbook[] +endif::doctype-manpage[] + +# configure XML man page header +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[header] +template::[header-declarations] + + +{mantitle} +{manvolnum} +LTTng +{lttng_version} +LTTng Manual + + + {manname} + {manpurpose} + +endif::backend-docbook[] +endif::doctype-manpage[] diff --git a/doc/man/common-authors.txt b/doc/man/common-authors.txt new file mode 100644 index 00000000..fe1ccb09 --- /dev/null +++ b/doc/man/common-authors.txt @@ -0,0 +1,5 @@ +AUTHORS +------- +LTTng-UST was originally written by Mathieu Desnoyers, with additional +contributions from various other people. It is currently maintained by +mailto:mathieu.desnoyers@efficios.com[Mathieu Desnoyers]. diff --git a/doc/man/common-copyrights.txt b/doc/man/common-copyrights.txt new file mode 100644 index 00000000..a5cc0e2f --- /dev/null +++ b/doc/man/common-copyrights.txt @@ -0,0 +1,9 @@ +COPYRIGHTS +---------- +This {object-type} is part of the LTTng-UST project. + +This {object-type} is distributed under the +http://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html[GNU Lesser +General Public License, version 2.1]. See the +https://github.com/lttng/lttng-ust/blob/master/COPYING[`COPYING`] file +for more details. diff --git a/doc/man/common-footer-author.txt b/doc/man/common-footer-author.txt new file mode 100644 index 00000000..b98be71e --- /dev/null +++ b/doc/man/common-footer-author.txt @@ -0,0 +1,8 @@ +include::common-footer.txt[] + + +AUTHORS +------- +LTTng-UST was originally written by Mathieu Desnoyers, with additional +contributions from various other people. It is currently maintained by +mailto:mathieu.desnoyers@efficios.com[Mathieu Desnoyers]. diff --git a/doc/man/common-footer.txt b/doc/man/common-footer.txt new file mode 100644 index 00000000..66e6c761 --- /dev/null +++ b/doc/man/common-footer.txt @@ -0,0 +1,27 @@ +BUGS +---- +If you encounter any issue or usability problem, please report it on the +https://bugs.lttng.org/projects/lttng-ust[LTTng bug tracker]. + + +RESOURCES +--------- +* http://lttng.org[LTTng project website] +* http://lttng.org/docs[LTTng documentation] +* http://git.lttng.org[Git repositories] +* http://github.com/lttng[GitHub organization] +* http://ci.lttng.org/[Continuous integration] +* http://lists.lttng.org[Mailing list] for support and + development: `lttng-dev@lists.lttng.org` +* irc://irc.oftc.net/lttng[IRC channel]: `#lttng` on `irc.oftc.net` + + +COPYRIGHTS +---------- +This {object-type} is part of the LTTng-UST project. + +LTTng-UST is distributed under the +http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html[GNU General +Public License version 2]. See the +https://github.com/lttng/lttng-ust/blob/master/COPYING[`COPYING`] file +for details. diff --git a/doc/man/do_tracepoint.3 b/doc/man/do_tracepoint.3 new file mode 100644 index 00000000..afb50be9 --- /dev/null +++ b/doc/man/do_tracepoint.3 @@ -0,0 +1 @@ +.so man3/lttng-ust.3 diff --git a/doc/man/log-levels.txt b/doc/man/log-levels.txt new file mode 100644 index 00000000..b5afe92f --- /dev/null +++ b/doc/man/log-levels.txt @@ -0,0 +1,44 @@ +`TRACE_EMERG`:: + System is unusable. + +`TRACE_ALERT`:: + Action must be taken immediately. + +`TRACE_CRIT`:: + Critical conditions. + +`TRACE_ERR`:: + Error conditions. + +`TRACE_WARNING`:: + Warning conditions. + +`TRACE_NOTICE`:: + Normal, but significant, condition. + +`TRACE_INFO`:: + Informational message. + +`TRACE_DEBUG_SYSTEM`:: + Debug information with system-level scope (set of programs). + +`TRACE_DEBUG_PROGRAM`:: + Debug information with program-level scope (set of processes). + +`TRACE_DEBUG_PROCESS`:: + Debug information with process-level scope (set of modules). + +`TRACE_DEBUG_MODULE`:: + Debug information with module (executable/library) scope (set of units). + +`TRACE_DEBUG_UNIT`:: + Debug information with compilation unit scope (set of functions). + +`TRACE_DEBUG_FUNCTION`:: + Debug information with function-level scope. + +`TRACE_DEBUG_LINE`:: + Debug information with line-level scope (default log level). + +`TRACE_DEBUG`:: + Debug-level message. diff --git a/doc/man/lttng-gen-tp.1 b/doc/man/lttng-gen-tp.1 deleted file mode 100644 index cbaf3c77..00000000 --- a/doc/man/lttng-gen-tp.1 +++ /dev/null @@ -1,124 +0,0 @@ -.TH "LTTNG-GEN-TP" "1" "February 16, 2012" "" "" - -.SH "NAME" -lttng-gen-tp \(em LTTng UST 2.x tracepoint code generator - -.SH "SYNOPSIS" - -.PP -.nf -lttng\-gen\-tp [OPTIONS] TEMPLATE_FILE -.fi -.SH "DESCRIPTION" - -.PP -The LTTng project aims at providing highly efficient tracing tools for Linux. -Its tracers help in tracking down performance issues and debugging problems -involving multiple concurrent processes and threads. Tracing across multiple -systems is also possible. - -The \fBlttng\-gen\-tp\fP tool simplifies the generation of the UST tracepoint -files. It takes a simple template file and generates the necessary code to use the defined tracepoints in your application. -The section TEMPLATE FILE FORMAT describes the content of the template file. - -Currently, the tool can generate the .h, .c and .o associated with your -tracepoint. The generated .h can be directly included in your application. -You can let the tool generate the .o or compile the .c yourself. -You can compile the .c into a .o, .a or .so at your choice and -link it with your application. -Refer to the UST documentation for the -advantages and disadvantage of each form. -To compile the resulting .c file, you need to add the options -"\-llttng-ust \-I.". - -.SH "OPTIONS" - -.PP -This program follows the usual GNU command line syntax with long options starting with -two dashes. Below is a summary of the available options. -.PP - -.TP -.BR "\-h, \-\-help" -Show summary of possible options and commands. -.TP -.BR "\-v, \-\-verbose" -Increase verbosity. -.TP -.BR "\-o, \-\-output" -Specify the generated file. The type of the generated file depend on the file -extension (.h, .c, .o). -This option can be specified multiple times to generate different file type. - -.PP -When no output is specified the default files are generated with the same base filename as the template file. The default files are: .h, .c, .o. - -.SH "TEMPLATE FILE FORMAT" - -The template file, which has the usual extension \fB.tp\fP, contains a list of -TRACEPOINT_EVENT definitions and other optional definition entries like -TRACEPOINT_LOGLEVEL. -(See lttng-ust(3) for the complete list of available definition.) - -You write them as you would write them in a C header file. You can add -comments with \fB/* */\fP, \fB//\fP and \fB#\fP. - -The provider name (the first field of TRACEPOINT_EVENT) must be -the same for the whole file. - -.TP -.SH "Example" -.TP -.nf -TRACEPOINT_EVENT( - sample_tracepoint, - message, // Comment - TP_ARGS(char *, text), - /* Next are the fields */ - TP_FIELDS( - ctf_string(message, text) - ) -) -.SH "ENVIRONMENT VARIABLES" - -.PP -When the tool generates a .o file, it will look for the following environment variables -.PP - -.PP -.IP "CC" -Specify which C compiler to use. If the variable is not specified, the -tool will try "cc" and "gcc" - -.IP "CFLAGS" -Flags directly passed to the compiler -.SH "SEE ALSO" - -.PP -lttng-ust(3), lttng(1) -.PP -.SH "BUGS" - -.PP -If you encounter any issues or usability problem, please report it on our -mailing list to help improve this project. -.SH "CREDITS" - -.PP -lttng\-gen\-tp is distributed under the GNU General Public License version 2. See the file -COPYING for details. -.PP -A Web site is available at http://lttng.org for more information on the LTTng -project. -.PP -You can also find our git tree at http://git.lttng.org. -.PP -Mailing lists for support and development: . -.PP -You can find us on IRC server irc.oftc.net (OFTC) in #lttng. -.PP -.SH "AUTHORS" - -.PP -lttng\-gen\-tp is written by Yannick Brosseau . -.PP diff --git a/doc/man/lttng-gen-tp.1.txt b/doc/man/lttng-gen-tp.1.txt new file mode 100644 index 00000000..49467921 --- /dev/null +++ b/doc/man/lttng-gen-tp.1.txt @@ -0,0 +1,134 @@ +lttng-gen-tp(1) +=============== +:object-type: program + + +NAME +---- +lttng-gen-tp - Generate LTTng-UST tracepoint provider code + + +SYNOPSIS +-------- +[verse] +*lttng-gen-tp* [option:--verbose] [option:--output='FILE'.c] + [option:--output='FILE'.h] [option:--output='FILE'.o] 'TEMPLATE' + + +DESCRIPTION +----------- +The `lttng-gen-tp` tool simplifies the generation of LTTng-UST +tracepoint provider files. It takes a simple template file, 'TEMPLATE', +and generates the necessary C code to use the defined tracepoints in +your application. See the <> +section below for more information about the format of 'TEMPLATE'. + +Currently, `lttng-gen-tp` can generate the `.h`, `.c`, and `.o` files +associated with your tracepoint provider. The generated `.h` file can be +included directly in your application. You can let `lttng-gen-tp` +generate the `.o` file or compile the `.c` file yourself. See +man:lttng-ust(3) for more information about compiling LTTng-UST +tracepoint providers. + +By default, `lttng-gen-tp` generates the `.h`, `.c`, and `.o` files, +their basename being the basename of 'TEMPLATE'. You can generate one or +more specific file types with the option:--output option, repeated if +needed. + + +[[template-file-format]] +Template file format +~~~~~~~~~~~~~~~~~~~~ +The template file, which usually has the `.tp` extension, contains a +list of `TRACEPOINT_EVENT()` definitions and other optional definition +entries, like `TRACEPOINT_LOGLEVEL()`. See man:lttng-ust(3) for +the complete list of available definitions. + +The `TRACEPOINT_EVENT()` definitions are written as you would write them +in an LTTng-UST template provider header file. C comments are supported +(`/* */` and `//`), as well as lines starting with `#`. + +NOTE: The provider name (the first argument of `TRACEPOINT_EVENT()`) +must be the same in all the `TRACEPOINT_EVENT()` macros of 'TEMPLATE'. + +Here's an example: + +--------------------------------------- +TRACEPOINT_EVENT( + // Tracepoint provider name + my_provider, + + // Tracepoint/event name + my_event, + + // Tracepoint arguments (input) + TP_ARGS(char *, text), + + // Tracepoint/event fields (output) + TP_FIELDS( + ctf_string(message, text) + ) +) +--------------------------------------- + + +OPTIONS +------- +option:-o, option:--output='FILE':: + Do not generate default files: generate 'FILE'. ++ +The extension of 'FILE' determines what is generated, amongst `.h`, +`.c`, and `.o`. This option can be used more than one time to generate +different file types. + +option:-v, option:--verbose:: + Increase verbosity. + +option:-h, option:--help:: + Show command help. + + +ENVIRONMENT VARIABLES +--------------------- +`CC`:: + C compiler to use. Default: `cc`, then `gcc` if `cc` is not found. + This option is only relevant when generating the `.o` file. + +`CFLAGS`:: + Flags and options passed directly to the compiler (`$CC`). + This option is only relevant when generating the `.o` file. + + +EXIT STATUS +----------- +*0*:: + Success + +*Non-zero*:: + Error + + +include::common-footer.txt[] + + +COPYRIGHTS +---------- +`lttng-gen-tp` is part of the LTTng-UST project. + +`lttng-gen-tp` is distributed under the +http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html[GNU General +Public License, version 2]. See the +https://github.com/lttng/lttng-ust/blob/master/COPYING[`COPYING`] file +for more details. + + +AUTHOR +------ +`lttng-gen-tp` was originally written by +mailto:yannick.brosseau@gmail.com[Yannick Brosseau]. It is currently +maintained by mailto:mathieu.desnoyers@efficios.com[Mathieu Desnoyers]. + + +SEE ALSO +-------- +man:lttng-ust(3) diff --git a/doc/man/lttng-ust-cyg-profile.3 b/doc/man/lttng-ust-cyg-profile.3 deleted file mode 100644 index 341d3ae3..00000000 --- a/doc/man/lttng-ust-cyg-profile.3 +++ /dev/null @@ -1,79 +0,0 @@ -.TH "LTTNG-UST-CYG-PROFILE" "3" "March 26, 2013" "" "" -.SH "NAME" -lttng-ust-cyg-profile \(em LTTng UST 2.x Function Tracing -.SH "SYNOPSIS" -Compile the application source code with option \fB-finstrument-functions\fP -and launch your application either with: -.TP -\fBLD_PRELOAD=liblttng-ust-cyg-profile-fast.so\fP appname -.PP -or (to use verbose function tracing) -.TP -\fBLD_PRELOAD=liblttng-ust-cyg-profile.so\fP appname -.PP -All events emitted for function tracing are provided on loglevel -TRACE_DEBUG_FUNCTION. The following command can be used to add -function tracing events in your trace session: -.TP -.B lttng enable-event -u -a --loglevel-only TRACE_DEBUG_FUNCTION -.SH "DESCRIPTION" -For compilers that provide code generation option -\fB-finstrument-functions\fP (e.g. GCC and LLVM/Clang) LTTng-UST provides -shared libraries that allow users to trace the function flow of their -applications. - -Function tracing comes in two flavors (each providing different trade-offs): -.IP liblttng-ust-cyg-profile-fast.so -This is a lightweight variant that should only be used where it can be -guaranteed that the complete event stream is recorded without any missing -events. Any kind of duplicate information is left out. - -At each function entry the address of the called function is recored as -lttng_ust_cyg_profile_fast:func_entry. Function exit is recorded as -lttng_ust_cyg_profile_fast:func_exit (without any field data). - -.IP liblttng-ust-cyg-profile.so -This is a more robust variant which also works for use-cases where events -might get discarded or not recorded from application startup. In these cases -the trace analyzer needs extra information to be able to reconstruct the -program flow. - -For each function entry and exit the address of the called function and the -call site address are recorded as lttng_ust_cyg_profile:func_entry and -lttng_ust_cyg_profile:func_exit. -.SH "USAGE" -To use function tracing you need to make sure the sources of your application -are compiled with \-finstrument\-functions. It might be necessary to limit -the number of source files where this option is used to prevent excessive -amount of trace data to be generated during run time. Usually there are -additional compiler flags that allow you to specify more fine grained selection -of function instrumentation. - -For each instrumented function the executable will contain calls to profiling -function hooks (after function entry and just before function exit). - -By preloading (LD_PRELOAD) one of the provided shared libraries, these -profiling hooks get defined to emit LTTng events (as described above). - -Using this feature can result in massive amount trace data to be generated -by the instrumented application. Application runtime is also considerably -affected. Be careful on systems with limited resources. -.SH "SEE ALSO" -lttng-ust(3), lttng(1), gcc(1), ld.so(8) -.SH "BUGS" -If you encounter any issues or usability problem, please report it on -our mailing list to help improve this -project. -.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: . - -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 . diff --git a/doc/man/lttng-ust-cyg-profile.3.txt b/doc/man/lttng-ust-cyg-profile.3.txt new file mode 100644 index 00000000..267b9a40 --- /dev/null +++ b/doc/man/lttng-ust-cyg-profile.3.txt @@ -0,0 +1,174 @@ +lttng-ust-dl(3) +=============== +:object-type: library + + +NAME +---- +lttng-ust-cyg-profile - Function tracing (LTTng-UST helper) + + +SYNOPSIS +-------- +Compile your application with compiler option +nloption:-finstrument-functions. + +Launch your application by preloading +`liblttng-ust-cyg-profile-fast.so` for fast function tracing: + +[role="term"] +[verse] +*LD_PRELOAD=liblttng-ust-cyg-profile-fast.so* my-app + +Launch your application by preloading +`liblttng-ust-cyg-profile.so` for slower, more verbose function +tracing: + +[role="term"] +[verse] +*LD_PRELOAD=liblttng-ust-cyg-profile.so* my-app + + +DESCRIPTION +----------- +When the `liblttng-ust-cyg-profile.so` or the +`liblttng-ust-cyg-profile-fast.so` library is preloaded before a given +application starts, all function entry and return points are traced by +LTTng-UST (see man:lttng-ust(3)), provided said application was compiled +with the nloption:-finstrument-functions compiler option. + +See man:lttng(1) to learn more about how to control LTTng tracing +sessions. + +Function tracing with LTTng-UST comes in two flavors, each one +providing a different trade-off between performance and robustness: + +`liblttng-ust-cyg-profile-fast.so`:: + This is a lightweight variant that should only be used where it can + be _guaranteed_ that the complete event stream is recorded without + any missing events. Any kind of duplicate information is left out. ++ +At each function entry, the address of the called function is +recorded in an LTTng-UST event. Function exits are recorded as +another, empty LTTng-UST event. ++ +See the <> section below for the +complete list of emitted events and their fields. + +`liblttng-ust-cyg-profile.so`:: + This is a more robust variant which also works for use cases where + events might get discarded, or not recorded from application + startup. In these cases, the trace analyzer needs extra + information to be able to reconstruct the program flow. ++ +At each function entry _and_ exit, the address of the called +function _and_ the call site address are recorded in an LTTng-UST +event. ++ +See the <> section below for +the complete list of emitted events and their fields. + + +Usage +~~~~~ +To use LTTng-UST function tracing, you need to make sure the sources of +your application are compiled with the nloption:-finstrument-functions +compiler option. + +It might be necessary to limit the number of source files where this +option is used to prevent excessive amount of trace data to be generated +at run time. Usually, there are additional compiler flags that allow +you to specify a more fine-grained selection of function +instrumentation. + +For each instrumented function, the executable will contain calls to +profiling function hooks (after function entry, named `__cyg_profile_func_enter()`, +and just before function exit, named `__cyg_profile_func_exit()`). + +By preloading (using the `LD_PRELOAD` environment variable) one of the +provided shared libraries, these profiling hooks get defined to emit +LTTng events (as described below). + +NOTE: Using this feature can result in a *massive amount* of trace data +to be generated by the instrumented application. Application run time is +also considerably affected. Be careful on systems with limited +resources. + + +[[ftrace-fast]] +Fast function tracing +~~~~~~~~~~~~~~~~~~~~~ +The following LTTng-UST events are available when using +`liblttng-ust-cyg-profile-fast.so`. Their log level is set to +`TRACE_DEBUG_FUNCTION`. + +`lttng_ust_cyg_profile_fast:func_entry`:: + Emitted when an application function is entered, or more + specifically, when `__cyg_profile_func_enter()` is called. ++ +Fields: ++ +[options="header"] +|========================================================================= +| Field name | Description +| `func_addr` | Function address +|========================================================================= + +`lttng_ust_cyg_profile_fast:func_exit`:: + Emitted when an application function returns, or more + specifically, when `__cyg_profile_func_exit()` is called. ++ +This event has no fields. Since the `liblttng-ust-cyg-profile-fast.so` +library should only be used when it can be guaranteed that the complete +event stream is recorded without any missing events, a per-thread, +stack-based approach can be used on the trace analyzer side to match +function entry and return events. + + +[[ftrace-verbose]] +Verbose function tracing +~~~~~~~~~~~~~~~~~~~~~~~~ +The following LTTng-UST events are available when using +`liblttng-ust-cyg-profile.so`. Their log level is set to +`TRACE_DEBUG_FUNCTION`. + +`lttng_ust_cyg_profile:func_entry`:: + Emitted when an application function is entered, or more + specifically, when `__cyg_profile_func_enter()` is called. ++ +Fields: ++ +[options="header"] +|========================================================================= +| Field name | Description +| `func_addr` | Function address +| `call_site` | Address from which this function was called +|========================================================================= + +`lttng_ust_cyg_profile:func_exit`:: + Emitted when an application function returns, or more + specifically, when `__cyg_profile_func_exit()` is called. ++ +Fields: ++ +[options="header"] +|========================================================================= +| Field name | Description +| `func_addr` | Function address +| `call_site` | Address from which this function was called +|========================================================================= + + +include::common-footer.txt[] + +include::common-copyrights.txt[] + +include::common-authors.txt[] + + +SEE ALSO +-------- +man:lttng-ust(3), +man:lttng(1), +man:gcc(1), +man:ld.so(8) diff --git a/doc/man/lttng-ust-dl.3 b/doc/man/lttng-ust-dl.3 deleted file mode 100644 index cfd961eb..00000000 --- a/doc/man/lttng-ust-dl.3 +++ /dev/null @@ -1,52 +0,0 @@ -.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: -.TP -\fBLD_PRELOAD=liblttng-ust-dl.so\fP appname -.PP -This LD_PRELOAD library causes all calls to dlopen and dlclose in the -application to be traced with LTTng. In addition to loading this -library, enabling this tracing requires the following two events to be -enabled: "ust_baddr:push" and "ust_baddr:pop". - -.SH "DESCRIPTION" -The events have the following detailed definitions: -.PP -.IP "ust_baddr:push" -This event is used to trace dlopen calls. The base address (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 the "size" field and its time of last modification (in seconds since -Epoch) is recorded in the "mtime" field. -.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. -.PP - -.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 to help improve this -project. - -.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: . - -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 . diff --git a/doc/man/lttng-ust-dl.3.txt b/doc/man/lttng-ust-dl.3.txt new file mode 100644 index 00000000..93022220 --- /dev/null +++ b/doc/man/lttng-ust-dl.3.txt @@ -0,0 +1,99 @@ +lttng-ust-dl(3) +=============== +:object-type: library + + +NAME +---- +lttng-ust-dl - Dynamic linker tracing (LTTng-UST helper) + + +SYNOPSIS +-------- +Launch your application by preloading `liblttng-ust-dl.so`: + +[role="term"] +[verse] +*LD_PRELOAD=liblttng-ust-dl.so* my-app + + +DESCRIPTION +----------- +When the `liblttng-ust-dl.so` library is preloaded before a given +application starts, it causes all calls to man:dlopen(3) and +man:dlclose(3) in said application to be traced with LTTng-UST (see +man:lttng-ust(3)). + +See man:lttng(1) to learn more about how to control LTTng tracing +sessions. + +The following LTTng-UST events are available when using this library: + +`lttng_ust_dl:dlopen`:: + Emitted when man:dlopen(3) is called. ++ +Fields: ++ +[options="header"] +|============================================================== +| Field name | Description +| `baddr` | Base address of loaded library +| `memsz` | Size of loaded library in memory +| `sopath` | Path to loaded library file +|============================================================== + +`lttng_ust_dl:dlclose`:: + Emitted when man:dlclose(3) is called. ++ +Fields: ++ +[options="header"] +|============================================================== +| Field name | Description +| `baddr` | Base address of loaded library +|============================================================== + +`lttng_ust_dl:debug_link`:: + Emitted when debug link information is found when loading a library + with man:dlopen(3). See + https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files] + for more information about debug links. ++ +Fields: ++ +[options="header"] +|============================================================== +| Field name | Description +| `baddr` | Base address of loaded library +| `filename` | Debug link file name +| `crc` | Debug link file's CRC +|============================================================== + +`lttng_ust_dl:build_id`:: + Emitted when a build ID is found when loading a library + with man:dlopen(3). See + https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files] + for more information about build IDs. ++ +Fields: ++ +[options="header"] +|============================================================== +| Field name | Description +| `baddr` | Base address of loaded library +| `build_id` | Build ID +|============================================================== + + +include::common-footer.txt[] + +include::common-copyrights.txt[] + +include::common-authors.txt[] + + +SEE ALSO +-------- +man:lttng-ust(3), +man:dlopen(3), +man:lttng(1) diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3 deleted file mode 100644 index 4adef5b9..00000000 --- a/doc/man/lttng-ust.3 +++ /dev/null @@ -1,619 +0,0 @@ -.TH "LTTNG-UST" "3" "February 16, 2012" "" "" - -.SH "NAME" -lttng-ust \(em Linux Trace Toolkit Next Generation User-Space Tracer 2.x - -.SH "SYNOPSIS" - -.PP -.nf -Link liblttng-ust.so with applications, following this manpage. -.fi -.SH "DESCRIPTION" - -.PP -LTTng-UST, the Linux Trace Toolkit Next Generation Userspace Tracer, is a -port of the low-overhead tracing capabilities of the LTTng kernel tracer -to user-space. The library "liblttng-ust" enables tracing of -applications and libraries. - -.SH "USAGE WITH TRACEF" -.PP -The simplest way to add instrumentation to your code is by far the -tracef() API. To do it, in a nutshell: - -1) #include - -2) /* in your code, use like a printf */ - tracef("my message, this integer %d", 1234); - -3) Link your program against liblttng-ust.so. - -4) Enable UST events when tracing with the following sequence of commands - from lttng-tools: - - lttng create - lttng enable-event -u -a - lttng start - [... run your program ...] - lttng stop - lttng view - -That's it! - -If you want to have more flexibility and control on the event names, -payload typing, etc, you can continue reading on and use the tracepoints -below. "tracef()" is there for quick and dirty ad hoc instrumentation, -whereas tracepoint.h is meant for thorough instrumentation of a code -base to be integrated with an upstream project. -.PP - -.SH "USAGE WITH TRACELOG" -.PP -If you want to migrate existing logging (info, errors, ...) -to LTTng UST, you can use the tracelog() interface. -To do it, in a nutshell: - -1) #include - -2) /* in your code, use like a printf, with extra loglevel info. */ - tracelog(TRACE_INFO, "Message with integer %d", 1234); - -3) Link your program against liblttng-ust.so. - -4) Enable UST events when tracing with the following sequence of commands - from lttng-tools: - - lttng create - lttng enable-event -u "lttng_ust_tracelog:*" - lttng start - [... run your program ...] - lttng stop - lttng view - -That's it! - -You can replace the enable-event line above with a selection of -loglevels, e.g.: - - lttng enable-event -u -a --loglevel TRACE_INFO - -Which will gather all events from TRACE_INFO and more important -loglevels. - -.PP - -.SH "USAGE WITH TRACEPOINT" -.PP -The simple way to generate the lttng-ust tracepoint probes is to use the -lttng-gen-tp(1) tool. See the lttng-gen-tp(1) manpage for explanation. -.PP - -.PP -Here is the way to do it manually, without the lttng-gen-tp(1) helper -script, through an example: -.PP - -.SH "CREATION OF TRACEPOINT PROVIDER" - -.nf - -To create a tracepoint provider, within a build tree similar to -examples/easy-ust installed with lttng-ust documentation, see -sample_component_provider.h for the general layout. You will need to -define TRACEPOINT_CREATE_PROBES before including your tracepoint -provider probe in one source file of your application. See tp.c from -easy-ust for an example of a tracepoint probe source file. This manpage -will focus on the various types that can be recorded into a trace -event: - -TRACEPOINT_EVENT( - /* - * provider name, not a variable but a string starting with a - * letter and containing either letters, numbers or underscores. - * Needs to be the same as TRACEPOINT_PROVIDER. Needs to - * follow the namespacing guide-lines in lttng/tracepoint.h: - * - * Must be included before include tracepoint provider - * ex.: project_event - * ex.: project_component_event - * - * Optional company name goes here - * ex.: com_efficios_project_component_event - * - * In this example, "sample" is the project, and "component" is the - * component. - */ - sample_component, - - /* - * tracepoint name, characters permitted follow the same - * constraints as the provider name. The name of this example - * event is "sample_event". - */ - sample_event, - - /* - * TP_ARGS macro contains the arguments passed for the tracepoint - * it is in the following format - * TP_ARGS(type1, name1, type2, name2, ... type10, - name10) - * where there can be from zero to ten elements. - * typeN is the datatype, such as int, struct or double **. - * name is the variable name (in "int myInt" the name would be - * myint) - * TP_ARGS() is valid to mean no arguments - * TP_ARGS(void) is valid too - */ - TP_ARGS(int, anint, int, netint, long *, values, - char *, text, size_t, textlen, - double, doublearg, float, floatarg), - - /* - * TP_FIELDS describes how to write the fields of the trace event. - * You can put expressions in the "argument expression" area, - * typically using the input arguments from TP_ARGS. - */ - TP_FIELDS( - /* - * ctf_integer: standard integer field. - * args: (type, field name, argument expression) - */ - ctf_integer(int, intfield, anint) - ctf_integer(long, longfield, anint) - - /* - * ctf_integer_hex: integer field printed as hexadecimal. - * args: (type, field name, argument expression) - */ - ctf_integer_hex(int, intfield2, anint) - - /* - * ctf_integer_network: integer field in network byte - * order. (_hex: printed as hexadecimal too) - * args: (type, field name, argument expression) - */ - ctf_integer_network(int, netintfield, netint) - ctf_integer_network_hex(int, netintfieldhex, netint) - - /* - * ctf_array: a statically-sized array. - * args: (type, field name, argument expression, value) - */ - ctf_array(long, arrfield1, values, 3) - - /* - * ctf_array_text: a statically-sized array, printed as - * a string. No need to be terminated by a null - * character. - * Behavior is undefined if "text" argument is NULL. - */ - ctf_array_text(char, arrfield2, text, 10) - - /* - * ctf_sequence: a dynamically-sized array. - * args: (type, field name, argument expression, - * type of length expression, length expression) - * The "type of length expression" needs to be an - * unsigned type. As a reminder, "unsigned char" should - * be preferred to "char", since the signedness of - * "char" is implementation-defined. - * Behavior is undefined if "text" argument is NULL. - */ - ctf_sequence(char, seqfield1, text, - size_t, textlen) - - /* - * ctf_sequence_text: a dynamically-sized array, printed - * as string. No need to be null-terminated. - * Behavior is undefined if "text" argument is NULL. - */ - ctf_sequence_text(char, seqfield2, text, - size_t, textlen) - - /* - * ctf_string: null-terminated string. - * args: (field name, argument expression) - * Behavior is undefined if "text" argument is NULL. - */ - ctf_string(stringfield, text) - - /* - * ctf_float: floating-point number. - * args: (type, field name, argument expression) - */ - ctf_float(float, floatfield, floatarg) - ctf_float(double, doublefield, doublearg) - - /* - * ctf_enum: a field using a previously declared - * enumeration args: (provider, enum name, container - * type, field name, argument expression). The - * enumeration itself and its values must have been - * defined previously with the TRACEPOINT_ENUM macro, - * described below. - */ - ctf_enum(sample_component, enumeration_name, int, - enumfield, enumarg) - ) -) - -There can be an arbitrary number of tracepoint providers within an -application, but they must each have their own provider name. Duplicate -provider names are not allowed. - -The CTF specification also supports enumerations that can be declared -inside a tracepoint provider and used as fields in the tracepoint. This -shows how to specify enumerations and what they can be used for: - -The enumeration is a mapping between an integer, or a range of integers, and a -string. It can be used to have a more compact trace in cases where the possible -values for a field are limited: - -TRACEPOINT_ENUM( - /* - * The provider name, as described in the TRACEPOINT_EVENT macro. - */ - sample_component, - - /* - * The name of this enumeration, that will be used when using this - * global type in tracepoint fields. - */ - enumeration_name, - - /* - * TP_ENUM_VALUES describe the values of this enumeration and what they - * map to. - */ - TP_ENUM_VALUES( - /* - * Maps an integer with this string value. By default, enumerations - * start at 0 and increment 1 for each entry. - */ - ctf_enum_value(string_value) - - /* - * Maps the string value to integers in the range 'start' to 'end' - * inclusively. If 'start' == 'end', then the string is mapped to - * a specific value. - * Enumeration ranges may overlap, but the behavior is - * implementation-defined, each trace reader will handle overlapping - * as it wishes. - */ - ctf_enum_range(start, end, string_value) - ) -) - -.fi - -.SH "ASSIGNING LOGLEVEL TO EVENTS" - -.nf - -Optionally, a loglevel can be assigned to a TRACEPOINT_EVENT using the -following construct: - - TRACEPOINT_LOGLEVEL(< [com_company_]project[_component] >, - < event >, < loglevel_name >) - -The first field is the provider name, the second field is the name of -the tracepoint, and the third field is the loglevel name. A -TRACEPOINT_EVENT should be declared prior to the the TRACEPOINT_LOGLEVEL -for a given tracepoint name. The TRACEPOINT_PROVIDER must be already -declared before declaring a TRACEPOINT_LOGLEVEL. - -The loglevels go from 0 to 14. Higher numbers imply the most verbosity -(higher event throughput expected. - -Loglevels 0 through 6, and loglevel 14, match syslog(3) loglevels -semantic. Loglevels 7 through 13 offer more fine-grained selection of -debug information. - - TRACE_EMERG 0 - system is unusable - - TRACE_ALERT 1 - action must be taken immediately - - TRACE_CRIT 2 - critical conditions - - TRACE_ERR 3 - error conditions - - TRACE_WARNING 4 - warning conditions - - TRACE_NOTICE 5 - normal, but significant, condition - - TRACE_INFO 6 - informational message - - TRACE_DEBUG_SYSTEM 7 - debug information with system-level scope (set of programs) - - TRACE_DEBUG_PROGRAM 8 - debug information with program-level scope (set of processes) - - TRACE_DEBUG_PROCESS 9 - debug information with process-level scope (set of modules) - - TRACE_DEBUG_MODULE 10 - debug information with module (executable/library) scope (set of - units) - - TRACE_DEBUG_UNIT 11 - debug information with compilation unit scope (set of functions) - - TRACE_DEBUG_FUNCTION 12 - debug information with function-level scope - - TRACE_DEBUG_LINE 13 - debug information with line-level scope (TRACEPOINT_EVENT default) - - TRACE_DEBUG 14 - debug-level message - -See lttng(1) for information on how to use LTTng-UST loglevels. - -.fi - -.SH "ADDING TRACEPOINTS TO YOUR CODE" - -.nf - -Include the provider header in each C files you plan to instrument, -following the building/linking directives in the next section. - -For instance, add within a function: - - tracepoint(ust_tests_hello, tptest, i, netint, values, - text, strlen(text), dbl, flt); - -As a call to the tracepoint. It will only be activated when requested by -lttng(1) through lttng-sessiond(8). - -Even though LTTng-UST supports tracepoint() call site duplicates having -the same provider and event name, it is recommended to use a -provider event name pair only once within the source code to help -map events back to their call sites when analyzing the trace. - -Sometimes arguments to the probe are expensive to compute (e.g. -take call stack). To avoid the computation when the tracepoint is -disabled one can use more 'low level' tracepoint_enabled() and -do_tracepoint() macros as following: - - if (tracepoint_enabled(ust_tests_hello, tptest)) { - /* prepare arguments */ - do_tracepoint(ust_tests_hello, tptest, i, netint, values, - text, strlen(text), dbl, flt); - } - -Here do_tracepoint() doesn't contain check if the tracepoint is enabled. -Using tracepoint() in such scenario is dangerous since it also contains -enabled check and thus race condition is possible in the following code -if the tracepoint has been enabled after check in tracepoint_enabled() -but before tracepoint(): - - if (tracepoint_enabled(provider, name)) { /* tracepoint is disabled */ - prepare(args); - } - /* tracepoint is enabled by 'lttng' tool */ - tracepoint(provider, name, args); /* args wasn't prepared properly */ - -Note also that neither tracepoint_enabled() nor do_tracepoint() have -STAP_PROBEV() call so if you need it you should emit this call yourself. - -.fi - -.SH "BUILDING/LINKING THE TRACEPOINT PROVIDER" - -.nf -There are 2 ways to compile the Tracepoint Provider with the -application: either statically or dynamically. Please follow -carefully: - - 1) Compile the Tracepoint Provider with the application, either - directly or through a static library (.a): - - Into exactly one object of your application, define - "TRACEPOINT_DEFINE" and include the tracepoint provider. - - Use "\-I." for the compilation unit containing the tracepoint - provider include (e.g., tp.c). - - Link the application with "\-llttng-ust" and "\-ldl". - - Include the tracepoint provider header into all C files using - the provider. - - Examples: - - doc/examples/easy-ust/ sample.c sample_component_provider.h tp.c - Makefile - - doc/examples/hello-static-lib/ hello.c tp.c ust_test_hello.h Makefile - - 2) Compile the Tracepoint Provider separately from the application, - using dynamic linking: - - Into exactly one object of your application: define - "TRACEPOINT_DEFINE" _and_ also define - "TRACEPOINT_PROBE_DYNAMIC_LINKAGE", then include the tracepoint - provider header. - - Include the tracepoint provider header into all instrumented C - files that use the provider. - - Compile the tracepoint provider with "\-I.". - - Link the tracepoint provider with "\-llttng-ust". - - Link application with "\-ldl". - - Set a LD_PRELOAD environment to preload the tracepoint provider - shared object before starting the application when tracing is - needed. Another way is to dlopen the tracepoint probe when needed - by the application. - - Example: - - doc/examples/demo demo.c tp*.c ust_tests_demo*.h demo-trace Makefile - - - Note about dlclose() usage: it is not safe to use dlclose on a - provider shared object that is being actively used for tracing due - to a lack of reference counting from lttng-ust to the used shared - object. - - Enable instrumentation and control tracing with the "lttng" command - from lttng-tools. See lttng-tools doc/quickstart.txt. - - Note for C++ support: although an application instrumented with - tracepoints can be compiled with g++, tracepoint probes should be - compiled with gcc (only tested with gcc so far). - -.fi - -.SH "USING LTTNG UST WITH DAEMONS" - -.nf -Some extra care is needed when using liblttng-ust with daemon -applications that call fork(), clone(), or BSD rfork() without a -following exec() family system call. The library "liblttng-ust-fork.so" -needs to be preloaded for the application (launch with e.g. -LD_PRELOAD=liblttng-ust-fork.so appname). - -.fi - -.SH "CONTEXT" - -.PP -Context information can be prepended by the tracer before each, or some, -events. The following context information is supported by LTTng-UST: -.PP - -.PP -.IP "vtid" -Virtual thread ID: thread ID as seen from the point of view of the -process namespace. -.PP - -.PP -.IP "vpid" -Virtual process ID: process ID as seen from the point of view of the -process namespace. -.PP - -.PP -.IP "ip" -Instruction pointer: Enables recording of the exact location where a tracepoint -was emitted. Can be used to reverse-lookup the source location that caused the -event to be emitted. -.PP - -.PP -.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 -tracepoint for that thread. -.PP - -.PP -.IP "pthread_id" -Pthread identifier. Can be used on architectures where pthread_t maps -nicely to an unsigned long type. -.PP - -.SH "BASE ADDRESS STATEDUMP" - -.PP -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 event -needs to be enabled: -.PP -.IP "ust_baddr_statedump:soinfo" -This event is used to trace a currently loaded shared object. The base address -(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 the "size" field and its time of last modification -(in seconds since Epoch) is recorded in the "mtime" field. -.PP -If the event above is enabled, a series of "ust_baddr_statedump:soinfo" -events is recorded at session-enable time. It represents the state of -currently loaded shared objects for the traced process. If this -information gets combined with the lttng-ust-dl(3) instrumentation, all -aspects of dynamic loading that are relevant for symbol and -line number lookup are traced by LTTng. -.PP -.SH "ENVIRONMENT VARIABLES" - -.PP -.IP "LTTNG_UST_DEBUG" -Activate liblttng-ust debug and error output. -.PP -.IP "LTTNG_UST_REGISTER_TIMEOUT" -The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to -specify how long the applications should wait for sessiond -"registration done" command before proceeding to execute the main -program. The default is 3000ms (3 seconds). The timeout value is -specified in milliseconds. The value 0 means "don't wait". The value -\-1 means "wait forever". Setting this environment variable to 0 is -recommended for applications with time constraints on the process -startup time. -.PP -.IP "LTTNG_UST_WITHOUT_BADDR_STATEDUMP" -Prevent liblttng-ust to perform a base-address statedump on session-enable. -.PP -.IP "LTTNG_UST_GETCPU_PLUGIN" -Used by the getcpu override plugin system. The environment variable -provides the path to the shared object which will act as the getcpu override -plugin. An example can be found in the lttng-ust documentation under -examples/getcpu-override . -.PP -.IP "LTTNG_UST_CLOCK_PLUGIN" -Used by the clock override plugin system. The environment variable -provides the path to the shared object which will act as the clock override -plugin. An example can be found in the lttng-ust documentation under -doc/examples/clock-override . -.PP - -.SH "SEE ALSO" - -.PP -lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-ust-cyg-profile(3), -lttng-ust-dl(3), lttng-sessiond(8) -.PP - -.SH "COMPATIBILITY" - -.PP -Older lttng-ust libraries reject more recent, and incompatible, probe -providers. Newer lttng-ust libraries accept older probe providers, even -though some newer features might not be available with those providers. -.PP - -.SH "BUGS" - -.PP -LTTng-UST 2.0 and 2.1 lttng-ust libraries do not check for probe -provider version compatibility. This can lead to out-of-bound accesses -when using a more recent probe provider with an older lttng-ust library. -These error only trigger when tracing is active. This issue has been -fixed in LTTng-UST 2.2. - -If you encounter any issues or usability problem, please report it on -our mailing list to help improve this -project. -.SH "CREDITS" - -liblttng-ust is distributed under the GNU Lesser General Public License -version 2.1. The headers are distributed under the MIT license. -.PP -See http://lttng.org for more information on the LTTng project. -.PP -Mailing list for support and development: . -.PP -You can find us on IRC server irc.oftc.net (OFTC) in #lttng. -.PP -.SH "THANKS" - -Thanks to Ericsson for funding this work, providing real-life use-cases, -and testing. - -Special thanks to Michel Dagenais and the DORSAL laboratory at -Polytechnique de Montreal for the LTTng journey. -.PP -.SH "AUTHORS" - -.PP -liblttng-ust was originally written by Mathieu Desnoyers, with additional -contributions from various other people. It is currently maintained by -Mathieu Desnoyers . -.PP diff --git a/doc/man/lttng-ust.3.txt b/doc/man/lttng-ust.3.txt new file mode 100644 index 00000000..2fddbdc5 --- /dev/null +++ b/doc/man/lttng-ust.3.txt @@ -0,0 +1,1061 @@ +lttng-ust(3) +============ +:object-type: library + + +NAME +---- +lttng-ust - LTTng user space tracing + + +SYNOPSIS +-------- +[verse] +*#include * + +[verse] +#define *TRACEPOINT_ENUM*('prov_name', 'enum_name', 'mappings') +#define *TRACEPOINT_EVENT*('prov_name', 't_name', 'args', 'fields') +#define *TRACEPOINT_EVENT_CLASS*('prov_name', 'class_name', + 'args', 'fields') +#define *TRACEPOINT_EVENT_INSTANCE*('prov_name', 'class_name', + 't_name', 'args') +#define *TRACEPOINT_LOGLEVEL*('prov_name', 't_name', 'level') +#define *ctf_array*('int_type', 'field_name', 'expr', 'count') +#define *ctf_array_nowrite*('int_type', 'field_name', 'expr', 'count') +#define *ctf_array_text*(char, 'field_name', 'expr', 'count') +#define *ctf_array_text_nowrite*(char, 'field_name', 'expr', 'count') +#define *ctf_enum*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr') +#define *ctf_enum_nowrite*('prov_name', 'enum_name', 'int_type', + 'field_name', 'expr') +#define *ctf_enum_value*('label', 'value') +#define *ctf_enum_range*('label', 'start', 'end') +#define *ctf_float*('float_type', 'field_name', 'expr') +#define *ctf_float_nowrite*('float_type', 'field_name', 'expr') +#define *ctf_integer*('int_type', 'field_name', 'expr') +#define *ctf_integer_hex*('int_type', 'field_name', 'expr') +#define *ctf_integer_network*('int_type', 'field_name', 'expr') +#define *ctf_integer_network_hex*('int_type', 'field_name', 'expr') +#define *ctf_integer_nowrite*('int_type', 'field_name', 'expr') +#define *ctf_sequence*('int_type', 'field_name', 'expr', 'len_type', 'len_expr') +#define *ctf_sequence_nowrite*('int_type', 'field_name', 'expr', + 'len_type', 'len_expr') +#define *ctf_sequence_text*(char, 'field_name', 'expr', 'len_type', 'len_expr') +#define *ctf_sequence_text_nowrite*(char, 'field_name', 'expr', + 'len_type', 'len_expr') +#define *ctf_string*('field_name', 'expr') +#define *ctf_string_nowrite*('field_name', 'expr') +#define *do_tracepoint*('prov_name', 't_name', ...) +#define *tracepoint*('prov_name', 't_name', ...) +#define *tracepoint_enabled*('prov_name', 't_name') + +Link with `-llttng-ust -ldl`, following this man page. + + +DESCRIPTION +----------- +The http://lttng.org/[_Linux Trace Toolkit: next generation_] is an open +source software package used for correlated tracing of the Linux kernel, +user applications, and user libraries. + +LTTng-UST is the user space tracing component of the LTTng project. It +is a port to user space of the low-overhead tracing capabilities of the +LTTng Linux kernel tracer. The `liblttng-ust` library is used to trace +user applications and libraries. + +NOTE: This man page is about the `liblttng-ust` library. The LTTng-UST +project also provides Java and Python packages to trace applications +written in those languages. How to instrument and trace Java and Python +applications is documented in +http://lttng.org/docs/[the online LTTng documentation]. + +There are three ways to use `liblttng-ust`: + + * Using the man:tracef(3) API, which is similar to man:printf(3). + * Using the man:tracelog(3) API, which is man:tracef(3) with + a log level parameter. + * Defining your own tracepoints. See the + <> section below. + + +[[creating-tp]] +Creating a tracepoint provider +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Creating a tracepoint provider is the first step of using +`liblttng-ust`. The next steps are: + + * <> + * Building your application with LTTng-UST support, either + <> or <>. + +A *tracepoint provider* is a compiled object containing the event +probes corresponding to your custom tracepoint definitions. A tracepoint +provider contains the code to get the size of an event and to serialize +it, amongst other things. + +To create a tracepoint provider, start with the following +_tracepoint provider header_ template: + +------------------------------------------------------------------------ +#undef TRACEPOINT_PROVIDER +#define TRACEPOINT_PROVIDER my_provider + +#undef TRACEPOINT_INCLUDE +#define TRACEPOINT_INCLUDE "./tp.h" + +#if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ) +#define _TP_H + +#include + +/* + * TRACEPOINT_EVENT(), TRACEPOINT_EVENT_CLASS(), + * TRACEPOINT_EVENT_INSTANCE(), TRACEPOINT_LOGLEVEL(), + * and `TRACEPOINT_ENUM()` are used here. + */ + +#endif /* _TP_H */ + +#include +------------------------------------------------------------------------ + +In this template, the tracepoint provider is named `my_provider` +(`TRACEPOINT_PROVIDER` definition). The file needs to bear the +name of the `TRACEPOINT_INCLUDE` definition (`tp.h` in this case). +Between `#include ` and `#endif` go +the invocations of the <>, +<>, +<>, +<>, and +<> macros. + +NOTE: You can avoid writing the prologue and epilogue boilerplate in the +template file above by using the man:lttng-gen-tp(1) tool shipped with +LTTng-UST. + +The tracepoint provider header file needs to be included in a source +file which looks like this: + +------------------------------------------------------------------------ +#define TRACEPOINT_CREATE_PROBES + +#include "tp.h" +------------------------------------------------------------------------ + +Together, those two files (let's call them `tp.h` and `tp.c`) form the +tracepoint provider sources, ready to be compiled. + +You can create multiple tracepoint providers to be used in a single +application, but each one must have its own header file. + +The <> section below +shows how to use the `TRACEPOINT_EVENT()` macro to define the actual +tracepoints in the tracepoint provider header file. + +See the <> section below for a complete example. + + +[[tracepoint-event]] +`TRACEPOINT_EVENT()` usage +~~~~~~~~~~~~~~~~~~~~~~~~~~ +The `TRACEPOINT_EVENT()` macro is used in a template provider +header file (see the <> +section above) to define LTTng-UST tracepoints. + +The `TRACEPOINT_EVENT()` usage template is as follows: + +------------------------------------------------------------------------ +TRACEPOINT_EVENT( + /* Tracepoint provider name */ + my_provider, + + /* Tracepoint/event name */ + my_tracepoint, + + /* List of tracepoint arguments (input) */ + TP_ARGS( + ... + ), + + /* List of fields of eventual event (output) */ + TP_FIELDS( + ... + ) +) +------------------------------------------------------------------------ + +The `TP_ARGS()` macro contains the input arguments of the tracepoint. +Those arguments can be used in the argument expressions of the output +fields defined in `TP_FIELDS()`. + +The format of the `TP_ARGS()` parameters is: C type, then argument name; +repeat as needed, up to ten times. For example: + +------------------------------------------------------------------------ +TP_ARGS( + int, my_int, + const char *, my_string, + FILE *, my_file, + double, my_float, + struct my_data *, my_data +) +------------------------------------------------------------------------ + +The `TP_FIELDS()` macro contains the output fields of the tracepoint, +that is, the actual data that can be recorded in the payload of an +event emitted by this tracepoint. + +The `TP_FIELDS()` macro contains a list of `ctf_*()` macros +:not: separated by commas. The available macros are documented in the +<> section below. + + +[[ctf-macros]] +Available `ctf_*()` field type macros +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This section documents the available `ctf_*()` macros that can be +inserted in the `TP_FIELDS()` macro of the +<>. + +Standard integer, displayed in base 10: + +[verse] +*ctf_integer*('int_type', 'field_name', 'expr') +*ctf_integer_nowrite*('int_type', 'field_name', 'expr') + +Standard integer, displayed in base 16: + +[verse] +*ctf_integer_hex*('int_type', 'field_name', 'expr') + +Integer in network byte order (big endian), displayed in base 10: + +[verse] +*ctf_integer_network*('int_type', 'field_name', 'expr') + +Integer in network byte order, displayed in base 16: + +[verse] +*ctf_integer_network_hex*('int_type', 'field_name', 'expr') + +Floating point number: + +[verse] +*ctf_float*('float_type', 'field_name', 'expr') +*ctf_float_nowrite*('float_type', 'field_name', 'expr') + +Null-terminated string: + +[verse] +*ctf_string*('field_name', 'expr') +*ctf_string_nowrite*('field_name', 'expr') + +Statically-sized array of integers: + +[verse] +*ctf_array*('int_type', 'field_name', 'expr', 'count') +*ctf_array_nowrite*('int_type', 'field_name', 'expr', 'count') + +Statically-sized array, printed as text; no need to be null-terminated: + +[verse] +*ctf_array_text*(char, 'field_name', 'expr', 'count') +*ctf_array_text_nowrite*(char, 'field_name', 'expr', 'count') + +Dynamically-sized array of integers: + +[verse] +*ctf_sequence*('int_type', 'field_name', 'expr', 'len_type', 'len_expr') +*ctf_sequence_nowrite*('int_type', 'field_name', 'expr', 'len_type', 'len_expr') + +Dynamically-sized array, displayed as text; no need to be null-terminated: + +[verse] +*ctf_sequence_text*(char, 'field_name', 'expr', 'len_type', 'len_expr') +*ctf_sequence_text_nowrite*(char, 'field_name', 'expr', 'len_type', 'len_expr') + +Enumeration. The enumeration field must be defined before using this +macro with the `TRACEPOINT_ENUM()` macro. See the +<> section for more +information. + +[verse] +*ctf_enum*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr') +*ctf_enum_nowrite*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr') + +The parameters are: + +'int_type':: + Integer C type. The size of this type determines the size of the + integer/enumeration field. + +'float_type':: + Float C type (`float` or `double`). The size of this type determines + the size of the floating point number field. + +'field_name':: + Event field name (C identifier syntax, :not: a literal string). + +'expr':: + C expression resulting in the field's value. This expression can + use one or more arguments passed to the tracepoint. The arguments + of a given tracepoint are defined in the `TP_ARGS()` macro (see + the <> section above). + +'count':: + Number of elements in array/sequence. This must be known at + compile time. + +'len_type':: + Unsigned integer C type of sequence's length. + +'len_expr':: + C expression resulting in the sequence's length. This expression + can use one or more arguments passed to the tracepoint. + +'prov_name':: + Tracepoint provider name. This must be the same as the tracepoint + provider name used in a previous field definition. + +'enum_name':: + Name of an enumeration field previously defined with the + `TRACEPOINT_ENUM()` macro. See the + <> section for more + information. + +The `_nowrite` versions omit themselves from the recorded trace, but are +otherwise identical. Their primary purpose is to make some of the +event context available to the event filters without having to commit +the data to sub-buffers. See man:lttng-enable-event(1) to learn more +about dynamic event filtering. + +See the <> section below for a complete example. + + +[[tracepoint-enum]] +`TRACEPOINT_ENUM()` usage +~~~~~~~~~~~~~~~~~~~~~~~~~ +An enumeration field is a list of mappings between an integers, or a +range of integers, and strings (sometimes called _labels_ or +_enumerators_). Enumeration fields can be used to have a more compact +trace when the possible values for a field are limited. + +An enumeration field is defined with the `TRACEPOINT_ENUM()` macro: + +------------------------------------------------------------------------ +TRACEPOINT_ENUM( + /* Tracepoint provider name */ + my_provider, + + /* Enumeration name (unique in the whole tracepoint provider) */ + my_enum, + + /* Enumeration mappings */ + TP_ENUM_VALUES( + ... + ) +) +------------------------------------------------------------------------ + +`TP_ENUM_VALUES()` contains a list of enumeration mappings, :not: +separated by commas. Two macros can be used in the `TP_ENUM_VALUES()`: +`ctf_enum_value()` and `ctf_enum_range()`. + +`ctf_enum_value()` is a single value mapping: + +[verse] +*ctf_enum_value*('label', 'value') + +This macro maps the given 'label' string to the value 'value'. + +`ctf_enum_range()` is a range mapping: + +[verse] +*ctf_enum_range*('label', 'start', 'end') + +This macro maps the given 'label' string to the range of integers from +'start' to 'end', inclusively. Range mappings may overlap, but the +behaviour is implementation-defined: each trace reader handles +overlapping ranges as it wishes. + +See the <> section below for a complete example. + + +[[tracepoint-event-class]] +`TRACEPOINT_EVENT_CLASS()` usage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A *tracepoint class* is a class of tracepoints sharing the +same field types and names. A tracepoint instance is one instance of +such a declared tracepoint class, with its own event name. + +LTTng-UST creates one event serialization function per tracepoint +class. Using `TRACEPOINT_EVENT()` creates one tracepoint class per +tracepoint definition, whereas using `TRACEPOINT_EVENT_CLASS()` and +`TRACEPOINT_EVENT_INSTANCE()` creates one tracepoint class, and one or +more tracepoint instances of this class. In other words, many +tracepoints can reuse the same serialization code. Reusing the same +code, when possible, can reduce cache pollution, thus improve +performance. + +The `TRACEPOINT_EVENT_CLASS()` macro accepts the same parameters as +the `TRACEPOINT_EVENT()` macro, except that instead of an event name, +its second parameter is the _tracepoint class name_: + +------------------------------------------------------------------------ +TRACEPOINT_EVENT_CLASS( + /* Tracepoint provider name */ + my_provider, + + /* Tracepoint class name */ + my_tracepoint_class, + + /* List of tracepoint arguments (input) */ + TP_ARGS( + ... + ), + + /* List of fields of eventual event (output) */ + TP_FIELDS( + ... + ) +) +------------------------------------------------------------------------ + +Once the tracepoint class is defined, you can create as many tracepoint +instances as needed: + +------------------------------------------------------------------------- +TRACEPOINT_EVENT_INSTANCE( + /* Tracepoint provider name */ + my_provider, + + /* Tracepoint class name */ + my_tracepoint_class, + + /* Tracepoint/event name */ + my_tracepoint, + + /* List of tracepoint arguments (input) */ + TP_ARGS( + ... + ) +) +------------------------------------------------------------------------ + +As you can see, the `TRACEPOINT_EVENT_INSTANCE()` does not contain +the `TP_FIELDS()` macro, because they are defined at the +`TRACEPOINT_EVENT_CLASS()` level. + +See the <> section below for a complete example. + + +[[tracepoint-loglevel]] +`TRACEPOINT_LOGLEVEL()` usage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Optionally, a *log level* can be assigned to a defined tracepoint. +Assigning different levels of severity to tracepoints can be useful: +when controlling tracing sessions, you can choose to only enable +events falling into a specific log level range using the +nloption:--loglevel and nloption:--loglevel-only options of the +man:lttng-enable-event(1) command. + +Log levels are assigned to tracepoints that are already defined using +the `TRACEPOINT_LOGLEVEL()` macro. The latter must be used after having +used `TRACEPOINT_EVENT()` or `TRACEPOINT_EVENT_INSTANCE()` for a given +tracepoint. The `TRACEPOINT_LOGLEVEL()` macro is used as follows: + +------------------------------------------------------------------------ +TRACEPOINT_LOGLEVEL( + /* Tracepoint provider name */ + my_provider, + + /* Tracepoint/event name */ + my_tracepoint, + + /* Log level */ + TRACE_INFO +) +------------------------------------------------------------------------ + +The available log level definitions are: + +include::log-levels.txt[] + +See the <> section below for a complete example. + + +[[tracepoint]] +Instrumenting your application +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Once the tracepoint provider is created (see the +<> section above), you can +instrument your application with the defined tracepoints thanks to the +`tracepoint()` macro: + +[verse] +#define *tracepoint*('prov_name', 't_name', ...) + +With: + +'prov_name':: + Tracepoint provider name. + +'t_name':: + Tracepoint/event name. + +`...`:: + Tracepoint arguments, if any. + +Make sure to include the tracepoint provider header file anywhere you +use `tracepoint()` for this provider. + +NOTE: Even though LTTng-UST supports `tracepoint()` call site duplicates +having the same provider and tracepoint names, it is recommended to use +a provider/tracepoint name pair only once within the application source +code to help map events back to their call sites when analyzing the +trace. + +Sometimes, arguments to the tracepoint are expensive to compute (take +call stack, for example). To avoid the computation when the tracepoint +is disabled, you can use the `tracepoint_enabled()` and +`do_tracepoint()` macros: + +[verse] +#define *tracepoint_enabled*('prov_name', 't_name') +#define *do_tracepoint*('prov_name', 't_name', ...) + +`tracepoint_enabled()` returns a non-zero value if the tracepoint +named 't_name' from the provider named 'prov_name' is enabled at +run time. + +`do_tracepoint()` is like `tracepoint()`, except that it doesn't check +if the tracepoint is enabled. Using `tracepoint()` with +`tracepoint_enabled()` is dangerous since `tracepoint()` also contains +the `tracepoint_enabled()` check, thus a race condition is possible +in this situation: + +------------------------------------------------------------------------ +if (tracepoint_enabled(my_provider, my_tracepoint)) { + stuff = prepare_stuff(); +} + +tracepoint(my_provider, my_tracepoint, stuff); +------------------------------------------------------------------------ + +If the tracepoint is enabled after the condition, then `stuff` is not +prepared: the emitted event will either contain wrong data, or the +whole application could crash (segmentation fault, for example). + +NOTE: Neither `tracepoint_enabled()` nor `do_tracepoint()` have +a `STAP_PROBEV()` call, so if you need it, you should emit this call +yourself. + + +[[build-static]] +Statically linking the tracepoint provider +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +With the static linking method, compiled tracepoint providers are copied +into the target application. + +Define `TRACEPOINT_DEFINE` definition below the +`TRACEPOINT_CREATE_PROBES` definition in the tracepoint provider +source: + +------------------------------------------------------------------------ +#define TRACEPOINT_CREATE_PROBES +#define TRACEPOINT_DEFINE + +#include "tp.h" +------------------------------------------------------------------------ + +Create the tracepoint provider object file: + +[role="term"] +-------------- +cc -c -I. tp.c +-------------- + +NOTE: Although an application instrumented with LTTng-UST tracepoints +can be compiled with a C++ compiler, tracepoint probes should be +compiled with a C compiler. + +At this point, you _can_ archive this tracepoint provider object file, +possibly with other object files of your application or with other +tracepoint provider object files, as a static library: + +[role="term"] +--------------- +ar rc tp.a tp.o +--------------- + +Using a static library does have the advantage of centralising the +tracepoint providers objects so they can be shared between multiple +applications. This way, when the tracepoint provider is modified, the +source code changes don't have to be patched into each application's +source code tree. The applications need to be relinked after each +change, but need not to be otherwise recompiled (unless the tracepoint +provider's API changes). + +Then, link your application with this object file (or with the static +library containing it) and with `liblttng-ust` and `libdl` +(`libc` on a BSD system): + +[role="term"] +------------------------------------- +cc -o app tp.o app.o -llttng-ust -ldl +------------------------------------- + + +[[build-dynamic]] +Dynamically loading the tracepoint provider +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The second approach to package the tracepoint provider is to use the +dynamic loader: the library and its member functions are explicitly +sought, loaded at run time. + +In this scenario, the tracepoint provider is compiled as a shared +object. + +The process to create the tracepoint provider shared object is pretty +much the same as the <>, except +that: + + * Since the tracepoint provider is not part of the application, + `TRACEPOINT_DEFINE` must be defined, for each tracepoint + provider, in exactly one source file of the + _application_ + * `TRACEPOINT_PROBE_DYNAMIC_LINKAGE` must be defined next + to `TRACEPOINT_DEFINE` + +Regarding `TRACEPOINT_DEFINE` and `TRACEPOINT_PROBE_DYNAMIC_LINKAGE`, +the recommended practice is to use a separate C source file in your +application to define them, then include the tracepoint provider header +files afterwards. For example, as `tp-define.c`: + +------------------------------------------------------------------------ +#define TRACEPOINT_DEFINE +#define TRACEPOINT_PROBE_DYNAMIC_LINKAGE + +#include "tp.h" +------------------------------------------------------------------------ + +The tracepoint provider object file used to create the shared library is +built like it is using the static linking method, but with the +nloption:-fpic option: + +[role="term"] +-------------------- +cc -c -fpic -I. tp.c +-------------------- + +It is then linked as a shared library like this: + +[role="term"] +------------------------------------------------------- +cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust +------------------------------------------------------- + +This tracepoint provider shared object isn't linked with the user +application: it must be loaded manually. This is why the application is +built with no mention of this tracepoint provider, but still needs +libdl: + +[role="term"] +-------------------------------- +cc -o app app.o tp-define.o -ldl +-------------------------------- + +There are two ways to dynamically load the tracepoint provider shared +object: + + * Load it manually from the application using man:dlopen(3) + * Make the dynamic loader load it with the `LD_PRELOAD` + environment variable (see man:ld.so(8)) + +If the application does not dynamically load the tracepoint provider +shared object using one of the methods above, tracing is disabled for +this application, and the events are not listed in the output of +man:lttng-list(1). + +Note that it is not safe to use man:dlclose(3) on a tracepoint provider +shared object that is being actively used for tracing, due to a lack of +reference counting from LTTng-UST to the shared object. + +For example, statically linking a tracepoint provider to a shared object +which is to be dynamically loaded by an application (a plugin, for +example) is not safe: the shared object, which contains the tracepoint +provider, could be dynamically closed (man:dlclose(3)) at any time by +the application. + +To instrument a shared object, either: + + * Statically link the tracepoint provider to the application, or + * Build the tracepoint provider as a shared object (following the + procedure shown in this section), and preload it when tracing is + needed using the `LD_PRELOAD` environment variable. + + +Using LTTng-UST with daemons +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Some extra care is needed when using `liblttng-ust` with daemon +applications that call man:fork(2), man:clone(2), or BSD's man:rfork(2) +without a following man:exec(3) family system call. The library +`liblttng-ust-fork.so` needs to be preloaded before starting the +application with the `LD_PRELOAD` environment variable (see +man:ld.so(8)). + + +Context information +~~~~~~~~~~~~~~~~~~~ +Context information can be prepended by the LTTng-UST tracer before +each event, or before specific events. + +Context fields can be added to specific channels using +man:lttng-add-context(1). + +The following context fields are supported by LTTng-UST: + +`cpu_id`:: + CPU ID. ++ +NOTE: This context field is always enabled, and it cannot be added +with man:lttng-add-context(1). Its main purpose is to be used for +dynamic event filtering. See man:lttng-enable-event(1) for more +information about event filtering. + +`ip`:: + Instruction pointer: enables recording the exact address from which + an event was emitted. This context field can be used to + reverse-lookup the source location that caused the event + to be emitted. + ++perf:thread:COUNTER+:: + perf counter named 'COUNTER'. Use `lttng add-context --list` to + list the available perf counters. ++ +Only available on IA-32 and x86-64 architectures. + +`pthread_id`:: + POSIX thread identifier. Can be used on architectures where + `pthread_t` maps nicely to an `unsigned long` type. + +`procname`:: + Thread name, as set by man:exec(3) or man:prctl(2). It is + recommended that programs set their thread name with man:prctl(2) + before hitting the first tracepoint for that thread. + +`vpid`:: + Virtual process ID: process ID as seen from the point of view of + the process namespace. + +`vtid`:: + Virtual thread ID: thread ID as seen from the point of view of + the process namespace. + + +LTTng-UST state dump +~~~~~~~~~~~~~~~~~~~~ +If an application that uses `liblttng-ust` becomes part of a tracing +session, information about its currently loaded shared objects, their +build IDs, and their debug link informations are emitted as events +by the tracer. + +The following LTTng-UST state dump events exist and must be enabled +to record application state dumps. + +`lttng_ust_statedump:start`:: + Emitted when the state dump begins. ++ +This event has no fields. + +`lttng_ust_statedump:end`:: + Emitted when the state dump ends. Once this event is emitted, it + is guaranteed that, for a given process, the state dump is + complete. ++ +This event has no fields. + +`lttng_ust_statedump:soinfo`:: + Emitted when information about a currently loaded shared object is + found. ++ +Fields: ++ +[options="header"] +|============================================================== +| Field name | Description +| `baddr` | Base address of loaded library +| `memsz` | Size of loaded library in memory +| `sopath` | Path to loaded library file +|============================================================== + +`lttng_ust_statedump:build_id`:: + Emitted when a build ID is found in a currently loaded shared + library. See + https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files] + for more information about build IDs. ++ +Fields: ++ +[options="header"] +|============================================================== +| Field name | Description +| `baddr` | Base address of loaded library +| `build_id` | Build ID +|============================================================== + +`lttng_ust_statedump:debug_link`:: + Emitted when debug link information is found in a currently loaded + shared library. See + https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files] + for more information about debug links. ++ +Fields: ++ +[options="header"] +|============================================================== +| Field name | Description +| `baddr` | Base address of loaded library +| `crc` | Debug link file's CRC +| `filename` | Debug link file name +|============================================================== + + +[[example]] +EXAMPLE +------- +NOTE: A few examples are available in the +https://github.com/lttng/lttng-ust/tree/master/doc/examples[`doc/examples`] +directory of LTTng-UST's source tree. + +This example shows all the features documented in the previous +sections. The <> method is chosen here +to link the application with the tracepoint provider. + +Let's start with the tracepoint provider header file (`tp.h`): + +------------------------------------------------------------------------ +#undef TRACEPOINT_PROVIDER +#define TRACEPOINT_PROVIDER my_provider + +#undef TRACEPOINT_INCLUDE +#define TRACEPOINT_INCLUDE "./tp.h" + +#if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ) +#define _TP_H + +#include +#include + +#include "app.h" + +TRACEPOINT_EVENT( + my_provider, + simple_event, + TP_ARGS( + int, my_integer_arg, + const char *, my_string_arg + ), + TP_FIELDS( + ctf_string(argc, my_string_arg) + ctf_integer(int, argv, my_integer_arg) + ) +) + +TRACEPOINT_ENUM( + my_provider, + my_enum, + TP_ENUM_VALUES( + ctf_enum_value("ZERO", 0) + ctf_enum_value("ONE", 1) + ctf_enum_value("TWO", 2) + ctf_enum_range("A RANGE", 52, 125) + ctf_enum_value("ONE THOUSAND", 1000) + ) +) + +TRACEPOINT_EVENT( + my_provider, + big_event, + TP_ARGS( + int, my_integer_arg, + const char *, my_string_arg, + FILE *, stream, + double, flt_arg, + int *, array_arg + ), + TP_FIELDS( + ctf_integer(int, int_field1, my_integer_arg * 2) + ctf_integer_hex(long int, stream_pos, ftell(stream)) + ctf_float(double, float_field, flt_arg) + ctf_string(string_field, my_string_arg) + ctf_array(int, array_field, array_arg, 7) + ctf_array_text(char, array_text_field, array_arg, 5) + ctf_sequence(int, seq_field, array_arg, int, + my_integer_arg / 10) + ctf_sequence_text(char, seq_text_field, array_arg, + int, my_integer_arg / 5) + ctf_enum(my_provider, my_enum, int, + enum_field, array_arg[1]) + ) +) + +TRACEPOINT_LOGLEVEL(my_provider, big_event, TRACE_WARNING) + +TRACEPOINT_EVENT_CLASS( + my_provider, + my_tracepoint_class, + TP_ARGS( + int, my_integer_arg, + struct app_struct *, app_struct_arg + ), + TP_FIELDS( + ctf_integer(int, a, my_integer_arg) + ctf_integer(unsigned long, b, app_struct_arg->b) + ctf_string(c, app_struct_arg->c) + ) +) + +TRACEPOINT_EVENT_INSTANCE( + my_provider, + my_tracepoint_class, + event_instance1, + TP_ARGS( + int, my_integer_arg, + struct app_struct *, app_struct_arg + ) +) + +TRACEPOINT_EVENT_INSTANCE( + my_provider, + my_tracepoint_class, + event_instance2, + TP_ARGS( + int, my_integer_arg, + struct app_struct *, app_struct_arg + ) +) + +TRACEPOINT_LOGLEVEL(my_provider, event_instance2, TRACE_INFO) + +TRACEPOINT_EVENT_INSTANCE( + my_provider, + my_tracepoint_class, + event_instance3, + TP_ARGS( + int, my_integer_arg, + struct app_struct *, app_struct_arg + ) +) + +#endif /* _TP_H */ + +#include +------------------------------------------------------------------------ + +The tracepoint provider source file looks like this (`tp.c`): + +------------------------------------------------------------------------ +#define TRACEPOINT_CREATE_PROBES +#define TRACEPOINT_DEFINE + +#include "tp.h" +------------------------------------------------------------------------ + +The included `app.h`, where the application structure resides, is: + +------------------------------------------------------------------------ +#ifndef _APP_H +#define _APP_H + +struct app_struct { + unsigned long b; + const char *c; + double d; +}; + +#endif /* _APP_H */ +------------------------------------------------------------------------ + +Finally, the application itself, `app.c`, using the defined tracepoints: + +------------------------------------------------------------------------ +#include +#include + +#include "tp.h" +#include "app.h" + +static int array_of_ints[] = { + 100, -35, 1, 23, 14, -6, 28, 1001, -3000, +}; + +int main(int argc, char* argv[]) +{ + FILE *stream; + struct app_struct app_struct; + + tracepoint(my_provider, simple_event, argc, argv[0]); + stream = fopen("/tmp/app.txt", "w"); + + if (!stream) { + fprintf(stderr, + "Error: Cannot open /tmp/app.txt for writing\n"); + return EXIT_FAILURE; + } + + if (fprintf(stream, "0123456789") != 10) { + fclose(stream); + fprintf(stderr, "Error: Cannot write to /tmp/app.txt\n"); + return EXIT_FAILURE; + } + + tracepoint(my_provider, big_event, 35, "hello tracepoint", + stream, -3.14, array_of_ints); + fclose(stream); + app_struct.b = argc; + app_struct.c = "[the string]"; + tracepoint(my_provider, event_instance1, 23, &app_struct); + app_struct.b = argc * 5; + app_struct.c = "[other string]"; + tracepoint(my_provider, event_instance2, 17, &app_struct); + app_struct.b = 23; + app_struct.c = "nothing"; + tracepoint(my_provider, event_instance3, -52, &app_struct); + + return EXIT_SUCCESS; +} +------------------------------------------------------------------------ + +Here are the steps to compile the source files and link them together +statically: + +[role="term"] +------------------------------------- +cc -c -I. tp.c +cc -c app.c +cc -o app tp.o app.o -llttng-ust -ldl +------------------------------------- + + +include::common-footer.txt[] + +include::common-copyrights.txt[] + +include::common-authors.txt[] + + +SEE ALSO +-------- +man:tracef(3), +man:tracelog(3), +man:lttng-gen-tp(1), +man:lttng-ust-dl(3), +man:lttng-ust-cyg-profile(3), +man:lttng(1), +man:lttng-enable-event(1), +man:lttng-list(1), +man:lttng-add-context(1), +man:babeltrace(1), +man:dlopen(3), +man:ld.so(8) diff --git a/doc/man/tracef-tracelog-limitations.txt b/doc/man/tracef-tracelog-limitations.txt new file mode 100644 index 00000000..a9491903 --- /dev/null +++ b/doc/man/tracef-tracelog-limitations.txt @@ -0,0 +1,24 @@ +The +{macro-name}()+ utility macro was developed to make user space +tracing super simple, albeit with notable disadvantages compared to +custom, full-fledged tracepoint providers: + + * All generated events have the same provider/event names. + * There's no static type checking. + * The only event field with user data you actually get, named `msg`, + is a string potentially containing the values you passed to the + macro using your own format. This also means that you cannot use + filtering using a custom expression at run time because there are no + isolated fields. + * Since +{macro-name}()+ uses C standard library's man:vasprintf(3) + function in the background to format the strings at run time, its + expected performance is lower than using custom tracepoint providers + with typed fields, which do not require a conversion to a string. + * Generally, a string containing the textual representation of the + user data fields is not as compact as binary fields in the + resulting trace. + +Thus, +{macro-name}()+ is useful for quick prototyping and debugging, but +should not be considered for any permanent/serious application +instrumentation. + +See man:lttng-ust(3) to learn more about custom tracepoint providers. diff --git a/doc/man/tracef.3.txt b/doc/man/tracef.3.txt new file mode 100644 index 00000000..cb35cc85 --- /dev/null +++ b/doc/man/tracef.3.txt @@ -0,0 +1,122 @@ +tracef(3) +========= +:object-type: macro + + +NAME +---- +tracef - LTTng-UST man:printf(3)-like interface + + +SYNOPSIS +-------- +[verse] +*#include * + +[verse] +#define *tracef*('fmt', ...) + +Link with `-llttng-ust`. + + +DESCRIPTION +----------- +The LTTng-UST `tracef()` API allows you to trace your application with +the help of a simple man:printf(3)-like macro. The 'fmt' argument is +passed directly to the 'fmt' parameter of man:vasprintf(3), as well as +the optional parameters following 'fmt'. + +To use `tracef()`, include `` where you need it, and +link your application with `liblttng-ust`. See the <> +section below for a complete usage example. + +Once your application is instrumented with `tracef()` calls and +ready to run, use man:lttng-enable-event(1) to enable the +`lttng_ust_tracef:*` event. + +The `tracef()` events contain a single field, named `msg`, which is the +formatted string output. + +If you need to attach a specific log level to a `tracef()` call, use +man:tracelog(3) instead. + +See also the <> section below for important +limitations to consider when using `tracef()`. + + +[[example]] +EXAMPLE +------- +Here's a usage example of `tracef()`: + +------------------------------------------------------------------- +#include +#include + +int main(void) +{ + int i; + + for (i = 0; i < 25; i++) { + tracef("my message: %s, this integer: %d", "a message", i); + } + + return EXIT_SUCCESS; +} +------------------------------------------------------------------- + +This C source file, saved as `app.c`, can be compiled into a program +like this: + +[role="term"] +--------------------------- +cc -o app app.c -llttng-ust +--------------------------- + +You can create an LTTng tracing session, enable the `tracef()` events, +and start the created tracing session like this: + +[role="term"] +--------------------------------------------------- +lttng create my-session +lttng enable-event --userspace 'lttng_ust_tracef:*' +lttng start +--------------------------------------------------- + +Next, start the program to be traced: + +[role="term"] +----- +./app +----- + +Finally, stop the tracing session, and inspect the recorded events: + +[role="term"] +---------- +lttng stop +lttng view +---------- + + +[[limitations]] +LIMITATIONS +----------- +:macro-name: tracef + +include::tracef-tracelog-limitations.txt[] + + +include::common-footer.txt[] + +include::common-copyrights.txt[] + +include::common-authors.txt[] + + +SEE ALSO +-------- +man:tracelog(3), +man:lttng-ust(3), +man:lttng(1), +man:printf(3) diff --git a/doc/man/tracelog.3.txt b/doc/man/tracelog.3.txt new file mode 100644 index 00000000..139e91be --- /dev/null +++ b/doc/man/tracelog.3.txt @@ -0,0 +1,158 @@ +tracelog(3) +=========== +:object-type: macro + + +NAME +---- +tracelog - LTTng-UST man:printf(3)-like interface with a log level + + +SYNOPSIS +-------- +[verse] +*#include * + +[verse] +#define *tracelog*('level', 'fmt', ...) + +Link with `-llttng-ust`. + + +DESCRIPTION +----------- +The LTTng-UST `tracelog()` API allows you to trace your application with +the help of a simple man:printf(3)-like macro, with an additional +parameter for the desired log level. The 'fmt' argument is passed +directly to the 'fmt' parameter of man:vasprintf(3), as well as +the optional parameters following 'fmt'. + +The purpose of `tracelog()` is to ease the migration from logging to +tracing. + +The available values for the 'level' parameter are: + +include::log-levels.txt[] + +To use `tracelog()`, include `` where you need it, and +link your application with `liblttng-ust`. See the <> +section below for a complete usage example. + +Once your application is instrumented with `tracelog()` calls and +ready to run, use man:lttng-enable-event(1) to enable the +`lttng_ust_tracelog:*` event. You can isolate specific log levels with +the nloption:--loglevel and nloption:--loglevel-only options of this +command. + +The `tracelog()` events contain the following fields: + +[options="header"] +|=============================================================== +| Field name | Description +| `line` | Line in source file where `tracelog()` was called +| `file` | Source file from which `tracelog()` was called +| `func` | Function name from which `tracelog()` was called +| `msg` | Formatted string output +|=============================================================== + +If you do not need to attach a specific log level to a `tracelog()` +call, use man:tracef(3) instead. + +See also the <> section below for important +limitations to consider when using `tracelog()`. + + +[[example]] +EXAMPLE +------- +Here's a usage example of `tracelog()`: + +------------------------------------------------------------------- +#include +#include + +int main(int argc, char *argv[]) +{ + int i; + + if (argc < 2) { + tracelog(TRACE_CRIT, "Not enough arguments: %d", argc); + return EXIT_FAILURE; + } + + tracelog(TRACE_INFO, "Starting app with %d arguments", argc); + + for (i = 0; i < argc; i++) { + tracelog(TRACE_DEBUG, "Argument %d: %s", i, argv[i]); + } + + tracelog(TRACE_INFO, "Exiting app"); + + return EXIT_SUCCESS; +} +------------------------------------------------------------------- + +This C source file, saved as `app.c`, can be compiled into a program +like this: + +[role="term"] +--------------------------- +cc -o app app.c -llttng-ust +--------------------------- + +You can create an LTTng tracing session, enable all the `tracelog()` +events, and start the created tracing session like this: + +[role="term"] +--------------------------------------------------- +lttng create my-session +lttng enable-event --userspace 'lttng_ust_tracelog:*' +lttng start +--------------------------------------------------- + +Or you can enable `tracelog()` events matching a log level at least +as severe as a given log level: + +[role="term"] +------------------------------------------------------- +lttng enable-event --userspace 'lttng_ust_tracelog:*' \ + --loglevel=TRACE_INFO +------------------------------------------------------- + +Next, start the program to be traced: + +[role="term"] +------------------------------------------------ +./app a few arguments passed to this application +------------------------------------------------ + +Finally, stop the tracing session, and inspect the recorded events: + +[role="term"] +---------- +lttng stop +lttng view +---------- + + +[[limitations]] +LIMITATIONS +----------- +:macro-name: tracelog + +include::tracef-tracelog-limitations.txt[] + + +include::common-footer.txt[] + +include::common-copyrights.txt[] + +include::common-authors.txt[] + + +SEE ALSO +-------- +man:tracef(3), +man:lttng-ust(3), +man:lttng(1), +man:printf(3) diff --git a/doc/man/tracepoint.3 b/doc/man/tracepoint.3 new file mode 100644 index 00000000..afb50be9 --- /dev/null +++ b/doc/man/tracepoint.3 @@ -0,0 +1 @@ +.so man3/lttng-ust.3 diff --git a/doc/man/tracepoint_enabled.3 b/doc/man/tracepoint_enabled.3 new file mode 100644 index 00000000..afb50be9 --- /dev/null +++ b/doc/man/tracepoint_enabled.3 @@ -0,0 +1 @@ +.so man3/lttng-ust.3 diff --git a/doc/man/xsl/manpage-bold-literal.xsl b/doc/man/xsl/manpage-bold-literal.xsl new file mode 100644 index 00000000..36dff92e --- /dev/null +++ b/doc/man/xsl/manpage-bold-literal.xsl @@ -0,0 +1,8 @@ + + + + \fB + + \fR + + diff --git a/doc/man/xsl/manpage-callouts.xsl b/doc/man/xsl/manpage-callouts.xsl new file mode 100644 index 00000000..2f7a5d7f --- /dev/null +++ b/doc/man/xsl/manpage-callouts.xsl @@ -0,0 +1,17 @@ + + + + + + + sp + + + + + + + + br + + diff --git a/doc/man/xsl/manpage-headings.xsl b/doc/man/xsl/manpage-headings.xsl new file mode 100644 index 00000000..70e44e18 --- /dev/null +++ b/doc/man/xsl/manpage-headings.xsl @@ -0,0 +1,6 @@ + + + + + + diff --git a/doc/man/xsl/manpage-links.xsl b/doc/man/xsl/manpage-links.xsl new file mode 100644 index 00000000..a92e209b --- /dev/null +++ b/doc/man/xsl/manpage-links.xsl @@ -0,0 +1,11 @@ + + + + <> + + + + + \fI\fR + + diff --git a/doc/man/xsl/manpage.xsl b/doc/man/xsl/manpage.xsl new file mode 100644 index 00000000..2c593c46 --- /dev/null +++ b/doc/man/xsl/manpage.xsl @@ -0,0 +1,9 @@ + + + + + + + + 0 +