You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by sw...@apache.org on 2022/10/03 23:57:44 UTC
[logging-log4cxx] branch master updated: Update the main page introduction to log4cxx (#138)
This is an automated email from the ASF dual-hosted git repository.
swebb2066 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
The following commit(s) were added to refs/heads/master by this push:
new 9fae03c3 Update the main page introduction to log4cxx (#138)
9fae03c3 is described below
commit 9fae03c3280ca45040604b557da3ba23f15b1350
Author: Stephen Webb <st...@ieee.org>
AuthorDate: Tue Oct 4 10:57:39 2022 +1100
Update the main page introduction to log4cxx (#138)
* Add a link to performance on the main page introduction to log4cxx
* Add a summary of configuration options on the main introduction page
---
src/site/markdown/index.md | 46 ++++++++++++++++++++++++----------------
src/site/markdown/performance.md | 5 ++++-
2 files changed, 32 insertions(+), 19 deletions(-)
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index 8c0ad45e..7cfd507a 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -22,26 +22,36 @@ which uses [Apache Portable Runtime] for most platform-specific code and should
be usable on any platform supported by APR. Apache Log4cxx is licensed under
the [Apache License], an open source license certified by the [Open Source Initiative].
-Almost every large application includes its own logging or tracing API.
-Inserting log statements into code is a low-tech method for debugging it.
-It may also be the only way because debuggers are not always available or
-applicable. This is usually the case for multithreaded applications and distributed
-applications at large.
-
-Experience indicates that logging is an important component of the development
-cycle. It offers several advantages. It provides precise context about a run of
-the application. Once inserted into the code, the generation of logging output
-requires no human intervention. Moreover, log output can be saved in persistent
-medium to be studied at a later time. In addition to its use in the development
-cycle, a sufficiently rich logging package can also be viewed as an auditing tool.
-
-Logging does have its drawbacks. It can slow down an application. If too verbose,
-it can cause scrolling blindness. To alleviate these concerns, Log4cxx is
-designed to be reliable, fast and extensible. Since logging is rarely the
-main focus of an application, the Log4cxx API strives to be simple to
-understand and to use.
+Experience indicates that almost every large application needs runtime configurable logging.
+Informational, warning and error log messages should be saved
+in persistent medium available for study at a later time.
+
+In the development cycle, logging can be an auditing tool.
+Debugging log output can be activated for an aspect of the application
+simply by modifying a configuration file.
+The correctness of a function should be verified by viewing logged calculated values.
+A faulty piece of code can be isolated by viewing logged function input values
+and the corresponding logged result values.
+These debugging log statements can be removed from the shipped application
+using a compiler build directive.
+Logging statements do increase the (code) size of the application,
+but with log4cxx the speed of the application is not generally affected (see [Performance]).
+
+Logging is useful where debuggers are not, for example:
+- distributed applications
+- multithreaded applications
+- scientific applications (with vector and matrix valued variables)
+- real-time applications
+- event centered (e.g. GUI) applications
+
+For persisted messages, the storage location and the quantity retained
+can be specified and changed using a configuration file.
+The configuration also allows you to control the destination of log messages.
+They can be sent to a file, a remote socket server, event loggers as well as the console,
+with support for directing particular messages to one or more destinations.
[Apache log4j]:https://logging.apache.org/log4j/2.x/
[Apache Portable Runtime]:https://apr.apache.org/
[Apache License]:https://www.apache.org/licenses/
[Open Source Initiative]:https://opensource.org/
+[Performance]:usage.html#performance
\ No newline at end of file
diff --git a/src/site/markdown/performance.md b/src/site/markdown/performance.md
index c56c3bfb..53f44926 100644
--- a/src/site/markdown/performance.md
+++ b/src/site/markdown/performance.md
@@ -63,5 +63,8 @@ values), however the one utilizing fmt is close to 2x as fast.
```
If you wish to benchmark Log4cxx on your own system, have a look at the tools
-under the src/test/cpp/throughput directory. These tests may be built by
+under the src/test/cpp/throughput and src/test/cpp/benchmark directories.
+The throughput tests may be built by
specifying `BUILD_THROUGHPUT` with CMake when building Log4cxx.
+The benckmark tests require the [{google benchmark}](https://github.com/google/benchmark) library
+and may be built by specifying `BUILD_BENCHMARK_CHECKS` with CMake when building Log4cxx.
\ No newline at end of file