Gitiles
Code Review Sign In
gerrit.opencord.org / xos / e18b3446e847dc64339db83990f2db9af6803b99 / . / planetstack / core / static / log4javascript-1.4.6 / docs / quickstart.html
blob: 3bffff5497fbc7af4b08f0edd3176689ab4f9f2a [file] [log] [blame]
Siobhan Tullye18b3442014-02-23 14:23:34 -0500[diff] [blame^]1<?xml version="1.0"?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
4 <head>
5 <title>log4javascript quick start tutorial</title>
6 <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
7 <meta name="author" content="Tim Down - tim@log4javascript.org" />
8 <meta name="description" content="log4javascript, a logging framework for JavaScript based on log4j" />
9 <meta name="robots" content="all" />
10 <link rel="stylesheet" type="text/css" media="screen,print" href="../main.css" title="Default" />
11 </head>
12 <body>
13 <div id="container" class="nonav">
14 <div id="header">
15 <h1><a href="index.html">log4javascript</a></h1>
16 </div>
17 <div id="content">
18 <div id="nav">
19 <a class="navitem" href="../index.html">home</a>
20 | <a class="navitem" href="http://sourceforge.net/projects/log4javascript" target="_blank" title="Download (opens in new window)">download</a>
21 | <a class="navitem" href="index.html">docs</a>
22 | <span class="navitem">quick start</span>
23 | <a class="navitem" href="../demos/index.html">demos</a>
24 | <a class="navitem" href="http://log4javascript.org" target="_blank">website</a>
25 | <a class="navitem" href="http://www.timdown.co.uk" target="_blank">timdown.co.uk</a>
26 </div>
27 <h1>log4javascript quick start tutorial</h1>
28 <h2>Three step guide</h2>
29 <ol>
30 <li>
31 <h3>Download the code</h3>
32 <p>
33 Unzip the distribution and copy log4javascript.js into the desired
34 location. No other files are necessary.
35 </p>
36 </li>
37 <li>
38 <h3>Initialize log4javascript in your web page</h3>
39 <p>
40 Include log4javascript.js in your page using the code below. This
41 code assumes log4javascript is stored in the same directory as
42 your web page.
43 </p>
44 <pre class="code">
45&lt;script type="text/javascript" src="log4javascript.js"&gt;&lt;/script&gt;
46&lt;script type="text/javascript"&gt;
47 var log = log4javascript.getDefaultLogger();
48&lt;/script&gt;
49</pre>
50 <p>
51 The default logger uses a <code><a href="manual.html#popupappender">PopUpAppender</a></code>
52 which opens a pop-up window. By default, this window will open when the first
53 log message is written. For this to work, you will need to disable any pop-up blockers
54 you may have.
55 </p>
56 </li>
57 <li>
58 <h3>Include logging statements in your code</h3>
59 <p>
60 You have six logging methods at your disposal, depending on the severity
61 of the message you wish to log. By default, all messages are logged
62 in the pop-up window. The logging methods are:
63 </p>
64 <ul>
65 <li><code>log.trace(<em>message</em>[, <em>message2</em>, ... ][, <em>exception</em>])</code></li>
66 <li><code>log.debug(<em>message</em>[, <em>message2</em>, ... ][, <em>exception</em>])</code></li>
67 <li><code>log.info(<em>message</em>[, <em>message2</em>, ... ][, <em>exception</em>])</code></li>
68 <li><code>log.warn(<em>message</em>[, <em>message2</em>, ... ][, <em>exception</em>])</code></li>
69 <li><code>log.error(<em>message</em>[, <em>message2</em>, ... ][, <em>exception</em>])</code></li>
70 <li><code>log.fatal(<em>message</em>[, <em>message2</em>, ... ][, <em>exception</em>])</code></li>
71 </ul>
72 <p>
73 And that's it, log away. Below are some examples of common types of logging.
74 </p>
75 </li>
76 </ol>
77 <h2>Logging examples</h2>
78 <ol>
79 <li>
80 <h3>A simple logging message string</h3>
81 <pre class="code">
82 log.info("Hello world");
83</pre>
84displays
85 <pre class="console info">
8619:52:03 INFO - Hello world
87</pre>
88 </li>
89 <li>
90 <h3>Logging an error with a message</h3>
91 <pre class="code">
92 try {
93 throw new Error("Faking something going wrong!");
94 } catch (e) {
95 log.error("An error occurred", e);
96 }
97</pre>
98displays
99 <pre class="console error">
10019:52:32 ERROR - An error occurred
101Exception: Faking something going wrong! on line number 80 in file basic.html
102</pre>
103 </li>
104 <li>
105 <h3>Logging multiple messages with one logging call</h3>
106 <pre class="code">
107 var a = "Hello";
108 var b = 3;
109 log.debug(a, b);
110</pre>
111displays
112 <pre class="console debug">
11319:53:05 DEBUG - Hello 3
114</pre>
115 </li>
116 <li>
117 <h3>Logging an object</h3>
118 <p>Logging an object:</p>
119 <pre class="code">
120 var obj = new Object();
121 obj.name = "Octopus";
122 obj.tentacles = 8;
123 log.info(obj);
124</pre>
125displays
126 <pre class="console info">
12719:53:17 INFO - {
128 name: Octopus,
129 tentacles: 8
130}
131</pre>
132 </li>
133 </ol>
134 <h2>Tweaking the default logger</h2>
135 <p>
136 The default logger is fine as a starting point, but what if you want the default logger
137 with a few different options (say, bringing the pop-up to the front whenever a log message is
138 logged, or having new log messages appear at the top of the pop-up rather than the bottom)?
139 </p>
140 <p>
141 In this case, you will need to create a new logger, then create a
142 <code><a href="manual.html#popupappender">PopUpAppender</a></code>, set options
143 on it, and add it to the logger:
144 </p>
145 <pre class="code">
146&lt;script type="text/javascript" src="log4javascript.js"&gt;&lt;/script&gt;
147&lt;script type="text/javascript"&gt;
148 // Create the logger
149 var log = log4javascript.getLogger();
150
151 // Create a PopUpAppender with default options
152 var popUpAppender = new log4javascript.PopUpAppender();
153
154 // Change the desired configuration options
155 popUpAppender.setFocusPopUp(true);
156 popUpAppender.setNewestMessageAtTop(true);
157
158 // Add the appender to the logger
159 log.addAppender(popUpAppender);
160
161 // Test the logger
162 log.debug("Hello world!");
163&lt;/script&gt;
164</pre>
165 <p>
166 <a href="../examples/example_quickstart_1.html" title="View example (opens in new window)"
167 target="_blank">See this example in action</a> (opens in new window)
168 </p>
169 <p>
170 Refer to the manual for more information about
171 <a href="manual.html#configuration">configuring appenders</a> and more
172 details about <code><a href="manual.html#popupappender">PopUpAppender</a></code>.
173 </p>
174 <h2>Sending log messages to the server</h2>
175 <p>
176 For this you will need to use an <code><a href="manual.html#ajaxappender">AjaxAppender</a></code>
177 as follows:
178 </p>
179 <pre class="code">
180 var ajaxAppender = new log4javascript.AjaxAppender(<em>URL</em>);
181 log.addAppender(ajaxAppender);
182</pre>
183 <p>
184 Now your log messages will appear in the pop-up window and be sent
185 asynchronously to the URL you specify in the form of HTTP post parameters.
186 No server-side code to process these requests is provided with log4javascript.
187 </p>
188 <p>
189 See <code><a href="manual.html#ajaxappender">AjaxAppender</a></code> for more details
190 on formatting log messages.
191 </p>
192 <h2>Changing the format of log messages</h2>
193 <p>
194 Using a <code><a href="manual.html#layouts">Layout</a></code>, you can
195 format log messages however you like. For example:
196 </p>
197 <pre class="code">
198 var log = log4javascript.getLogger("mylogger");
199 var popUpAppender = new log4javascript.PopUpAppender();
200 var layout = new log4javascript.PatternLayout("[%-5p] %m");
201 popUpAppender.setLayout(layout);
202</pre>
203 <p>A call to</p>
204 <pre class="code">
205 log.debug("Hello world");
206</pre>
207 <p>will now result in output in the pop-up window of </p>
208 <pre class="console debug">
209[DEBUG] Hello world
210</pre>
211 <p>
212 See <code><a href="manual.html#patternlayout">PatternLayout</a></code> for more details
213 on formatting log messages.
214 </p>
215 </div>
216 <div id="footer">
217 <span class="externallinkinfo">
218 <strong>NB.</strong> All external links open in a new window.
219 </span>
220 Written by Tim Down. <a href="mailto:tim@log4javascript.org">tim@log4javascript.org</a>
221 <br />
222 log4javascript is distributed under the <a href="http://www.apache.org/licenses/LICENSE-2.0.html"
223 title="Apache License, Version 2.0 (opens in new window)" target="_blank">Apache License,
224 Version 2.0</a>
225
226 </div>
227 </div>
228
229 </body>
230</html>