vy commented on code in PR #2584:
URL: https://github.com/apache/logging-log4j2/pull/2584#discussion_r1603281548
##########
src/site/antora/modules/ROOT/pages/manual/markers.adoc:
##########
@@ -16,85 +16,111 @@
////
= Markers
-One of the primary purpose of a logging framework is to provide the
-means to generate debugging and diagnostic information only when it is
-needed, and to allow filtering of that information so that it does not
-overwhelm the system or the individuals who need to make use of it. As
-an example, an application desires to log its entry, exit and other
-operations separately from SQL statements being executed, and wishes to
-be able to log queries separate from updates. One way to accomplish this
-is shown below:
-
-[source,java]
+Markers allow "tag" log statements with a Marker object, labeling them
+as belonging to a specific type. For example, developers can use Markers to tag
+log statements related to a particular subsystem or functionality.
+
+By using Markers, it is possible to filter log statements based on the Marker
+and display only those log statements that are of interest, such as those
+related to XML processing or SQL queries.
+
+Markers offer more fine-grained control over log filtering beyond log levels
or package names.
+
+== Creating Markers
+
+To create a Marker, use the MarkerManager class. The MarkerManager class
provides
+a factory method to create a Marker object is used to tag log statements.
+
+[source, java]
+----
+Marker SQL_MARKER = MarkerManager.getMarker("SQL");
+----
+
+Since a Marker is reusable across multiple log statements, it makes sense
+to store the Marker in a static final field and make it a constant.
+Once done, use it as the first argument in the log statement.
+
+[source, java]
+----
+logger.debug(SQL_MARKER, "Here is my SQL related message");
+----
+
+A complete example is shown below. It creates the Marker as the constant
+and then uses it to tag a log statement. The log method works "as usual,"
+but the marker needs to be added as the first argument.
+
+[source, java]
----
import org.apache.logging.log4j.Logger;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.MarkerManager;
-import java.util.Map;
public class MyApp {
+ private Logger logger = LogManager.getLogger();
+ private static final Marker SQL_MARKER =
MarkerManager.getMarker("MY_APP_SQL"); <1>
+
+ public void doQuery(String table) {
+ // do business logic here
- private Logger logger = LogManager.getLogger(MyApp.class.getName());
- private static final Marker SQL_MARKER = MarkerManager.getMarker("SQL");
- private static final Marker UPDATE_MARKER =
MarkerManager.getMarker("SQL_UPDATE").setParents(SQL_MARKER);
- private static final Marker QUERY_MARKER =
MarkerManager.getMarker("SQL_QUERY").setParents(SQL_MARKER);
+ logger.debug(SQL_MARKER, "SELECT * FROM {}", table); <2>
+ }
+}
+----
+<1> The marker is created and stored as a constant
+<2> Using the marker to tag a log statement
- public String doQuery(String table) {
- logger.traceEntry();
+You must create a configuration file to write log statements tagged with the
"SQL" marker to the console.
+This file uses the `<MarkerFilter>` element to accept or deny log statements
+based on the marker.
- logger.debug(QUERY_MARKER, "SELECT * FROM {}", table);
+The following code shows how the MarkerFilter is used in the configuration
file.
+It assumes that the Console appender is defined in the configuration file.
- String result = ...
+[source, xml]
+----
+<Logger name="com.example" level="all" additivity="false">
+ <AppenderRef ref="Console">
+ <Filters>
+ <MarkerFilter marker="MY_APP_SQL" onMatch="ACCEPT"
onMismatch="DENY"/> <1>
+ </Filters>
+ </AppenderRef>
+</Logger>
+----
+<1> The MarkerFilter is used to accept only SQL markers but deny others
- return logger.traceExit(result);
- }
+== Parent and child Markers
- public String doUpdate(String table, Map<String, String> params) {
- logger.traceEntry();
+A Marker can have zero or more parent Markers. This allows for a hierarchy of
Markers.
+To create such a hierarchy, you must use the `setParents` method on the Marker
object
+after you create the child marker. This method will connect both markers.
- if (logger.isDebugEnabled()) {
- logger.debug(UPDATE_MARKER, "UPDATE {} SET {}", table,
formatCols());
- }
-
- String result = ...
+[source, java]
+----
+Marker SQL_MARKER = MarkerManager.getMarker("MY_APP_SQL"); <1>
+Marker UPDATE_MARKER =
MarkerManager.getMarker("MY_APP_SQL_UPDATE").setParents(SQL_MARKER); <2>
+----
+<1> Creating the parent marker
+<2> Creating the child marker and connecting it to the parent marker
- return logger.traceExit(result);
- }
+The child marker works as expected by adding to the log method as the first
argument.
- private String formatCols(Map<String, String> cols) {
- StringBuilder sb = new StringBuilder();
- boolean first = true;
- for (Map.Entry<String, String> entry : cols.entrySet()) {
- if (!first) {
- sb.append(", ");
- }
- sb.append(entry.getKey()).append("=").append(entry.getValue());
- first = false;
- }
- return sb.toString();
- }
-}
+[source, java]
----
+logger.debug(UPDATE_MARKER, "UPDATE {} SET {}", table, values);
Review Comment:
```suggestion
LOGGER.debug(UPDATE_MARKER, "UPDATE {} SET {}", table, values);
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscr...@logging.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
