From: David Goulet Date: Thu, 24 Oct 2013 14:23:34 +0000 (-0400) Subject: Merge branch 'master' into memleak-finder X-Git-Url: http://git.liburcu.org/?a=commitdiff_plain;h=8b833f70b3d3697e74c54f3a2f5efbe5292097ef;hp=5aaa62a111f332a7c4412558bb9da9b30320eefd;p=lttng-tools.git Merge branch 'master' into memleak-finder --- diff --git a/.gitignore b/.gitignore index 96a1ab140..5d1e2ffa0 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,7 @@ Makefile.in *.info *.bz2 *.tar +.dirstamp configure aclocal.m4 autom4te.cache/ @@ -45,6 +46,7 @@ src/lib/lttng-ctl/filter/filter-parser.output extras/bindings/swig/python/lttng.i extras/bindings/swig/python/lttng.py extras/bindings/swig/python/lttng_wrap.c +extras/core-handler/crash .checkpatch.conf @@ -75,5 +77,6 @@ tests/regression/ust/exit-fast/exit-fast tests/regression/ust/fork/fork tests/regression/ust/fork/fork2 tests/regression/ust/libc-wrapper/prog +tests/utils/testapp/gen-ust-nevents/gen-ust-nevents benchmark/ diff --git a/ChangeLog b/ChangeLog index af8d9c833..4868c2c23 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,228 @@ +2013-09-03 lttng-tools 2.3.0 + * Fix: remove periodical flush test from make check + +2013-08-30 lttng-tools 2.3.0-rc3 + * Fix: hashtable: take split_count_order into account + * Fix: remove wrong doing asserts in sessiond + * Tests: fix periodical flush tests to stop app + * Fix: correctly close metadata on sessiond thread shutdown + * Fix: delete the trace directory used for the test + * Fix: remove bad check after epoll wait in consumer + * Fix: missing data pending signess conversion + * Fix: consumer data pending for empty streams + * Fix: hash table growth (for small tables) should be limited (v2) + * Fix: run_as gid/uid test should return result to parent + * Fix: missing check for metadata data pending + * Tests: change buffers UID test to PID + * Tests: fix health tests to use custom socket timeout + * Fix: remove health test from fast regression + * Use socket timeout value for tcp timeout if available + * Fix: set the health delta tcp timeout aware + * Get the maximum TCP timeout in sessiond + * Fix: don't report error if UST app dies + * Fix: support VPATH build for tests + * Improve comments after review + * Rename consumer socket fd to fd_ptr + * Lock consumer data before fd check during destroy + * Use single callsite for send/recv ops. for consumer in sessiond + * Use consumer fd reference in consumer socket obj + * Update bash completion + * Add --list-commands option to the snapshot command + * Reorder functions _lttng_cmd_* functions in bash completion + * Use parse_size_suffix in snapshot + * Fix: snapshot record error handling + * Fix: improve error message when UST support is disabled + * Fix: add missing short filter option in help + * Fix: typo in configure.ac for version check + * Fix: remove calibrate syscall option from code + * Fix: snapshot should fail if no successful snapshot is taken + * Fix: check UST float field mantissa length + * Fix: add UST context in the same order the user enabled them + * Introduce configure --with-lttng-system-rundir + * Add .dirstamp to gitignore file + * Fix: snapshot with multiple UIDs + * Prepare for automake deprecation of missing subdir-objects + * Fix: typos in --help and manpage + * Fix: add-context without -c apply to all channels + * Fix: channels can be _enabled_ after tracing is started, but not created + * Fix filter parser segmentation fault with bison 3.0 + * Fix: typo in error msg + * Fix: imprecise error message about root sessiond/tracing group + * Fix: don't skip chmod if tracing group is not found + * Tracepoint probes don't need extern C + * Fix: Snapshot should be taken asap in core handler script + * Fix: reset out_fd_offset when we rotate the trace file + * Fix: LTTNG_ERR_NEED_ROOT_SESSIOND error message + * inet/inet6 sockets: apply timeout + * Implement timeout for connect ipv4/ipv6 + * Introduce LTTNG_NETWORK_SOCKET_TIMEOUT env. var + * bash completion: add calls to _lttng_complete_sessions + * bash completion: Fix copy-paste typo + * Extras: Remove deprecated consumer commands in bash completion + * bash completion: Remove underscores in handler function names + * bash completion: Remove --event for add-context + * Update gitignore + * relayd: use version macros from build rather than scanf + * sessiond: use version major/minor from build for communication with relayd + * build: export major/minor/patchlevel numbers + * Fix: Dead code when checking return value from (ust_app|kernel)_snapshot_record + * Test: enable kernel events after start + * Fix: kernel ctl error codes are based on errno + * Fix: format string mismatch + * test: test_periodical_metadata_flush shrink timer period, kill app + * Fix: format string type mismatch + * snapshot howto: update text + * Add snapshot howto + +2013-07-19 lttng-tools 2.3.0-rc2 + * Add core-handler README to dist tarball + * extras: core-handler: simplify, allow usage from tracing group + * Cleanup: add missing dot + * Fix: documentation: create name and options + * Add core dump snapshot handler script + * Fix: sym name len (kernel) + * Fix: tests: provide channel name when a non-default channel exists: per-pid + * Fix: tests: provide channel name when a non-default channel exists + * Fix: data pending race + * Fix hang in make check snapshots/test_ust + * Cleanup: ust-consumer: wrong indentation + * Fix: print dots while waiting for data availability + * Fix: remove sleep(1) added by "Fix: (slight UI change) refuse missing -c if non-default channel exists" + * Fix: (slight UI change) refuse missing -c if non-default channel exists + * Fix: push metadata on stop for per-UID buffers + * README: update python documentation + * Manpage: other layout cleanups + * Manpage: cleanup layout of view + * Manpage: cleanup layout of version + * Manpage: cleanup layout of stop + * Manpage: cleanup layout of start + * Manpage: cleanup layout of snapshot + * Manpage: cleanup layout of set-session + * Manpage: cleanup layout of list + * Manpage: cleanup layout of disable-event + * Manpage: cleanup layout of disable-channel + * Manpage: cleanup layout of enable-event + * Manpage: cleanup layout of enable-channel + * Manpage: cleanup layout of destroy + * Manpage: cleanup layout of create + * Manpage: cleanup layout of calibrate + * Manpage: cleanup layout of add-context + * Documentation: create --snapshot in manpage + +2013-07-17 lttng-tools 2.3.0-rc1 + * Fix: add missing snapshot header to dist tarball + * Documentation: fix thread quit pipe comment + * Test for presence of bison and flex when building from git + * Test UST snapshot with large metadata + * Add test application with large metadata + * Cleanup: remove redundant assignment + * Fix: use per-uid buffer registry for UID buffer snapshots + * cmd.c: fix typos in snapshot commands + * Test snapshot per-uid post-mortem + * Remove leftover fprintf + * Fix deadlock: don't take channel lock in timer + * Introduce channel timer lock + * document lttng_ustconsumer_request_metadata locking constraints + * consumer: remove unused lttng_ustconsumer_push_metadata + * Document metadata_socket_lock nesting + * lttng_ustconsumer_recv_metadata does not need all those locks + * document metadata_switch_timer() deadlock + * Fix: add missing metadata socket lock + * document metadata_switch_timer() locking constraints + * consumer: remove timeout for UST metadata + * Introduce pipe for UST metadata cache and stream + * consumer: replace DBG2() instances by DBG() + * Introduce utils_create_pipe_cloexec_nonblock() + * ust consumer: data_pending check is endpoint active + * Fix: kernel consumer: data_pending check if endpoint active + * consumer: explicitly set endpoint status to active at init + * document consumer_metadata_cache_flushed use of consumer_data.lock + * consumer: introduce channel lock + * Merge branch 'master' of git://git.lttng.org/lttng-tools + * Fix: update lttng snapshot help output + * Man: fix part of snapshot documentation + * Fix: set tracefile size test with PID buffers + * Fix: Babelstats fail to parse output with no process name or pid + * Missing NULL pointer init in tap.c + * Fix: Unchecked asprintf/vasprintf return values + * Add snapshots test to fast regression + * Fix: kernel data unit test + * Fix: snapshot returned valid LTTNG_ERR code + * Add the number of snapshot taken to the output path + * Fix: RCU read side lock unbalanced + * Fix: zeroed snapshot output at init + * Support del-output with an output name + * Update man page with snapshot command + * New UST default buffers is now per UID + * Bump UST ABI major version for 2.3 release + * Add snapshot mode to lttng list session + * Fix: support temporary snapshot max size and name + * Support snapshot max-size limitation + * Tests: per-UID UST snapshot + * Fix: snapshot support for UST and kernel in same session + * Implement lttng create --snapshot command + * Add create session snapshot API in lttng-sessiond + * Add snapshot output init call that uses URIs + * Fix: consumer err_sock cloexec + * Callsite: add "ip" context + * Fix: possible consumer sockets double close on cleanup + * Automatically load kvm-x86 and kvm-x86-mmu probes. + * Fix: consumer: use uint64_t for all sessiond_id + * Fix: add gpl and lgpl files to tarball + * Fix: don't install libtap system wide + * Fix: close consumer sockets in sessiond cleanup + * Fix: set globally visible flag to kernel stream + * Fix: lttng: memory leak in snapshot record command + * Fix: kernel-consumer: double-close + * Fix: consumer: incorrect size zmalloc + * Fix: don't try to send stream to relayd if not in streaming + * Fix: relayd refcount updates for stream + * Fix: don't send error to sessiond on orderly shutdown + * Fix: bad pathname used when sending kernel stream to relayd + * Fix: add globally visible flag in stream + * Fix: destroy metadata stream on setup metadata error path + * Fix: send kernel stream to relayd only if needed + * Fix: destroy streams for kernel snapshot sessions as well + * Fix: close and destroy metadata stream after a kernel snapshot + * Fix: print errno message on connect() error + * Fix: possible double-close on stream out_fd + * Fix: session ID signess to uin64_t in sessiond + * Tests: fix validation trace path in kernel snapshot + * Tests: Add UST snapshot local and streaming + * Add UST snapshot support + * Fix: consumer_add_relayd_socket() report errors to sessiond + * Fix: add missing enum lttcomm_return_code entries + * Fix: UST per-UID channels persist across application teardown + * Fix: kernel snapshot metadata handling and error paths + * Fix: coding style and debug statement + * Fix: put subbuffer back in kernel snapshot error path + * Fix: overflow in uri_to_str_url + * Fix: detect the correct version of LTTng-UST + * Fix: sessiond: use uint64_t for all session ids + * Tests: add kernel snapshot streaming to root regression + * Tests: remove debug output from test + * Tests: Add kernel snapshot streaming + * Fix: use snapshot consumer output for kernel + * Fix: periodical flush check trace before stop + * Fix: consumer: 64-bit index for relayd rather than 32-bit (v2) + * Fix UST channel/stream output assignation + * Fix: send per-pid session id in channel creation + * Fix: consumer double-close on error + * Update URCU detection to correctly check for a 0.7 version + * Fix: snapshot path + * Add utils function to format current time as a string + * Fix: set hidden attribute to utils_* calls + * Fix: consumer handling of metadata for relayd + * Add kernel snapshot support + * Support flight recorder mode for a session + * Implement snapshot commands in lttng-sessiond + * Add snapshot command to lttng UI + * Initial import of the snapshot ABI/API in lttng-ctl + * Use the consumer stream API in consumer_del_stream() + * Add consumer-stream.c/.h in libconsumer + * Move multiple URLs parsing fct from lttng-ctl to uri.c + * Add a lttng-ctl header to facilitate code separation + 2013-06-25 lttng-tools 2.2.0 (National Catfish Day) * STABLE VERSION * Fix: if relayd is unreachable, disable consumer for the session diff --git a/Makefile.am b/Makefile.am index b0537ce6e..584f59b2e 100644 --- a/Makefile.am +++ b/Makefile.am @@ -11,4 +11,4 @@ dist_doc_DATA = LICENSE \ dist_noinst_DATA = CodingStyle -EXTRA_DIST = extras/lttng-bash_completion +EXTRA_DIST = extras/lttng-bash_completion gpl-2.0.txt lgpl-2.1.txt diff --git a/README b/README index 538996e9e..e38602d53 100644 --- a/README +++ b/README @@ -47,7 +47,7 @@ REQUIREMENTS: - python-dev (optional) Python headers - * Debian/Ubuntu package: python-dev + * Debian/Ubuntu package: python3-dev - For kernel tracing: modprobe @@ -92,6 +92,11 @@ INSTALLATION INSTRUCTIONS: the configure script, to generate it. If you want Python bindings, run ./configure --enable-python-bindings. + Please note that some distributions will need the following + environment variables set before running configure: + + export PYTHON="python3" + export PYTHON_CONFIG="/usr/bin/python3-config" USAGE: diff --git a/configure.ac b/configure.ac index b43015249..2b4a340f5 100644 --- a/configure.ac +++ b/configure.ac @@ -1,4 +1,4 @@ -AC_INIT([lttng-tools],[2.2.0],[dgoulet@efficios.com],[],[http://lttng.org]) +AC_INIT([lttng-tools],[2.4.0-pre1],[dgoulet@efficios.com],[],[http://lttng.org]) AC_CONFIG_AUX_DIR([config]) AC_CANONICAL_TARGET AC_CANONICAL_HOST @@ -6,8 +6,20 @@ AC_CONFIG_MACRO_DIR([config]) AM_INIT_AUTOMAKE([foreign dist-bzip2 no-dist-gzip]) m4_ifdef([AM_SILENT_RULES], [AM_SILENT_RULES([yes])]) -version_name="Cuda" -version_description="Brewed at the Benelux microbrewery, this IPA has huge floral, citric and resinous hop aroma, simply an amazing nose. The flavor is very fresh with a light caramel malting touch completing a strong body. Huge amounts of hops, lots of grapefruit, lemon and oranges. This is an outstanding IPA!" +# Compute minor/major/patchlevel version numbers +AC_PROG_SED +major_version=$(echo AC_PACKAGE_VERSION | sed 's/^\([[0-9]]\)*\.[[0-9]]*\.[[0-9]]*.*$/\1/') +minor_version=$(echo AC_PACKAGE_VERSION | sed 's/^[[0-9]]*\.\([[0-9]]*\)\.[[0-9]]*.*$/\1/') +patchlevel_version=$(echo AC_PACKAGE_VERSION | sed 's/^[[0-9]]*\.[[0-9]]*\.\([[0-9]]*\).*$/\1/') +AC_SUBST([MAJOR_VERSION], [$major_version]) +AC_SUBST([MINOR_VERSION], [$minor_version]) +AC_SUBST([PATCHLEVEL_VERSION], [$patchlevel_version]) +AC_DEFINE_UNQUOTED([VERSION_MAJOR], $major_version, [LTTng-Tools major version number]) +AC_DEFINE_UNQUOTED([VERSION_MINOR], $minor_version, [LTTng-Tools minor version number]) +AC_DEFINE_UNQUOTED([VERSION_PATCHLEVEL], $patchlevel_version, [LTTng-Tools patchlevel version number]) + +version_name="Dominus Vobiscum" +version_description="A very succulent line-up of beers brewed at Microbrasserie Charlevoix. Elaborated starting from special malts and fermented with a Belgian yeast. These beers are refermented in bottle and will make you discover the richness of wheat, amber and triple styles." AC_DEFINE_UNQUOTED([VERSION_NAME], ["$version_name"], "") AC_DEFINE_UNQUOTED([VERSION_DESCRIPTION], ["$version_description"], "") @@ -98,6 +110,13 @@ AC_ARG_WITH([sessiond-bin], [SESSIOND_BIN='']) AC_SUBST([SESSIOND_BIN]) +AC_ARG_WITH([lttng-system-rundir], + AS_HELP_STRING([--with-lttng-system-rundir], + [Location of the system directory where the system-wide lttng-sessiond runtime files are kept. The default is "/var/run/lttng".]), + [LTTNG_SYSTEM_RUNDIR="$withval"], + [LTTNG_SYSTEM_RUNDIR="/var/run/lttng"]) +AC_SUBST([LTTNG_SYSTEM_RUNDIR]) + AC_DEFINE_UNQUOTED([CONFIG_CONSUMERD32_BIN], "$CONSUMERD32_BIN", [Location of the 32-bit consumerd executable.]) AC_DEFINE_UNQUOTED([CONFIG_CONSUMERD64_BIN], "$CONSUMERD64_BIN", [Location of the 64-bit consumerd executable]) AC_DEFINE_UNQUOTED([CONFIG_CONSUMERD32_LIBDIR], "$CONSUMERD32_LIBDIR", [Search for consumerd 32-bit libraries in this location.]) @@ -105,6 +124,7 @@ AC_DEFINE_UNQUOTED([CONFIG_CONSUMERD64_LIBDIR], "$CONSUMERD64_LIBDIR", [Search f AC_DEFINE_UNQUOTED([CONFIG_BABELTRACE_BIN], "$BABELTRACE_BIN", [Location of the babeltrace viewer executable.]) AC_DEFINE_UNQUOTED([CONFIG_LTTV_GUI_BIN], "$LTTV_GUI_BIN", [Location of the lttv GUI viewer executable.]) AC_DEFINE_UNQUOTED([CONFIG_SESSIOND_BIN], "$SESSIOND_BIN", [Location of the sessiond executable.]) +AC_DEFINE_UNQUOTED([CONFIG_LTTNG_SYSTEM_RUNDIR], ["$LTTNG_SYSTEM_RUNDIR"], [LTTng system runtime directory]) # Check for pthread AC_CHECK_LIB([pthread], [pthread_create], [], @@ -287,7 +307,19 @@ LT_INIT AC_PROG_YACC AC_PROG_LEX -AC_DEFUN([AC_PROG_BISON], [AC_CHECK_PROGS(BISON, bison, bison)]) +if test ! -f "$srcdir/src/lib/lttng-ctl/filter/filter-parser.h"; then + if test x"$YACC" != "xbison -y"; then + AC_MSG_ERROR([[bison not found and is required when building from git. + Please install bison]]) + fi +fi + +if test ! -f "$srcdir/src/lib/lttng-ctl/filter/filter-lexer.c"; then + if test x"$LEX" != "xflex"; then + AC_MSG_ERROR([[flex not found and is required when building from git. + Please install flex]]) + fi +fi CFLAGS="-Wall $CFLAGS -g -fno-strict-aliasing" @@ -310,6 +342,7 @@ AC_CONFIG_FILES([ extras/bindings/Makefile extras/bindings/swig/Makefile extras/bindings/swig/python/Makefile + extras/core-handler/Makefile src/Makefile src/common/Makefile src/common/kernel-ctl/Makefile @@ -320,6 +353,8 @@ AC_CONFIG_FILES([ src/common/compat/Makefile src/common/relayd/Makefile src/common/testpoint/Makefile + src/common/index/Makefile + src/common/health/Makefile src/lib/Makefile src/lib/lttng-ctl/Makefile src/lib/lttng-ctl/filter/Makefile @@ -343,7 +378,7 @@ AC_CONFIG_FILES([ tests/regression/ust/high-throughput/Makefile tests/regression/ust/low-throughput/Makefile tests/regression/ust/before-after/Makefile - tests/regression/ust/buffers-uid/Makefile + tests/regression/ust/buffers-pid/Makefile tests/regression/ust/periodical-metadata-flush/Makefile tests/regression/ust/multi-session/Makefile tests/regression/ust/overlap/Makefile @@ -359,6 +394,7 @@ AC_CONFIG_FILES([ tests/utils/tap/Makefile tests/utils/testapp/Makefile tests/utils/testapp/gen-ust-events/Makefile + tests/utils/testapp/gen-ust-nevents/Makefile ]) AC_OUTPUT diff --git a/doc/Makefile.am b/doc/Makefile.am index 8edb6dc1e..6f05d7a78 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,6 +1,8 @@ SUBDIRS = man EXTRA_DIST = quickstart.txt streaming-howto.txt python-howto.txt \ - calibrate.txt kernel-CodingStyle.txt + snapshot-howto.txt calibrate.txt kernel-CodingStyle.txt \ + live-reading-howto.txt live-reading-protocol.txt dist_doc_DATA = quickstart.txt streaming-howto.txt python-howto.txt \ - calibrate.txt + snapshot-howto.txt calibrate.txt live-reading-howto.txt \ + live-reading-protocol.txt diff --git a/doc/live-reading-howto.txt b/doc/live-reading-howto.txt new file mode 100644 index 000000000..4a54f1c4a --- /dev/null +++ b/doc/live-reading-howto.txt @@ -0,0 +1,53 @@ +LTTng Live trace reading how-to + +Julien Desfossez +September 27th, 2013 + +This document presents a summary on how to use the live trace reading feature +introduced in LTTng 2.4. For the details about the protocol, please refer to +the live-reading-protocol.txt document. + +Live trace reading refers to the feature of reading the trace while it is being +recorded. In order to do that, the trace must be streamed a relay even if the +viewer is running on the same machine as the tracer. + +So, the first thing to do is to start a lttng-relayd process. It can be +anywhere on the network (including localhost) as long as the sessiond/consumerd +and the viewer can communicate with it over TCP/IP. + +$ lttng-relayd -d + +Then, we can create a session configured for streaming with the new --live +parameter. + +$ lttng create --live 1000000 -U net://localhost + +The --live parameter activates a session-wide timer (usec) that is responsible +for checking at a user-defined rate if new data is available. If there is new +data, it is flushed automatically, otherwise a beacon is sent to the relayd to +inform it that the stream is currently empty and the viewer can ignore this +stream up to a certain point in time. + +Once the session is created, the user can activate events as usual. + +In order to view the live trace, the viewer must implement the live-reading +protocol. + +For now, a basic client is available in the branch index2013 of the git +repository : +https://github.com/jdesfossez/babeltrace-dev.git + +This client is still in heavy development and the branch will be rebased, it is +only provided as a proof-of-concept and an exemple on how to use the protocol. +Once compiled and installed, just run : +$ test-live hostname 2>/dev/null + +If you want to see all the debug, just get rid of "2>/dev/null". +Once again, it is a client in development, the name is purposely bad and the +debug output is relatively heavy. + +Known viewer issues : +- adding metadata on the fly (enabling events when a viewer is connected) +- destroy not clean +- aggressive polling when all the streams are inactive (after a lttng stop) +- restart reading from the beginning (SEEK_LAST not implemented yet) diff --git a/doc/live-reading-protocol.txt b/doc/live-reading-protocol.txt new file mode 100644 index 000000000..fcc75b37d --- /dev/null +++ b/doc/live-reading-protocol.txt @@ -0,0 +1,117 @@ +LTTng Live trace reading protocol + +Julien Desfossez +September 18th, 2013 + +This document describes the protocol of live trace reading. It is mainly +intended for trace-viewer developers. + +Live trace reading allows a viewer to read safely a LTTng trace while it is +being recorded. The protocol ensures that the viewer is never in a position +where it can read for which it does not have the metadata, and also allows to +viewer to know about inactive streams and skip those up to a certain point in +time. + +This feature is implemented starting at lttng-tools 2.4 + +* General informations +All the data structures required to implement this protocole are provided in +the lttng-viewer.h header. All integer are encoded in big endian during the +transfer. + +Just like the streaming protocol, this protocol works always in only one +direction : from the viewer to the relay. After each command, the relay sends a +reply to the viewer (or closes the connection on fatal error). + +When the viewer sends a command to the relay, it sends a struct +lttng_viewer_cmd which contains the command (enum lttcomm_relayd_command) and +the size of the actual command if the command requires a payload. +For example, if the viewer wants to list the sessions, it sends a struct +lttng_viewer_cmd with : +cmd = htobe32(VIEWER_CONNECT); +data_size = htobe64(sizeof(struct lttng_viewer_connect)); + +The cmd_version is currently unused, but might get useful when we extend the +protocol later. + +* Protocol sequence +In this section, we describe the normal sequence of event during a live-reading +session. The viewer is abbreviated V and the relay R for conciseness. + +Establishing a connection : +- V connects to R on port TCP/5344 +- V establishes a session by sending a VIEWER_CONNECT command, payload in + struct lttng_viewer_connect. In this struct, it sets its major and minor + version of the protocol it implements, and the type of connection it wants, + for now only VIEWER_CLIENT_COMMAND is supported. +- If the protocol implemented by V and R are compatible, R sends back the same + struct with its own version and the newly assigned viewer_session_id. + Protocols are compatible if they have the same major number. At this point, + if the communication continues and the minor are not the same, it is implied + that the two processes will use the min(minor) of the protocol during this + connection. Protocol versions follow lttng-tools version, so if R implements + the 2.5 protocol and V implements the 2.4 protocol, R will use the 2.4 + protocol for this connection. + +List the sessions : +Once V and R agree on a protocol, V can start interacting with R. The first +thing to do is list the sessions currently active on R. +- V sends the command VIEWER_LIST_SESSIONS with no payload (data_size ignored) +- R sends back a struct lttng_viewer_list_sessions which contains the number of + sessions to receive, and then for each session (sessions_count), it sends a + struct lttng_viewer_session +- V must first receive the struct lttng_viewer_list_sessions and then receive + all the lttng_viewer_session structs. The live_timer corresponds to the value + set by the user who created the tracing session, if it is 0, the session + cannot be read in live. This timer in microseconds is the minimum rate at + which R receives information about the running session. The "clients" field + contains the number of connected clients to this session, for now only one + client at a time can attach to session. + +Attach to a session : +Now V can select a session and attach to it. In order to do so, it sends the +command VIEWER_ATTACH_SESSION with the session_id it wants. The "seek" +parameter allows the viewer to attach to a session from its beginning (it will +receive all trace data still on the relayd) or from now (data will be available +to read starting at the next packet received on the relay). Only one session +can be established by connection. Lots of clock synchronisation issues can +happen when connecting to multiple sessions from multiple hosts at the same +time, we let the viewers have fun with it ;-) +R replies with a struct lttng_viewer_attach_session_response with a status and +the number of streams currently active in this session. Then, for each stream, +it sends a struct lttng_viewer_stream. Just like with the session list, V must +receive the first header and then all the stream structs. The ctf_trace_id +parameter in the struct lttng_viewer_stream is particularly important since it +allows the viewer to match all the streams belonging to the same CTF trace (so +one metadata file and multiple stream files). If the stream is a metadata +stream, metadata_flag will be set to 1. + +#### below needs to be well written, but the essential is here ### + +Get metadata : +A CTF trace cannot be read without the complete metadata. +Send the command VIEWER_GET_METADATA and the struct lttng_viewer_get_metadata. + +Once we have all the metadata, we can start processing the trace. In order to +do that, we work with the indexes. Whenever we need to read a new packet from a +stream, we first ask for the next index for this stream and then ask for a +trace packet at a certain offset and length. + +Get the next index : +Command VIEWER_GET_NEXT_INDEX +struct lttng_viewer_get_next_index +Receive back a struct lttng_viewer_index + +Get data packet : +Command VIEWER_GET_PACKET +struct lttng_viewer_get_packet +Receive back a struct lttng_viewer_trace_packet + +For the VIEWER_GET_NEXT_INDEX and VIEWER_GET_PACKET, the viewer must check the +"flags" element of the struct it receives, because it contains important +information such as the information that new metadata must be received before +being able to receive and read the next packet. +When new metadata is added during a session, the GET_NEXT_INDEX will succeed +but it will have the flag LTTNG_VIEWER_FLAG_NEW_METADATA, but the +GET_DATA_PACKET will fail with the same flag as long as the metadata is not +downloaded. diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index e20613a02..d91a91a88 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -1,3 +1,2 @@ dist_man1_MANS = lttng.1 -dist_man3_MANS = lttng-health-check.3 dist_man8_MANS = lttng-sessiond.8 lttng-relayd.8 diff --git a/doc/man/lttng-health-check.3 b/doc/man/lttng-health-check.3 index 67aafd4c4..9ab6635ae 100644 --- a/doc/man/lttng-health-check.3 +++ b/doc/man/lttng-health-check.3 @@ -1,5 +1,7 @@ .TH LTTNG_HEALTH_CHECK 3 2012-09-19 "LTTng" "LTTng Developer Manual" .SH NAME +.B DEPRECATED + lttng_health_check \- Monitor health of the session daemon .SH SYNOPSIS .nf diff --git a/doc/man/lttng-relayd.8 b/doc/man/lttng-relayd.8 index 44631b1b2..1d1802a4c 100644 --- a/doc/man/lttng-relayd.8 +++ b/doc/man/lttng-relayd.8 @@ -61,6 +61,15 @@ Output base directory. Must use an absolute path (~/lttng-traces is the default) .TP .BR "-V, --version" Show version number +.SH "ENVIRONMENT VARIABLES" + +.PP +.IP "LTTNG_NETWORK_SOCKET_TIMEOUT" +Control timeout of socket connection, receive and send. Takes an integer +parameter: the timeout value, in milliseconds. A value of 0 or -1 uses +the timeout of the operating system (this is the default). +.PP + .SH "SEE ALSO" .PP diff --git a/doc/man/lttng-sessiond.8 b/doc/man/lttng-sessiond.8 index dfc94185f..347bffcaa 100644 --- a/doc/man/lttng-sessiond.8 +++ b/doc/man/lttng-sessiond.8 @@ -134,9 +134,14 @@ Debug-mode disabling use of clone/fork. Insecure, but required to allow debuggers to work with sessiond on some operating systems. .IP "LTTNG_APP_SOCKET_TIMEOUT" Control the timeout of application's socket when sending and receiving -commands. After this period of time, the application is unregistered by the -session daemon. A value of 0 or -1 means an infinite timeout. Default value is -5 seconds. +commands. Takes an integer parameter: the timeout value, in seconds. +After this period of time, the application is unregistered by the +session daemon. A value of 0 or -1 means an infinite timeout. Default +value is 5 seconds. +.IP "LTTNG_NETWORK_SOCKET_TIMEOUT" +Control timeout of socket connection, receive and send. Takes an integer +parameter: the timeout value, in milliseconds. A value of 0 or -1 uses +the timeout of the operating system (this is the default). .SH "SEE ALSO" .PP diff --git a/doc/man/lttng.1 b/doc/man/lttng.1 index 72454f0d3..a16c7c3a7 100644 --- a/doc/man/lttng.1 +++ b/doc/man/lttng.1 @@ -1,4 +1,4 @@ -.TH "LTTNG" "1" "December 3rd, 2012" "" "" +.TH "LTTNG" "1" "July 18th, 2013" "" "" .SH "NAME" lttng \(em LTTng 2.x tracer control command line tool @@ -6,20 +6,18 @@ lttng \(em LTTng 2.x tracer control command line tool .SH "SYNOPSIS" .PP -.nf lttng [OPTIONS] -.fi .SH "DESCRIPTION" .PP The LTTng project aims at providing highly efficient tracing tools for Linux. -It's tracers help tracking down performance issues and debugging problems +Its tracers help track down performance issues and debug problems involving multiple concurrent processes and threads. Tracing across multiple systems is also possible. The \fBlttng\fP command line tool from the lttng-tools package is used to control -both kernel and user-space tracing. Every interactions with the tracer should -be done by this tool or by the liblttng-ctl provided with the lttng-tools +both kernel and user-space tracing. Every interaction with the tracer should +be done by this tool or by the liblttng-ctl library provided by the lttng-tools package. LTTng uses a session daemon (lttng-sessiond(8)), acting as a tracing registry, @@ -31,19 +29,18 @@ those traces is done using the babeltrace(1) text viewer. We introduce the notion of \fBtracing domains\fP which is essentially a type of tracer (kernel or user space for now). In the future, we could see a third tracer being for instance an hypervisor. For some commands, you'll need to -specify on which domain the command applies (-u or -k). For instance, enabling -a kernel event, you must specify the kernel domain to the command so we know -for which tracer this event is for. +specify on which domain the command operates (-u or -k). For instance, the +kernel domain must be specified when enabling a kernel event. In order to trace the kernel, the session daemon needs to be running as root. LTTng provides the use of a \fBtracing group\fP (default: tracing). Whomever is in that group can interact with the root session daemon and thus trace the -kernel. Session daemons can co-exist meaning that you can have a session daemon +kernel. Session daemons can co-exist, meaning that you can have a session daemon running as Alice that can be used to trace her applications along side with a -root daemon or even a Bob daemon. We highly recommend to start the session +root daemon or even a Bob daemon. We highly recommend starting the session daemon at boot time for stable and long term tracing. -Every user-space applications instrumented with lttng-ust(3), will +All user-space applications instrumented with lttng-ust(3) will automatically register to the session daemon. This feature gives you the ability to list available traceable applications and tracepoints on a per user basis. (See \fBlist\fP command). @@ -82,9 +79,9 @@ Simple listing of lttng options. Simple listing of lttng commands. .SH "COMMANDS" -.TP -\fBadd-context\fP -.nf +.PP +\fBadd-context\fP [OPTIONS] +.RS Add context to event(s) and/or channel(s). A context is basically extra information appended to a channel. For instance, @@ -96,7 +93,10 @@ For example, this command will add the context information 'prio' and two perf counters (hardware branch misses and cache misses), to all events in the trace data output: -# lttng add-context \-k \-t prio \-t perf:branch-misses \-t perf:cache-misses +.nf +# lttng add-context \-k \-t prio \-t perf:branch-misses \\ + \-t perf:cache-misses +.fi Please take a look at the help (\-h/\-\-help) for a detailed list of available contexts. @@ -107,30 +107,34 @@ Otherwise the context will be added only to the given channel (\-c). If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-s, \-\-session NAME - Apply on session name. -\-c, \-\-channel NAME - Apply on channel name. -\-k, \-\-kernel - Apply for the kernel tracer -\-u, \-\-userspace - Apply for the user-space tracer -\-t, \-\-type TYPE - Context type. You can repeat this option on the command line. Please - use "lttng add-context \-h" to list all available types. -.fi - -.IP +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-s, \-\-session NAME" +Apply on session name. +.TP +.BR "\-c, \-\-channel NAME" +Apply on channel name. +.TP +.BR "\-k, \-\-kernel" +Apply for the kernel tracer +.TP +.BR "\-u, \-\-userspace" +Apply for the user-space tracer +.TP +.BR "\-t, \-\-type TYPE" +Context type. You can repeat this option on the command line. Please +use "lttng add-context \-h" to list all available types. +.RE +.PP -.IP "\fBcalibrate\fP" -.nf +.PP +\fBcalibrate\fP [OPTIONS] +.RS Quantify LTTng overhead The LTTng calibrate command can be used to find out the combined average @@ -152,16 +156,21 @@ an empty function, gathering PMU counters LLC (Last Level Cache) misses information (see lttng add-context \-\-help to see the list of available PMU counters). +.nf # lttng create calibrate-function -# lttng enable-event calibrate \-\-kernel \-\-function lttng_calibrate_kretprobe -# lttng add-context \-\-kernel \-t perf:LLC-load-misses \-t perf:LLC-store-misses \\ - \-t perf:LLC-prefetch-misses +# lttng enable-event calibrate \-\-kernel \\ + \-\-function lttng_calibrate_kretprobe +# lttng add-context \-\-kernel \-t perf:LLC-load-misses \\ + \-t perf:LLC-store-misses \\ + \-t perf:LLC-prefetch-misses # lttng start # for a in $(seq 1 10); do \\ lttng calibrate \-\-kernel \-\-function; done # lttng destroy -# babeltrace $(ls \-1drt ~/lttng-traces/calibrate-function-* | tail \-n 1) +# babeltrace $(ls \-1drt ~/lttng-traces/calibrate-function-* \\ + | tail \-n 1) +.fi The output from babeltrace can be saved to a text file and opened in a spreadsheet (e.g. oocalc) to focus on the per-PMU counter delta between @@ -172,10 +181,12 @@ staying on the same CPU must be considered. The average result, for the i7, on 10 samples: +.nf Average Std.Dev. perf_LLC_load_misses: 5.0 0.577 perf_LLC_store_misses: 1.6 0.516 perf_LLC_prefetch_misses: 9.0 14.742 +.fi As we can notice, the load and store misses are relatively stable across runs (their standard deviation is relatively low) compared to the prefetch misses. @@ -183,29 +194,31 @@ We can conclude from this information that LLC load and store misses can be accounted for quite precisely, but prefetches within a function seems to behave too erratically (not much causality link between the code executed and the CPU prefetch activity) to be accounted for. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-k, \-\-kernel - Apply for the kernel tracer -\-u, \-\-userspace - Apply for the user-space tracer -\-\-function - Dynamic function entry/return probe (default) -.fi - -.IP +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-k, \-\-kernel" +Apply for the kernel tracer +.TP +.BR "\-u, \-\-userspace" +Apply for the user-space tracer +.TP +.BR "\-\-function" +Dynamic function entry/return probe (default) +.RE +.PP -.IP "\fBcreate\fP [NAME] [OPTIONS] -.nf +.PP +\fBcreate\fP [NAME] [OPTIONS] +.RS Create tracing session. A tracing session contains channel(s) which contains event(s). It is domain -agnostic meaning that you can enable channels and events for either the +agnostic, meaning that channels and events can be enabled for the user-space tracer and/or the kernel tracer. It acts like a container aggregating multiple tracing sources. @@ -219,87 +232,129 @@ $HOME/lttng-traces. The $HOME environment variable can be overridden by defining the environment variable LTTNG_HOME. This is useful when the user running the commands has a non-writeable home directory. -.fi .B OPTIONS: +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-o, \-\-output PATH" +Specify output path for traces +.TP +.BR "\-\-no-output" +Traces will not be output +.TP +.BR "\-\-snapshot" +Set the session in snapshot mode. Created in no-output mode and uses the +URL, if one is specified, as the default snapshot output. Every channel will be set +in overwrite mode and with mmap output (splice not supported). +.TP +.BR "\-\-live USEC" +Set the session exclusively in live mode. The paremeter is the delay in micro +seconds before the data is flushed and streamed. The live mode allows you to +stream the trace and view it while it's being recorded by any tracer. For that, +you need a lttng-relayd and this session requires a network URL (\-U or +\-C/\-D). + +To read a live session, you can use babeltrace(1) or the live streaming +protocol in doc/live-reading-protocol.txt. Here is an example: + .nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -\-o, \-\-output PATH - Specify output path for traces +$ lttng-relayd -o /tmp/lttng +$ lttng create --live 200000 -U net://localhost +$ lttng enable-event -a --userspace +$ lttng start +.fi + +After the start, you'll be able to read the events while they are being +recorded in /tmp/lttng. +.TP +.BR "\-U, \-\-set-url=URL" +Set URL for the consumer output destination. It is persistent for the +session lifetime. Redo the command to change it. This will set both data +and control URL for network. +.TP +.BR "\-C, \-\-ctrl-url=URL" +Set control path URL. (Must use -D also) +.TP +.BR "\-D, \-\-data-url=URL" +Set data path URL. (Must use -C also) +.PP Using these options, each API call can be controlled individually. For instance, \-C does not enable the consumer automatically. You'll need the \-e option for that. -\-U, \-\-set-url=URL - Set URL for the consumer output destination. It is persistent for the - session lifetime. Redo the command to change it. This will set both - data and control URL for network. -\-C, \-\-ctrl-url=URL - Set control path URL. (Must use -D also) -\-D, \-\-data-url=URL - Set data path URL. (Must use -C also) - .B URL FORMAT: proto://[HOST|IP][:PORT1[:PORT2]][/TRACE_PATH] Supported protocols are (proto): -> file://... - Local filesystem full path. +.TP +.BR "file://..." +Local filesystem full path. -> net://... - This will use the default network transport layer which is TCP for both - control (PORT1) and data port (PORT2). The default ports are - respectively 5342 and 5343. Note that net[6]:// is not yet supported. +.TP +.BR "net://..." +This will use the default network transport layer which is TCP for both +control (PORT1) and data port (PORT2). The default ports are +respectively 5342 and 5343. Note that net[6]:// is not yet supported. -> tcp[6]://... - Can only be used with -C and -D together +.TP +.BR "tcp[6]://..." +Can only be used with -C and -D together NOTE: IPv6 address MUST be enclosed in brackets '[]' (rfc2732) .B EXAMPLES: +.nf # lttng create -U net://192.168.1.42 +.fi Uses TCP and default ports for the given destination. +.nf # lttng create -U net6://[fe80::f66d:4ff:fe53:d220] +.fi Uses TCP, default ports and IPv6. +.nf # lttng create s1 -U net://myhost.com:3229 -Create session s1 and set its consumer to myhost.com on port 3229 for control. .fi +Create session s1 and set its consumer to myhost.com on port 3229 for control. +.RE +.PP -.IP - -.IP "\fBdestroy\fP [OPTIONS] [NAME]" -.nf +.PP +\fBdestroy\fP [NAME] [OPTIONS] +.RS Teardown tracing session Free memory on the session daemon and tracer side. It's gone! If NAME is omitted, the session name is taken from the .lttngrc file. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-a, \-\-all - Destroy all sessions -\-\-list-options - Simple listing of options -.fi - -.IP +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-a, \-\-all" +Destroy all sessions +.TP +.BR "\-\-list-options" +Simple listing of options +.RE +.PP -.IP "\fBenable-channel\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]" -.nf +.PP +\fBenable-channel\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS] +.RS Enable tracing channel To enable an event, you must enable both the event and the channel that @@ -308,205 +363,252 @@ contains it. If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. +Exactly one of \-k or -u must be specified. + It is important to note that if a certain type of buffers is used, the session will be set with that type and all other subsequent channel needs to have the same type. Note that once the session has been started and enabled on the tracer side, it's not possible anymore to enable a new channel for that session. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show this help -\-\-list-options - Simple listing of options -\-s, \-\-session NAME - Apply on session name -\-k, \-\-kernel - Apply to the kernel tracer -\-u, \-\-userspace - Apply to the user-space tracer - -\-\-discard - Discard event when subbuffers are full (default) -\-\-overwrite - Flight recorder mode : overwrites events when subbuffers are full -\-\-subbuf-size SIZE - Subbuffer size in bytes {+k,+M,+G} - (default UST uid: 131072, UST pid: 4096, kernel: 262144, metadata: 4096) - Rounded up to the next power of 2. - - The minimum subbuffer size, for each tracer, is the max value between - the default above and the system page size. You can issue this command - to get the current page size on your system: \fB$ getconf PAGE_SIZE\fP -\-\-num-subbuf NUM - Number of subbuffers. (default UST uid: 4, UST pid: 4, kernel: 4, metadata: 2) - Rounded up to the next power of 2. -\-\-switch-timer USEC - Switch subbuffer timer interval in µsec. - (default UST uid: 0, UST pid: 0, kernel: 0, metadata: 0) -\-\-read-timer USEC - Read timer interval in µsec. - (default UST uid: 0, UST pid: 0, kernel: 200000, metadata: 0) -\-\-output TYPE - Channel output type. Possible values: mmap, splice - (default UST uid: mmap, UST pid: mmap, kernel: splice, metadata: mmap) -\-\-buffers-uid - Use per UID buffer (\-u only). Buffers are shared between applications - that have the same UID. -\-\-buffers-pid - Use per PID buffer (\-u only). Each application has its own buffers. -\-\-buffers-global - Use shared buffer for the whole system (\-k only) -\-C, \-\-tracefile-size SIZE - Maximum size of each tracefile within a stream (in bytes). - 0 means unlimited. (default: 0) -\-W, \-\-tracefile-count COUNT - Used in conjunction with \-C option, this will limit the number - of files created to the specified count. 0 means unlimited. (default: 0) +.TP +.BR "\-h, \-\-help" +Show this help +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-s, \-\-session NAME" +Apply on session name +.TP +.BR "\-k, \-\-kernel" +Apply to the kernel tracer +.TP +.BR "\-u, \-\-userspace" +Apply to the user-space tracer +.TP +.BR "\-\-discard" +Discard event when subbuffers are full (default) +.TP +.BR "\-\-overwrite" +Flight recorder mode : overwrites events when subbuffers are full +.TP +.BR "\-\-subbuf-size SIZE" +Subbuffer size in bytes {+k,+M,+G}. +(default UST uid: 131072, UST pid: 4096, kernel: 262144, metadata: 4096) +Rounded up to the next power of 2. + +The minimum subbuffer size, for each tracer, is the max value between +the default above and the system page size. You can issue this command +to get the current page size on your system: \fB$ getconf PAGE_SIZE\fP +.TP +.BR "\-\-num-subbuf NUM" +Number of subbuffers. (default UST uid: 4, UST pid: 4, kernel: 4, +metadata: 2) Rounded up to the next power of 2. +.TP +.BR "\-\-switch-timer USEC" +Switch subbuffer timer interval in µsec. +(default UST uid: 0, UST pid: 0, kernel: 0, metadata: 0) +.TP +.BR "\-\-read-timer USEC" +Read timer interval in µsec. +(default UST uid: 0, UST pid: 0, kernel: 200000, metadata: 0) +.TP +.BR "\-\-output TYPE" +Channel output type. Possible values: mmap, splice +(default UST uid: mmap, UST pid: mmap, kernel: splice, metadata: mmap) +.TP +.BR "\-\-buffers-uid" +Use per UID buffer (\-u only). Buffers are shared between applications +that have the same UID. +.TP +.BR "\-\-buffers-pid" +Use per PID buffer (\-u only). Each application has its own buffers. +.TP +.BR "\-\-buffers-global" +Use shared buffer for the whole system (\-k only) +.TP +.BR "\-C, \-\-tracefile-size SIZE" +Maximum size of each tracefile within a stream (in bytes). +0 means unlimited. (default: 0) +.TP +.BR "\-W, \-\-tracefile-count COUNT" +Used in conjunction with \-C option, this will limit the number of files +created to the specified count. 0 means unlimited. (default: 0) .B EXAMPLES: -$ lttng enable-channel -C 4096 -W 32 chan1 -For each stream, the maximum size of each trace file will be 4096 bytes, and +.nf +$ lttng enable-channel -k -C 4096 -W 32 chan1 +.fi +For each stream, the maximum size of each trace file will be 4096 bytes and there will be a maximum of 32 different files. The file count is appended after the stream number as seen in the following example. The last trace file is smaller than 4096 since it was not completely filled. +.nf ~/lttng-traces/[...]/chan1_0_0 (4096) ~/lttng-traces/[...]/chan1_0_1 (4096) ~/lttng-traces/[...]/chan1_0_2 (3245) ~/lttng-traces/[...]/chan1_1_0 (4096) ... +.fi -$ lttng enable-channel -C 4096 +.nf +$ lttng enable-channel -k -C 4096 +.fi This will create trace files of 4096 bytes and will create new ones as long as there is data available. -.fi - -.IP +.RE +.PP -.IP "\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]" -.nf +.PP +\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS] +.RS Enable tracing event A tracing event is always assigned to a channel. If \fB\-c, \-\-channel\fP is omitted, a default channel named '\fBchannel0\fP' is created and the event is -added to it. For the user-space tracer, using \fB\-a, \-\-all\fP is the same as -using the wildcard "*". +added to it. If \fB\-c, \-\-channel\fP is omitted, but a non-default +channel already exists within the session, an error is returned. For the +user-space tracer, using \fB\-a, \-\-all\fP is the same as using the +wildcard "*". If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. -.fi .B OPTIONS: +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-s, \-\-session NAME" +Apply on session name +.TP +.BR "\-c, \-\-channel NAME" +Apply on channel name +.TP +.BR "\-a, \-\-all" +Enable all tracepoints and syscalls. This actually enables a single +wildcard event "*". +.TP +.BR "\-k, \-\-kernel" +Apply for the kernel tracer +.TP +.BR "\-u, \-\-userspace" +Apply for the user-space tracer +.TP +.BR "\-\-tracepoint" +Tracepoint event (default). Userspace tracer supports wildcards at the end +of string. Don't forget to quote to deal with bash expansion. +e.g.: .nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -\-s, \-\-session NAME - Apply on session name -\-c, \-\-channel NAME - Apply on channel name -\-a, \-\-all - Enable all tracepoints and syscalls. This actually enable a single - wildcard event "*". -\-k, \-\-kernel - Apply for the kernel tracer -\-u, \-\-userspace - Apply for the user-space tracer - -\-\-tracepoint - Tracepoint event (default) - - userspace tracer supports wildcards at end of string. Don't forget to - quote to deal with bash expansion. - e.g.: "*" "app_component:na*" -\-\-loglevel NAME - Tracepoint loglevel range from 0 to loglevel. Listed in the help (\-h). -\-\-loglevel-only NAME - Tracepoint loglevel (only this loglevel). - - The loglevel or loglevel-only options should be combined with a - tracepoint name or tracepoint wildcard. -\-\-probe [addr | symbol | symbol+offset] - Dynamic probe. Addr and offset can be octal (0NNN...), decimal (NNN...) - or hexadecimal (0xNNN...) -\-\-function [addr | symbol | symbol+offset] - Dynamic function entry/return probe. Addr and offset can be octal - (0NNN...), decimal (NNN...) or hexadecimal (0xNNN...) -\-\-syscall - System call event. Enabling syscalls tracing (kernel tracer), you will - not be able to disable them with disable-event. This is a known - limitation. You can disable the entire channel to do the trick. - -\-\-filter 'expression' - Set a filter on a newly enabled event. Filter expression on event - fields and context. Event recording depends on evaluation. Only - specify on first activation of a given event within a session. - Filter only allowed when enabling events within a session before - tracing is started. If the filter fails to link with the event - within the traced domain, the event will be discarded. - Currently, filter is only implemented for the user-space tracer. - - Expression examples: - - 'intfield > 500 && intfield < 503' - '(stringfield == "test" || intfield != 10) && intfield > 33' - 'doublefield > 1.1 && intfield < 5.3' - - Wildcards are allowed at the end of strings: - 'seqfield1 == "te*"' - In string literals, the escape character is a '\\'. Use '\\*' for - the '*' character, and '\\\\' for the '\\' character. Wildcard - match any sequence of characters, including an empty sub-string - (match 0 or more characters). - - Context information can be used for filtering. The examples - below show usage of context filtering on process name (with a - wildcard), process ID range, and unique thread ID for filtering. - The process and thread ID of running applications can be found - under columns "PID" and "LWP" of the "ps -eLf" command. - - '$ctx.procname == "demo*"' - '$ctx.vpid >= 4433 && $ctx.vpid < 4455' - '$ctx.vtid == 1234' .fi +.TP +.BR "\-\-loglevel NAME" +Tracepoint loglevel range from 0 to loglevel. Listed in the help (\-h). +.TP +.BR "\-\-loglevel-only NAME" +Tracepoint loglevel (only this loglevel). +The loglevel or loglevel-only options should be combined with a +tracepoint name or tracepoint wildcard. +.TP +.BR "\-\-probe (addr | symbol | symbol+offset)" +Dynamic probe. Addr and offset can be octal (0NNN...), decimal (NNN...) +or hexadecimal (0xNNN...) +.TP +.BR "\-\-function (addr | symbol | symbol+offset)" +Dynamic function entry/return probe. Addr and offset can be octal +(0NNN...), decimal (NNN...) or hexadecimal (0xNNN...) +.TP +.BR "\-\-syscall" +System call event. Enabling syscalls tracing (kernel tracer), you will +not be able to disable them with disable-event. This is a known +limitation. You can disable the entire channel to do the trick. +.TP +.BR "\-\-filter 'expression'" +Set a filter on a newly enabled event. Filter expression on event +fields and context. The event will be recorded if the filter's +expression evaluates to TRUE. Only specify on first activation of a +given event within a session. +Specifying a filter is only allowed when enabling events within a session before +tracing is started. If the filter fails to link with the event +within the traced domain, the event will be discarded. +Filtering is currently only implemented for the user-space tracer. + +Expression examples: -.IP "\fBdisable-channel\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]" .nf + 'intfield > 500 && intfield < 503' + '(strfield == "test" || intfield != 10) && intfield > 33' + 'doublefield > 1.1 && intfield < 5.3' +.fi + +Wildcards are allowed at the end of strings: + 'seqfield1 == "te*"' +In string literals, the escape character is a '\\'. Use '\\*' for +the '*' character, and '\\\\' for the '\\' character sequence. Wildcard +matches any sequence of characters, including an empty sub-string +(matches 0 or more characters). + +Context information can be used for filtering. The examples below shows +usage of context filtering on the process name (using a wildcard), process ID +range, and unique thread ID. The process and thread IDs of +running applications can be found under columns "PID" and "LWP" of the +"ps -eLf" command. + +.nf + '$ctx.procname == "demo*"' + '$ctx.vpid >= 4433 && $ctx.vpid < 4455' + '$ctx.vtid == 1234' +.fi + +.RE +.PP + +.PP +\fBdisable-channel\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS] +.RS Disable tracing channel -Disabling a channel makes all event(s) in that channel to stop tracing. You can -enable it back by calling \fBlttng enable-channel NAME\fP again. +Disabling a channel disables the tracing of all of the channel's events. A channel +can be reenabled by calling \fBlttng enable-channel NAME\fP again. If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -\-s, \-\-session NAME - Apply on session name -\-k, \-\-kernel - Apply for the kernel tracer -\-u, \-\-userspace - Apply for the user-space tracer -.fi +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-s, \-\-session NAME" +Apply on session name +.TP +.BR "\-k, \-\-kernel" +Apply for the kernel tracer +.TP +.BR "\-u, \-\-userspace" +Apply for the user-space tracer +.RE +.PP -.IP "\fBdisable-event\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]" -.nf +.PP +\fBdisable-event\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS] +.RS Disable tracing event The event, once disabled, can be re-enabled by calling \fBlttng enable-event @@ -514,28 +616,41 @@ NAME\fP again. If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. -.fi + +If \fB\-c, \-\-channel\fP is omitted, the default channel name is used. +If \fB\-c, \-\-channel\fP is omitted, but a non-default channel already +exists within the session, an error is returned. .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -\-s, \-\-session NAME - Apply on session name -\-a, \-\-all-events - Disable all events. This does NOT disable "*" but rather - every known events of the session. -\-k, \-\-kernel - Apply for the kernel tracer -\-u, \-\-userspace - Apply for the user-space tracer -.fi +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-s, \-\-session NAME" +Apply on session name +.TP +.BR "\-c, \-\-channel NAME" +Apply on channel name +.TP +.BR "\-a, \-\-all-events" +Disable all events. This does NOT disable "*" but rather every known +events of the session. +.TP +.BR "\-k, \-\-kernel" +Apply for the kernel tracer +.TP +.BR "\-u, \-\-userspace" +Apply for the user-space tracer +.RE +.PP -.IP "\fBlist\fP [\-k|\-u] [SESSION [SESSION_OPTIONS]]" -.nf +.PP +\fBlist\fP [OPTIONS] [SESSION [SESSION OPTIONS]] +.RS List tracing session information. With no arguments, it will list available tracing session(s). @@ -549,74 +664,157 @@ calls events). With \-u alone, it will list all available user-space events from registered applications. Here is an example of 'lttng list \-u': +.nf PID: 7448 - Name: /tmp/lttng-ust/tests/hello/.libs/lt-hello ust_tests_hello:tptest_sighandler (type: tracepoint) ust_tests_hello:tptest (type: tracepoint) +.fi You can now enable any event listed by using the name : \fBust_tests_hello:tptest\fP. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -\-k, \-\-kernel - Select kernel domain -\-u, \-\-userspace - Select user-space domain. +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-k, \-\-kernel" +Select kernel domain +.TP +.BR "\-u, \-\-userspace" +Select user-space domain. +.PP .B SESSION OPTIONS: -\-c, \-\-channel NAME - List details of a channel -\-d, \-\-domain - List available domain(s) -.fi +.TP +.BR "\-c, \-\-channel NAME" +List details of a channel +.TP +.BR "\-d, \-\-domain" +List available domain(s) +.RE +.PP -.IP "\fBset-session\fP NAME" -.nf +.PP +\fBset-session\fP NAME [OPTIONS] +.RS Set current session name Will change the session name in the .lttngrc file. -.fi .B OPTIONS: +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.RE +.PP + +.PP +\fBsnapshot\fP [OPTIONS] ACTION +.RS +Snapshot command for LTTng session. + +.B OPTIONS: + +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options + +.PP +.B ACTION: + +.TP +\fBadd-output\fP [-m ] [-s ] [-n ] | -C -D + +Setup and add an snapshot output for a session. Output are the destination +where the snapshot will be sent. Only one output is permitted. To change it, +you'll need to delete it and add back the new one. + +.TP +\fBdel-output\fP ID | NAME [-s ] + +Delete an output for a session using the ID. You can either specify the +output's ID that can be found with list-output or the name. + +.TP +\fBlist-output\fP [-s ] + +List the output of a session. Attributes of the output are printed. + +.TP +\fBrecord\fP [-m ] [-s ] [-n ] [ | -C -D ] + +Snapshot a session's buffer(s) for all domains. If an URL is specified, it is +used instead of a previously added output. Specifying only a name or/and a max +size will override the current output values. For instance, you can record a +snapshot with a custom maximum size or with a different name. + .nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options +$ lttng snapshot add-output -n mysnapshot file:///data/snapshot +[...] +$ lttng snapshot record -n new_name_snapshot .fi -.IP +The above will create a snapshot in /data/snapshot/new_name_snapshot* directory +rather then in mysnapshot*/ -.IP "\fBstart\fP [NAME] [OPTIONS]" -.nf +.PP +.B DETAILED ACTION OPTIONS + +.TP +.BR "\-s, \-\-session NAME" +Apply to session name. +.TP +.BR "\-n, \-\-name NAME" +Name of the snapshot's output. +.TP +.BR "\-m, \-\-max-size SIZE" +Maximum size in bytes of the snapshot. The maxium size does not include the +metadata file. Human readable format is accepted: {+k,+M,+G}. For instance, +\-\-max-size 5M +.TP +.BR "\-C, \-\-ctrl-url URL" +Set control path URL. (Must use -D also) +.TP +.BR "\-D, \-\-data-url URL" +Set data path URL. (Must use -C also) +.RE +.PP + +.PP +\fBstart\fP [NAME] [OPTIONS] +.RS Start tracing It will start tracing for all tracers for a specific tracing session. - If NAME is omitted, the session name is taken from the .lttngrc file. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -.fi - -.IP +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.RE +.PP -.IP "\fBstop\fP [NAME] [OPTIONS]" -.nf +.PP +\fBstop\fP [NAME] [OPTIONS] +.RS Stop tracing It will stop tracing for all tracers for a specific tracing session. Before @@ -625,75 +823,75 @@ until the trace is readable for the session. Use \-\-no-wait to avoid this behavior. If NAME is omitted, the session name is taken from the .lttngrc file. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -\-\-no-wait - Don't wait for data availability. -.fi - -.IP +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.TP "\-\-no-wait" +Don't wait for data availability. +.RE +.PP -.IP "\fBversion\fP" -.nf +.PP +\fBversion\fP +.RS Show version information -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -.fi - -.IP - -.IP "\fBview\fP [SESSION_NAME] [OPTIONS]" -.nf -View traces of a tracing session - -By default, the babeltrace viewer will be used for text viewing. - -If SESSION_NAME is omitted, the session name is taken from the .lttngrc file. +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.RE +.PP -.fi +.PP +\fBview\fP [SESSION_NAME] [OPTIONS] +.RS +View traces of a tracing session. By default, the babeltrace viewer +will be used for text viewing. If SESSION_NAME is omitted, the session +name is taken from the .lttngrc file. .B OPTIONS: -.nf -\-h, \-\-help - Show this help -\-\-list-options - Simple listing of options -\-t, \-\-trace-path PATH - Trace directory path for the viewer -\-e, \-\-viewer CMD - Specify viewer and/or options to use - This will completely override the default viewers so - please make sure to specify the full command. The trace - directory path of the session will be appended at the end - to the arguments -.fi +.TP +.BR "\-h, \-\-help" +Show this help +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-t, \-\-trace-path PATH" +Trace directory path for the viewer +.TP +.BR "\-e, \-\-viewer CMD" +Specify viewer and/or options to use This will completely override the +default viewers so please make sure to specify the full command. The +trace directory path of the session will be appended at the end to the +arguments +.RE +.PP .SH "EXIT VALUES" +.PP On success 0 is returned and a positive value on error. Value of 1 means a command error, 2 an undefined command, 3 a fatal error and 4 a command warning meaning that something went wrong during the command. Any other value above 10, please refer to -.BR +.BR "" for a detailed list or use lttng_strerror() to get a human readable string of the error code. - .PP + .SH "ENVIRONMENT VARIABLES" .PP @@ -704,17 +902,22 @@ Note that all command line options override environment variables. .IP "LTTNG_SESSIOND_PATH" Allows one to specify the full session daemon binary path to lttng command line tool. You can also use \-\-sessiond-path option having the same effect. +.PP + .SH "SEE ALSO" .BR babeltrace(1), .BR lttng-ust(3), .BR lttng-sessiond(8), .BR lttng-relayd(8), -.BR lttng-health-check(3) + .SH "BUGS" +.PP If you encounter any issues or usability problem, please report it on our mailing list to help improve this project or at https://bugs.lttng.org which is a bugtracker. +.PP + .SH "CREDITS" .PP diff --git a/doc/proposals/0006-lttng-snapshot.txt b/doc/proposals/0006-lttng-snapshot.txt new file mode 100644 index 000000000..399fcca2e --- /dev/null +++ b/doc/proposals/0006-lttng-snapshot.txt @@ -0,0 +1,164 @@ +RFC - LTTng snapshot + +Author: David Goulet + +Version: + - v0.1: 11/04/2013 + * Initial proposal + +Motivation +---------- + +This proposal is for the snapshot feature in lttng-tools. The idea is to be +able to snapshot a portion of the trace and write it to a specified output +(disk or network). This could be particularly useful in flight recorder mode +where you detect a problem on your system for instance and then use this +snapshot feature to save the latest buffers which should contain information to +help understand the issue. + +Requirements +----------------- + +In order to snapshot a session, it must be set in flight recorder mode meaning +that there is *no* consumer extracting the trace and writing it to a +destination. To do that, the --no-output option is added to "lttng create" +command. + + $ lttng create --no-output + Create a session with active tracing but no data being collected. + + For the API call lttng_create_session(), simply set the URL to NULL. + +Furthermore, by default, this command will set all subsequent channel in +overwrite mode. You can force the discard value (overwrite=0) but it is a bit +pointless since the snapshot does NOT remove the data from the buffers. + +Proposed Solution +----------------- + +First, the new lttng command line UI is presented followed by the new API +calls. + +This new command uses a git-alike UI, but in the form of the object first +followed by the desired action, whereas other commands only use actions such as +"enable-event". + + $ lttng snapshot [ACTION] [OPTIONS] + + ACTION: (detailed below) + +The user can specify an output destination either for the current session +(being the default) or on the spot when the command is executed. To specify an +output for the session, use the "add-output" action. + + $ lttng snapshot add-output [URL] [OPTIONS] + + OPTIONS: + -s, --session NAME + -C, --ctrl-url URL + -D, --data-url URL + -a, --alias ALIAS Name of the output in the session. + -m, --max-size SIZE Maximum bytes size of the snapshot. + +Without the -s, the current session is used. The above command adds an output +location to the session so when a snapshot is recorded later on, it's sent +there. This action command takes either a valid lttng URL (see proposal 0004) +or the -C/-D options from "lttng create" can be used to define relayd on +different ports. The alias option can be used to give a name to the output so +it's recognizable in the list command and can also be used with the del +command. + +Following that, two new actions are available to control outputs. You can list +and delete outputs. + + $ lttng snapshot list-output + [1]: file://[...] + [2]: net://1.1.1.1:8762:9123 + [3] - ALIAS: file://[...] + + $ lttng snapshot del-output ID|ALIAS + + The output identified by the ID or alias is removed from the session. In + this case the ID is the number returned by list-output (e.g.: 2). + +To specify an output destination on the spot when the snapshot is taken, use +the record action. + + $ lttng snapshot record [URL] [OPTIONS] + + OPTIONS: + -s, --session NAME Session name + -n, --name NAME Name of the snapshot to recognize it afterwards. + -m, --max-size SIZE Maximum bytes size of the snapshot. + -C, --ctrl-url URL + -D, --data-url URL + +No URL means that the default output of the session is used. The max-size is +the maximum size of the trace you want to snapshot. The name is used so you can +recognize the snapshot once taken and written on disk. Finally, the -s let the +user specify a session name or else the current session is used (in .lttngrc). + +Finally, we allow the snapshot command to be used without an action which +basically do "lttng snapshot record". + + $ lttng snapshot [OPTIONS] + + OPTIONS: + -s, --session NAME + -m, --max-size SIZE Maximum bytes size of the snapshot. + + $ lttng snapshot -s mysession -m 8192 + + Snapshot the session and puts it in the session define output directory. + +By default, the snapshot(s) are saved in the session directory in the snapshot/ directory. + + SESSION_DIR/snapshot/--