Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 159 lines (112 sloc) 5.126 kb
fa894bb Alexander Dorofeev typo
authored
1 # ain*
1a8d27d Alexander Dorofeev Initial commit
authored
2
fa894bb Alexander Dorofeev typo
authored
3 Brain-free [syslog](http://en.wikipedia.org/wiki/Syslog)** logging for
4 [node.js](http://nodejs.org).
1a8d27d Alexander Dorofeev Initial commit
authored
5
6 *Ain* written with full compatibility with *node.js* `console` module. It
7 implements all `console` functions and formatting. Also *ain* supports UTF-8
8 (tested on Debian Testing/Sid).
9
8fa275e Alexander Dorofeev docs
authored
10 *Ain* send messages by UDP to `127.0.0.1:514` (it's more scalable than
11 unix domain socket `/dev/log`) in
12 [RFC 3164](http://www.faqs.org/rfcs/rfc3164.html).
13
fa894bb Alexander Dorofeev typo
authored
14 *In the Phoenician alphabet letter "ain" indicates eye.
96962a8 Alexander Dorofeev typo
authored
15
fa894bb Alexander Dorofeev typo
authored
16 **All examples tested under Debian Squeeze `rsyslog`. On other operating
17 systems and logging daemons settings and paths may differ.
18
2b1a358 Alexander Dorofeev package for NPM
authored
19 ## Installation
20
21 You can install *ain* as usual - by copy "ain" directory in your
22 `~/.node_libraries` or via *npm*
23
24 npm install ain
25
1a8d27d Alexander Dorofeev Initial commit
authored
26 ## Usage
27
28 Usage of *ain* is very similar to *node.js* console. Following example
29 demonstrates the replacement of the console:
30
31 var console = require('ain');
32
8fa275e Alexander Dorofeev docs
authored
33 console.log('notice: %d', Date.now());
34 console.info('info');
35 console.error('error');
fa894bb Alexander Dorofeev typo
authored
36
37 After launch in `/var/log/user` you can see the following:
38
8fa275e Alexander Dorofeev docs
authored
39 Dec 5 06:45:26 localhost ex.js[6041]: notice: 1291513526013
40 Dec 5 06:45:26 localhost ex.js[6041]: info
41 Dec 5 06:45:26 localhost ex.js[6041]: error
42
43 ## Changing destinations
44
45 By default *ain* sets following destinations:
46
47 * `TAG` - `__filename`
48 * `Facility` - user (1)
49 * `HOSTNAME` - localhost
50
51 You can change them by `set` function. `set` function is chainable.
52
53 var logger = require('ain')
54 .set('node-test-app', 'daemon', 'devhost');
55 logger.warn('some warning');
56
57 ... and in `/var/log/daemon.log`:
58
59 Dec 5 07:08:58 devhost node-test-app[10045]: some warning
fa894bb Alexander Dorofeev typo
authored
60
8fa275e Alexander Dorofeev docs
authored
61 `set` function takes three arguments: `tag`, `facility` and `hostname`. All
62 of these are optional.
63
64 `tag` and `hostname` arguments is just *RFC 3164* `TAG` and `HOSTNAME` of
65 your messages.
66
67 `facility` is little more than just name. Refer to *Section 4.1.1* of
68 [RFC 3164](http://www.faqs.org/rfcs/rfc3164.html) it can be:
69
70 ## String Description
71 -----------------------
72 0 kern kernel messages
73 1 user user-level messages
74 2 mail mail system
75 3 daemon system daemons
76 4 auth security/authorization messages
77 5 syslog messages generated internally by syslog daemon
78 6 lpr line printer subsystem
79 7 news network news subsystem
80 8 uucp UUCP subsystem
81 16 local0 local use 0
82 17 local1 local use 1
83 18 local2 local use 2
84 19 local3 local use 3
85 20 local4 local use 4
86 21 local5 local use 5
87 22 local6 local use 6
88 23 local7 local use 7
89
90 You can set `facility` by `String` or `Number`:
91
92 logger.init('node-test-app', 3);
93 logger.init('node-test-app', 'daemon');
fa894bb Alexander Dorofeev typo
authored
94
8fa275e Alexander Dorofeev docs
authored
95 Also you can set `TAG`, `Facility` and `HOSTNAME` separatelly by `setTag`,
96 `setFacility` and `setHostname` functions. All of them is chainable too.
97
98 You can get all destinations by theese properties:
99
100 * `tag` TAG
101 * `facility` Numerical representation of RFC 3164 facility
102 * `hostname` HOSTNAME
103
104 ## Logging
105
106 As noticed before *ain* implements all `console` functions. Severity level is
107 referenced to [RFC 3164](http://www.faqs.org/rfcs/rfc3164.html):
108
109 # String Description
110 -----------------------
111 0 emerg Emergency: system is unusable
112 1 alert Alert: action must be taken immediately
113 2 crit Critical: critical conditions
114 3 err Error: error conditions
115 4 warn Warning: warning conditions
116 5 notice Notice: normal but significant condition
117 6 info Informational: informational messages
118 7 debug Debug: debug-level messages
119
120 *Ain* `console`-like functions behaviour is fully compatible to *node.js* and
121 logs messages with different severity levels:
122
123 * `log` - notice (5)
124 * `info` - info (6)
125 * `warn` - warn (4)
126 * `error` - err (3)
127 * `dir` - notice (5)
128 * `time`, `timeEnd` - notice (5)
129 * `trace` - err (3)
130 * `assert` - err (3)
131
132 To log message with desired severity level you can use `send` function:
133
134 logger.send('message', 'alert');
135
136 `send` function takes two arguments: message and optional severity level. By
137 default, severity level is *notice*.
138
139 ## Additional loggers
140
141 After importing *ain* already has default logger. Everything that was
142 described above - just about it.
143
144 If you need log message with different `TAG`, `facility` and `HOSTNAME`
145 without touching default logger, you can get independent instance of logger
146 by `get` function.
147
148 var logger = require('ain').set('node-test-app', 'daemon', 'devhost');
149 logger.warn('some warning');
150
151 var anotherLogger = logger.get(logger.tag, 'local0', logger.hostname);
152 anotherLogger.log('another messgage');
153
154 `get` function takes three arguments - as well as `set` function and return
155 new logger object. This object is just new instance of "logger" and has all
156 *ain* functions (including `get`).
157
158
Something went wrong with that request. Please try again.