From 641c659aa0558ea68008e96c64abe9629d540ae7 Mon Sep 17 00:00:00 2001 From: Mathieu Desnoyers Date: Thu, 12 Dec 2013 07:29:26 -0500 Subject: [PATCH] Implement tracef() instrumentation API Signed-off-by: Mathieu Desnoyers --- .gitignore | 1 + doc/examples/Makefile.am | 2 +- doc/examples/demo-tracef/Makefile | 35 ++++++++++++++++++ doc/examples/demo-tracef/README | 20 ++++++++++ doc/examples/demo-tracef/demo-tracef.c | 47 ++++++++++++++++++++++++ doc/man/lttng-ust.3 | 30 ++++++++++++++- include/Makefile.am | 4 +- liblttng-ust/Makefile.am | 4 +- liblttng-ust/lttng-ust-tracef-provider.h | 37 +++++++++++++++++++ liblttng-ust/tracef.c | 46 +++++++++++++++++++++++ 10 files changed, 222 insertions(+), 4 deletions(-) create mode 100644 doc/examples/demo-tracef/Makefile create mode 100644 doc/examples/demo-tracef/README create mode 100644 doc/examples/demo-tracef/demo-tracef.c create mode 100644 liblttng-ust/lttng-ust-tracef-provider.h create mode 100644 liblttng-ust/tracef.c diff --git a/.gitignore b/.gitignore index ce7c5729..b29bf8d3 100644 --- a/.gitignore +++ b/.gitignore @@ -36,6 +36,7 @@ doc/examples/easy-ust/sample 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 diff --git a/doc/examples/Makefile.am b/doc/examples/Makefile.am index 0d341c82..d239458d 100644 --- a/doc/examples/Makefile.am +++ b/doc/examples/Makefile.am @@ -43,7 +43,7 @@ if NO_SHARED # 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 diff --git a/doc/examples/demo-tracef/Makefile b/doc/examples/demo-tracef/Makefile new file mode 100644 index 00000000..644acdce --- /dev/null +++ b/doc/examples/demo-tracef/Makefile @@ -0,0 +1,35 @@ +# Copyright (C) 2013 Jérémie Galarneau +# Copyright (C) 2014 Mathieu Desnoyers +# +# 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 diff --git a/doc/examples/demo-tracef/README b/doc/examples/demo-tracef/README new file mode 100644 index 00000000..af0eadf0 --- /dev/null +++ b/doc/examples/demo-tracef/README @@ -0,0 +1,20 @@ +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" } diff --git a/doc/examples/demo-tracef/demo-tracef.c b/doc/examples/demo-tracef/demo-tracef.c new file mode 100644 index 00000000..9e8b95d7 --- /dev/null +++ b/doc/examples/demo-tracef/demo-tracef.c @@ -0,0 +1,47 @@ +/* + * Copyright (C) 2009 Pierre-Marc Fournier + * Copyright (C) 2011-2014 Mathieu Desnoyers + * + * 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 +#include +#include + +#include + +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; +} diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3 index 2c58fba1..591c1db0 100644 --- a/doc/man/lttng-ust.3 +++ b/doc/man/lttng-ust.3 @@ -17,7 +17,35 @@ port of the low-overhead tracing capabilities of the LTTng kernel tracer to user-space. The library "liblttng-ust" enables tracing of applications and libraries. -.SH "USAGE" +.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 + +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. diff --git a/include/Makefile.am b/include/Makefile.am index 46cc3fd3..b77c1364 100644 --- a/include/Makefile.am +++ b/include/Makefile.am @@ -18,7 +18,9 @@ nobase_include_HEADERS = \ 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. diff --git a/liblttng-ust/Makefile.am b/liblttng-ust/Makefile.am index e9022d8a..569a701a 100644 --- a/liblttng-ust/Makefile.am +++ b/liblttng-ust/Makefile.am @@ -44,7 +44,9 @@ liblttng_ust_runtime_la_SOURCES = \ 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 \ diff --git a/liblttng-ust/lttng-ust-tracef-provider.h b/liblttng-ust/lttng-ust-tracef-provider.h new file mode 100644 index 00000000..b759191d --- /dev/null +++ b/liblttng-ust/lttng-ust-tracef-provider.h @@ -0,0 +1,37 @@ +#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 + * + * 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 + +#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 diff --git a/liblttng-ust/tracef.c b/liblttng-ust/tracef.c new file mode 100644 index 00000000..9ef063ce --- /dev/null +++ b/liblttng-ust/tracef.c @@ -0,0 +1,46 @@ +/* + * Copyright (C) 2013-2014 Mathieu Desnoyers + * + * 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 + +#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); +} -- 2.34.1