"Fossies" - the Fresh Open Source Software Archive 
Member "apache-log4j-2.12.4-src/src/site/xdoc/manual/flowtracing.xml" (20 Dec 2021, 15968 Bytes) of package /linux/misc/apache-log4j-2.12.4-src.tar.gz:
As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
See also the last
Fossies "Diffs" side-by-side code changes report for "flowtracing.xml":
2.18.0_vs_2.19.0.
1 <?xml version="1.0"?>
2 <!--
3 Licensed to the Apache Software Foundation (ASF) under one or more
4 contributor license agreements. See the NOTICE file distributed with
5 this work for additional information regarding copyright ownership.
6 The ASF licenses this file to You under the Apache License, Version 2.0
7 (the "License"); you may not use this file except in compliance with
8 the License. You may obtain a copy of the License at
9
10 http://www.apache.org/licenses/LICENSE-2.0
11
12 Unless required by applicable law or agreed to in writing, software
13 distributed under the License is distributed on an "AS IS" BASIS,
14 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 See the License for the specific language governing permissions and
16 limitations under the License.
17 -->
18
19 <document xmlns="http://maven.apache.org/XDOC/2.0"
20 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
21 xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
22 <properties>
23 <title>Log4j 2 API</title>
24 <author email="rgoers@apache.org">Ralph Goers</author>
25 </properties>
26
27 <body>
28 <section name="Log4j 2 API">
29 <a name="FlowTracing"/>
30 <subsection name="Flow Tracing">
31 <p>
32 The Logger class provides logging methods that are quite useful for following the
33 execution path of applications. These methods generate logging events that can be filtered
34 separately from other debug logging. Liberal use of these methods is encouraged as the output has
35 been found to
36 </p>
37 <ul>
38 <li>aid in problem diagnosis in development without requiring a debug session</li>
39 <li>aid in problem diagnosis in production where no debugging is possible</li>
40 <li>help educate new developers in learning the application.</li>
41 </ul>
42 <p>
43 The most used methods are the entry() or traceEntry() and exit() or traceExit() methods. entry()
44 or traceEntry() should be placed at the beginning of methods, except perhaps for simple
45 getters and setters. entry() can be called passing from 0 to 4 parameters. Typically these will be
46 parameters passed to the method. traceEntry() can be passed a format String and a variable list of
47 parameters, or a Message. The entry() and traceEntry() methods log with a level of TRACE and uses
48 a Marker with a name of "ENTER" which is also a "FLOW" Marker and all message strings will begin
49 with "event", even if a format String or Message is used.
50 </p>
51 <p>The main difference between the entry and traceEntry methods is that the entry method accepts a
52 variable list of objects where presumably each is a method parameter. The traceEntry method
53 accepts a format string followed by a variable list of objects, presumably included in the
54 format String. It is not possible to have a single method that includes both of these as it would
55 be ambiguous whether the first String is a parameter or a format String.</p>
56 <p>
57 An exit() or traceExit() method should be placed before any return statement or as the last statement of
58 methods without a return. exit() and traceExit() can be called with or without a parameter. Typically,
59 methods that return void will use exit() or traceExit() while methods that return an Object will use
60 exit(Object obj) or traceExit(object, new SomeMessage(object)). The exit() and traceExit() methods log
61 with a level of TRACE and uses a Marker with a name of "EXIT" which is also a "FLOW" Marker and all
62 message strings will begin with "exit", even if a format String or Message is used.
63 </p>
64 <p>
65 The throwing() method can be used by an application when it is throwing an exception that is
66 unlikely to be handled, such as a RuntimeException. This will insure that proper diagnostics
67 are available if needed. The logging event generated will have a level of ERROR and will have
68 an associated Marker with a name of "THROWING" which is also an "EXCEPTION" Marker.
69 </p>
70 <p>
71 The catching() method can be used by an application when it catches an Exception that it is not
72 going to rethrow, either explicitly or attached to another Exception. The logging event generated
73 will have a level of ERROR and will have an associated Marker with a name of "CATCHING" which is
74 also an "EXCEPTION" Marker.
75 </p>
76 <p>
77 The following example shows a simple application using these methods in a fairly typical manner. The
78 throwing() is not present since no Exceptions are explicitly thrown and not handled.
79 </p>
80 <pre class="prettyprint linenums">
81 package com.test;
82
83 import org.apache.logging.log4j.Logger;
84 import org.apache.logging.log4j.LogManager;
85
86 import java.util.Random;
87
88 public class TestService {
89 private Logger logger = LogManager.getLogger(TestService.class.getName());
90
91 private String[] messages = new String[] {
92 "Hello, World",
93 "Goodbye Cruel World",
94 "You had me at hello"
95 };
96 private Random rand = new Random(1);
97
98 public void setMessages(String[] messages) {
99 logger.traceEntry(new JsonMessage(messages));
100 this.messages = messages;
101 logger.traceExit();
102 }
103
104 public String[] getMessages() {
105 logger.traceEntry();
106 return logger.traceExit(messages, new JsonMessage(messages));
107 }
108
109 public String retrieveMessage() {
110 logger.entry();
111
112 String testMsg = getMessage(getKey());
113
114 return logger.exit(testMsg);
115 }
116
117 public void exampleException() {
118 logger.entry();
119 try {
120 String msg = messages[messages.length];
121 logger.error("An exception should have been thrown");
122 } catch (Exception ex) {
123 logger.catching(ex);
124 }
125 logger.exit();
126 }
127
128 public String getMessage(int key) {
129 logger.entry(key);
130
131 String value = messages[key];
132
133 return logger.exit(value);
134 }
135
136 private int getKey() {
137 logger.entry();
138 int key = rand.nextInt(messages.length);
139 return logger.exit(key);
140 }
141 }</pre>
142 <p>
143 This test application uses the preceding service to generate logging events.
144 </p>
145 <pre class="prettyprint linenums">
146 package com.test;
147
148 public class App {
149
150 public static void main( String[] args ) {
151 TestService service = new TestService();
152 service.retrieveMessage();
153 service.retrieveMessage();
154 service.exampleException();
155 }
156 }</pre>
157 <p>
158 The configuration below will cause all output to be routed to target/test.log. The pattern for
159 the FileAppender includes the class name, line number and method name. Including these
160 in the pattern are critical for the log to be of value.
161 </p>
162 <pre class="prettyprint linenums"><![CDATA[
163 <?xml version="1.0" encoding="UTF-8"?>
164 <Configuration status="error">
165 <Appenders>
166 <Console name="Console" target="SYSTEM_OUT">
167 <ThresholdFilter level="ERROR" onMatch="ACCEPT" onMismatch="DENY"/>
168 <!-- Flow tracing is most useful with a pattern that shows location.
169 Below pattern outputs class, line number and method name. -->
170 <PatternLayout pattern="%d{HH:mm:ss.SSS} %-5level %class{36} %L %M - %msg%xEx%n"/>
171 </Console>
172 <File name="log" fileName="target/test.log" append="false">
173 <PatternLayout pattern="%d{HH:mm:ss.SSS} %-5level %class{36} %L %M - %msg%xEx%n"/>
174 </File>
175 </Appenders>
176 <Loggers>
177 <Root level="trace">
178 <AppenderRef ref="log"/>
179 </Root>
180 </Loggers>
181 </Configuration>]]></pre>
182 <p>
183 Here is the output that results from the Java classes and configuration above.
184 </p>
185 <pre>
186 19:08:07.056 TRACE com.test.TestService 19 retrieveMessage - entry
187 19:08:07.060 TRACE com.test.TestService 46 getKey - entry
188 19:08:07.060 TRACE com.test.TestService 48 getKey - exit with (0)
189 19:08:07.060 TRACE com.test.TestService 38 getMessage - entry parms(0)
190 19:08:07.060 TRACE com.test.TestService 42 getMessage - exit with (Hello, World)
191 19:08:07.060 TRACE com.test.TestService 23 retrieveMessage - exit with (Hello, World)
192 19:08:07.061 TRACE com.test.TestService 19 retrieveMessage - entry
193 19:08:07.061 TRACE com.test.TestService 46 getKey - entry
194 19:08:07.061 TRACE com.test.TestService 48 getKey - exit with (1)
195 19:08:07.061 TRACE com.test.TestService 38 getMessage - entry parms(1)
196 19:08:07.061 TRACE com.test.TestService 42 getMessage - exit with (Goodbye Cruel World)
197 19:08:07.061 TRACE com.test.TestService 23 retrieveMessage - exit with (Goodbye Cruel World)
198 19:08:07.062 TRACE com.test.TestService 27 exampleException - entry
199 19:08:07.077 DEBUG com.test.TestService 32 exampleException - catching java.lang.ArrayIndexOutOfBoundsException: 3
200 at com.test.TestService.exampleException(TestService.java:29) [classes/:?]
201 at com.test.App.main(App.java:9) [classes/:?]
202 at com.test.AppTest.testApp(AppTest.java:15) [test-classes/:?]
203 at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[?:1.6.0_29]
204 at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) ~[?:1.6.0_29]
205 at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) ~[?:1.6.0_29]
206 at java.lang.reflect.Method.invoke(Method.java:597) ~[?:1.6.0_29]
207 at org.junit.internal.runners.TestMethodRunner.executeMethodBody(TestMethodRunner.java:99) [junit-4.3.1.jar:?]
208 at org.junit.internal.runners.TestMethodRunner.runUnprotected(TestMethodRunner.java:81) [junit-4.3.1.jar:?]
209 at org.junit.internal.runners.BeforeAndAfterRunner.runProtected(BeforeAndAfterRunner.java:34) [junit-4.3.1.jar:?]
210 at org.junit.internal.runners.TestMethodRunner.runMethod(TestMethodRunner.java:75) [junit-4.3.1.jar:?]
211 at org.junit.internal.runners.TestMethodRunner.run(TestMethodRunner.java:45) [junit-4.3.1.jar:?]
212 at org.junit.internal.runners.TestClassMethodsRunner.invokeTestMethod(TestClassMethodsRunner.java:66) [junit-4.3.1.jar:?]
213 at org.junit.internal.runners.TestClassMethodsRunner.run(TestClassMethodsRunner.java:35) [junit-4.3.1.jar:?]
214 at org.junit.internal.runners.TestClassRunner$1.runUnprotected(TestClassRunner.java:42) [junit-4.3.1.jar:?]
215 at org.junit.internal.runners.BeforeAndAfterRunner.runProtected(BeforeAndAfterRunner.java:34) [junit-4.3.1.jar:?]
216 at org.junit.internal.runners.TestClassRunner.run(TestClassRunner.java:52) [junit-4.3.1.jar:?]
217 at org.apache.maven.surefire.junit4.JUnit4TestSet.execute(JUnit4TestSet.java:35) [surefire-junit4-2.7.2.jar:2.7.2]
218 at org.apache.maven.surefire.junit4.JUnit4Provider.executeTestSet(JUnit4Provider.java:115) [surefire-junit4-2.7.2.jar:2.7.2]
219 at org.apache.maven.surefire.junit4.JUnit4Provider.invoke(JUnit4Provider.java:97) [surefire-junit4-2.7.2.jar:2.7.2]
220 at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[?:1.6.0_29]
221 at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) ~[?:1.6.0_29]
222 at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) ~[?:1.6.0_29]
223 at java.lang.reflect.Method.invoke(Method.java:597) ~[?:1.6.0_29]
224 at org.apache.maven.surefire.booter.ProviderFactory$ClassLoaderProxy.invoke(ProviderFactory.java:103) [surefire-booter-2.7.2.jar:2.7.2]
225 at $Proxy0.invoke(Unknown Source) [?:?]
226 at org.apache.maven.surefire.booter.SurefireStarter.invokeProvider(SurefireStarter.java:150) [surefire-booter-2.7.2.jar:2.7.2]
227 at org.apache.maven.surefire.booter.SurefireStarter.runSuitesInProcess(SurefireStarter.java:91) [surefire-booter-2.7.2.jar:2.7.2]
228 at org.apache.maven.surefire.booter.ForkedBooter.main(ForkedBooter.java:69) [surefire-booter-2.7.2.jar:2.7.2]
229 19:08:07.087 TRACE com.test.TestService 34 exampleException - exit</pre>
230 <p>
231 Simply changing the root logger level to DEBUG in the example above will reduce the output
232 considerably.
233 </p>
234 <pre>
235 19:13:24.963 DEBUG com.test.TestService 32 exampleException - catching java.lang.ArrayIndexOutOfBoundsException: 3
236 at com.test.TestService.exampleException(TestService.java:29) [classes/:?]
237 at com.test.App.main(App.java:9) [classes/:?]
238 at com.test.AppTest.testApp(AppTest.java:15) [test-classes/:?]
239 at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[?:1.6.0_29]
240 at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) ~[?:1.6.0_29]
241 at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) ~[?:1.6.0_29]
242 at java.lang.reflect.Method.invoke(Method.java:597) ~[?:1.6.0_29]
243 at org.junit.internal.runners.TestMethodRunner.executeMethodBody(TestMethodRunner.java:99) [junit-4.3.1.jar:?]
244 at org.junit.internal.runners.TestMethodRunner.runUnprotected(TestMethodRunner.java:81) [junit-4.3.1.jar:?]
245 at org.junit.internal.runners.BeforeAndAfterRunner.runProtected(BeforeAndAfterRunner.java:34) [junit-4.3.1.jar:?]
246 at org.junit.internal.runners.TestMethodRunner.runMethod(TestMethodRunner.java:75) [junit-4.3.1.jar:?]
247 at org.junit.internal.runners.TestMethodRunner.run(TestMethodRunner.java:45) [junit-4.3.1.jar:?]
248 at org.junit.internal.runners.TestClassMethodsRunner.invokeTestMethod(TestClassMethodsRunner.java:66) [junit-4.3.1.jar:?]
249 at org.junit.internal.runners.TestClassMethodsRunner.run(TestClassMethodsRunner.java:35) [junit-4.3.1.jar:?]
250 at org.junit.internal.runners.TestClassRunner$1.runUnprotected(TestClassRunner.java:42) [junit-4.3.1.jar:?]
251 at org.junit.internal.runners.BeforeAndAfterRunner.runProtected(BeforeAndAfterRunner.java:34) [junit-4.3.1.jar:?]
252 at org.junit.internal.runners.TestClassRunner.run(TestClassRunner.java:52) [junit-4.3.1.jar:?]
253 at org.apache.maven.surefire.junit4.JUnit4TestSet.execute(JUnit4TestSet.java:35) [surefire-junit4-2.7.2.jar:2.7.2]
254 at org.apache.maven.surefire.junit4.JUnit4Provider.executeTestSet(JUnit4Provider.java:115) [surefire-junit4-2.7.2.jar:2.7.2]
255 at org.apache.maven.surefire.junit4.JUnit4Provider.invoke(JUnit4Provider.java:97) [surefire-junit4-2.7.2.jar:2.7.2]
256 at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[?:1.6.0_29]
257 at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) ~[?:1.6.0_29]
258 at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) ~[?:1.6.0_29]
259 at java.lang.reflect.Method.invoke(Method.java:597) ~[?:1.6.0_29]
260 at org.apache.maven.surefire.booter.ProviderFactory$ClassLoaderProxy.invoke(ProviderFactory.java:103) [surefire-booter-2.7.2.jar:2.7.2]
261 at $Proxy0.invoke(Unknown Source) [?:?]
262 at org.apache.maven.surefire.booter.SurefireStarter.invokeProvider(SurefireStarter.java:150) [surefire-booter-2.7.2.jar:2.7.2]
263 at org.apache.maven.surefire.booter.SurefireStarter.runSuitesInProcess(SurefireStarter.java:91) [surefire-booter-2.7.2.jar:2.7.2]
264 at org.apache.maven.surefire.booter.ForkedBooter.main(ForkedBooter.java:69) [surefire-booter-2.7.2.jar:2.7.2]</pre>
265 </subsection>
266 </section>
267 </body>
268 </document>