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
- [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
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
-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
--- /dev/null
+# 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)
--- /dev/null
+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._).
--- /dev/null
+[macros]
+
+# man macro
+#
+# Inspired by linkgit macro:
+# <https://github.com/git/git/blob/master/Documentation/asciidoc.conf>
+#
+# Usage: man:command(manpage-section)
+(?su)[\\]?(?P<name>man):(?P<target>\S*?)\((?P<attrlist>.*?)\)=
+
+# no link option macro
+#
+# Usage: nloption:--option-name
+(?su)[\\]?(?P<name>nloption):(?P<opt>--?[a-zA-Z0-9-]*)=
+
+# option macro
+#
+# Usage: option:--option-name
+(?su)[\\]?(?P<name>option):(?P<opt>--?[a-zA-Z0-9-]*)=
+
+# not macro
+#
+# Usage: :not:
+:not:=not
+
+# man macro expansions
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[man-inlinemacro]
+{0%{target}}
+{0#<citerefentry>}
+{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
+{0#</citerefentry>}
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+# option macro expansions
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[option-inlinemacro]
+<literal>{opt}</literal>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+# no link option macro expansions
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[nloption-inlinemacro]
+<literal>{opt}</literal>
+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]
+<refentry>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">LTTng</refmiscinfo>
+<refmiscinfo class="version">{lttng_version}</refmiscinfo>
+<refmiscinfo class="manual">LTTng Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+ <refname>{manname}</refname>
+ <refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
--- /dev/null
+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].
--- /dev/null
+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.
--- /dev/null
+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].
--- /dev/null
+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.
--- /dev/null
+.so man3/lttng-ust.3
--- /dev/null
+`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.
+++ /dev/null
-.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 <lttng-dev@lists.lttng.org> 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: <lttng-dev@lists.lttng.org>.
-.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 <yannick.brosseau@gmail.com>.
-.PP
--- /dev/null
+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 <<template-file-format,Template file format>>
+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)
+++ /dev/null
-.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 <lttng-dev@lists.lttng.org> 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: <lttng-dev@lists.lttng.org>.
-
-You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
-.SH "AUTHORS"
-liblttng-ust was originally written by Mathieu Desnoyers, with additional
-contributions from various other people. It is currently maintained by
-Mathieu Desnoyers <mathieu.desnoyers@efficios.com>.
--- /dev/null
+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 <<ftrace-fast,Fast function tracing>> 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 <<ftrace-verbose,Verbose function tracing>> 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)
+++ /dev/null
-.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 <lttng-dev@lists.lttng.org> 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: <lttng-dev@lists.lttng.org>.
-
-You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
-
-.SH "AUTHORS"
-liblttng-ust was originally written by Mathieu Desnoyers, with additional
-contributions from various other people. It is currently maintained by
-Mathieu Desnoyers <mathieu.desnoyers@efficios.com>.
--- /dev/null
+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)
+++ /dev/null
-.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 <lttng/tracef.h>
-
-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 <lttng/tracelog.h>
-
-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 <lttng-dev@lists.lttng.org> 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: <lttng-dev@lists.lttng.org>.
-.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 <mathieu.desnoyers@efficios.com>.
-.PP
--- /dev/null
+lttng-ust(3)
+============
+:object-type: library
+
+
+NAME
+----
+lttng-ust - LTTng user space tracing
+
+
+SYNOPSIS
+--------
+[verse]
+*#include <lttng/tracepoint.h>*
+
+[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
+ <<creating-tp,Creating a tracepoint provider>> section below.
+
+
+[[creating-tp]]
+Creating a tracepoint provider
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Creating a tracepoint provider is the first step of using
+`liblttng-ust`. The next steps are:
+
+ * <<tracepoint,Instrumenting your application with `tracepoint()` calls>>
+ * Building your application with LTTng-UST support, either
+ <<build-static,statically>> or <<build-dynamic,dynamically>>.
+
+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 <lttng/tracepoint.h>
+
+/*
+ * TRACEPOINT_EVENT(), TRACEPOINT_EVENT_CLASS(),
+ * TRACEPOINT_EVENT_INSTANCE(), TRACEPOINT_LOGLEVEL(),
+ * and `TRACEPOINT_ENUM()` are used here.
+ */
+
+#endif /* _TP_H */
+
+#include <lttng/tracepoint-event.h>
+------------------------------------------------------------------------
+
+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 <lttng/tracepoint.h>` and `#endif` go
+the invocations of the <<tracepoint-event,`TRACEPOINT_EVENT()`>>,
+<<tracepoint-event-class,`TRACEPOINT_EVENT_CLASS()`>>,
+<<tracepoint-event-class,`TRACEPOINT_EVENT_INSTANCE()`>>,
+<<tracepoint-loglevel,`TRACEPOINT_LOGLEVEL()`>>, and
+<<tracepoint-enum,`TRACEPOINT_ENUM()`>> 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 <<tracepoint-event,`TRACEPOINT_EVENT()` usage>> section below
+shows how to use the `TRACEPOINT_EVENT()` macro to define the actual
+tracepoints in the tracepoint provider header file.
+
+See the <<example,EXAMPLE>> 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 <<creating-tp,Creating a tracepoint provider>>
+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
+<<ctf-macros,Available `ctf_*()` field type macros>> 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
+<<tracepoint-event,`TRACEPOINT_EVENT()` macro>>.
+
+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
+<<tracepoint-enum,`TRACEPOINT_ENUM()` usage>> 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 <<creating-tp,Creating a tracepoint provider>> 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
+ <<tracepoint-enum,`TRACEPOINT_ENUM()` usage>> 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 <<example,EXAMPLE>> 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 <<example,EXAMPLE>> 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 <<example,EXAMPLE>> 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 <<example,EXAMPLE>> section below for a complete example.
+
+
+[[tracepoint]]
+Instrumenting your application
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Once the tracepoint provider is created (see the
+<<creating-tp,Creating a tracepoint provider>> 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 <<build-static,static linking method>>, 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 <<build-static,static linking>> 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 <lttng/tracepoint.h>
+#include <stdio.h>
+
+#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 <lttng/tracepoint-event.h>
+------------------------------------------------------------------------
+
+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 <stdlib.h>
+#include <stdio.h>
+
+#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)
--- /dev/null
+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.
--- /dev/null
+tracef(3)
+=========
+:object-type: macro
+
+
+NAME
+----
+tracef - LTTng-UST man:printf(3)-like interface
+
+
+SYNOPSIS
+--------
+[verse]
+*#include <lttng/tracef.h>*
+
+[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 `<lttng/tracef.h>` where you need it, and
+link your application with `liblttng-ust`. See the <<example,EXAMPLE>>
+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 <<limitations,LIMITATIONS>> section below for important
+limitations to consider when using `tracef()`.
+
+
+[[example]]
+EXAMPLE
+-------
+Here's a usage example of `tracef()`:
+
+-------------------------------------------------------------------
+#include <stdlib.h>
+#include <lttng/tracef.h>
+
+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)
--- /dev/null
+tracelog(3)
+===========
+:object-type: macro
+
+
+NAME
+----
+tracelog - LTTng-UST man:printf(3)-like interface with a log level
+
+
+SYNOPSIS
+--------
+[verse]
+*#include <lttng/tracelog.h>*
+
+[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 `<lttng/tracelog.h>` where you need it, and
+link your application with `liblttng-ust`. See the <<example,EXAMPLE>>
+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 <<limitations,LIMITATIONS>> section below for important
+limitations to consider when using `tracelog()`.
+
+
+[[example]]
+EXAMPLE
+-------
+Here's a usage example of `tracelog()`:
+
+-------------------------------------------------------------------
+#include <stdlib.h>
+#include <lttng/tracelog.h>
+
+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)
--- /dev/null
+.so man3/lttng-ust.3
--- /dev/null
+.so man3/lttng-ust.3
--- /dev/null
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+ <!-- this template makes the literal elements bold -->
+ <xsl:template match="literal">
+ <xsl:text>\fB</xsl:text>
+ <xsl:value-of select="." />
+ <xsl:text>\fR</xsl:text>
+ </xsl:template>
+</xsl:stylesheet>
--- /dev/null
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+ <xsl:template match="co">
+ <xsl:value-of select="concat('\','fB(',substring-after(@id,'-'),')','\','fR')"/>
+ </xsl:template>
+ <xsl:template match="calloutlist">
+ <xsl:value-of select="."/>
+ <xsl:text>sp </xsl:text>
+ <xsl:apply-templates/>
+ <xsl:text> </xsl:text>
+ </xsl:template>
+ <xsl:template match="callout">
+ <xsl:value-of select="concat('\','fB',substring-after(@arearefs,'-'),'. ','\','fR')"/>
+ <xsl:apply-templates/>
+ <xsl:value-of select="."/>
+ <xsl:text>br </xsl:text>
+ </xsl:template>
+</xsl:stylesheet>
--- /dev/null
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+ <!-- this template cancels the style of literal elements in title elements -->
+ <xsl:template match="title/literal">
+ <xsl:value-of select="."/>
+ </xsl:template>
+</xsl:stylesheet>
--- /dev/null
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+ <!-- this template appends the URL to the external link text -->
+ <xsl:template match="ulink">
+ <xsl:apply-templates/><xsl:text> <</xsl:text><xsl:value-of select="@url"/><xsl:text>></xsl:text>
+ </xsl:template>
+
+ <!-- this template emphasizes the internal link text -->
+ <xsl:template match="link">
+ <xsl:text>\fI</xsl:text><xsl:value-of select="."/><xsl:text>\fR</xsl:text>
+ </xsl:template>
+</xsl:stylesheet>
--- /dev/null
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+ <xsl:import href="manpage-callouts.xsl" />
+ <xsl:import href="manpage-bold-literal.xsl" />
+ <xsl:import href="manpage-links.xsl" />
+ <xsl:import href="manpage-headings.xsl" />
+
+ <!-- disable end notes -->
+ <xsl:param name="man.endnotes.are.numbered">0</xsl:param>
+</xsl:stylesheet>
projects / lttng-ust.git / commitdiff
