SUBDIRS += examples
endif
-dist_doc_DATA = java-agent.txt
+dist_doc_DATA = \
+ java-agent.md \
+ python-agent.md
java-jul/run \
java-jul/ApplicationContextExample.java \
java-jul/FilterChangeListenerExample.java \
- java-jul/README
+ java-jul/README.md
SUBDIRS_JUL = java-jul
endif
dist_doc_examples_demo_DATA = demo/demo.c \
demo/demo-trace \
demo/Makefile \
- demo/README \
+ demo/README.md \
demo/tp2.c \
demo/tp3.c \
demo/tp.c \
dist_doc_examples_hello_static_lib_DATA = hello-static-lib/Makefile \
hello-static-lib/hello.c \
- hello-static-lib/README \
+ hello-static-lib/README.md \
hello-static-lib/ust_tests_hello.h \
hello-static-lib/tp.c
dist_doc_examples_demo_tracef_DATA = demo-tracef/Makefile \
demo-tracef/demo-tracef.c \
demo-tracef/demo-vtracef.c \
- demo-tracef/README
+ demo-tracef/README.md
dist_doc_examples_demo_tracelog_DATA = demo-tracelog/Makefile \
demo-tracelog/demo-tracelog.c \
demo-tracelog/demo-vtracelog.c \
- demo-tracelog/README
+ demo-tracelog/README.md
dist_doc_examples_clock_override_DATA = clock-override/Makefile \
clock-override/lttng-ust-clock-override-example.c \
clock-override/run-clock-override \
- clock-override/README
+ clock-override/README.md
dist_doc_examples_getcpu_override_DATA = getcpu-override/Makefile \
getcpu-override/lttng-ust-getcpu-override-example.c \
getcpu-override/run-getcpu-override \
- getcpu-override/README
+ getcpu-override/README.md
# Copies are for VPATH build support
SUBDIRS_PROXY = easy-ust demo hello-static-lib demo-tracef clock-override \
+++ /dev/null
-This clock override example shows how to implement and load a clock
-override plugin for LTTng-UST. This can be useful in cases where direct
-hardware access is available for architecture-specific clocks, and where
-it should be used rather than the Linux kernel Monotonic clock.
-
-When using LTTng-tools keep in mind that lttng-sessiond uses lttng-ust's clock
-definition and functions. Thus LTTNG_UST_CLOCK_PLUGIN needs to be defined when
-launching lttng-sessiond.
--- /dev/null
+<!--
+SPDX-FileCopyrightText: 2014 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+This clock override example shows how to implement and load a clock
+override plugin for LTTng-UST. This can be useful in cases where direct
+hardware access is available for architecture-specific clocks, and where
+it should be used rather than the Linux kernel Monotonic clock.
+
+When using LTTng-tools keep in mind that lttng-sessiond uses lttng-ust's clock
+definition and functions. Thus `LTTNG_UST_CLOCK_PLUGIN` needs to be defined
+when launching lttng-sessiond.
#!/bin/sh
+
+# SPDX-FileCopyrightText: 2023 EfficiOS, Inc
#
# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2023 EfficiOS, Inc
+#
# SPDX-License-Identifier: MIT
cmake_minimum_required(VERSION 2.8.11)
# ``TRUE`` if the ``tracef()`` API is available in the system's LTTng-UST
# ``LTTNGUST_HAS_TRACELOG``
# ``TRUE`` if the ``tracelog()`` API is available in the system's LTTng-UST
-
-#=============================================================================
-# Copyright 2016 Kitware, Inc.
-# Copyright 2016 Philippe Proulx <pproulx@efficios.com>
#
-# Distributed under the OSI-approved BSD License (the "License");
-# see accompanying file Copyright.txt for details.
+# SPDX-FileCopyrightText: 2016 Kitware, Inc.
+# SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
#
-# This software is distributed WITHOUT ANY WARRANTY; without even the
-# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-# See the License for more information.
-#=============================================================================
-# (To distribute this file outside of CMake, substitute the full
-# License text for the above reference.)
+# SPDX-License-Identifier: BSD-3-Clause
find_path(LTTNGUST_INCLUDE_DIRS NAMES lttng/tracepoint.h)
# Must also check for the path of generated header files since out-of-tree
#!/bin/bash
+
+# SPDX-FileCopyrightText: 2023 EfficiOS, Inc
#
# SPDX-License-Identifier: MIT
+++ /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
+<!--
+SPDX-FileCopyrightText: 2013 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+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
-This is a demo application showing how to trace logging statements into
-LTTng-UST.
-
-The simplest commands to trace the demo program are:
-
-lttng create
-lttng enable-event -u "lttng_ust_tracelog:*"
-lttng start
-./demo-tracelog
-lttng stop
-lttng view
-lttng destroy
-
-The resulting lttng view output should look like this:
-
-[15:54:19.454863179] (+?.?????????) thinkos lttng_ust_tracelog:TRACE_ERR: { cpu_id = 0 }, { line = 45, file = "demo-tracelog.c", func = "main", _msg_length = 17, msg = "Error condition 0" }
-[15:54:19.454871660] (+0.000008481) thinkos lttng_ust_tracelog:TRACE_ERR: { cpu_id = 0 }, { line = 45, file = "demo-tracelog.c", func = "main", _msg_length = 17, msg = "Error condition 1" }
-[15:54:19.454872838] (+0.000001178) thinkos lttng_ust_tracelog:TRACE_ERR: { cpu_id = 0 }, { line = 45, file = "demo-tracelog.c", func = "main", _msg_length = 17, msg = "Error condition 2" }
-[15:54:19.454873541] (+0.000000703) thinkos lttng_ust_tracelog:TRACE_ERR: { cpu_id = 0 }, { line = 45, file = "demo-tracelog.c", func = "main", _msg_length = 17, msg = "Error condition 3" }
-[15:54:19.454874283] (+0.000000742) thinkos lttng_ust_tracelog:TRACE_ERR: { cpu_id = 0 }, { line = 45, file = "demo-tracelog.c", func = "main", _msg_length = 17, msg = "Error condition 4" }
--- /dev/null
+<!--
+SPDX-FileCopyrightText: 2015 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+This is a demo application showing how to trace logging statements into
+LTTng-UST.
+
+The simplest commands to trace the demo program are:
+
+```
+lttng create
+lttng enable-event -u "lttng_ust_tracelog:*"
+lttng start
+./demo-tracelog
+lttng stop
+lttng view
+lttng destroy
+```
+
+The resulting lttng view output should look like this:
+
+```
+[15:54:19.454863179] (+?.?????????) thinkos lttng_ust_tracelog:TRACE_ERR: { cpu_id = 0 }, { line = 45, file = "demo-tracelog.c", func = "main", _msg_length = 17, msg = "Error condition 0" }
+[15:54:19.454871660] (+0.000008481) thinkos lttng_ust_tracelog:TRACE_ERR: { cpu_id = 0 }, { line = 45, file = "demo-tracelog.c", func = "main", _msg_length = 17, msg = "Error condition 1" }
+[15:54:19.454872838] (+0.000001178) thinkos lttng_ust_tracelog:TRACE_ERR: { cpu_id = 0 }, { line = 45, file = "demo-tracelog.c", func = "main", _msg_length = 17, msg = "Error condition 2" }
+[15:54:19.454873541] (+0.000000703) thinkos lttng_ust_tracelog:TRACE_ERR: { cpu_id = 0 }, { line = 45, file = "demo-tracelog.c", func = "main", _msg_length = 17, msg = "Error condition 3" }
+[15:54:19.454874283] (+0.000000742) thinkos lttng_ust_tracelog:TRACE_ERR: { cpu_id = 0 }, { line = 45, file = "demo-tracelog.c", func = "main", _msg_length = 17, msg = "Error condition 4" }
+```
-/*
- * SPDX-License-Identifier: LGPL-2.1-only
- *
- * Copyright (C) 2020 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
- */
+// SPDX-FileCopyrightText: 2020 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
+//
+// SPDX-License-Identifier: LGPL-2.1-only
#include <stdarg.h>
#include <stdlib.h>
+++ /dev/null
-This is a demo application used to test the LTTng userspace tracer.
-
-demo-trace shell script preloads the provider shared objects before
-executing the demo. Executing "demo" without the shell wrapper will not
-provide any tracing support. This ensures the demo binary can be
-distributed on distros without depending on having liblttng-ust.so in
-place. Note: the "demo" program must be compiled with "-ldl" on Linux,
-with "-lc" on BSD.
-
-The simplest command to trace the demo program are:
-lttng create
-lttng enable-event -u -a
-lttng start
-./demo-trace
-lttng destroy
-
-That will create a trace in your $HOME/lttng-traces directory.
-
-The resulting babeltrace output should look like this:
-[554297567999315] ust_tests_demo:starting: { 1 }, { value = 123 }
-[554297568020834] ust_tests_demo2:loop: { 1 }, { intfield = 0, intfield2 = 0x0, longfield = 0, netintfield = 0, netintfieldhex = 0x0, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4, seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2 }
-[554297568024780] ust_tests_demo2:loop: { 1 }, { intfield = 1, intfield2 = 0x1, longfield = 1, netintfield = 1, netintfieldhex = 0x1, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4, seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2 }
-[554297568027050] ust_tests_demo2:loop: { 1 }, { intfield = 2, intfield2 = 0x2, longfield = 2, netintfield = 2, netintfieldhex = 0x2, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4, seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2 }
-[554297568029014] ust_tests_demo2:loop: { 1 }, { intfield = 3, intfield2 = 0x3, longfield = 3, netintfield = 3, netintfieldhex = 0x3, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4, seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2 }
-[554297568030861] ust_tests_demo2:loop: { 1 }, { intfield = 4, intfield2 = 0x4, longfield = 4, netintfield = 4, netintfieldhex = 0x4, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4, seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2 }
-[554297568033138] ust_tests_demo:done: { 1 }, { value = 456 }
-[554297568034533] ust_tests_demo3:done: { 1 }, { value = 42 }
--- /dev/null
+<!--
+SPDX-FileCopyrightText: 2013 Jérémie Galarneau <jeremie.galarneau@efficios.com>
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+This is a demo application used to test the LTTng userspace tracer.
+
+demo-trace shell script preloads the provider shared objects before
+executing the demo. Executing "demo" without the shell wrapper will not
+provide any tracing support. This ensures the demo binary can be
+distributed on distros without depending on having liblttng-ust.so in
+place. Note: the "demo" program must be compiled with "-ldl" on Linux,
+with "-lc" on BSD.
+
+The simplest command to trace the demo program are:
+lttng create
+lttng enable-event -u -a
+lttng start
+./demo-trace
+lttng destroy
+
+That will create a trace in your $HOME/lttng-traces directory.
+
+The resulting babeltrace output should look like this:
+[554297567999315] ust_tests_demo:starting: { 1 }, { value = 123 }
+[554297568020834] ust_tests_demo2:loop: { 1 }, { intfield = 0, intfield2 = 0x0, longfield = 0, netintfield = 0, netintfieldhex = 0x0, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4, seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2 }
+[554297568024780] ust_tests_demo2:loop: { 1 }, { intfield = 1, intfield2 = 0x1, longfield = 1, netintfield = 1, netintfieldhex = 0x1, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4, seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2 }
+[554297568027050] ust_tests_demo2:loop: { 1 }, { intfield = 2, intfield2 = 0x2, longfield = 2, netintfield = 2, netintfieldhex = 0x2, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4, seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2 }
+[554297568029014] ust_tests_demo2:loop: { 1 }, { intfield = 3, intfield2 = 0x3, longfield = 3, netintfield = 3, netintfieldhex = 0x3, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4, seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2 }
+[554297568030861] ust_tests_demo2:loop: { 1 }, { intfield = 4, intfield2 = 0x4, longfield = 4, netintfield = 4, netintfieldhex = 0x4, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4, seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2 }
+[554297568033138] ust_tests_demo:done: { 1 }, { value = 456 }
+[554297568034533] ust_tests_demo3:done: { 1 }, { value = 42 }
#!/bin/sh
+
+# SPDX-FileCopyrightText: 2023 EfficiOS, Inc
#
# SPDX-License-Identifier: MIT
-/*
- * SPDX-License-Identifier: MIT
- *
- * Copyright (C) 2011-2012 Matthew Khouzam <matthew.khouzam@ericsson.com>
- * Copyright (C) 2012 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
- */
+// SPDX-FileCopyrightText: 2011-2012 Matthew Khouzam <matthew.khouzam@ericsson.com>
+// SPDX-FileCopyrightText: 2012 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
+//
+// SPDX-License-Identifier: MIT
#include <unistd.h>
+// SPDX-FileCopyrightText: 2011-2012 Matthew Khouzam <matthew.khouzam@ericsson.com>
+// SPDX-FileCopyrightText: 2012 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
+//
+// SPDX-License-Identifier: MIT
+
LTTNG_UST_TRACEPOINT_EVENT(
sample_tracepoint,
message, // C++ Style comment
+++ /dev/null
-This getcpu override example shows how to implement and load a getcpu
-override plugin for LTTng-UST. This can be useful in cases where direct
-hardware access is available for architecture-specific registers holding
-the CPU number, and where it should be used rather than the Linux kernel
-sched_getcpu() vDSO/syscall.
--- /dev/null
+<!--
+SPDX-FileCopyrightText: 2014 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+This getcpu override example shows how to implement and load a getcpu
+override plugin for LTTng-UST. This can be useful in cases where direct
+hardware access is available for architecture-specific registers holding
+the CPU number, and where it should be used rather than the Linux kernel
+sched_getcpu() vDSO/syscall.
#!/bin/sh
+
+# SPDX-FileCopyrightText: 2023 EfficiOS, Inc
#
# SPDX-License-Identifier: MIT
+++ /dev/null
-This is a "hello world" application used to verify that an instrumented
-program can be built successfully and linked with tracepoint providers
-built as a separate static library.
--- /dev/null
+<!--
+SPDX-FileCopyrightText: 2013 Jérémie Galarneau <jeremie.galarneau@efficios.com>
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+This is a "hello world" application used to verify that an instrumented
+program can be built successfully and linked with tracepoint providers
+built as a separate static library.
+++ /dev/null
-Type "make" to compile and use "./run" to start the example.
-
-The Hello.java file contains a lot of useful information in order to instrument
-your application.
-
-The "run" file shows you how to link your Java application with the LTTng UST
-JUL library.
--- /dev/null
+<!--
+SPDX-FileCopyrightText: 2013 David Goulet <dgoulet@efficios.com>
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+Type `make` to compile and use `./run` to start the example.
+
+The `Hello.java` file contains a lot of useful information in order to
+instrument your application.
+
+The `./run` file shows you how to link your Java application with the LTTng UST
+JUL library.
#!/bin/bash
+
+# SPDX-FileCopyrightText: 2023 EfficiOS, Inc
#
# SPDX-License-Identifier: MIT
+
#
# The -cp path should be changed to the lttng ust JUL jar file on your system
# or locally to the project. Same goes for the Java library path in order to
#!/bin/bash
+
+# SPDX-FileCopyrightText: 2023 EfficiOS, Inc
#
# SPDX-License-Identifier: MIT
<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+SPDX-FileCopyrightText: 2023 EfficiOS, Inc.
+
+SPDX-License-Identifier: LGPL-2.1-or-later
+-->
+
<Configuration status="WARN">
<Appenders>
<Console name="Console" target="SYSTEM_OUT">
#!/bin/bash
+
+# SPDX-FileCopyrightText: 2023 EfficiOS, Inc
#
# SPDX-License-Identifier: MIT
<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+SPDX-FileCopyrightText: 2023 EfficiOS, Inc.
+
+SPDX-License-Identifier: LGPL-2.1-or-later
+-->
+
<Configuration name="Context1" status="WARN">
<Appenders>
<Console name="Console" target="SYSTEM_OUT">
<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+SPDX-FileCopyrightText: 2023 EfficiOS, Inc.
+
+SPDX-License-Identifier: LGPL-2.1-or-later
+-->
+
<Configuration name="Context2" status="WARN">
<Appenders>
<Console name="Console" target="SYSTEM_OUT">
#!/bin/bash
+
+# SPDX-FileCopyrightText: 2023 EfficiOS, Inc
#
# SPDX-License-Identifier: MIT
#!/bin/bash
+
+# SPDX-FileCopyrightText: 2023 EfficiOS, Inc
#
# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2023 EfficiOS, Inc
+#
# SPDX-License-Identifier: MIT
import lttngust
--- /dev/null
+<!--
+SPDX-FileCopyrightText: 2014 Christian Babeux <christian.babeux@efficios.com>
+SPDX-FileCopyrightText: 2015 Alexandre Montplaisir <alexmonthy@efficios.com>
+SPDX-FileCopyrightText: 2022 Michael Jeanson <mjeanson@efficios.com>
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+# Using the Java agent
+
+The agent can be built in three different configurations:
+
+1) Java agent with JUL support:
+
+ $ ./configure --enable-java-agent-jul
+
+2) Java agent with Log4j 1.x support (deprecated):
+
+ $ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar
+ $ ./configure --enable-java-agent-log4j
+
+3) Java agent with Log4j 2.x support:
+
+ $ export CLASSPATH=$CLASSPATH:/path/to/log4j-core.jar:/path/to/log4j-api.jar
+ $ ./configure --enable-java-agent-log4j2
+
+4) Java agent with JUL + Log4j 1.x + Log4j 2.x support
+
+ $ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar:/path/to/log4j-core.jar:/path/to/log4j-api.jar
+ $ ./configure --enable-java-agent-all
+
+To build the agent with log4j support, make sure that the log4j jar
+is in your Java classpath.
+
+The configure script will automatically detect the appropriate Java
+binaries to use in order to build the Java agent.
+
+Enabling the JUL support will build a `lttng-ust-agent-jul.jar` file. Enabling
+the log4j 1.x support will build a `lttng-ust-agent-log4j.jar` and enabling
+log4j 2.x support will build a `lttng-ust-agent-log4j2.jar`. All of these jars
+depend on a fourth `lttng-ust-agent-common.jar`, which will always be built.
+
+All these archives will be installed in the arch-agnostic `$prefix/share/java`
+path, e.g: `/usr/share/java`. You need to make sure the .jar for the logging
+API you want to use (either `lttng-ust-agent-jul.jar`,
+`lttng-ust-agent-log4j.jar` or `lttng-ust-agent-log4j2.jar`) is on your
+application's classpath.
+
+The logging libraries require an architecture-specific shared object,
+`liblttng-ust-jul-jni.so` for JUL and `liblttng-ust-jul-log4j.so` for both
+Log4j 1.x and 2.x, which are installed by the build system when doing `make
+install`. Make sure that your Java application can find this shared object, by
+using the `java.library.path` property if necessary.
+
+In order to use UST tracing in your Java application, you simply need to
+instantiate a `LttngLogHandler` or a `LttngLogAppender` (for JUL or Log4j,
+respectively), then attach it to a JUL or Log4j Logger class.
+
+Refer to the code examples in `examples/java-jul/`, `examples/java-log4j/` and
+`examples/java-log4j2-*/`.
+
+LTTng session daemon agents will be initialized as needed. If no session daemon
+is available, the execution will continue and the agents will retry connecting
+every 3 seconds.
+
+
+# Object model
+
+The object model of the Java agent implementation is as follows:
+
+## Ownership
+
+Log Handlers: LttngLogHandler, LttngLogAppender
+ n handlers/appenders, managed by the application.
+ Can be created programmatically, or via a configuration file,
+ Each one registers to a specific agent singleton (one per logging API) that is loaded on-demand
+
+Agent singletons: LttngJulAgent, LttngLog4jAgent
+ Keep track of all handlers/appenders registered to them.
+ Are disposed when last handler deregisters.
+ Each agent instantiates 2 TCP clients, one for the root session daemon, one for the user one.
+ One type of TCP client class for now. TCP client may become a singleton in the future.
+
+## Control
+
+Messages come from the session daemon through the socket connection.
+Agent passes back-reference to itself to the TCP clients.
+Clients use this reference to invoke callbacks, which modify the state of the agent (enabling/disabling events, etc.)
+
+## Data path
+
+Log messages are generated by the application and sent to the Logger objects,
+which then send them to the Handlers.
+
+When a log event is received by a Handler (publish(LogRecord)), the handler
+checks with the agent if it should log it or not, via
+ILttngAgent#isEventEnabled() for example.
+
+Events that are logged call the native tracepoint through JNI, which generates
+a UST event. There is one type of tracepoint per domain (Jul or Logj4).
+
+## Filtering notifications
+
+FilterChangeNotifier is the singleton notifier class.
+Applications implement an IFilterChangeListener, and register it to the notifier.
+
+Whenever new event rules are enabled or disabled, the relevant agent informs the
+notifier, which then sends notifications to all registered listeners by invoking
+their callbacks.
+
+Upon registration, a new listener will receive notifications for all currently
+active rules.
+
+The notifier keeps track of its own event rule refcounting, to handle the case
+of multiple sessions or multiple agents enabling identical event rules.
+
+The FilterChangeNotifier does not have threads of its own. The listeners's
+callbacks will be invoked by these threads:
+* In the case of a notification being received while a listener is already
+ registered, the callback is executed by the TCP client's thread. This
+ effectively blocks the "lttng" command line until all callbacks are processed
+ (assuming no timeouts).
+* In the case of a listener registering and receiving the currently-active
+ rules, the callbacks will be executed by the application's thread doing the
+ registerListener() call.
+
+The notifier is entirely synchronized. This ensure that if a rule is enabled
+at the same time a listener is registered, that listener does not miss or
+receive duplicate notifications.
+++ /dev/null
-======================
- Using the Java agent
-======================
-
-The agent can be built in three different configurations:
-
-1) Java agent with JUL support:
-
-$ ./configure --enable-java-agent-jul
-
-2) Java agent with Log4j 1.x support (deprecated):
-
-$ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar
-$ ./configure --enable-java-agent-log4j
-
-3) Java agent with Log4j 2.x support:
-
-$ export CLASSPATH=$CLASSPATH:/path/to/log4j-core.jar:/path/to/log4j-api.jar
-$ ./configure --enable-java-agent-log4j2
-
-4) Java agent with JUL + Log4j 1.x + Log4j 2.x support
-
-$ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar:/path/to/log4j-core.jar:/path/to/log4j-api.jar
-$ ./configure --enable-java-agent-all
-
-To build the agent with log4j support, make sure that the log4j jar
-is in your Java classpath.
-
-The configure script will automatically detect the appropriate Java
-binaries to use in order to build the Java agent.
-
-Enabling the JUL support will build a "lttng-ust-agent-jul.jar" file. Enabling
-the log4j 1.x support will build a "lttng-ust-agent-log4j.jar" and enabling
-log4j 2.x support will build a "lttng-ust-agent-log4j2.jar". All of these jars
-depend on a third "lttng-ust-agent-common.jar", which will always be built.
-
-All these archives will be installed in the arch-agnostic "$prefix/share/java"
-path, e.g: "/usr/share/java". You need to make sure the .jar for the logging
-API you want to use (either "lttng-ust-agent-jul.jar",
-"lttng-ust-agent-log4j.jar" or "lttng-ust-agent-log4j2.jar") is on your
-application's classpath.
-
-The logging libraries require an architecture-specific shared object,
-"liblttng-ust-jul-jni.so" for JUL and "liblttng-ust-jul-log4j.so" for both
-Log4j 1.x and 2.x, which are installed by the build system when doing "make
-install". Make sure that your Java application can find this shared object, by
-using the "java.library.path" property if necessary.
-
-In order to use UST tracing in your Java application, you simply need to
-instantiate a LttngLogHandler or a LttngLogAppender (for JUL or Log4j,
-respectively), then attach it to a JUL or Log4j Logger class.
-
-Refer to the code examples in "examples/java-jul/", "examples/java-log4j/" and
-"examples/java-log4j2-*/".
-
-LTTng session daemon agents will be initialized as needed. If no session daemon
-is available, the execution will continue and the agents will retry connecting
-every 3 seconds.
-
-
-==============
- Object model
-==============
-
-The object model of the Java agent implementation is as follows:
-
----------
-Ownership
----------
-Log Handlers: LttngLogHandler, LttngLogAppender
- n handlers/appenders, managed by the application.
- Can be created programmatically, or via a configuration file,
- Each one registers to a specific agent singleton (one per logging API) that is loaded on-demand
-
-Agent singletons: LttngJulAgent, LttngLog4jAgent
- Keep track of all handlers/appenders registered to them.
- Are disposed when last handler deregisters.
- Each agent instantiates 2 TCP clients, one for the root session daemon, one for the user one.
- One type of TCP client class for now. TCP client may become a singleton in the future.
-
--------
-Control
--------
-Messages come from the session daemon through the socket connection.
-Agent passes back-reference to itself to the TCP clients.
-Clients use this reference to invoke callbacks, which modify the state of the agent (enabling/disabling events, etc.)
-
----------
-Data path
----------
-Log messages are generated by the application and sent to the Logger objects,
-which then send them to the Handlers.
-
-When a log event is received by a Handler (publish(LogRecord)), the handler
-checks with the agent if it should log it or not, via
-ILttngAgent#isEventEnabled() for example.
-
-Events that are logged call the native tracepoint through JNI, which generates
-a UST event. There is one type of tracepoint per domain (Jul or Logj4).
-
------------------------
-Filtering notifications
------------------------
-FilterChangeNotifier is the singleton notifier class.
-Applications implement an IFilterChangeListener, and register it to the notifier.
-
-Whenever new event rules are enabled or disabled, the relevant agent informs the
-notifier, which then sends notifications to all registered listeners by invoking
-their callbacks.
-
-Upon registration, a new listener will receive notifications for all currently
-active rules.
-
-The notifier keeps track of its own event rule refcounting, to handle the case
-of multiple sessions or multiple agents enabling identical event rules.
-
-The FilterChangeNotifier does not have threads of its own. The listeners's
-callbacks will be invoked by these threads:
-* In the case of a notification being received while a listener is already
- registered, the callback is executed by the TCP client's thread. This
- effectively blocks the "lttng" command line until all callbacks are processed
- (assuming no timeouts).
-* In the case of a listener registering and receiving the currently-active
- rules, the callbacks will be executed by the application's thread doing the
- registerListener() call.
-
-The notifier is entirely synchronized. This ensure that if a rule is enabled
-at the same time a listener is registered, that listener does not miss or
-receive duplicate notifications.
+# SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+#
+# SPDX-License-Identifier: CC-BY-4.0
+
[macros]
# man macro
+// SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+// SPDX-License-Identifier: CC-BY-4.0
+//
AUTHORS
-------
LTTng-UST was originally written by Mathieu Desnoyers, with additional
+// SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+// SPDX-License-Identifier: CC-BY-4.0
+//
COPYRIGHTS
----------
This {object-type} is part of the LTTng-UST project.
+// SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+// SPDX-License-Identifier: CC-BY-4.0
+//
include::common-footer.txt[]
+// SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+// SPDX-License-Identifier: CC-BY-4.0
+//
BUGS
----
If you encounter any issue or usability problem, please report it on the
+.\" SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+.\" SPDX-License-Identifier: CC-BY-4.0
.so man3/lttng-ust.3
+// SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+// SPDX-License-Identifier: CC-BY-4.0
+//
`LTTNG_UST_TRACEPOINT_LOGLEVEL_EMERG`::
System is unusable.
+// SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+// SPDX-License-Identifier: CC-BY-4.0
+//
lttng-gen-tp(1)
===============
:object-type: program
+// SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+// SPDX-License-Identifier: CC-BY-4.0
+//
lttng-ust-cyg-profile(3)
========================
:object-type: library
+// SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+// SPDX-License-Identifier: CC-BY-4.0
+//
lttng-ust-dl(3)
===============
:object-type: library
+// SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+// SPDX-License-Identifier: CC-BY-4.0
+//
lttng-ust(3)
============
:object-type: library
+.\" SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+.\" SPDX-License-Identifier: CC-BY-4.0
.so man3/lttng-ust.3
+// SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+// SPDX-License-Identifier: CC-BY-4.0
+//
lttng_ust_tracef(3)
===================
:object-type: macro
+// SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+// SPDX-License-Identifier: CC-BY-4.0
+//
lttng_ust_tracelog(3)
=====================
:object-type: macro
+.\" SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+.\" SPDX-License-Identifier: CC-BY-4.0
.so man3/lttng-ust.3
+.\" SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+.\" SPDX-License-Identifier: CC-BY-4.0
.so man3/lttng-ust.3
<?xml version='1.0'?>
+
+<!--
+SPDX-FileCopyrightText: 2017 Philippe Proulx <pproulx@efficios.com>
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<!-- callouts -->
+// SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+// SPDX-License-Identifier: CC-BY-4.0
+//
:macro-name: lttng_ust_{macro-suffix}
:vmacro-name: lttng_ust_v{macro-suffix}
+// SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+// SPDX-License-Identifier: CC-BY-4.0
+//
tracef(3)
=========
:object-type: macro
+// SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+// SPDX-License-Identifier: CC-BY-4.0
+//
tracelog(3)
===========
:object-type: macro
+.\" SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+.\" SPDX-License-Identifier: CC-BY-4.0
.so man3/lttng-ust.3
+.\" SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+.\" SPDX-License-Identifier: CC-BY-4.0
.so man3/lttng-ust.3
--- /dev/null
+<!--
+SPDX-FileCopyrightText: 2015 Jonathan Rajotte <jonathan.rajotte-julien@efficios.com>
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+# Using the python agent
+
+To build the agent:
+
+ $ ./configure --enable-python-agent
+
+The configure script is set to look for the first python version >= 2.7.
+To build the agent against another version of python:
+
+ $ export PYTHON=<python path>
+ $ ./configure --enable-python-agent
+++ /dev/null
-======================
- Using the python agent
-======================
-
-To build the agent:
-
-$ ./configure --enable-python-agent
-
-The configure script is set to look for the first python version >= 2.7.
-To build the agent against another version of python:
-
-$ export PYTHON=<python path>
-$ ./configure --enable-python-agent
projects / lttng-ust.git / commitdiff
