You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
With these methods, we can investigate environments where traditional debugging is not possible,
32
+
such as in production or during live application monitoring.
33
+
Furthermore, new developers can be educated on the application's behavior by examining the logs.
94
34
95
-
public void setMessages(String[] messages) {
96
-
logger.traceEntry(new JsonMessage(messages));
97
-
this.messages = messages;
98
-
logger.traceExit();
99
-
}
35
+
Flow tracing offers a structured approach to all this.
100
36
101
-
public String[] getMessages() {
102
-
logger.traceEntry();
103
-
return logger.traceExit(messages, new JsonMessage(messages));
104
-
}
37
+
== Flow Tracing Methods
105
38
106
-
public String retrieveMessage() {
107
-
logger.entry();
39
+
The methods often used are `traceEntry()` and `traceExit()`.
40
+
As the name suggests, the "entry" method is used at the beginning and the "exit" method at the end of a method.
108
41
109
-
String testMsg = getMessage(getKey());
42
+
[source, java]
43
+
----
44
+
public void someMethod() {
45
+
logger.traceEntry(); <1>
46
+
// method body
47
+
logger.traceExit(); <2>
48
+
}
49
+
----
50
+
<1> The `entry()` method is called at the beginning of the method.
51
+
<2> The `exit()` method is called at the end of the method.
110
52
111
-
return logger.exit(testMsg);
112
-
}
53
+
Developers can call both `traceEntry()` and `traceExit()` methods with or without parameters.
54
+
In the case of `traceEntry()`, it makes sense to pass the method parameters on as arguments.
113
55
114
-
public void exampleException() {
115
-
logger.entry();
116
-
try {
117
-
String msg = messages[messages.length];
118
-
logger.error("An exception should have been thrown");
119
-
} catch (Exception ex) {
120
-
logger.catching(ex);
121
-
}
122
-
logger.exit();
123
-
}
56
+
[source, java]
57
+
----
58
+
public void someMethod(String param) {
59
+
logger.traceEntry(param); <1>
60
+
// method body
61
+
logger.traceExit(); <2>
62
+
}
63
+
----
64
+
<1> The `traceEntry()` method is called at the beginning of the method.
65
+
<2> The `traceExit()` method is called at the end of the method.
124
66
125
-
public String getMessage(int key) {
126
-
logger.entry(key);
67
+
The `traceEntry()` also supports messages.
127
68
128
-
String value = messages[key];
69
+
[source, java]
70
+
----
71
+
public void someMethod(String[] text) {
72
+
logger.traceEntry(new JsonMessage(text)); <1>
73
+
// method body
74
+
}
75
+
----
76
+
<1> Using the `JsonMessage` class to log the `text` parameter.
129
77
130
-
return logger.exit(value);
131
-
}
78
+
Very similar, it is possible to use `traceExit()` with methods that return a value.
132
79
133
-
private int getKey() {
134
-
logger.entry();
135
-
int key = rand.nextInt(messages.length);
136
-
return logger.exit(key);
137
-
}
80
+
[source, java]
81
+
----
82
+
public String someMethod() {
83
+
String result = "Hello";
84
+
// method body
85
+
return logger.traceExit(result); <1>
138
86
}
139
87
----
88
+
<1> The `traceExit()` method can also return a value.
89
+
90
+
Developers can use the `catching()` and `throwing()` methods to work with exceptions.
140
91
141
-
This test application uses the preceding service to generate logging
142
-
events.
92
+
The following code shows the `catching()` method. It will be called
93
+
inside the `catch` block of a try-catch statement.
143
94
144
-
[source,java]
95
+
The `catching()` method can be used by an application when it catches an
96
+
Exception that it will not rethrow, either explicitly or attached
97
+
to another Exception. The generated logging event will have an `ERROR` level.
98
+
99
+
[source, java]
100
+
----
101
+
public void someMethod() {
102
+
try {
103
+
// Let's assume an exception is thrown here
104
+
String msg = messages[messages.length];
105
+
} catch (Exception ex) {
106
+
logger.catching(ex); <1>
107
+
}
108
+
}
145
109
----
146
-
package com.test;
110
+
<1> The `catching()` method logs exceptions that are caught and not rethrown.
111
+
112
+
The `throwing()` method is used to log exceptions that are thrown and not caught.
113
+
The code shows how to use the `throwing()` method- like `catching()`, which will be called
114
+
inside the `catch` block of a try-catch statement.
147
115
148
-
public class App {
116
+
The `throwing()` method can be used by an application when it is throwing
117
+
an exception that is unlikely to be handled, such as a RuntimeException.
118
+
This will ensure that proper diagnostics are available if needed.
119
+
The generated logging event will have an `ERROR` level.
149
120
150
-
public static void main( String[] args ) {
151
-
TestService service = new TestService();
152
-
service.retrieveMessage();
153
-
service.retrieveMessage();
154
-
service.exampleException();
121
+
[source, java]
122
+
----
123
+
public void someMethod() {
124
+
try {
125
+
// Let's assume an exception is thrown here
126
+
String msg = messages[messages.length];
127
+
} catch (Exception ex) {
128
+
logger.throwing(ex); <1>
155
129
}
156
130
}
157
131
----
132
+
<1> The `throwing()` method logs exceptions that are thrown and not caught.
133
+
134
+
== Differences in flow tracing methods
135
+
136
+
Flow tracing methods have specific markers assigned and logs with a level of `TRACE`.
137
+
It's also noteworthy that all messages begin with "event".
138
+
139
+
The table below shows the methods and their unique features.
140
+
141
+
[cols="3,3,3", options="header"]
142
+
|===
143
+
| Method Name | Marker Name | Special Features
144
+
145
+
| `traceEntry()`
146
+
| `ENTER`, `FLOW`
147
+
| Can take a format string and a variable list of parameters.
148
+
149
+
| `entry()`
150
+
| `ENTER`, `FLOW`
151
+
| DEPRECATED. Accepts 0 to 4 parameters
152
+
153
+
| `traceExit()`
154
+
| `EXIT`, `FLOW`
155
+
| Handles return values differently based on the method signature.
156
+
157
+
| `exit()`
158
+
| `EXIT`, `FLOW`
159
+
| DEPRECATED. Can be called with or without parameters.
160
+
161
+
| `throwing()`
162
+
| `THROWING`, `EXCEPTION`
163
+
| Typically used when an application throws an exception that is unlikely to be handled, such as a RuntimeException.
164
+
165
+
| `catching()`
166
+
| `CATCHING`, `EXCEPTION`
167
+
| Used when catching exceptions that are not rethrown; logs with ERROR level.
168
+
169
+
|===
170
+
171
+
== Flow Tracing Example Configuration
172
+
173
+
The following example demonstrates how to configure Log4j to use flow tracing.
174
+
Note: While developers should prefer the `JsonTemplateLayout` in production, this example uses `PatternLayout` for simplicity.
175
+
176
+
Two appenders are defined: `Console` and `File`.
177
+
178
+
The `Console` appender outputs logs to `SYSTEM_OUT`, typically the console.
179
+
It includes a `ThresholdFilter` set to only accept messages at the `ERROR` level or above.
180
+
Less severe messages are filtered.
181
+
182
+
Similarly, the File appender directs logs to a file named `target/test.log`.
183
+
The appenders configuration will create a new file for every application run.
184
+
185
+
Both appenders use the already mentioned `PatternLayout`, which includes detailed information such as time, log level, class name, line number, and method name.
158
186
159
-
The configuration below will cause all output to be routed to
160
-
target/test.log. The pattern for the FileAppender includes the class
161
-
name, line number and method name. Including these in the pattern are
162
-
critical for the log to be of value.
187
+
Finally, in the Loggers section, the Root logger is set to a `TRACE` level, which is necessary to see flow tracing in action.
188
+
The Root logger references the File appender, directing its output to the configured file.
0 commit comments