Siobhan Tully | e18b344 | 2014-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 | <script type="text/javascript" src="log4javascript.js"></script>
|
| 46 | <script type="text/javascript">
|
| 47 | var log = log4javascript.getDefaultLogger();
|
| 48 | </script>
|
| 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>
|
| 84 | displays
|
| 85 | <pre class="console info">
|
| 86 | 19: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>
|
| 98 | displays
|
| 99 | <pre class="console error">
|
| 100 | 19:52:32 ERROR - An error occurred
|
| 101 | Exception: 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>
|
| 111 | displays
|
| 112 | <pre class="console debug">
|
| 113 | 19: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>
|
| 125 | displays
|
| 126 | <pre class="console info">
|
| 127 | 19: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 | <script type="text/javascript" src="log4javascript.js"></script>
|
| 147 | <script type="text/javascript">
|
| 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 | </script>
|
| 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>
|