ppkarwasz commented on code in PR #2662:
URL: https://github.com/apache/logging-log4j2/pull/2662#discussion_r1640060322
##########
src/site/antora/modules/ROOT/pages/manual/flowtracing.adoc:
##########
@@ -14,109 +14,94 @@
See the License for the specific language governing permissions and
limitations under the License.
////
+
= Flow Tracing
-Flow tracing in Log4j is an advanced logging technique designed to enhance
-the visibility of application processes. With this technique, developers can
track
-data flow through their application using unique methods that log entry
-and exit points within the code.
+xref:manual/api.adoc[Log4j API] provides convenience logging methods to aid
the tracking of the data flow through an application, which is referred to as
*flow tracing*.
+<<impl,Logging implementations>> can choose to <<log-events,generate
specialized log events>> allowing users to handle these messages different from
the rest – see <<example>>.
-These methods are:
+Flow tracing is known to help with the following use cases:
-* `traceEntry()` (Deprecated `entry()`)
-* `traceExit()` (Deprecated: `exit()`)
-* `throwing()`
-* `catching()`
+* Troubleshooting without requiring a debugging session
+* Helping educate new developers in learning the application
-With these methods, we can investigate environments where traditional
debugging is not possible,
-such as in production or during live application monitoring.
-Furthermore, new developers can be educated on the application's behavior by
examining the logs.
+[#usage]
+== Usage
-Flow tracing offers a structured approach to all this.
+link:../javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`]
provides following methods for flow tracing purposes:
-== Flow Tracing Methods
+`traceEntry()`:: Marks the entry to a block
+`traceExit()`:: Marks the exit from a block
+`catching()`:: Reports caught exceptions
+`throwing()`:: Reports exceptions that are either discarded or unlikely to be
handled
-The methods often used are `traceEntry()` and `traceExit()`.
-As the name suggests, the "entry" method is used at the beginning and the
"exit" method at the end of a method.
+The most used `traceEntry()` and `traceExit()` methods are intended to mark
the _entry_ and _exit_ points of a particular block of code:
+[#example-trace]
+.Example `traceEntry()` and `traceExit()` usage
[source, java]
----
public void someMethod() {
- logger.traceEntry(); <1>
+ LOGGER.traceEntry(); //<1>
// method body
- logger.traceExit(); <2>
+ LOGGER.traceExit(); //<2>
}
----
-<1> The `entry()` method is called at the beginning of the method.
-<2> The `exit()` method is called at the end of the method.
+<1> `traceEntry()` marks the entry to the block
+<2> `traceExit()` marks the exit from the block
-Developers can call both `traceEntry()` and `traceExit()` methods with or
without parameters.
-In the case of `traceEntry()`, it makes sense to pass the method parameters on
as arguments.
+Both `traceEntry()` and `traceExit()` also accept parameters.
+You can use them to track the input and output of the associated block:
+[#example-trace-args]
+.Example `traceEntry()` and `traceExit()` usage with arguments
[source, java]
----
-public void someMethod(String param) {
- logger.traceEntry(param); <1>
+public String someMethod(String input) {
+ logger.traceEntry(input); // <1>
// method body
- logger.traceExit(); <2>
+ String output = ...;
+ logger.traceExit(output); // <2>
+ return output;
}
----
-<1> The `traceEntry()` method is called at the beginning of the method.
-<2> The `traceExit()` method is called at the end of the method.
+<1> `traceEntry()` marks the entry to the block along with the input
+<2> `traceExit()` marks the exit from the block along with the output
-The `traceEntry()` also supports messages.
+The `catching()` method can be used by an application when it catches an
exception that it will not rethrow, either explicitly or attached to another
exception:
+[#example-catching]
+.Example `catching()` usage
[source, java]
----
-public void someMethod(String[] text) {
- logger.traceEntry(new JsonMessage(text)); <1>
- // method body
-}
-----
-<1> Using the `JsonMessage` class to log the `text` parameter.
-
-Very similar, it is possible to use `traceExit()` with methods that return a
value.
-
-[source, java]
-----
-public String someMethod() {
- String result = "Hello";
- // method body
- return logger.traceExit(result); <1>
+public void someMethod() {
+ try {
+ // Business logic
+ } catch (Exception error) {
+ logger.catching(error); // <1>
+ }
}
----
-<1> The `traceExit()` method can also return a value.
-
-Developers can use the `catching()` and `throwing()` methods to work with
exceptions.
-
-The following code shows the `catching()` method. It will be called
-inside the `catch` block of a try-catch statement.
+<1> `catching()` reports the caught exception
-The `catching()` method can be used by an application when it catches an
-Exception that it will not rethrow, either explicitly or attached
-to another Exception. The generated logging event will have an `ERROR` level.
+The `throwing()` method can be used by an application when it is throwing an
exception that is unlikely to be handled, such as a `RuntimeException`.
+This will ensure that proper diagnostics are available if needed.
+[#example-throwing]
+.Example `throwing()` usage
[source, java]
----
public void someMethod() {
try {
- // Let's assume an exception is thrown here
- String msg = messages[messages.length];
- } catch (Exception ex) {
- logger.catching(ex); <1>
+ // Business logic
+ } catch (RuntimeException error) {
+ logger.throwing(error); // <1>
+ throw new RuntimeException(error); // <2>
Review Comment:
```suggestion
throw logger.throwing(error); // <1>
```
##########
src/site/antora/modules/ROOT/pages/manual/flowtracing.adoc:
##########
@@ -14,109 +14,94 @@
See the License for the specific language governing permissions and
limitations under the License.
////
+
= Flow Tracing
-Flow tracing in Log4j is an advanced logging technique designed to enhance
-the visibility of application processes. With this technique, developers can
track
-data flow through their application using unique methods that log entry
-and exit points within the code.
+xref:manual/api.adoc[Log4j API] provides convenience logging methods to aid
the tracking of the data flow through an application, which is referred to as
*flow tracing*.
+<<impl,Logging implementations>> can choose to <<log-events,generate
specialized log events>> allowing users to handle these messages different from
the rest – see <<example>>.
-These methods are:
+Flow tracing is known to help with the following use cases:
-* `traceEntry()` (Deprecated `entry()`)
-* `traceExit()` (Deprecated: `exit()`)
-* `throwing()`
-* `catching()`
+* Troubleshooting without requiring a debugging session
+* Helping educate new developers in learning the application
-With these methods, we can investigate environments where traditional
debugging is not possible,
-such as in production or during live application monitoring.
-Furthermore, new developers can be educated on the application's behavior by
examining the logs.
+[#usage]
+== Usage
-Flow tracing offers a structured approach to all this.
+link:../javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`]
provides following methods for flow tracing purposes:
-== Flow Tracing Methods
+`traceEntry()`:: Marks the entry to a block
+`traceExit()`:: Marks the exit from a block
+`catching()`:: Reports caught exceptions
+`throwing()`:: Reports exceptions that are either discarded or unlikely to be
handled
-The methods often used are `traceEntry()` and `traceExit()`.
-As the name suggests, the "entry" method is used at the beginning and the
"exit" method at the end of a method.
+The most used `traceEntry()` and `traceExit()` methods are intended to mark
the _entry_ and _exit_ points of a particular block of code:
+[#example-trace]
+.Example `traceEntry()` and `traceExit()` usage
[source, java]
----
public void someMethod() {
- logger.traceEntry(); <1>
+ LOGGER.traceEntry(); //<1>
// method body
- logger.traceExit(); <2>
+ LOGGER.traceExit(); //<2>
}
----
-<1> The `entry()` method is called at the beginning of the method.
-<2> The `exit()` method is called at the end of the method.
+<1> `traceEntry()` marks the entry to the block
+<2> `traceExit()` marks the exit from the block
-Developers can call both `traceEntry()` and `traceExit()` methods with or
without parameters.
-In the case of `traceEntry()`, it makes sense to pass the method parameters on
as arguments.
+Both `traceEntry()` and `traceExit()` also accept parameters.
+You can use them to track the input and output of the associated block:
+[#example-trace-args]
+.Example `traceEntry()` and `traceExit()` usage with arguments
[source, java]
----
-public void someMethod(String param) {
- logger.traceEntry(param); <1>
+public String someMethod(String input) {
+ logger.traceEntry(input); // <1>
Review Comment:
```suggestion
logger.traceEntry(null, input); // <1>
```
This is a call to [`traceEntry(String format, Object...
params)`](https://logging.apache.org/log4j/2.x/javadoc/log4j-api/org/apache/logging/log4j/Logger.html#traceEntry(java.lang.String,java.lang.Object...),
so passing user-generated data as the format string is dangerous. :wink:
If the format is `null` the default `FlowMessageFactory` generates the
appropriate format. In this case `params({})`.
##########
src/site/antora/modules/ROOT/pages/manual/flowtracing.adoc:
##########
@@ -14,109 +14,94 @@
See the License for the specific language governing permissions and
limitations under the License.
////
+
= Flow Tracing
-Flow tracing in Log4j is an advanced logging technique designed to enhance
-the visibility of application processes. With this technique, developers can
track
-data flow through their application using unique methods that log entry
-and exit points within the code.
+xref:manual/api.adoc[Log4j API] provides convenience logging methods to aid
the tracking of the data flow through an application, which is referred to as
*flow tracing*.
+<<impl,Logging implementations>> can choose to <<log-events,generate
specialized log events>> allowing users to handle these messages different from
the rest – see <<example>>.
-These methods are:
+Flow tracing is known to help with the following use cases:
-* `traceEntry()` (Deprecated `entry()`)
-* `traceExit()` (Deprecated: `exit()`)
-* `throwing()`
-* `catching()`
+* Troubleshooting without requiring a debugging session
+* Helping educate new developers in learning the application
-With these methods, we can investigate environments where traditional
debugging is not possible,
-such as in production or during live application monitoring.
-Furthermore, new developers can be educated on the application's behavior by
examining the logs.
+[#usage]
+== Usage
-Flow tracing offers a structured approach to all this.
+link:../javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`]
provides following methods for flow tracing purposes:
-== Flow Tracing Methods
+`traceEntry()`:: Marks the entry to a block
+`traceExit()`:: Marks the exit from a block
+`catching()`:: Reports caught exceptions
+`throwing()`:: Reports exceptions that are either discarded or unlikely to be
handled
-The methods often used are `traceEntry()` and `traceExit()`.
-As the name suggests, the "entry" method is used at the beginning and the
"exit" method at the end of a method.
+The most used `traceEntry()` and `traceExit()` methods are intended to mark
the _entry_ and _exit_ points of a particular block of code:
+[#example-trace]
+.Example `traceEntry()` and `traceExit()` usage
[source, java]
----
public void someMethod() {
- logger.traceEntry(); <1>
+ LOGGER.traceEntry(); //<1>
// method body
- logger.traceExit(); <2>
+ LOGGER.traceExit(); //<2>
}
----
-<1> The `entry()` method is called at the beginning of the method.
-<2> The `exit()` method is called at the end of the method.
+<1> `traceEntry()` marks the entry to the block
+<2> `traceExit()` marks the exit from the block
-Developers can call both `traceEntry()` and `traceExit()` methods with or
without parameters.
-In the case of `traceEntry()`, it makes sense to pass the method parameters on
as arguments.
+Both `traceEntry()` and `traceExit()` also accept parameters.
+You can use them to track the input and output of the associated block:
+[#example-trace-args]
+.Example `traceEntry()` and `traceExit()` usage with arguments
[source, java]
----
-public void someMethod(String param) {
- logger.traceEntry(param); <1>
+public String someMethod(String input) {
+ logger.traceEntry(input); // <1>
// method body
- logger.traceExit(); <2>
+ String output = ...;
+ logger.traceExit(output); // <2>
+ return output;
Review Comment:
```suggestion
return logger.traceExit(output); // <2>
```
I am not sure whether `traceExit(R result)` is the correct method for this
example. Maybe `traceExit(String format, R result)` is better. If `format` is
`null` it uses `with({})`.
Maybe we should also add an example, where the output of `traceEntry` is fed
as parameter to `traceExit` to obtain a message like:
```
Exit: params(input): output
```
##########
src/site/antora/modules/ROOT/pages/manual/flowtracing.adoc:
##########
@@ -131,83 +116,145 @@ public void someMethod() {
----
<1> The `throwing()` method logs exceptions that are thrown and not caught.
-== Differences in flow tracing methods
+[#aop]
+=== Aspect-oriented programming
+
+Logging has been a notorious example for demonstrating
https://en.wikipedia.org/wiki/Aspect-oriented_programming[aspect-oriented
programming] (AOP).
+For instance, using AOP, you can inject logging statements to methods that
match a particular footprint, e.g., all public methods in `com.mycompany`
package.
+With a couple of lines of AOP instructions, you can log input and output of
all matching functions.
+Flow tracing methods fits like a glove to this AOP use case.
+You can see a demonstration of this in
https://github.com/apache/logging-log4j-samples/tree/main/log4j-samples-aspectj[the
`log4j-samples-aspectj` project] demonstrating how you can implement this use
case using Log4j API flow methods and Spring Boot AspectJ support.
+
+[#impl]
+== Implementation
+
+This section explains how flow tracing is implemented by different logging
implementations.
-Flow tracing methods have specific markers assigned and logs with a level of
`TRACE`.
-It's also noteworthy that all messages begin with "event".
+[#impl-log4j]
+=== Log4j Core
-The table below shows the methods and their unique features.
+Log4j Core, the reference implementation of Log4j API, implements the flow
tracing methods such that
-[cols="3,3,3", options="header"]
+* <<impl-log4j-log-events,It generates specialized log events>>
+* <<impl-log4j-config,Its behaviour is configurable>>
+
+[#impl-log4j-log-events]
+==== Log events
+
+Log4j Core implements the flow tracing methods such that the generated log
events are decorated to accommodate any need to selectively handle them:
Review Comment:
Although I am not strongly opinionated about this, I would prefer to view
this section as section that applies to all Log4j API implementations.
Although this is not part of the contract, all known implementation
translate flow tracing calls into `log` calls with the given parameters.
##########
src/site/antora/modules/ROOT/pages/manual/flowtracing.adoc:
##########
@@ -131,83 +116,145 @@ public void someMethod() {
----
<1> The `throwing()` method logs exceptions that are thrown and not caught.
-== Differences in flow tracing methods
+[#aop]
+=== Aspect-oriented programming
+
+Logging has been a notorious example for demonstrating
https://en.wikipedia.org/wiki/Aspect-oriented_programming[aspect-oriented
programming] (AOP).
+For instance, using AOP, you can inject logging statements to methods that
match a particular footprint, e.g., all public methods in `com.mycompany`
package.
+With a couple of lines of AOP instructions, you can log input and output of
all matching functions.
+Flow tracing methods fits like a glove to this AOP use case.
+You can see a demonstration of this in
https://github.com/apache/logging-log4j-samples/tree/main/log4j-samples-aspectj[the
`log4j-samples-aspectj` project] demonstrating how you can implement this use
case using Log4j API flow methods and Spring Boot AspectJ support.
+
+[#impl]
+== Implementation
+
+This section explains how flow tracing is implemented by different logging
implementations.
-Flow tracing methods have specific markers assigned and logs with a level of
`TRACE`.
-It's also noteworthy that all messages begin with "event".
+[#impl-log4j]
+=== Log4j Core
-The table below shows the methods and their unique features.
+Log4j Core, the reference implementation of Log4j API, implements the flow
tracing methods such that
-[cols="3,3,3", options="header"]
+* <<impl-log4j-log-events,It generates specialized log events>>
+* <<impl-log4j-config,Its behaviour is configurable>>
+
+[#impl-log4j-log-events]
+==== Log events
+
+Log4j Core implements the flow tracing methods such that the generated log
events are decorated to accommodate any need to selectively handle them:
+
+[%header,cols="2m,1m,2,3"]
+|===
+|Method
+|Level
+|Markers
+|Message
+
+|traceEntry()
+|TRACE
+|`ENTER`, `FLOW`
+|link:../javadoc/log4j-api/org/apache/logging/log4j/message/EntryMessage.html[`EntryMessage`]
extending from
link:../javadoc/log4j-api/org/apache/logging/log4j/message/FlowMessage.html[`FlowMessage`]
+
+|traceExit()
+|TRACE
+|`EXIT`, `FLOW`
+|link:../javadoc/log4j-api/org/apache/logging/log4j/message/EntryMessage.html[`ExitMessage`]
extending from
link:../javadoc/log4j-api/org/apache/logging/log4j/message/FlowMessage.html[`FlowMessage`]
+
+|`throwing()`
Review Comment:
```suggestion
| throwing()
```
Already part of the column specification.
##########
src/site/antora/modules/ROOT/examples/manual/flowtracing/log4j2.xml:
##########
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ 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.
+ -->
+<Configuration xmlns="https://logging.apache.org/xml/ns";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="
+ https://logging.apache.org/xml/ns
+ https://logging.apache.org/xml/ns/log4j-config-2.xsd";>
+
+ <MarkerFilter marker="FLOW" onMatch="ACCEPT" onMismatch="NEUTRAL"/><!--1-->
+
+ <Appenders>
+ <Console name="CONSOLE">
+ <PatternLayout>
+ <MarkerPatternSelector defaultPattern="%d %5p [%t] %c{1} -
%m%n"><!--2-->
+ <PatternMatch key="ENTER" pattern="%d %5p [%t] %c{1} →
%m%n"/><!--3-->
Review Comment:
Graphically `→` is barely noticeable. Maybe we should:
- either choose a bigger Unicode arrow,
- or use `=>` instead.
The latter is used for example by Exim.
##########
src/site/antora/modules/ROOT/pages/manual/flowtracing.adoc:
##########
@@ -131,83 +116,145 @@ public void someMethod() {
----
<1> The `throwing()` method logs exceptions that are thrown and not caught.
-== Differences in flow tracing methods
+[#aop]
+=== Aspect-oriented programming
+
+Logging has been a notorious example for demonstrating
https://en.wikipedia.org/wiki/Aspect-oriented_programming[aspect-oriented
programming] (AOP).
+For instance, using AOP, you can inject logging statements to methods that
match a particular footprint, e.g., all public methods in `com.mycompany`
package.
+With a couple of lines of AOP instructions, you can log input and output of
all matching functions.
+Flow tracing methods fits like a glove to this AOP use case.
+You can see a demonstration of this in
https://github.com/apache/logging-log4j-samples/tree/main/log4j-samples-aspectj[the
`log4j-samples-aspectj` project] demonstrating how you can implement this use
case using Log4j API flow methods and Spring Boot AspectJ support.
+
+[#impl]
+== Implementation
+
+This section explains how flow tracing is implemented by different logging
implementations.
-Flow tracing methods have specific markers assigned and logs with a level of
`TRACE`.
-It's also noteworthy that all messages begin with "event".
+[#impl-log4j]
+=== Log4j Core
-The table below shows the methods and their unique features.
+Log4j Core, the reference implementation of Log4j API, implements the flow
tracing methods such that
-[cols="3,3,3", options="header"]
+* <<impl-log4j-log-events,It generates specialized log events>>
+* <<impl-log4j-config,Its behaviour is configurable>>
+
+[#impl-log4j-log-events]
+==== Log events
+
+Log4j Core implements the flow tracing methods such that the generated log
events are decorated to accommodate any need to selectively handle them:
+
+[%header,cols="2m,1m,2,3"]
+|===
+|Method
+|Level
+|Markers
+|Message
+
+|traceEntry()
+|TRACE
+|`ENTER`, `FLOW`
+|link:../javadoc/log4j-api/org/apache/logging/log4j/message/EntryMessage.html[`EntryMessage`]
extending from
link:../javadoc/log4j-api/org/apache/logging/log4j/message/FlowMessage.html[`FlowMessage`]
+
+|traceExit()
+|TRACE
+|`EXIT`, `FLOW`
+|link:../javadoc/log4j-api/org/apache/logging/log4j/message/EntryMessage.html[`ExitMessage`]
extending from
link:../javadoc/log4j-api/org/apache/logging/log4j/message/FlowMessage.html[`FlowMessage`]
+
+|`throwing()`
+|ERROR
+|`THROWING`, `EXCEPTION`
+|Plain message
+
+|`catching()`
Review Comment:
```suggestion
| catching()
```
Same as above.
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
