Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 159 lines (112 sloc) 5.126 kB
fa894bb @akaspin typo
authored
1 # ain*
1a8d27d @akaspin Initial commit
authored
2
fa894bb @akaspin typo
authored
3 Brain-free [syslog](http://en.wikipedia.org/wiki/Syslog)** logging for
4 [node.js](http://nodejs.org).
1a8d27d @akaspin 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 @akaspin 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 @akaspin typo
authored
14 *In the Phoenician alphabet letter "ain" indicates eye.
96962a8 @akaspin typo
authored
15
fa894bb @akaspin 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 @akaspin 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 @akaspin 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 @akaspin docs
authored
33 console.log('notice: %d', Date.now());
34 console.info('info');
35 console.error('error');
fa894bb @akaspin typo
authored
36
37 After launch in `/var/log/user` you can see the following:
38
8fa275e @akaspin 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 @akaspin typo
authored
60
8fa275e @akaspin 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 @akaspin typo
authored
94
8fa275e @akaspin 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.