doc/examples/hello-static-lib/hello
doc/examples/gen-tp/sample
doc/examples/gen-tp/sample_tracepoint.h
+doc/examples/demo-tracef/demo-tracef
tests/hello/hello
tests/hello.cxx/hello
# disabled.
else
# Copies are for VPATH build support
-SUBDIRS_PROXY = easy-ust demo hello-static-lib
+SUBDIRS_PROXY = easy-ust demo hello-static-lib demo-tracef
if BUILD_GEN_TP_EXAMPLES
SUBDIRS_PROXY += gen-tp
--- /dev/null
+# Copyright (C) 2013 Jérémie Galarneau <jeremie.galarneau@efficios.com>
+# Copyright (C) 2014 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
+#
+# THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
+# OR IMPLIED. ANY USE IS AT YOUR OWN RISK.
+#
+# Permission is hereby granted to use or copy this program for any
+# purpose, provided the above notices are retained on all copies.
+# Permission to modify the code and to distribute modified code is
+# granted, provided the above notices are retained, and a notice that
+# the code was modified is included with the above copyright notice.
+#
+# This Makefile is not using automake so that users may see how to build
+# a program with tracepoint provider probes as stand-alone shared objects.
+#
+# This makefile is purposefully kept simple to support GNU and BSD make.
+
+CC = gcc
+LIBS = -ldl -llttng-ust # On Linux
+#LIBS = -lc # On BSD
+LOCAL_CPPFLAGS += -I.
+
+all: demo-tracef
+
+demo-tracef.o: demo-tracef.c
+ $(CC) $(CPPFLAGS) $(LOCAL_CPPFLAGS) $(CFLAGS) $(AM_CPPFLAGS) \
+ $(AM_CFLAGS) -c -o $@ $<
+
+demo-tracef: demo-tracef.o
+ $(CC) $(LDFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(AM_CFLAGS) \
+ -o $@ $< $(LIBS)
+
+.PHONY: clean
+clean:
+ rm -f *.o *.a demo-tracef
--- /dev/null
+This is a demo application showing how to trace formatted strings into
+LTTng-UST.
+
+The simplest command to trace the demo program are:
+
+lttng create
+lttng enable-event -u "lttng_ust_tracef:event"
+lttng start
+./demo-tracef
+lttng stop
+lttng view
+lttng destroy
+
+The resulting lttng view output should look like this:
+
+[07:32:02.021045683] (+?.?????????) thinkos lttng_ust:tracef: { cpu_id = 2 }, { _msg_length = 46, msg = "This is a "mystring test" formatted 0 event 42" }
+[07:32:02.021062328] (+0.000016645) thinkos lttng_ust:tracef: { cpu_id = 2 }, { _msg_length = 46, msg = "This is a "mystring test" formatted 1 event 42" }
+[07:32:02.021066300] (+0.000003972) thinkos lttng_ust:tracef: { cpu_id = 2 }, { _msg_length = 46, msg = "This is a "mystring test" formatted 2 event 42" }
+[07:32:02.021069507] (+0.000003207) thinkos lttng_ust:tracef: { cpu_id = 2 }, { _msg_length = 46, msg = "This is a "mystring test" formatted 3 event 42" }
+[07:32:02.021072541] (+0.000003034) thinkos lttng_ust:tracef: { cpu_id = 2 }, { _msg_length = 46, msg = "This is a "mystring test" formatted 4 event 42" }
--- /dev/null
+/*
+ * Copyright (C) 2009 Pierre-Marc Fournier
+ * Copyright (C) 2011-2014 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; version 2.1 of
+ * the License.
+ *
+ * This library 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
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ */
+
+#include <stdlib.h>
+#include <stdio.h>
+#include <unistd.h>
+
+#include <lttng/tracef.h>
+
+int main(int argc, char **argv)
+{
+ int i;
+ int delay = 0;
+ const char *str = "mystring test";
+ long l = 0x42;
+
+ if (argc == 2)
+ delay = atoi(argv[1]);
+
+ fprintf(stderr, "Demo program starting.\n");
+
+ sleep(delay);
+
+ fprintf(stderr, "Tracing... ");
+ for (i = 0; i < 5; i++) {
+ tracef("This is a \"%s\" formatted %d event %lx",
+ str, i, l);
+ }
+ fprintf(stderr, " done.\n");
+ return 0;
+}
to user-space. The library "liblttng-ust" enables tracing of
applications and libraries.
-.SH "USAGE"
+.SH "USAGE WITH TRACEF"
+.PP
+The simplest way to add instrumentation to your code is by far the
+tracef() API. To you it, in a nutshell:
+
+1) #include <lttng/tracef.h>
+
+2) /* in your code, use like a printf */
+ tracef("my message, this integer %d", 1234);
+
+3) Link your program against liblttng-ust.so.
+
+4) Enable the UST event "lttng_ust_tracef:event" when tracing with the
+ following sequence of commands from lttng-tools:
+
+ lttng create; lttng enable-event -u "lttng_ust_tracef:event"; lttng start
+ [... run your program ...]
+ lttng stop; lttng view
+
+That's it!
+
+If you want to have more flexibility and control on the event names,
+payload typing, etc, you can continue reading on and use the tracepoints
+below. "tracef()" is there for quick and dirty ad hoc instrumentation,
+whereas tracepoint.h is meant for thorough instrumentation of a code
+base to be integrated with an upstream project.
+.PP
+
+.SH "USAGE WITH TRACEPOINT"
.PP
The simple way to generate the lttng-ust tracepoint probes is to use the
lttng-gen-tp(1) tool. See the lttng-gen-tp(1) manpage for explanation.
lttng/ringbuffer-config.h \
lttng/align.h \
lttng/bug.h \
- lttng/ust-error.h
+ lttng/ust-error.h \
+ lttng/tracef.h \
+ lttng/lttng-ust-tracef.h
# note: usterr-signal-safe.h, core.h and share.h need namespace cleanup.
wait.h \
jhash.h \
lttng-ust-uuid.h \
- error.h
+ error.h \
+ tracef.c \
+ lttng-ust-tracef-provider.h
liblttng_ust_support_la_SOURCES = \
lttng-tracer.h \
--- /dev/null
+#undef TRACEPOINT_PROVIDER
+#define TRACEPOINT_PROVIDER lttng_ust_tracef
+
+#if !defined(_TRACEPOINT_LTTNG_UST_TRACEF_PROVIDER_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
+#define _TRACEPOINT_LTTNG_UST_TRACEF_PROVIER_H
+
+/*
+ * Copyright (C) 2011-2014 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#include <lttng/lttng-ust-tracef.h>
+
+#endif /* _TRACEPOINT_LTTNG_UST_TRACEF_PROVIDER_H */
+
+#undef TRACEPOINT_INCLUDE
+#define TRACEPOINT_INCLUDE "./lttng-ust-tracef.h"
+
+/* This part must be outside ifdef protection */
+#include <lttng/tracepoint-event.h>
--- /dev/null
+/*
+ * Copyright (C) 2013-2014 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#define _GNU_SOURCE
+#define _LGPL_SOURCE
+#include <stdio.h>
+
+#define TRACEPOINT_CREATE_PROBES
+#define TRACEPOINT_DEFINE
+#include "lttng-ust-tracef-provider.h"
+
+void _lttng_ust_tracef(const char *fmt, ...)
+{
+ va_list ap;
+ char *msg;
+ int len;
+
+ va_start(ap, fmt);
+ len = vasprintf(&msg, fmt, ap);
+ /* len does not include the final \0 */
+ if (len < 0)
+ goto end;
+ __tracepoint_cb_lttng_ust_tracef___event(msg, len);
+ free(msg);
+end:
+ va_end(ap);
+}
projects / lttng-ust.git / commitdiff
