[logging-log4cxx] branch next_stable updated: LOGCXX-567 (#170)

[rm...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

rmiddleton pushed a commit to branch next_stable
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git


The following commit(s) were added to refs/heads/next_stable by this push:
     new bffa0d97 LOGCXX-567 (#170)
bffa0d97 is described below

commit bffa0d970d6b609a2312ab6955dea7dbd0eb9414
Author: Robert Middleton <rm...@users.noreply.github.com>
AuthorDate: Fri Dec 30 10:17:09 2022 -0500

    LOGCXX-567 (#170)
    
    Added stacktrace to assert statements and document how to use it.
---
 src/main/include/log4cxx/logger.h               | 21 ++++++++++
 src/site/markdown/1-usage.md                    |  1 +
 src/site/markdown/macros-influencing-log4cxx.md |  1 +
 src/site/markdown/stacktrace.md                 | 51 +++++++++++++++++++++++++
 4 files changed, 74 insertions(+)

diff --git a/src/main/include/log4cxx/logger.h b/src/main/include/log4cxx/logger.h
index 229e44eb..14edd657 100644
--- a/src/main/include/log4cxx/logger.h
+++ b/src/main/include/log4cxx/logger.h
@@ -1957,6 +1957,25 @@ LOG4CXX_LIST_DEF(LoggerList, LoggerPtr);
 	#endif
 #endif
 
+#if defined(LOG4CXX_ENABLE_STACKTRACE) && !defined(LOG4CXX_STACKTRACE)
+	#ifndef __has_include
+		#include <boost/stacktrace.hpp>
+		#define LOG4CXX_STACKTRACE ::log4cxx::MDC mdc_("stacktrace", LOG4CXX_EOL + boost::stacktrace::to_string(boost::stacktrace::stacktrace()));
+	#elif __has_include(<stacktrace>)
+		#include <stacktrace>
+		#define LOG4CXX_STACKTRACE ::log4cxx::MDC mdc_("stacktrace", LOG4CXX_EOL + std::stacktrace::to_string(std::stacktrace::stacktrace()));
+	#elif __has_include(<boost/stacktrace.hpp>)
+		#include <boost/stacktrace.hpp>
+		#define LOG4CXX_STACKTRACE ::log4cxx::MDC mdc_("stacktrace", LOG4CXX_EOL + boost::stacktrace::to_string(boost::stacktrace::stacktrace()));
+	#else
+		#warning "Stacktrace requested but no implementation found"
+	#endif
+#endif /* LOG4CXX_ENABLE_STACKTRACE */
+
+#if !defined(LOG4CXX_STACKTRACE)
+#define LOG4CXX_STACKTRACE
+#endif
+
 
 /**
 Add a new logging event containing \c message to attached appender(s) if this logger is enabled for \c events.
@@ -2173,6 +2192,7 @@ If \c condition is not true, add a new logging event containing \c message to at
 #define LOG4CXX_ASSERT(logger, condition, message) do { \
 		if (!(condition) && ::log4cxx::Logger::isErrorEnabledFor(logger)) {\
 			::log4cxx::helpers::MessageBuffer oss_; \
+			LOG4CXX_STACKTRACE \
 			logger->forcedLog(::log4cxx::Level::getError(), oss_.str(oss_ << message), LOG4CXX_LOCATION); }} while (0)
 
 /**
@@ -2184,6 +2204,7 @@ If \c condition is not true, add a new logging event containing libfmt formatted
 */
 #define LOG4CXX_ASSERT_FMT(logger, condition, ...) do { \
 		if (!(condition) && ::log4cxx::Logger::isErrorEnabledFor(logger)) {\
+			LOG4CXX_STACKTRACE \
 			logger->forcedLog(::log4cxx::Level::getError(), fmt::format( __VA_ARGS__ ), LOG4CXX_LOCATION); }} while (0)
 
 #else
diff --git a/src/site/markdown/1-usage.md b/src/site/markdown/1-usage.md
index 8f3a370b..5ce8aecf 100644
--- a/src/site/markdown/1-usage.md
+++ b/src/site/markdown/1-usage.md
@@ -27,6 +27,7 @@ See the following pages for usage information:
 * @subpage filters
 * @subpage threading
 * @subpage extending-log4cxx
+* @subpage stacktrace-support
 * @subpage faq
 * @subpage configuration-samples
 * @subpage qt-support
diff --git a/src/site/markdown/macros-influencing-log4cxx.md b/src/site/markdown/macros-influencing-log4cxx.md
index fc2edc48..4aaa189a 100644
--- a/src/site/markdown/macros-influencing-log4cxx.md
+++ b/src/site/markdown/macros-influencing-log4cxx.md
@@ -33,3 +33,4 @@ Log4cxx includes), or they may be set globally via your build system.
 | ----- | ----- |
 | LOG4CXX\_THRESHOLD | Used to determine if log messages are compiled in or not.  A higher value causes more messages to be compiled out.  See [removing log statements](usage.html#removing-log-statements) for more information. |
 | LOG4CXX\_DISABLE\_LOCATION\_INFO | Define this macro to disable location information on log statements.  Location information includes the filename, class name, method name, and line number |
+| LOG4CXX\_ENABLE\_STACKTRACE | Define this macro to cause a stacktrace string to be inserted into the MDC with a key of 'stacktrace'.  This requires Boost Stacktrace or C++23 stacktrace to be available when compiling your application.  When using the PatternLayout, print out the stacktrace using the `%%X{stacktrace}` specifier.  See [stacktrace support](stacktrace-support.html) for more information. |
diff --git a/src/site/markdown/stacktrace.md b/src/site/markdown/stacktrace.md
new file mode 100644
index 00000000..bb9e52cb
--- /dev/null
+++ b/src/site/markdown/stacktrace.md
@@ -0,0 +1,51 @@
+Stacktrace Support {#stacktrace-support}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+	http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+# Stacktrace Support
+When debugging a code base and an assertion is hit, it is often useful to
+have a stacktrace as part of an assertion in order for you to tell where
+you are in the code to know why it is buggy.  Generating a stacktrace can
+be done with [Boost Stacktrace](https://www.boost.org/doc/libs/1_81_0/doc/html/stacktrace.html),
+or using the [stacktrace](https://en.cppreference.com/w/cpp/header/stacktrace) header if you are using a C++23 compatible compiler.
+
+In order to enable stacktraces when using the `LOG4CXX_ASSERT` family of macros,
+simply define `LOG4CXX_ENABLE_STACKTRACE` in your buildsystem.  If you are using a
+compiler that does not support C++17 and the `__has_include` macro, Boost Stacktrace
+must be installed and available on your system.  If your compiler supports the
+`__has_include` macro, then it will search for Boost Stacktrace, followed by searching
+for `<stacktrace>`.  Both implementations will insert an
+entry into the MDC named `stacktrace` that may then be inserted into log
+statements.  When using the [PatternLayout](@ref log4cxx.PatternLayout), this
+may be accomplished by using the `%%X{stacktrace}` conversion pattern.
+
+## Putting the stacktrace into the MDC
+
+If you want a stacktrace in any part of your code(not just on assertions),
+the following snippet of code may be used to insert a stacktrace into the
+current MDC:
+
+~~~{.cpp}
+::log4cxx::MDC mdc_("stacktrace", LOG4CXX_EOL + boost::stacktrace::to_string(boost::stacktrace::stacktrace()));
+~~~
+
+This may be inserted at any point in your application, giving you access
+to the current stacktrace in any log statement, not just in assert statements.