On 05/19/2010 05:23 PM, Jon Bernard wrote:
* kerstin.jonsson<[email protected]> wrote:
Hi,
I have added a "deb" target to the ust and lttv make files, to
enable build of debian packages, I also did some minor changes to
the documentation - NB! not the contents, only to enable deb install
of the manual as info pages.
This is something that I did only for our own convenience, (i.e. the
debian control files needs more work before these patches can be
made public) we are using pbuilder to create boot images for
different targets and then it's neat to have everything installable
from deb packets.
Is this something that may be of interest? I'd be happy to mail the
patches. Or is the intention to keep the packaging separate from the
source tree?
Hi again, sorry! I was interrupted.
Hi Kerstin, thanks for your interest! I'm more than happy to collaborate
on the debian packaging.
I much prefer to keep the debian packaging development separate from
upstream development. The git repositories for this are hosted at
http://git.debian.org/ Ust and liburcu are available in Debian unstable
and testing, but if you need packages for lenny, let me know. I should
be able to backport them with little effort.
We are using testing and unstable but the problem we wanted to solve was
to have a simple way of including our own modifications to UST into the
boot images we create for the target machines. LTTV, however, is a different
matter, we will not do any modifications to lttv and then it's very nice to
be able to download the package directly. But still, testing and unstable
is just what we're looking for.
ltt-control is nearly done, I have a manpage or two to write and it will
be ready for upload. I can push a snapshot of this effort to a git
repository if you're interested.
We most certainly are:D
For lttv, I'm only waiting for the licensing to be updated before I can
upload that package.
Any patches you have please send them along and I'll make sure they get
included.
Since my lttv patches are soon to be obsolete, also for us, I'll attache
only the patches that I did to the UST source tree.
Best Regards,
Kerstin
Cheers
>From 29910c442b37285b075ea1ada04429698a9d17f0 Mon Sep 17 00:00:00 2001
From: Kerstin Jonsson <[email protected]>
Date: Thu, 20 May 2010 15:27:04 +0200
Subject: [PATCH 1/6] Add man to EXTRA_DIST target to enable clean make distcheck build
---
doc/Makefile.am | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)
diff --git a/doc/Makefile.am b/doc/Makefile.am
index c266f7d..c2c93ad 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,2 +1,2 @@
-EXTRA_DIST = manual
+EXTRA_DIST = manual man
man_MANS = man/ustctl.1 man/ustd.1 man/usttrace.1
--
1.7.1
>From 95f2ad564e7499c4c2b717ba3e049b12ee00525f Mon Sep 17 00:00:00 2001
From: Kerstin Jonsson <[email protected]>
Date: Thu, 20 May 2010 15:29:36 +0200
Subject: [PATCH 2/6] Added debian packet configuration files
---
debian/README.source | 9 +++++++++
debian/changelog | 6 ++++++
debian/compat | 1 +
debian/control | 31 +++++++++++++++++++++++++++++++
debian/copyright | 45 +++++++++++++++++++++++++++++++++++++++++++++
debian/docs | 2 ++
debian/libust.dirs | 1 +
debian/libust.install | 1 +
debian/rules | 13 +++++++++++++
debian/source/format | 1 +
debian/ust-dev.dirs | 2 ++
debian/ust-dev.info | 1 +
debian/ust-dev.install | 6 ++++++
debian/ust.dirs | 2 ++
debian/ust.install | 3 +++
15 files changed, 124 insertions(+), 0 deletions(-)
create mode 100644 debian/README.source
create mode 100644 debian/changelog
create mode 100644 debian/compat
create mode 100644 debian/control
create mode 100644 debian/copyright
create mode 100644 debian/docs
create mode 100644 debian/libust.dirs
create mode 100644 debian/libust.install
create mode 100755 debian/rules
create mode 100644 debian/source/format
create mode 100644 debian/ust-dev.dirs
create mode 100644 debian/ust-dev.info
create mode 100644 debian/ust-dev.install
create mode 100644 debian/ust.dirs
create mode 100644 debian/ust.install
diff --git a/debian/README.source b/debian/README.source
new file mode 100644
index 0000000..020ca1d
--- /dev/null
+++ b/debian/README.source
@@ -0,0 +1,9 @@
+ust for Debian
+--------------
+
+<this file describes information about the source package, see Debian policy
+manual section 4.14. You WILL either need to modify or delete this file>
+
+
+
+
diff --git a/debian/changelog b/debian/changelog
new file mode 100644
index 0000000..87b433b
--- /dev/null
+++ b/debian/changelog
@@ -0,0 +1,6 @@
+ust (0.4-1) unstable; urgency=low
+
+ * Initial release Closes: #12345
+ * First ust debian packet
+
+ -- Kerstin Jonsson <[email protected]> Tue, 27 Apr 2010 14:22:32 +0200
diff --git a/debian/compat b/debian/compat
new file mode 100644
index 0000000..7f8f011
--- /dev/null
+++ b/debian/compat
@@ -0,0 +1 @@
+7
diff --git a/debian/control b/debian/control
new file mode 100644
index 0000000..61e4d7f
--- /dev/null
+++ b/debian/control
@@ -0,0 +1,31 @@
+Source: ust
+Priority: extra
+Maintainer: Kerstin Jonsson <[email protected]>
+Build-Depends: debhelper (>= 7.0.50), autotools-dev, liburcu-dev (>=0.4.1-1), mime-support, libmagic1, file, mawk
+Standards-Version: 3.8.4
+Section: libs
+Homepage: http://lttng.org/ust
+Vcs-Git: git://git.dorsal.polymtl.ca/git/ust.git
+Vcs-Browser: http://git.dorsal.polymtl.ca
+
+Package: ust-dev
+Section: libdevel
+Architecture: any
+Depends: libust (= ${binary:Version}), dpkg (>= 1.15.4)
+Description: user space lttng devel package
+ user space lttng headers
+
+Package: libust
+Section: libs
+Architecture: any
+Depends: ${shlibs:Depends}, ${misc:Depends}
+Description: user space lttng libraries
+ user space lttng libraries
+
+Package: ust
+Architecture: any
+Depends: libust (= ${binary:Version}), ${shlibs:Depends}, ${misc:Depends}
+Recommends: lttv (>=0.12.31)
+Description: user space lttng binaries
+ user space lttng binaries and man pages
+
diff --git a/debian/copyright b/debian/copyright
new file mode 100644
index 0000000..c0f5b91
--- /dev/null
+++ b/debian/copyright
@@ -0,0 +1,45 @@
+This work was packaged for Debian by:
+
+ Kerstin Jonsson <[email protected]> on Tue, 27 Apr 2010 14:22:32 +0200
+
+It was downloaded from:
+
+ git://git.dorsal.polymtl.ca/git/ust.git
+
+Upstream Author(s):
+
+ Pierre-Marc Fournier <[email protected]>
+ Mathieu Desnoyers <[email protected]>
+
+Copyright:
+
+ Copyright (C) 2009 Pierre-Marc Fournier
+ Copyright (C) 2009 Mathieu Desnoyers
+
+License:
+
+ This package is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.
+
+ This package is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see <http://www.gnu.org/licenses/>
+
+On Debian systems, the complete text of the GNU General
+Public License version 2 can be found in "/usr/share/common-licenses/GPL-2".
+
+The Debian packaging is:
+
+ Copyright (C) 2010 Kerstin Jonsson <[email protected]>
+
+you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
diff --git a/debian/docs b/debian/docs
new file mode 100644
index 0000000..724e084
--- /dev/null
+++ b/debian/docs
@@ -0,0 +1,2 @@
+README
+TODO
diff --git a/debian/libust.dirs b/debian/libust.dirs
new file mode 100644
index 0000000..6845771
--- /dev/null
+++ b/debian/libust.dirs
@@ -0,0 +1 @@
+usr/lib
diff --git a/debian/libust.install b/debian/libust.install
new file mode 100644
index 0000000..d0dbfd1
--- /dev/null
+++ b/debian/libust.install
@@ -0,0 +1 @@
+usr/lib/lib*.so.*
diff --git a/debian/rules b/debian/rules
new file mode 100755
index 0000000..917d9bf
--- /dev/null
+++ b/debian/rules
@@ -0,0 +1,13 @@
+#!/usr/bin/make -f
+# -*- makefile -*-
+# Sample debian/rules that uses debhelper.
+# This file was originally written by Joey Hess and Craig Small.
+# As a special exception, when this file is copied by dh-make into a
+# dh-make output file, you may use that output file without restriction.
+# This special exception was added by Craig Small in version 0.37 of dh-make.
+
+# Uncomment this to turn on verbose mode.
+#export DH_VERBOSE=1
+
+%:
+ dh $@
diff --git a/debian/source/format b/debian/source/format
new file mode 100644
index 0000000..163aaf8
--- /dev/null
+++ b/debian/source/format
@@ -0,0 +1 @@
+3.0 (quilt)
diff --git a/debian/ust-dev.dirs b/debian/ust-dev.dirs
new file mode 100644
index 0000000..4418816
--- /dev/null
+++ b/debian/ust-dev.dirs
@@ -0,0 +1,2 @@
+usr/lib
+usr/include
diff --git a/debian/ust-dev.info b/debian/ust-dev.info
new file mode 100644
index 0000000..cfd9825
--- /dev/null
+++ b/debian/ust-dev.info
@@ -0,0 +1 @@
+doc/manual/ust.info
diff --git a/debian/ust-dev.install b/debian/ust-dev.install
new file mode 100644
index 0000000..358d2db
--- /dev/null
+++ b/debian/ust-dev.install
@@ -0,0 +1,6 @@
+usr/include/*
+usr/lib/lib*.a
+usr/lib/lib*.so
+usr/lib/libust-initializer.o
+usr/lib/*.la
+
diff --git a/debian/ust.dirs b/debian/ust.dirs
new file mode 100644
index 0000000..a215378
--- /dev/null
+++ b/debian/ust.dirs
@@ -0,0 +1,2 @@
+usr/share/man/man1
+usr/bin
diff --git a/debian/ust.install b/debian/ust.install
new file mode 100644
index 0000000..79b3d9c
--- /dev/null
+++ b/debian/ust.install
@@ -0,0 +1,3 @@
+usr/share/man/man1/*
+usr/bin/*
+
--
1.7.1
>From 31d88025d45150dbbe789847d4f2fc99b504c39d Mon Sep 17 00:00:00 2001
From: Kerstin Jonsson <[email protected]>
Date: Thu, 20 May 2010 15:48:00 +0200
Subject: [PATCH 3/6] modified make to build ust manual as info page
---
configure.ac | 1 +
doc/Makefile.am | 1 +
doc/manual/Makefile | 4 -
doc/manual/Makefile.am | 6 +
doc/manual/manual.texinfo | 530 --------------------------------------------
doc/manual/ust.texi | 535 +++++++++++++++++++++++++++++++++++++++++++++
6 files changed, 543 insertions(+), 534 deletions(-)
delete mode 100644 doc/manual/Makefile
create mode 100644 doc/manual/Makefile.am
delete mode 100644 doc/manual/manual.texinfo
create mode 100644 doc/manual/ust.texi
diff --git a/configure.ac b/configure.ac
index f9282f8..14fb3d6 100644
--- a/configure.ac
+++ b/configure.ac
@@ -107,6 +107,7 @@ AC_MSG_RESULT($LIBFORMAT)
AC_CONFIG_FILES([
Makefile
doc/Makefile
+ doc/manual/Makefile
include/Makefile
libust/Makefile
tests/Makefile
diff --git a/doc/Makefile.am b/doc/Makefile.am
index c2c93ad..ed0e40a 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,2 +1,3 @@
+SUBDIRS = manual
EXTRA_DIST = manual man
man_MANS = man/ustctl.1 man/ustd.1 man/usttrace.1
diff --git a/doc/manual/Makefile b/doc/manual/Makefile
deleted file mode 100644
index 62a430f..0000000
--- a/doc/manual/Makefile
+++ /dev/null
@@ -1,4 +0,0 @@
-all: ust.html
-
-ust.html: manual.texinfo
- makeinfo --html --no-split manual.texinfo
diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
new file mode 100644
index 0000000..2986d51
--- /dev/null
+++ b/doc/manual/Makefile.am
@@ -0,0 +1,6 @@
+AM_MAKEINFOFLAGS = --no-split
+AM_MAKEINFOHTMLFLAGS = --no-split
+
+info_TEXINFOS = ust.texi
+
+MAINTAINERCLEANFILES = Makefile.in
diff --git a/doc/manual/manual.texinfo b/doc/manual/manual.texinfo
deleted file mode 100644
index 8254cdb..0000000
--- a/doc/manual/manual.texinfo
+++ /dev/null
@@ -1,530 +0,0 @@
-\input texinfo @c -*-texinfo-*-
-...@c %**start of header
-...@setfilename ust.info
-...@settitle LTTng Userspace Tracer (UST) Manual
-...@c %**end of header
-
-...@copying
-This manual is for program, version version.
-
-Copyright @copyright{} copyright-owner.
-
-...@quotation
-Permission is granted to ...
-...@end quotation
-...@end copying
-
-...@titlepage
-...@title LTTng Userspace Tracer (UST) Manual
-...@c @subtitle subtitle-if-any
-...@c @subtitle second-subtitle
-...@c @author author
-
-...@c The following two commands
-...@c start the copyright page.
-...@c @page
-...@c @vskip 0pt plus 1filll
-...@c @insertcopying
-
-...@c Published by ...
-...@end titlepage
-
-...@c So the toc is printed at the start.
-...@contents
-
-...@ifnottex
-...@node Top
-...@top LTTng Userspace Tracer
-
-This manual is for UST 0.1.
-...@end ifnottex
-
-...@menu
-* Overview::
-* Installation::
-* Quick start::
-* Instrumenting an application::
-* Recording a trace::
-* Viewing traces::
-* Performance::
-...@c * Copying:: Your rights and freedoms.
-...@end menu
-
-...@node Overview
-...@chapter Overview
-
-...@menu
-* What is UST?::
-* License::
-* Supported platforms::
-...@end menu
-
-...@node What is UST?
-...@section What is UST?
-
-The LTTng Userspace Tracer (UST) is a library accompanied by a set of tools to
-trace userspace code.
-
-Code may be instrumented with either markers or tracepoints. A highly efficient
-lockless tracer records these events to a trace buffers. These buffers are reaped
-by a deamon which writes trace data to disk.
-
-High performance is achieved by the use of lockless buffering algorithms, RCU and
-per-cpu buffers. In addition, special care is taken to minize cache impact.
-
-...@node License
-...@section License
-The LTTng Userspace Tracer is intended to be linkable to open source software
-as well as to proprietary applications. This was accomplished by licensing
-the code that needs to be linked to the traced program as @acronym{LGPL}.
-
-Components licensed as LGPL v2.1:
-...@itemize @bullet
-...@item libust
-...@item libinterfork
-...@item libustcomm
-...@end itemize
-
-Components licensed as GPL v2:
-...@itemize @bullet
-...@item ustctl
-...@item libustcmd
-...@item ustd
-...@end itemize
-
-...@node Supported platforms
-...@section Supported platforms
-
-UST can currently trace applications running on Linux, on the x86-32 and x86-64 architectures.
-
-...@node Installation
-...@chapter Installation
-
-The LTTng userspace tracer is a library and a set of userspace tools.
-
-The following packages are required:
-
-...@itemize @bullet
-...@item
-ust
-
-This contains the tracing library, the ustd daemon, trace control tools
-and other helper tools.
-
-Repository: http://git.dorsal.polymtl.ca
-
-...@item
-libkcompat
-
-This is a library that contains a userspace port of some kernel APIs.
-
-Repository: http://git.dorsal.polymtl.ca
-
-...@item
-liburcu
-
-This is the userspace read-copy update library by Mathieu Desnoyers.
-
-Available in Debian as package liburcu-dev.
-
-Home page: http://lttng.org/?q=node/18
-
-...@item
-LTTV
-
-LTTV is a graphical (and text) viewer for LTTng traces.
-
-Home page: http://lttng.org
-
-...@end itemize
-
-Libkcompat and liburcu should be installed first. UST may then be compiled
-and installed. LTTV has no dependency on the other packages; it may therefore
-be installed on a system which does not have UST installed.
-
-Refer to the README in each of these packages for installation instructions.
-
-...@c @menu
-...@c @end menu
-
-...@node Quick start
-...@chapter Quick start
-
-First, instrument a program with a marker.
-
-...@example
-...@verbatim
-
-#include <ust/marker.h>
-
-int main(int argc, char **argv)
-{
- int v;
- char *st;
-
- /* ... set values of v and st ... */
-
- /* a marker: */
- trace_mark(ust, myevent, "firstarg %d secondarg %s", v, st);
-
- /* a marker without arguments: */
- trace_mark(ust, myotherevent, MARK_NOARGS);
-
- return 0;
-}
-
-...@end verbatim
-...@end example
-
-Then compile it in the regular way, linking it with libust. For example:
-
-...@example
-gcc -o foo -lust foo.c
-...@end example
-
-Run the program with @command{usttrace}. The @command{usttrace} output says where the trace
-was written.
-
-...@example
-usttrace ./foo
-...@end example
-
-Finally, open the trace in LTTV.
-
-...@example
-lttv-gui -t /path/to/trace
-...@end example
-
-The trace can also be dumped as text in the console:
-
-...@example
-lttv -m textDump -t /path/to/trace
-...@end example
-
-...@node Instrumenting an application
-...@chapter Instrumenting an application
-
-In order to record a trace of events occurring in a application, the
-application must be instrumented. Instrumentation points resemble function
-calls. When the program reaches an instrumentation point, an event is
-generated.
-
-There are no limitations on the type of code that may be instrumented.
-Multi-threaded programs may be instrumented without problem. Signal handlers
-may be instrumented as well.
-
-There are two APIs to instrument programs: markers and tracepoints. Markers are
-quick to add and are usually used for temporary instrumentation. Tracepoints
-provide a way to instrument code more cleanly and are suited for permanent
-instrumentation.
-
-In addition to executable programs, shared libraries may also be instrumented
-with the methods described in this chapter.
-
-...@menu
-* Markers::
-* Tracepoints::
-...@end menu
-
-...@node Markers
-...@section Markers
-
-Adding a marker is simply a matter of inserting one line in the program.
-
-...@example
-...@verbatim
-#include <ust/marker.h>
-
-int main(int argc, char **argv)
-{
- int v;
- char *st;
-
- /* ... set values of v and st ... */
-
- /* a marker: */
- trace_mark(main, myevent, "firstarg %d secondarg %s", v, st);
-
- /* another marker without arguments: */
- trace_mark(main, myotherevent, MARK_NOARGS);
-
- return 0;
-}
-...@end verbatim
-...@end example
-
-The invocation of the trace_mark() macro requires at least 3 arguments. The
-first, here "main", is the name of the event category. It is also the name of
-the channel the event will go in. The second, here "myevent" is the name of the
-event. The third is a format string that announces the names and the types of
-the event arguments. Its format resembles that of a printf() format string; it
-is described thoroughly in Appendix x.
-
-A given Marker may appear more than once in the same program. Other Markers may
-have the same name and a different format string, although this might induce
-some confusion at analysis time.
-
-...@node Tracepoints
-...@section Tracepoints
-
-The Tracepoints API uses the Markers, but provides a higher-level abstraction.
-Whereas the markers API provides limited type checking, the Tracepoints API
-provides more thorough type checking and discharges from the need to insert
-format strings directly in the code and to have format strings appear more than
-once if a given marker is reused.
-
-...@quotation Note Although this example uses @emph{mychannel} as the channel, the
-only channel name currently supported with early tracing is @strong{ust}. The
-...@command{usttrace} tool always uses the early tracing mode. When using manual
-mode without early tracing, any channel name may be used. @end quotation
-
-A function instrumented with a tracepoint looks like this:
-
-...@example
-...@verbatim
-#include "tp.h"
-
-void function()
-{
- int v;
- char *st;
-
- /* ... set values of v and st ... */
-
- /* a tracepoint: */
- trace_mychannel_myevent(v, st);
-}
-...@end verbatim
-...@end example
-
-Another file, here tp.h, contains declarations for the tracepoint.
-
-...@example
-...@verbatim
-#include <ust/tracepoint.h>
-
-DECLARE_TRACE(mychannel_myevent, TP_PROTO(int v, char *st),
- TP_ARGS(v, st));
-...@end verbatim
-...@end example
-
-A third file, here tp.c, contains definitions for the tracepoint.
-
-...@example
-...@verbatim
-#include <ust/marker.h>
-#include "tp.h"
-
-DEFINE_TRACE(mychannel_myevent);
-
-void mychannel_myevent_probe(int v, char *st)
-{
- trace_mark(mychannel, myevent, "v %d st %s", v, st);
-}
-
-static void __attribute__((constructor)) init()
-{
- register_trace_mychannel_myevent(mychannel_myevent_probe);
-}
-...@end verbatim
-...@end example
-
-Here, tp.h and tp.c could contain declarations and definitions for other
-tracepoints. The constructor would contain other register_* calls.
-
-...@node Recording a trace
-...@chapter Recording a trace
-
-...@menu
-* Using @command{usttrace}::
-* Setting up the recording manually::
-* Using early tracing::
-* Crash recovery::
-* Tracing across @code{fork()} and @code{clone()}::
-* Tracing programs and libraries that were not linked to libust::
-...@end menu
-
-...@node Using @command{usttrace}
-...@section Using @command{usttrace}
-
-The simplest way to record a trace is to use the @command{usttrace} script. An
-example is given in the quickstart above.
-
-The @command{usttrace} script automatically:
-...@itemize @bullet
-...@item creates a daemon
-...@item enables all markers
-...@item runs the command specified on the command line
-...@item after the command ends, prints the location where the trace was saved
-...@end itemize
-
-Each subdirectory of the save location contains the trace of one process that
-was generated by the command. The name of a subdirectory consists in the the PID
-of the process, followed by the timestamp of its creation.
-
-The save location also contains logs of the tracing.
-
-When using @command{usttrace}, the early tracing is always active, which means
-that the tracing is guaranteed to be started by the time the process enters its
-main() function.
-
-Several @command{usttrace}'s may be run simultaneously without risk of
-conflict. This facilitates the use of the tracer by idependent users on a
-system. Each instance of @command{usttrace} starts its own daemon which
-collects the events of the processes it creates.
-
-...@node Setting up the recording manually
-...@section Setting up the recording manually
-
-Instead of using @command{usttrace}, a trace may be recorded on an already
-running process.
-
-First the daemon must be started.
-
-...@example
-...@verbatim
-# Make sure the directory for the communication sockets exists.
-$ mkdir /tmp/ustsocks
-
-# Make sure the directory where ustd will write the trace exists.
-$ mkdir /tmp/trace
-
-# Start the daemon
-$ ustd
-
-# We assume the program we want to trace is already running and that
-# it has pid 1234.
-
-# List the available markers
-$ ustctl --list-markers 1234
-# A column indicates 0 for an inactive marker and 1 for an active marker.
-
-# Enable a marker
-$ ustctl --enable-marker ust/mymark 1234
-
-# Create a trace
-$ ustctl --create-trace 1234
-
-# Start tracing
-$ ustctl --start-trace 1234
-
-# Do things...
-
-# Stop tracing
-$ ustctl --stop-trace 1234
-
-# Destroy the trace
-$ ustctl --destroy-trace 1234
-...@end verbatim
-...@end example
-
-...@node Using early tracing
-...@section Using early tracing
-
-Early tracing consists in starting the tracing as early as possible in the
-program, so no events are lost between program start and the point where the
-command to start the tracing is given. When using early tracing, it is
-guaranteed that by the time the traced program enters its @code{main()}
-function, the tracing will be started.
-
-When using @command{usttrace}, the early tracing is always active.
-
-When using the manual mode (@command{ustctl}), early tracing is enabled using
-environment variables. Setting @env{UST_TRACE} to @code{1}, enables early
-tracing, while setting @env{UST_AUTOPROBE} to @code{1} enables all markers
-automatically.
-
-
-...@node Crash recovery
-...@section Crash recovery
-
-When a process being traced crashes, the daemon is able to recover all the
-events in its buffers that were successfully commited. This is possible because
-the buffers are in a shared memory segment which remains available to the
-daemon even after the termination of the traced process.
-
-...@node Tracing across @code{fork()} and @code{clone()}
-...@section Tracing across @code{fork()} and @code{clone()}
-
-Tracing across @code{clone()} when the @code{CLONE_VM} flag is specified is
-supported without any particular action.
-
-When @code{clone()} is called without @code{CLONE_VM} or @code{fork()} is
-called, a new address space is created and the tracer must be notified to
-create new buffers for it.
-
-This can be done automatically, by @env{LD_PRELOAD}'ing @file{libinterfork.so}.
-This library intercepts calls to @code{fork()} and informs the tracer it is
-being called. When using @command{usttrace}, this is accomplied by specifying
-the @option{-f} command line argument.
-
-Alternatively, the program can call @code{ust_before_fork()} before calling
-...@code{fork()} or @code{clone()} with @code{CLONE_VM}. After the call,
-...@code{ust_after_fork_parent()} must be called in the parent process and
-...@code{ust_after_fork_child()} must be called in the child process.
-
-
-...@node Tracing programs and libraries that were not linked to libust
-...@section Tracing programs and libraries that were not linked to libust
-
-Some programs need to be traced even though they were not linked to libust
-either because they were not instrumented or because it was not practical.
-
-An executable that is not instrumented can still yield interesting traces when
-at least one of its dynamic libraries is instrumented. It is also possible to
-trace certain function calls by intercepting them with a specially crafted
-library that is linked with @env{LD_PRELOAD} at program start.
-
-In any case, a program that was not linked to libust at compile time must be
-linked to it at run time with @env{LD_PRELOAD}. This can be accomplished with
-...@command{usttrace}'s @option{-l} option. It can also be done by setting the
-...@env{ld_preload} environment variable on the command line. For example:
-
-...@example
-...@verbatim
-# Run ls with usttrace, LD_PRELOAD'ing libust
-# (assuming one of the libraries used by ls is instrumented).
-$ usttrace -l ls
-
-# Run ls, manually adding the LD_PRELOAD.
-$ LD_PRELOAD=/usr/local/lib/libust.so.0 ls
-...@end verbatim
-...@end example
-
-
-...@node Performance
-...@chapter Performance
-
-Todo.
-
-...@node Viewing traces
-...@chapter Viewing traces
-
-Traces may be viewed with LTTV. An example of command for launching LTTV is
-given in the quickstart.
-
-...@menu
-* Viewing multiple traces::
-* Combined kernel-userspace tracing::
-...@end menu
-
-...@node Viewing multiple traces
-...@section Viewing multiple traces
-
-When tracing multi-process applications or several applications simultaneously,
-more than one trace will be obtained. LTTV can open and display all these
-traces simultaneously.
-
-...@node Combined kernel-userspace tracing
-...@section Combined kernel-userspace tracing
-
-In addition to multiple userspace traces, LTTV can open a kernel trace recorded
-with the LTTng kernel tracer. This provides events that enable the rendering of
-the Control Flow View and the Resource View.
-
-When doing so, it is necessary to use the same time source for the kernel
-tracer as well as the userspace tracer. Currently, the recommended method is to
-use the timestamp counter for both. The TSC can however only be used on architectures
-where it is synchronized across cores.
-
-...@bye
diff --git a/doc/manual/ust.texi b/doc/manual/ust.texi
new file mode 100644
index 0000000..1c6ea0c
--- /dev/null
+++ b/doc/manual/ust.texi
@@ -0,0 +1,535 @@
+\input texinfo @c -*-texinfo-*-
+...@c %**start of header
+...@setfilename ust.info
+...@settitle LTTng Userspace Tracer (UST) Manual
+...@c %**end of header
+
+...@dircategory Programming & development tools
+...@direntry
+* UST: (ust). LTTng Userspace Tracer (UST) Manual
+...@end direntry
+
+...@copying
+This manual is for program, version version.
+
+Copyright @copyright{} copyright-owner.
+
+...@quotation
+Permission is granted to ...
+...@end quotation
+...@end copying
+
+...@titlepage
+...@title LTTng Userspace Tracer (UST) Manual
+...@c @subtitle subtitle-if-any
+...@c @subtitle second-subtitle
+...@c @author author
+
+...@c The following two commands
+...@c start the copyright page.
+...@c @page
+...@c @vskip 0pt plus 1filll
+...@c @insertcopying
+
+...@c Published by ...
+...@end titlepage
+
+...@c So the toc is printed at the start.
+...@contents
+
+...@ifnottex
+...@node Top
+...@top LTTng Userspace Tracer
+
+This manual is for UST 0.1.
+...@end ifnottex
+
+...@menu
+* Overview::
+* Installation::
+* Quick start::
+* Instrumenting an application::
+* Recording a trace::
+* Viewing traces::
+* Performance::
+...@c * Copying:: Your rights and freedoms.
+...@end menu
+
+...@node Overview
+...@chapter Overview
+
+...@menu
+* What is UST?::
+* License::
+* Supported platforms::
+...@end menu
+
+...@node What is UST?
+...@section What is UST?
+
+The LTTng Userspace Tracer (UST) is a library accompanied by a set of tools to
+trace userspace code.
+
+Code may be instrumented with either markers or tracepoints. A highly efficient
+lockless tracer records these events to a trace buffers. These buffers are reaped
+by a deamon which writes trace data to disk.
+
+High performance is achieved by the use of lockless buffering algorithms, RCU and
+per-cpu buffers. In addition, special care is taken to minize cache impact.
+
+...@node License
+...@section License
+The LTTng Userspace Tracer is intended to be linkable to open source software
+as well as to proprietary applications. This was accomplished by licensing
+the code that needs to be linked to the traced program as @acronym{LGPL}.
+
+Components licensed as LGPL v2.1:
+...@itemize @bullet
+...@item libust
+...@item libinterfork
+...@item libustcomm
+...@end itemize
+
+Components licensed as GPL v2:
+...@itemize @bullet
+...@item ustctl
+...@item libustcmd
+...@item ustd
+...@end itemize
+
+...@node Supported platforms
+...@section Supported platforms
+
+UST can currently trace applications running on Linux, on the x86-32 and x86-64 architectures.
+
+...@node Installation
+...@chapter Installation
+
+The LTTng userspace tracer is a library and a set of userspace tools.
+
+The following packages are required:
+
+...@itemize @bullet
+...@item
+ust
+
+This contains the tracing library, the ustd daemon, trace control tools
+and other helper tools.
+
+Repository: http://git.dorsal.polymtl.ca
+
+...@item
+libkcompat
+
+This is a library that contains a userspace port of some kernel APIs.
+
+Repository: http://git.dorsal.polymtl.ca
+
+...@item
+liburcu
+
+This is the userspace read-copy update library by Mathieu Desnoyers.
+
+Available in Debian as package liburcu-dev.
+
+Home page: http://lttng.org/?q=node/18
+
+...@item
+LTTV
+
+LTTV is a graphical (and text) viewer for LTTng traces.
+
+Home page: http://lttng.org
+
+...@end itemize
+
+Libkcompat and liburcu should be installed first. UST may then be compiled
+and installed. LTTV has no dependency on the other packages; it may therefore
+be installed on a system which does not have UST installed.
+
+Refer to the README in each of these packages for installation instructions.
+
+...@c @menu
+...@c @end menu
+
+...@node Quick start
+...@chapter Quick start
+
+First, instrument a program with a marker.
+
+...@example
+...@verbatim
+
+#include <ust/marker.h>
+
+int main(int argc, char **argv)
+{
+ int v;
+ char *st;
+
+ /* ... set values of v and st ... */
+
+ /* a marker: */
+ trace_mark(ust, myevent, "firstarg %d secondarg %s", v, st);
+
+ /* a marker without arguments: */
+ trace_mark(ust, myotherevent, MARK_NOARGS);
+
+ return 0;
+}
+
+...@end verbatim
+...@end example
+
+Then compile it in the regular way, linking it with libust. For example:
+
+...@example
+gcc -o foo -lust foo.c
+...@end example
+
+Run the program with @command{usttrace}. The @command{usttrace} output says where the trace
+was written.
+
+...@example
+usttrace ./foo
+...@end example
+
+Finally, open the trace in LTTV.
+
+...@example
+lttv-gui -t /path/to/trace
+...@end example
+
+The trace can also be dumped as text in the console:
+
+...@example
+lttv -m textDump -t /path/to/trace
+...@end example
+
+...@node Instrumenting an application
+...@chapter Instrumenting an application
+
+In order to record a trace of events occurring in a application, the
+application must be instrumented. Instrumentation points resemble function
+calls. When the program reaches an instrumentation point, an event is
+generated.
+
+There are no limitations on the type of code that may be instrumented.
+Multi-threaded programs may be instrumented without problem. Signal handlers
+may be instrumented as well.
+
+There are two APIs to instrument programs: markers and tracepoints. Markers are
+quick to add and are usually used for temporary instrumentation. Tracepoints
+provide a way to instrument code more cleanly and are suited for permanent
+instrumentation.
+
+In addition to executable programs, shared libraries may also be instrumented
+with the methods described in this chapter.
+
+...@menu
+* Markers::
+* Tracepoints::
+...@end menu
+
+...@node Markers
+...@section Markers
+
+Adding a marker is simply a matter of inserting one line in the program.
+
+...@example
+...@verbatim
+#include <ust/marker.h>
+
+int main(int argc, char **argv)
+{
+ int v;
+ char *st;
+
+ /* ... set values of v and st ... */
+
+ /* a marker: */
+ trace_mark(main, myevent, "firstarg %d secondarg %s", v, st);
+
+ /* another marker without arguments: */
+ trace_mark(main, myotherevent, MARK_NOARGS);
+
+ return 0;
+}
+...@end verbatim
+...@end example
+
+The invocation of the trace_mark() macro requires at least 3 arguments. The
+first, here "main", is the name of the event category. It is also the name of
+the channel the event will go in. The second, here "myevent" is the name of the
+event. The third is a format string that announces the names and the types of
+the event arguments. Its format resembles that of a printf() format string; it
+is described thoroughly in Appendix x.
+
+A given Marker may appear more than once in the same program. Other Markers may
+have the same name and a different format string, although this might induce
+some confusion at analysis time.
+
+...@node Tracepoints
+...@section Tracepoints
+
+The Tracepoints API uses the Markers, but provides a higher-level abstraction.
+Whereas the markers API provides limited type checking, the Tracepoints API
+provides more thorough type checking and discharges from the need to insert
+format strings directly in the code and to have format strings appear more than
+once if a given marker is reused.
+
+...@quotation Note Although this example uses @emph{mychannel} as the channel, the
+only channel name currently supported with early tracing is @strong{ust}. The
+...@command{usttrace} tool always uses the early tracing mode. When using manual
+mode without early tracing, any channel name may be used. @end quotation
+
+A function instrumented with a tracepoint looks like this:
+
+...@example
+...@verbatim
+#include "tp.h"
+
+void function()
+{
+ int v;
+ char *st;
+
+ /* ... set values of v and st ... */
+
+ /* a tracepoint: */
+ trace_mychannel_myevent(v, st);
+}
+...@end verbatim
+...@end example
+
+Another file, here tp.h, contains declarations for the tracepoint.
+
+...@example
+...@verbatim
+#include <ust/tracepoint.h>
+
+DECLARE_TRACE(mychannel_myevent, TP_PROTO(int v, char *st),
+ TP_ARGS(v, st));
+...@end verbatim
+...@end example
+
+A third file, here tp.c, contains definitions for the tracepoint.
+
+...@example
+...@verbatim
+#include <ust/marker.h>
+#include "tp.h"
+
+DEFINE_TRACE(mychannel_myevent);
+
+void mychannel_myevent_probe(int v, char *st)
+{
+ trace_mark(mychannel, myevent, "v %d st %s", v, st);
+}
+
+static void __attribute__((constructor)) init()
+{
+ register_trace_mychannel_myevent(mychannel_myevent_probe);
+}
+...@end verbatim
+...@end example
+
+Here, tp.h and tp.c could contain declarations and definitions for other
+tracepoints. The constructor would contain other register_* calls.
+
+...@node Recording a trace
+...@chapter Recording a trace
+
+...@menu
+* Using @command{usttrace}::
+* Setting up the recording manually::
+* Using early tracing::
+* Crash recovery::
+* Tracing across @code{fork()} and @code{clone()}::
+* Tracing programs and libraries that were not linked to libust::
+...@end menu
+
+...@node Using @command{usttrace}
+...@section Using @command{usttrace}
+
+The simplest way to record a trace is to use the @command{usttrace} script. An
+example is given in the quickstart above.
+
+The @command{usttrace} script automatically:
+...@itemize @bullet
+...@item creates a daemon
+...@item enables all markers
+...@item runs the command specified on the command line
+...@item after the command ends, prints the location where the trace was saved
+...@end itemize
+
+Each subdirectory of the save location contains the trace of one process that
+was generated by the command. The name of a subdirectory consists in the the PID
+of the process, followed by the timestamp of its creation.
+
+The save location also contains logs of the tracing.
+
+When using @command{usttrace}, the early tracing is always active, which means
+that the tracing is guaranteed to be started by the time the process enters its
+main() function.
+
+Several @command{usttrace}'s may be run simultaneously without risk of
+conflict. This facilitates the use of the tracer by idependent users on a
+system. Each instance of @command{usttrace} starts its own daemon which
+collects the events of the processes it creates.
+
+...@node Setting up the recording manually
+...@section Setting up the recording manually
+
+Instead of using @command{usttrace}, a trace may be recorded on an already
+running process.
+
+First the daemon must be started.
+
+...@example
+...@verbatim
+# Make sure the directory for the communication sockets exists.
+$ mkdir /tmp/ustsocks
+
+# Make sure the directory where ustd will write the trace exists.
+$ mkdir /tmp/trace
+
+# Start the daemon
+$ ustd
+
+# We assume the program we want to trace is already running and that
+# it has pid 1234.
+
+# List the available markers
+$ ustctl --list-markers 1234
+# A column indicates 0 for an inactive marker and 1 for an active marker.
+
+# Enable a marker
+$ ustctl --enable-marker ust/mymark 1234
+
+# Create a trace
+$ ustctl --create-trace 1234
+
+# Start tracing
+$ ustctl --start-trace 1234
+
+# Do things...
+
+# Stop tracing
+$ ustctl --stop-trace 1234
+
+# Destroy the trace
+$ ustctl --destroy-trace 1234
+...@end verbatim
+...@end example
+
+...@node Using early tracing
+...@section Using early tracing
+
+Early tracing consists in starting the tracing as early as possible in the
+program, so no events are lost between program start and the point where the
+command to start the tracing is given. When using early tracing, it is
+guaranteed that by the time the traced program enters its @code{main()}
+function, the tracing will be started.
+
+When using @command{usttrace}, the early tracing is always active.
+
+When using the manual mode (@command{ustctl}), early tracing is enabled using
+environment variables. Setting @env{UST_TRACE} to @code{1}, enables early
+tracing, while setting @env{UST_AUTOPROBE} to @code{1} enables all markers
+automatically.
+
+
+...@node Crash recovery
+...@section Crash recovery
+
+When a process being traced crashes, the daemon is able to recover all the
+events in its buffers that were successfully commited. This is possible because
+the buffers are in a shared memory segment which remains available to the
+daemon even after the termination of the traced process.
+
+...@node Tracing across @code{fork()} and @code{clone()}
+...@section Tracing across @code{fork()} and @code{clone()}
+
+Tracing across @code{clone()} when the @code{CLONE_VM} flag is specified is
+supported without any particular action.
+
+When @code{clone()} is called without @code{CLONE_VM} or @code{fork()} is
+called, a new address space is created and the tracer must be notified to
+create new buffers for it.
+
+This can be done automatically, by @env{LD_PRELOAD}'ing @file{libinterfork.so}.
+This library intercepts calls to @code{fork()} and informs the tracer it is
+being called. When using @command{usttrace}, this is accomplied by specifying
+the @option{-f} command line argument.
+
+Alternatively, the program can call @code{ust_before_fork()} before calling
+...@code{fork()} or @code{clone()} with @code{CLONE_VM}. After the call,
+...@code{ust_after_fork_parent()} must be called in the parent process and
+...@code{ust_after_fork_child()} must be called in the child process.
+
+
+...@node Tracing programs and libraries that were not linked to libust
+...@section Tracing programs and libraries that were not linked to libust
+
+Some programs need to be traced even though they were not linked to libust
+either because they were not instrumented or because it was not practical.
+
+An executable that is not instrumented can still yield interesting traces when
+at least one of its dynamic libraries is instrumented. It is also possible to
+trace certain function calls by intercepting them with a specially crafted
+library that is linked with @env{LD_PRELOAD} at program start.
+
+In any case, a program that was not linked to libust at compile time must be
+linked to it at run time with @env{LD_PRELOAD}. This can be accomplished with
+...@command{usttrace}'s @option{-l} option. It can also be done by setting the
+...@env{ld_preload} environment variable on the command line. For example:
+
+...@example
+...@verbatim
+# Run ls with usttrace, LD_PRELOAD'ing libust
+# (assuming one of the libraries used by ls is instrumented).
+$ usttrace -l ls
+
+# Run ls, manually adding the LD_PRELOAD.
+$ LD_PRELOAD=/usr/local/lib/libust.so.0 ls
+...@end verbatim
+...@end example
+
+
+...@node Performance
+...@chapter Performance
+
+Todo.
+
+...@node Viewing traces
+...@chapter Viewing traces
+
+Traces may be viewed with LTTV. An example of command for launching LTTV is
+given in the quickstart.
+
+...@menu
+* Viewing multiple traces::
+* Combined kernel-userspace tracing::
+...@end menu
+
+...@node Viewing multiple traces
+...@section Viewing multiple traces
+
+When tracing multi-process applications or several applications simultaneously,
+more than one trace will be obtained. LTTV can open and display all these
+traces simultaneously.
+
+...@node Combined kernel-userspace tracing
+...@section Combined kernel-userspace tracing
+
+In addition to multiple userspace traces, LTTV can open a kernel trace recorded
+with the LTTng kernel tracer. This provides events that enable the rendering of
+the Control Flow View and the Resource View.
+
+When doing so, it is necessary to use the same time source for the kernel
+tracer as well as the userspace tracer. Currently, the recommended method is to
+use the timestamp counter for both. The TSC can however only be used on architectures
+where it is synchronized across cores.
+
+...@bye
--
1.7.1
>From 9bbb801dd224d21679f93f0d7dae6ad3a8a93fae Mon Sep 17 00:00:00 2001
From: Kerstin Jonsson <[email protected]>
Date: Thu, 20 May 2010 16:00:52 +0200
Subject: [PATCH 4/6] Added ust/clock.h to Makefile.am to enable make distcheck target'
---
include/Makefile.am | 1 +
1 files changed, 1 insertions(+), 0 deletions(-)
diff --git a/include/Makefile.am b/include/Makefile.am
index eba0fe5..15ed898 100644
--- a/include/Makefile.am
+++ b/include/Makefile.am
@@ -8,6 +8,7 @@ nobase_include_HEADERS = \
ust/tracectl.h \
ust/core.h \
ust/type-serializer.h \
+ ust/clock.h \
ust/kcompat/kcompat.h \
ust/kcompat/compiler.h \
ust/kcompat/disable.h \
--
1.7.1
>From 0c77b340f8661999e73cbcfd0c7fdf8008338f27 Mon Sep 17 00:00:00 2001
From: Kerstin Jonsson <[email protected]>
Date: Thu, 20 May 2010 16:02:23 +0200
Subject: [PATCH 5/6] added deb make target
---
Makefile.am | 22 ++++++++++++++++++++++
1 files changed, 22 insertions(+), 0 deletions(-)
diff --git a/Makefile.am b/Makefile.am
index 5a7c03b..8208375 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -22,3 +22,25 @@ libust.so: libust.ldscript.in
# may get obscure errors when linking to shared libraries.
libust-initializer.o: libust-initializer.c
$(CC) $(CFLAGS) -fno-strict-aliasing -fPIC -c -I$(top_srcdir)/include -o $@ $<
+
+deb: distcheck
+ case '$(DIST_ARCHIVES)' in \
+ *.tar.gz*) \
+ GZIP=$(GZIP_ENV) gzip -dc $(distdir).tar.gz | $(am__untar) ;;\
+ *.tar.bz2*) \
+ bzip2 -dc $(distdir).tar.bz2 | $(am__untar) ;;\
+ *.tar.lzma*) \
+ lzma -dc $(distdir).tar.lzma | $(am__untar) ;;\
+ *.tar.xz*) \
+ xz -dc $(distdir).tar.xz | $(am__untar) ;;\
+ *.tar.Z*) \
+ uncompress -c $(distdir).tar.Z | $(am__untar) ;;\
+ *.shar.gz*) \
+ GZIP=$(GZIP_ENV) gzip -dc $(distdir).shar.gz | unshar ;;\
+ *.zip*) \
+ unzip $(distdir).zip ;;\
+ esac
+ cd $(distdir) && echo y | dh_make --copyright gpl2 -s -f ../$(distdir).tar.gz
+ rm -rf $(distdir)/debian
+ cp -r -p debian $(distdir)/.
+ cd $(distdir) && dpkg-buildpackage
--
1.7.1
>From 2f8ce714ba9e4aa0c80980e75c2447be44060a8e Mon Sep 17 00:00:00 2001
From: Kerstin Jonsson <[email protected]>
Date: Thu, 20 May 2010 16:05:13 +0200
Subject: [PATCH 6/6] ignore generated files
---
.gitignore | 10 ++++++++++
1 files changed, 10 insertions(+), 0 deletions(-)
diff --git a/.gitignore b/.gitignore
index d8687e7..5bfe4fd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,3 +22,13 @@ stamp-h1
ustctl/ustctl
ustd/ustd
+m4/
+libtool
+ustctl/ustctl
+ustd/ustd
+*info
+*html
+*.deb
+*.dsc
+*.changes
+*.tar.gz
--
1.7.1
_______________________________________________
ltt-dev mailing list
[email protected]
http://lists.casi.polymtl.ca/cgi-bin/mailman/listinfo/ltt-dev
