liblogback-java-doc 1:1.1.3-2 / usr / share / doc / liblogback-java / manual / introduction.html

This file is indexed.

/usr/share/doc/liblogback-java/manual/introduction.html is in liblogback-java-doc 1:1.1.3-2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below. 

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
    <title>Chapter 1: Introduction</title>
    <link rel="stylesheet" type="text/css" href="../css/common.css" />
    <link rel="stylesheet" type="text/css" href="../css/screen.css" media="screen" />
    <link rel="stylesheet" type="text/css" href="../css/_print.css" media="print" />
    <link rel="stylesheet" type="text/css" href="../css/prettify.css" media="screen" />    

  </head>
  <body onload="prettyPrint(); decorate();">
    <script type="text/javascript">prefix='../';</script>
    <script type="text/javascript" src="../js/prettify.js"></script>
    <script src="../templates/header.js" type="text/javascript"> </script>
    <script type="text/javascript" src="../js/jquery-min.js"></script>
    <script type="text/javascript" src="../js/decorator.js"></script>
    <div id="left">
      <noscript>Please turn on Javascript to view this menu</noscript>
      <script src="../templates/left.js" type="text/javascript"></script>
    </div>
    <div id="right">
      <script src="menu.js" type="text/javascript"></script>
    </div>
    <div id="content">

    <h1>Chapter 1: Introduction</h1>

    <div class="quote">
      <p><em> The morale effects are startling. Enthusiasm jumps when
      there is a running system, even a simple one. Efforts redouble when
      the first picture from a new graphics software system appears on the
      screen, even if it is only a rectangle. One always has, at every
      stage in the process, a working system. I find that teams can grow
      much more complex entities in four months than they can
      build.</em></p>
      
      <p>&mdash;FREDERICK P. BROOKS, JR., <em>The Mythical Man-Month</em></p>
    </div>


    <script src="../templates/creative.js" type="text/javascript"></script>

    <h2>What is logback?</h2>

    <p>Logback is intended as a successor to the popular log4j
    project.  It was designed by Ceki G&#252;lc&#252;, log4j's
    founder.  It builds upon a decade of experience gained in
    designing industrial-strength logging systems. The resulting
    product, i.e. logback, is faster and has a smaller footprint than
    all existing logging systems, sometimes by a wide margin. Just as
    importantly, logback offers <a
    href="../reasonsToSwitch.html">unique and rather useful
    features</a> missing in other logging systems.
    </p>

    <h2>First Baby Step</h2>

    <script src="../templates/setup.js" type="text/javascript"></script>
    
    <a name="Requirements"></a>
    <h3>Requirements</h3>

    <p>Logback-classic module requires the presence of
    <em>slf4j-api.jar</em> and <em>logback-core.jar</em> in addition to
    <em>logback-classic.jar</em> on the classpath.
    </p>

    <p>The <em>logback-*.jar</em> files are part of the logback
    distribution whereas <em>slf4j-api-1.7.7.jar</em> ships
    with <a href="http://www.slf4j.org">SLF4J</a>, a separate project.
    </p>

    <p>Let us now begin experimenting with logback.</p>

<em>Example 1.1: Basic template for logging (<a href="../xref/chapters/introduction/HelloWorld1.html">logback-examples/src/main/java/chapters/introduction/HelloWorld1.java</a>)</em>
<pre class="prettyprint source">package chapters.introduction;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class HelloWorld1 {

  public static void main(String[] args) {

    Logger logger = LoggerFactory.getLogger("chapters.introduction.HelloWorld1");
    logger.debug("Hello world.");

  }
}</pre>

    <p><code>HelloWorld1</code> class is defined in the
    <code>chapters.introduction</code> package. It starts by importing the <a
    href="http://slf4j.org/api/org/slf4j/Logger.html"><code>Logger</code></a>
    and <a
    href="http://slf4j.org/api/org/slf4j/LoggerFactory.html"><code>LoggerFactory</code></a>
    classes defined in the SLF4J API, specifically within the
     <code>org.slf4j</code> package.
    </p>


    <p>On the first line of the main() method, the variable named
    <code>logger</code> is assigned a <code>Logger</code> instance
    retrieved by invoking the static <code>getLogger</code> method
    from the <code>LoggerFactory</code> class.  This logger is named
    "chapters.introduction.HelloWorld1". The main method proceeds to call the
    <code>debug</code> method of this logger passing "Hello World" as
    an argument.  We say that the main method contains a logging
    statement of level DEBUG with the message "Hello world".
    </p>

    <p>Note that the above example does not reference any logback
    classes. In most cases, as far as logging is concerned, your
    classes will only need to import SLF4J classes. Thus, the vast
    majority, if not all, of your classes will use the SLF4J
    API and will be oblivious to the existence of logback.
    </p>


    <p>You can launch the first
    sample application, <em>chapters.introduction.HelloWorld1</em> with the command:
    </p>
    <div class="source"><pre>java chapters.introduction.HelloWorld1</pre></div>

    <p>Launching the <code>HelloWorld1</code> application will output
    a single line on the console. By virtue of logback's default
    configuration policy, when no default configuration file is found,
    logback will add a <code>ConsoleAppender</code> to the root
    logger.
    </p>

    <p class="source">20:49:07.962 [main] DEBUG chapters.introduction.HelloWorld1 - Hello world.</p>

    <p>Logback can report information about its internal state using a
    built-in status system. Important events occurring during logback's
    lifetime can be accessed through a component called
    <code>StatusManager</code>. For the time being, let us instruct
    logback to print its internal state by invoking the static
    <code>print()</code> method of the <code>StatusPrinter</code>
    class.
    </p>

<em>Example: Printing Logger Status (<a href="../xref/chapters/introduction/HelloWorld2.html">logback-examples/src/main/java/chapters/introduction/HelloWorld2.java</a>)</em>
<pre class="prettyprint source">package chapters.introduction;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
<b>import ch.qos.logback.classic.LoggerContext;
import ch.qos.logback.core.util.StatusPrinter;</b>

public class HelloWorld2 {

  public static void main(String[] args) {
    Logger logger = LoggerFactory.getLogger("chapters.introduction.HelloWorld2");
    logger.debug("Hello world.");

    // print internal state
    <b>LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();
    StatusPrinter.print(lc);</b>
  }
}</pre>


   <p>Running the <code>HelloWorld2</code> application will produce
   the following output:</p>

<div class="source longline"><pre>12:49:22.203 [main] DEBUG chapters.introduction.HelloWorld2 - Hello world.
12:49:22,076 |-INFO in ch.qos.logback.classic.LoggerContext[default] - Could NOT find resource [logback.groovy]
12:49:22,078 |-INFO in ch.qos.logback.classic.LoggerContext[default] - Could NOT find resource [logback-test.xml]
12:49:22,093 |-INFO in ch.qos.logback.classic.LoggerContext[default] - Could NOT find resource [logback.xml]
12:49:22,093 |-INFO in ch.qos.logback.classic.LoggerContext[default] - Setting up default configuration.
</pre></div>


  <p>Logback explains that having failed to find the
  <em>logback-test.xml</em> and <em>logback.xml</em> configuration
  files (discussed later), it configured itself using its default
  policy, which is a basic <code>ConsoleAppender</code>.  An
  <code>Appender</code> is a class that can be seen as an output
  destination. Appenders exist for many different destinations
  including the console, files, Syslog, TCP Sockets, JMS and many
  more. Users can also easily create their own Appenders as
  appropriate for their specific situation.
  </p>

  <p>Note that in case of errors, logback will automatically print its
  internal state on the console.</p>

  <p>The previous examples are rather simple. Actual logging in a
  larger application would not be that different. The general pattern
  for logging statements would not change. Only the configuration
  process would be different. However, you would probably want to
  customize or configure logback according to your needs. Logback
  configuration will be covered in subsequent chapters.
  </p>

  <p>Note that in the above example we have instructed logback to
  print its internal state by invoking the
  <code>StatusPrinter.print()</code> method. Logback's internal status
  information can be very useful in diagnosing logback-related
  problems.
  </p>

  <p>Here is a list of the three required steps in order to enable
  logging in your application.
  </p>

  <ol> 
    <li>Configure the logback environment. You can do so in several
    more or less sophisticated ways. More on this later.</li>

    <li>In every class where you wish to perform logging, retrieve a
    <code>Logger</code> instance by invoking the
    <code>org.slf4j.LoggerFactory</code> class'
    <code>getLogger()</code> method, passing the current class name
    or the class itself as a parameter.</li>
    
    <li>Use this logger instance by invoking its printing methods,
    namely the debug(), info(), warn() and error() methods. This will
    produce logging output on the configured appenders.</li>
  </ol>
 
  
  <h2 class="doAnchor" name="building">Building logback</h2>
  
  <p>As its build tool, logback relies on <a
  href="http://maven.apache.org">Maven</a>, a widely-used open-source
  build tool.
  </p>

  <p>Once you have installed Maven, building the logback project,
  including all its modules, should be as easy as issuing a <code>mvn
  install</code> command from within the directory where you
  unarchived the logback distribution. Maven will automatically
  download the required external libraries.
  </p>

  <p>Logback distributions contain complete source code such that you
  can modify parts of logback library and build your own version of
  it. You may even redistribute the modified version, as long as you
  adhere to the conditions of the LGPL license or the EPL license.
  </p>

  <p>For building logback under an IDE, please see the <a
  href="../setup.html#ide">relevant section on the class path setup
  page</a>.</p>
  
  <script src="../templates/footer.js" type="text/javascript"></script>
</div>
</body>
</html>

APT Browse - Built by Thomas Orozco.