From 53f7d0d7404de911dd62dff06f08539e33ea7519 Mon Sep 17 00:00:00 2001 From: Michael Jeanson Date: Thu, 6 Jul 2023 14:40:15 -0400 Subject: [PATCH] doc: implement REUSE with SPDX identifiers The SPDX identifiers [1] are a legally binding shorthand, which can be used instead of the full boiler plate text. This is the first step towards implementing the full REUSE spec [2] to help with copyright and licensing audits and compliance. This will reduce a lot a manual work required for the licensing audit required in Debian on each update. For files that lacked copyright and licensing information, I used the following guidelines. If a clear author could be determined from the git history use it, otherwise use 'EfficiOS Inc.'. For build system files, use 'MIT', for documentation 'CC-BY-4.0' and for data files 'CC0-1.0'. Freeform text files were converted to Markdown to allow licensing comments. [1] https://spdx.org/ids-how [2] https://reuse.software/tutorial/ Change-Id: Idc57357d401c4efac4d0c641108607236fa8ecd4 Signed-off-by: Michael Jeanson Signed-off-by: Mathieu Desnoyers --- doc/Makefile.am | 4 +- doc/examples/Makefile.am | 14 ++-- .../clock-override/{README => README.md} | 10 ++- .../clock-override/run-clock-override | 2 + .../CMakeLists.txt | 2 + .../cmake/FindLTTngUST.cmake | 15 +--- .../cmake-multiple-shared-libraries/trace.sh | 2 + .../demo-tracef/{README => README.md} | 10 +++ .../demo-tracelog/{README => README.md} | 10 +++ doc/examples/demo-tracelog/demo-vtracelog.c | 8 +- doc/examples/demo/{README => README.md} | 6 ++ doc/examples/demo/demo-trace | 2 + doc/examples/gen-tp/sample.c | 10 +-- doc/examples/gen-tp/sample_tracepoint.tp | 5 ++ .../getcpu-override/{README => README.md} | 6 ++ .../getcpu-override/run-getcpu-override | 2 + .../hello-static-lib/{README => README.md} | 6 ++ doc/examples/java-jul/README | 7 -- doc/examples/java-jul/README.md | 13 +++ doc/examples/java-jul/run | 3 + doc/examples/java-log4j/run | 2 + doc/examples/java-log4j2-basic/log4j2.xml | 7 ++ doc/examples/java-log4j2-basic/run | 2 + doc/examples/java-log4j2-ctx/log4j2.ctx1.xml | 7 ++ doc/examples/java-log4j2-ctx/log4j2.ctx2.xml | 7 ++ doc/examples/java-log4j2-ctx/run | 2 + doc/examples/java-log4j2-prog/run | 2 + doc/examples/python/hello.py | 2 + doc/{java-agent.txt => java-agent.md} | 80 +++++++++---------- doc/man/asciidoc.conf | 4 + doc/man/common-authors.txt | 3 + doc/man/common-copyrights.txt | 3 + doc/man/common-footer-author.txt | 3 + doc/man/common-footer.txt | 3 + doc/man/do_tracepoint.3 | 2 + doc/man/log-levels.txt | 3 + doc/man/lttng-gen-tp.1.txt | 3 + doc/man/lttng-ust-cyg-profile.3.txt | 3 + doc/man/lttng-ust-dl.3.txt | 3 + doc/man/lttng-ust.3.txt | 3 + doc/man/lttng_ust_do_tracepoint.3 | 2 + doc/man/lttng_ust_tracef.3.txt | 3 + doc/man/lttng_ust_tracelog.3.txt | 3 + doc/man/lttng_ust_tracepoint.3 | 2 + doc/man/lttng_ust_tracepoint_enabled.3 | 2 + doc/man/manpage.xsl | 7 ++ doc/man/tracef-tracelog-limitations.txt | 3 + doc/man/tracef.3.txt | 3 + doc/man/tracelog.3.txt | 3 + doc/man/tracepoint.3 | 2 + doc/man/tracepoint_enabled.3 | 2 + doc/python-agent.md | 17 ++++ doc/python-agent.txt | 13 --- 53 files changed, 250 insertions(+), 93 deletions(-) rename doc/examples/clock-override/{README => README.md} (60%) rename doc/examples/demo-tracef/{README => README.md} (88%) rename doc/examples/demo-tracelog/{README => README.md} (89%) rename doc/examples/demo/{README => README.md} (95%) rename doc/examples/getcpu-override/{README => README.md} (71%) rename doc/examples/hello-static-lib/{README => README.md} (58%) delete mode 100644 doc/examples/java-jul/README create mode 100644 doc/examples/java-jul/README.md rename doc/{java-agent.txt => java-agent.md} (68%) create mode 100644 doc/python-agent.md delete mode 100644 doc/python-agent.txt diff --git a/doc/Makefile.am b/doc/Makefile.am index 59a4c5b5..7eac79f2 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -8,4 +8,6 @@ if ENABLE_EXAMPLES SUBDIRS += examples endif -dist_doc_DATA = java-agent.txt +dist_doc_DATA = \ + java-agent.md \ + python-agent.md diff --git a/doc/examples/Makefile.am b/doc/examples/Makefile.am index e7010a75..aebf63bd 100644 --- a/doc/examples/Makefile.am +++ b/doc/examples/Makefile.am @@ -20,7 +20,7 @@ dist_doc_examples_java_jul_DATA = java-jul/Makefile \ java-jul/run \ java-jul/ApplicationContextExample.java \ java-jul/FilterChangeListenerExample.java \ - java-jul/README + java-jul/README.md SUBDIRS_JUL = java-jul endif @@ -94,7 +94,7 @@ dist_doc_examples_gen_tp_DATA = gen-tp/Makefile \ 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 \ @@ -104,29 +104,29 @@ dist_doc_examples_demo_DATA = demo/demo.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 \ diff --git a/doc/examples/clock-override/README b/doc/examples/clock-override/README.md similarity index 60% rename from doc/examples/clock-override/README rename to doc/examples/clock-override/README.md index aabbee2a..9f945b91 100644 --- a/doc/examples/clock-override/README +++ b/doc/examples/clock-override/README.md @@ -1,8 +1,14 @@ + + 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. +definition and functions. Thus `LTTNG_UST_CLOCK_PLUGIN` needs to be defined +when launching lttng-sessiond. diff --git a/doc/examples/clock-override/run-clock-override b/doc/examples/clock-override/run-clock-override index 77a484fb..de896ce9 100755 --- a/doc/examples/clock-override/run-clock-override +++ b/doc/examples/clock-override/run-clock-override @@ -1,4 +1,6 @@ #!/bin/sh + +# SPDX-FileCopyrightText: 2023 EfficiOS, Inc # # SPDX-License-Identifier: MIT diff --git a/doc/examples/cmake-multiple-shared-libraries/CMakeLists.txt b/doc/examples/cmake-multiple-shared-libraries/CMakeLists.txt index 8cfc6112..946da8da 100644 --- a/doc/examples/cmake-multiple-shared-libraries/CMakeLists.txt +++ b/doc/examples/cmake-multiple-shared-libraries/CMakeLists.txt @@ -1,3 +1,5 @@ +# SPDX-FileCopyrightText: 2023 EfficiOS, Inc +# # SPDX-License-Identifier: MIT cmake_minimum_required(VERSION 2.8.11) diff --git a/doc/examples/cmake-multiple-shared-libraries/cmake/FindLTTngUST.cmake b/doc/examples/cmake-multiple-shared-libraries/cmake/FindLTTngUST.cmake index a98970c5..859de6a3 100644 --- a/doc/examples/cmake-multiple-shared-libraries/cmake/FindLTTngUST.cmake +++ b/doc/examples/cmake-multiple-shared-libraries/cmake/FindLTTngUST.cmake @@ -29,20 +29,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 # -# 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 # -# 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 diff --git a/doc/examples/cmake-multiple-shared-libraries/trace.sh b/doc/examples/cmake-multiple-shared-libraries/trace.sh index 445d3859..f8fb29eb 100755 --- a/doc/examples/cmake-multiple-shared-libraries/trace.sh +++ b/doc/examples/cmake-multiple-shared-libraries/trace.sh @@ -1,4 +1,6 @@ #!/bin/bash + +# SPDX-FileCopyrightText: 2023 EfficiOS, Inc # # SPDX-License-Identifier: MIT diff --git a/doc/examples/demo-tracef/README b/doc/examples/demo-tracef/README.md similarity index 88% rename from doc/examples/demo-tracef/README rename to doc/examples/demo-tracef/README.md index af0eadf0..bfbefabd 100644 --- a/doc/examples/demo-tracef/README +++ b/doc/examples/demo-tracef/README.md @@ -1,8 +1,15 @@ + + 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 @@ -10,11 +17,14 @@ lttng start 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-tracelog/README b/doc/examples/demo-tracelog/README.md similarity index 89% rename from doc/examples/demo-tracelog/README rename to doc/examples/demo-tracelog/README.md index 83f259e5..730834c9 100644 --- a/doc/examples/demo-tracelog/README +++ b/doc/examples/demo-tracelog/README.md @@ -1,8 +1,15 @@ + + 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 @@ -10,11 +17,14 @@ lttng start 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" } +``` diff --git a/doc/examples/demo-tracelog/demo-vtracelog.c b/doc/examples/demo-tracelog/demo-vtracelog.c index 69e7d5d2..f2181f40 100644 --- a/doc/examples/demo-tracelog/demo-vtracelog.c +++ b/doc/examples/demo-tracelog/demo-vtracelog.c @@ -1,8 +1,6 @@ -/* - * SPDX-License-Identifier: LGPL-2.1-only - * - * Copyright (C) 2020 Mathieu Desnoyers - */ +// SPDX-FileCopyrightText: 2020 Mathieu Desnoyers +// +// SPDX-License-Identifier: LGPL-2.1-only #include #include diff --git a/doc/examples/demo/README b/doc/examples/demo/README.md similarity index 95% rename from doc/examples/demo/README rename to doc/examples/demo/README.md index 03ee4ee1..7c2cefc6 100644 --- a/doc/examples/demo/README +++ b/doc/examples/demo/README.md @@ -1,3 +1,9 @@ + + This is a demo application used to test the LTTng userspace tracer. demo-trace shell script preloads the provider shared objects before diff --git a/doc/examples/demo/demo-trace b/doc/examples/demo/demo-trace index e520e9a6..d7c86267 100755 --- a/doc/examples/demo/demo-trace +++ b/doc/examples/demo/demo-trace @@ -1,4 +1,6 @@ #!/bin/sh + +# SPDX-FileCopyrightText: 2023 EfficiOS, Inc # # SPDX-License-Identifier: MIT diff --git a/doc/examples/gen-tp/sample.c b/doc/examples/gen-tp/sample.c index 52c4a9eb..b0b0388a 100644 --- a/doc/examples/gen-tp/sample.c +++ b/doc/examples/gen-tp/sample.c @@ -1,9 +1,7 @@ -/* - * SPDX-License-Identifier: MIT - * - * Copyright (C) 2011-2012 Matthew Khouzam - * Copyright (C) 2012 Mathieu Desnoyers - */ +// SPDX-FileCopyrightText: 2011-2012 Matthew Khouzam +// SPDX-FileCopyrightText: 2012 Mathieu Desnoyers +// +// SPDX-License-Identifier: MIT #include diff --git a/doc/examples/gen-tp/sample_tracepoint.tp b/doc/examples/gen-tp/sample_tracepoint.tp index 47462415..2f548f6c 100644 --- a/doc/examples/gen-tp/sample_tracepoint.tp +++ b/doc/examples/gen-tp/sample_tracepoint.tp @@ -1,3 +1,8 @@ +// SPDX-FileCopyrightText: 2011-2012 Matthew Khouzam +// SPDX-FileCopyrightText: 2012 Mathieu Desnoyers +// +// SPDX-License-Identifier: MIT + LTTNG_UST_TRACEPOINT_EVENT( sample_tracepoint, message, // C++ Style comment diff --git a/doc/examples/getcpu-override/README b/doc/examples/getcpu-override/README.md similarity index 71% rename from doc/examples/getcpu-override/README rename to doc/examples/getcpu-override/README.md index 05c8e321..9dc19be8 100644 --- a/doc/examples/getcpu-override/README +++ b/doc/examples/getcpu-override/README.md @@ -1,3 +1,9 @@ + + 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 diff --git a/doc/examples/getcpu-override/run-getcpu-override b/doc/examples/getcpu-override/run-getcpu-override index a418fc47..ac6227d7 100755 --- a/doc/examples/getcpu-override/run-getcpu-override +++ b/doc/examples/getcpu-override/run-getcpu-override @@ -1,4 +1,6 @@ #!/bin/sh + +# SPDX-FileCopyrightText: 2023 EfficiOS, Inc # # SPDX-License-Identifier: MIT diff --git a/doc/examples/hello-static-lib/README b/doc/examples/hello-static-lib/README.md similarity index 58% rename from doc/examples/hello-static-lib/README rename to doc/examples/hello-static-lib/README.md index abb056f8..83e7ecf0 100644 --- a/doc/examples/hello-static-lib/README +++ b/doc/examples/hello-static-lib/README.md @@ -1,3 +1,9 @@ + + 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. diff --git a/doc/examples/java-jul/README b/doc/examples/java-jul/README deleted file mode 100644 index d8998b69..00000000 --- a/doc/examples/java-jul/README +++ /dev/null @@ -1,7 +0,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. diff --git a/doc/examples/java-jul/README.md b/doc/examples/java-jul/README.md new file mode 100644 index 00000000..f90b062f --- /dev/null +++ b/doc/examples/java-jul/README.md @@ -0,0 +1,13 @@ + + +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. diff --git a/doc/examples/java-jul/run b/doc/examples/java-jul/run index feaa2362..19a279fc 100755 --- a/doc/examples/java-jul/run +++ b/doc/examples/java-jul/run @@ -1,6 +1,9 @@ #!/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 diff --git a/doc/examples/java-log4j/run b/doc/examples/java-log4j/run index c153e7b8..f03271a9 100755 --- a/doc/examples/java-log4j/run +++ b/doc/examples/java-log4j/run @@ -1,4 +1,6 @@ #!/bin/bash + +# SPDX-FileCopyrightText: 2023 EfficiOS, Inc # # SPDX-License-Identifier: MIT diff --git a/doc/examples/java-log4j2-basic/log4j2.xml b/doc/examples/java-log4j2-basic/log4j2.xml index 6e5fb83e..d73bd193 100644 --- a/doc/examples/java-log4j2-basic/log4j2.xml +++ b/doc/examples/java-log4j2-basic/log4j2.xml @@ -1,4 +1,11 @@ + + + diff --git a/doc/examples/java-log4j2-basic/run b/doc/examples/java-log4j2-basic/run index 4d9f25fb..662c6ef9 100755 --- a/doc/examples/java-log4j2-basic/run +++ b/doc/examples/java-log4j2-basic/run @@ -1,4 +1,6 @@ #!/bin/bash + +# SPDX-FileCopyrightText: 2023 EfficiOS, Inc # # SPDX-License-Identifier: MIT diff --git a/doc/examples/java-log4j2-ctx/log4j2.ctx1.xml b/doc/examples/java-log4j2-ctx/log4j2.ctx1.xml index 5606e452..90855e8c 100644 --- a/doc/examples/java-log4j2-ctx/log4j2.ctx1.xml +++ b/doc/examples/java-log4j2-ctx/log4j2.ctx1.xml @@ -1,4 +1,11 @@ + + + diff --git a/doc/examples/java-log4j2-ctx/log4j2.ctx2.xml b/doc/examples/java-log4j2-ctx/log4j2.ctx2.xml index 003ae105..bb7a0809 100644 --- a/doc/examples/java-log4j2-ctx/log4j2.ctx2.xml +++ b/doc/examples/java-log4j2-ctx/log4j2.ctx2.xml @@ -1,4 +1,11 @@ + + + diff --git a/doc/examples/java-log4j2-ctx/run b/doc/examples/java-log4j2-ctx/run index 5aae3240..cd0c57b8 100755 --- a/doc/examples/java-log4j2-ctx/run +++ b/doc/examples/java-log4j2-ctx/run @@ -1,4 +1,6 @@ #!/bin/bash + +# SPDX-FileCopyrightText: 2023 EfficiOS, Inc # # SPDX-License-Identifier: MIT diff --git a/doc/examples/java-log4j2-prog/run b/doc/examples/java-log4j2-prog/run index 8f4e81dd..4e4244da 100755 --- a/doc/examples/java-log4j2-prog/run +++ b/doc/examples/java-log4j2-prog/run @@ -1,4 +1,6 @@ #!/bin/bash + +# SPDX-FileCopyrightText: 2023 EfficiOS, Inc # # SPDX-License-Identifier: MIT diff --git a/doc/examples/python/hello.py b/doc/examples/python/hello.py index dd96e269..421b5af7 100644 --- a/doc/examples/python/hello.py +++ b/doc/examples/python/hello.py @@ -1,3 +1,5 @@ +# SPDX-FileCopyrightText: 2023 EfficiOS, Inc +# # SPDX-License-Identifier: MIT import lttngust diff --git a/doc/java-agent.txt b/doc/java-agent.md similarity index 68% rename from doc/java-agent.txt rename to doc/java-agent.md index a7612a68..dabddf0a 100644 --- a/doc/java-agent.txt +++ b/doc/java-agent.md @@ -1,27 +1,33 @@ -====================== - Using the Java agent -====================== + + +# Using the Java agent The agent can be built in three different configurations: 1) Java agent with JUL support: -$ ./configure --enable-java-agent-jul + $ ./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 + $ 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 + $ 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 + $ 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. @@ -29,44 +35,41 @@ 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. +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 +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. +`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, +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-*/". +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 -============== +# Object model The object model of the Java agent implementation is as follows: ---------- -Ownership ---------- +## Ownership + Log Handlers: LttngLogHandler, LttngLogAppender n handlers/appenders, managed by the application. Can be created programmatically, or via a configuration file, @@ -78,16 +81,14 @@ Agent singletons: LttngJulAgent, LttngLog4jAgent 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 -------- +## 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 ---------- +## Data path + Log messages are generated by the application and sent to the Logger objects, which then send them to the Handlers. @@ -98,9 +99,8 @@ 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 ------------------------ +## Filtering notifications + FilterChangeNotifier is the singleton notifier class. Applications implement an IFilterChangeListener, and register it to the notifier. diff --git a/doc/man/asciidoc.conf b/doc/man/asciidoc.conf index b3c8709d..a2f41b2c 100644 --- a/doc/man/asciidoc.conf +++ b/doc/man/asciidoc.conf @@ -1,3 +1,7 @@ +# SPDX-FileCopyrightText: 2016 Philippe Proulx +# +# SPDX-License-Identifier: CC-BY-4.0 + [macros] # man macro diff --git a/doc/man/common-authors.txt b/doc/man/common-authors.txt index fe1ccb09..0fb90858 100644 --- a/doc/man/common-authors.txt +++ b/doc/man/common-authors.txt @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: 2016 Philippe Proulx +// SPDX-License-Identifier: CC-BY-4.0 +// AUTHORS ------- LTTng-UST was originally written by Mathieu Desnoyers, with additional diff --git a/doc/man/common-copyrights.txt b/doc/man/common-copyrights.txt index 0203fb86..5e436e57 100644 --- a/doc/man/common-copyrights.txt +++ b/doc/man/common-copyrights.txt @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: 2016 Philippe Proulx +// SPDX-License-Identifier: CC-BY-4.0 +// COPYRIGHTS ---------- This {object-type} is part of the LTTng-UST project. diff --git a/doc/man/common-footer-author.txt b/doc/man/common-footer-author.txt index b98be71e..c251c7ff 100644 --- a/doc/man/common-footer-author.txt +++ b/doc/man/common-footer-author.txt @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: 2016 Philippe Proulx +// SPDX-License-Identifier: CC-BY-4.0 +// include::common-footer.txt[] diff --git a/doc/man/common-footer.txt b/doc/man/common-footer.txt index 2d78c589..6f1848e3 100644 --- a/doc/man/common-footer.txt +++ b/doc/man/common-footer.txt @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: 2016 Philippe Proulx +// SPDX-License-Identifier: CC-BY-4.0 +// BUGS ---- If you encounter any issue or usability problem, please report it on the diff --git a/doc/man/do_tracepoint.3 b/doc/man/do_tracepoint.3 index afb50be9..04749703 100644 --- a/doc/man/do_tracepoint.3 +++ b/doc/man/do_tracepoint.3 @@ -1 +1,3 @@ +.\" SPDX-FileCopyrightText: 2016 Philippe Proulx +.\" SPDX-License-Identifier: CC-BY-4.0 .so man3/lttng-ust.3 diff --git a/doc/man/log-levels.txt b/doc/man/log-levels.txt index 392c6cb4..c83e6692 100644 --- a/doc/man/log-levels.txt +++ b/doc/man/log-levels.txt @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: 2016 Philippe Proulx +// SPDX-License-Identifier: CC-BY-4.0 +// `LTTNG_UST_TRACEPOINT_LOGLEVEL_EMERG`:: System is unusable. diff --git a/doc/man/lttng-gen-tp.1.txt b/doc/man/lttng-gen-tp.1.txt index 969a1e31..41284c7e 100644 --- a/doc/man/lttng-gen-tp.1.txt +++ b/doc/man/lttng-gen-tp.1.txt @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: 2016 Philippe Proulx +// SPDX-License-Identifier: CC-BY-4.0 +// lttng-gen-tp(1) =============== :object-type: program diff --git a/doc/man/lttng-ust-cyg-profile.3.txt b/doc/man/lttng-ust-cyg-profile.3.txt index 73aac26c..51d03e4a 100644 --- a/doc/man/lttng-ust-cyg-profile.3.txt +++ b/doc/man/lttng-ust-cyg-profile.3.txt @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: 2016 Philippe Proulx +// SPDX-License-Identifier: CC-BY-4.0 +// lttng-ust-cyg-profile(3) ======================== :object-type: library diff --git a/doc/man/lttng-ust-dl.3.txt b/doc/man/lttng-ust-dl.3.txt index 4654ca57..c5971b92 100644 --- a/doc/man/lttng-ust-dl.3.txt +++ b/doc/man/lttng-ust-dl.3.txt @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: 2016 Philippe Proulx +// SPDX-License-Identifier: CC-BY-4.0 +// lttng-ust-dl(3) =============== :object-type: library diff --git a/doc/man/lttng-ust.3.txt b/doc/man/lttng-ust.3.txt index 0924a4de..ad1fbbf4 100644 --- a/doc/man/lttng-ust.3.txt +++ b/doc/man/lttng-ust.3.txt @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: 2016 Philippe Proulx +// SPDX-License-Identifier: CC-BY-4.0 +// lttng-ust(3) ============ :object-type: library diff --git a/doc/man/lttng_ust_do_tracepoint.3 b/doc/man/lttng_ust_do_tracepoint.3 index afb50be9..04749703 100644 --- a/doc/man/lttng_ust_do_tracepoint.3 +++ b/doc/man/lttng_ust_do_tracepoint.3 @@ -1 +1,3 @@ +.\" SPDX-FileCopyrightText: 2016 Philippe Proulx +.\" SPDX-License-Identifier: CC-BY-4.0 .so man3/lttng-ust.3 diff --git a/doc/man/lttng_ust_tracef.3.txt b/doc/man/lttng_ust_tracef.3.txt index e103c12a..bb66f8aa 100644 --- a/doc/man/lttng_ust_tracef.3.txt +++ b/doc/man/lttng_ust_tracef.3.txt @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: 2016 Philippe Proulx +// SPDX-License-Identifier: CC-BY-4.0 +// lttng_ust_tracef(3) =================== :object-type: macro diff --git a/doc/man/lttng_ust_tracelog.3.txt b/doc/man/lttng_ust_tracelog.3.txt index 760ac8a4..1108feee 100644 --- a/doc/man/lttng_ust_tracelog.3.txt +++ b/doc/man/lttng_ust_tracelog.3.txt @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: 2016 Philippe Proulx +// SPDX-License-Identifier: CC-BY-4.0 +// lttng_ust_tracelog(3) ===================== :object-type: macro diff --git a/doc/man/lttng_ust_tracepoint.3 b/doc/man/lttng_ust_tracepoint.3 index afb50be9..04749703 100644 --- a/doc/man/lttng_ust_tracepoint.3 +++ b/doc/man/lttng_ust_tracepoint.3 @@ -1 +1,3 @@ +.\" SPDX-FileCopyrightText: 2016 Philippe Proulx +.\" SPDX-License-Identifier: CC-BY-4.0 .so man3/lttng-ust.3 diff --git a/doc/man/lttng_ust_tracepoint_enabled.3 b/doc/man/lttng_ust_tracepoint_enabled.3 index afb50be9..04749703 100644 --- a/doc/man/lttng_ust_tracepoint_enabled.3 +++ b/doc/man/lttng_ust_tracepoint_enabled.3 @@ -1 +1,3 @@ +.\" SPDX-FileCopyrightText: 2016 Philippe Proulx +.\" SPDX-License-Identifier: CC-BY-4.0 .so man3/lttng-ust.3 diff --git a/doc/man/manpage.xsl b/doc/man/manpage.xsl index d576e140..5888967b 100644 --- a/doc/man/manpage.xsl +++ b/doc/man/manpage.xsl @@ -1,4 +1,11 @@ + + + diff --git a/doc/man/tracef-tracelog-limitations.txt b/doc/man/tracef-tracelog-limitations.txt index c5bb6bab..a10eac57 100644 --- a/doc/man/tracef-tracelog-limitations.txt +++ b/doc/man/tracef-tracelog-limitations.txt @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: 2016 Philippe Proulx +// SPDX-License-Identifier: CC-BY-4.0 +// :macro-name: lttng_ust_{macro-suffix} :vmacro-name: lttng_ust_v{macro-suffix} diff --git a/doc/man/tracef.3.txt b/doc/man/tracef.3.txt index 165e7261..7a39e668 100644 --- a/doc/man/tracef.3.txt +++ b/doc/man/tracef.3.txt @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: 2016 Philippe Proulx +// SPDX-License-Identifier: CC-BY-4.0 +// tracef(3) ========= :object-type: macro diff --git a/doc/man/tracelog.3.txt b/doc/man/tracelog.3.txt index 5f1603b9..3c071d37 100644 --- a/doc/man/tracelog.3.txt +++ b/doc/man/tracelog.3.txt @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: 2016 Philippe Proulx +// SPDX-License-Identifier: CC-BY-4.0 +// tracelog(3) =========== :object-type: macro diff --git a/doc/man/tracepoint.3 b/doc/man/tracepoint.3 index afb50be9..04749703 100644 --- a/doc/man/tracepoint.3 +++ b/doc/man/tracepoint.3 @@ -1 +1,3 @@ +.\" SPDX-FileCopyrightText: 2016 Philippe Proulx +.\" SPDX-License-Identifier: CC-BY-4.0 .so man3/lttng-ust.3 diff --git a/doc/man/tracepoint_enabled.3 b/doc/man/tracepoint_enabled.3 index afb50be9..04749703 100644 --- a/doc/man/tracepoint_enabled.3 +++ b/doc/man/tracepoint_enabled.3 @@ -1 +1,3 @@ +.\" SPDX-FileCopyrightText: 2016 Philippe Proulx +.\" SPDX-License-Identifier: CC-BY-4.0 .so man3/lttng-ust.3 diff --git a/doc/python-agent.md b/doc/python-agent.md new file mode 100644 index 00000000..aee63262 --- /dev/null +++ b/doc/python-agent.md @@ -0,0 +1,17 @@ + + +# 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= + $ ./configure --enable-python-agent diff --git a/doc/python-agent.txt b/doc/python-agent.txt deleted file mode 100644 index 61ae4d09..00000000 --- a/doc/python-agent.txt +++ /dev/null @@ -1,13 +0,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= -$ ./configure --enable-python-agent -- 2.34.1