Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

docs

  • Loading branch information...
commit 8fa275e0e1e8dc780068508f1a27dff768fe60e5 1 parent fa894bb
@akaspin authored
Showing with 170 additions and 23 deletions.
  1. +45 −19 index.js
  2. +125 −4 readme.md
View
64 index.js
@@ -97,32 +97,45 @@ function getDate() {
* @returns {SysLogger}
*/
function SysLogger() {
- this.times = {};
+ this._times = {};
}
+
/**
- * Init function
- * @param {Facility|Number|String} Optional facility
- * @param {String} name Optional name. By default is process.argv[1]
- * @param {String} hostname Optional hostname.
+ * Init function. All arguments is optional
+ * @param {String} tag By default is __filename
+ * @param {Facility|Number|String} By default is "user"
+ * @param {String} hostname By default is "localhost"
*/
-SysLogger.prototype.init = function(facility, name, hostname) {
+SysLogger.prototype.set = function(tag, facility, hostname) {
+ this.setTag(tag);
+ this.setFacility(facility);
+ this.setHostname(hostname);
+
+ return this;
+};
+
+SysLogger.prototype.setTag = function(tag) {
+ this.tag = tag || __filename;
+ return this;
+};
+SysLogger.prototype.setFacility = function(facility) {
this.facility = facility || Facility.user;
if (typeof this.facility == 'string')
- this.facility = Facility[this.facility];
-
- this.name = name || process.argv[1];
+ this.facility = Facility[this.facility];
+ return this;
+};
+SysLogger.prototype.setHostname = function(hostname) {
this.hostname = hostname || 'localhost';
+ return this;
};
+
/**
- * Get new instance of SysLogger.
- * @param {String} name Optional name. By default is process.argv[1]
- * @param {Facility|Number|String} facility
- * @param {String} hostname Optional hostname.
+ * Get new instance of SysLogger. All arguments is similar as `init`
* @returns {SysLogger}
*/
SysLogger.prototype.get = function() {
var newLogger = new SysLogger();
- newLogger.init.apply(newLogger, arguments);
+ newLogger.set.apply(newLogger, arguments);
return newLogger;
};
/**
@@ -134,9 +147,7 @@ SysLogger.prototype._send = function(message, severity) {
var client = dgram.createSocket('udp4');
var message = new Buffer('<' + (this.facility * 8 + severity) + '>' +
getDate() + ' ' + this.hostname + ' ' +
- this.name + '[' + process.pid + ']:' + message);
- console.log('%s', message);
-
+ this.tag + '[' + process.pid + ']:' + message);
client.send(message, 0, message.length, 514, '127.0.0.1',
function(err) {
if (err) console.error('Can\'t connect to localhost:514');
@@ -155,29 +166,44 @@ SysLogger.prototype.send = function(message, severity) {
this._send(message, severity);
};
+/**
+ * Send log message with notice severity.
+ */
SysLogger.prototype.log = function() {
this._send(format.apply(this, arguments), Severity.notice);
};
+/**
+ * Send log message with info severity.
+ */
SysLogger.prototype.info = function() {
this._send(format.apply(this, arguments), Severity.info);
};
+/**
+ * Send log message with warn severity.
+ */
SysLogger.prototype.warn = function() {
this._send(format.apply(this, arguments), Severity.warn);
};
+/**
+ * Send log message with err severity.
+ */
SysLogger.prototype.error = function() {
this._send(format.apply(this, arguments), Severity.err);
};
+/**
+ * Log object with `util.inspect` with notice severity
+ */
SysLogger.prototype.dir = function(object) {
var util = require('util');
this._send(util.inspect(object) + '\n', Severity.notice);
};
SysLogger.prototype.time = function(label) {
- this.times[label] = Date.now();
+ this._times[label] = Date.now();
};
SysLogger.prototype.timeEnd = function(label) {
- var duration = Date.now() - this.times[label];
+ var duration = Date.now() - this._times[label];
this.log('%s: %dms', label, duration);
};
View
129 readme.md
@@ -7,6 +7,10 @@ Brain-free [syslog](http://en.wikipedia.org/wiki/Syslog)** logging for
implements all `console` functions and formatting. Also *ain* supports UTF-8
(tested on Debian Testing/Sid).
+*Ain* send messages by UDP to `127.0.0.1:514` (it's more scalable than
+unix domain socket `/dev/log`) in
+[RFC 3164](http://www.faqs.org/rfcs/rfc3164.html).
+
*In the Phoenician alphabet letter "ain" indicates eye.
**All examples tested under Debian Squeeze `rsyslog`. On other operating
systems and logging daemons settings and paths may differ.
@@ -18,12 +22,129 @@ demonstrates the replacement of the console:
var console = require('ain');
- console.log('notice severity by number %d', Date.now());
- console.info('info severity');
- console.error('error severity');
+ console.log('notice: %d', Date.now());
+ console.info('info');
+ console.error('error');
After launch in `/var/log/user` you can see the following:
+ Dec 5 06:45:26 localhost ex.js[6041]: notice: 1291513526013
+ Dec 5 06:45:26 localhost ex.js[6041]: info
+ Dec 5 06:45:26 localhost ex.js[6041]: error
+
+## Changing destinations
+
+By default *ain* sets following destinations:
+
+* `TAG` - `__filename`
+* `Facility` - user (1)
+* `HOSTNAME` - localhost
+
+You can change them by `set` function. `set` function is chainable.
+
+ var logger = require('ain')
+ .set('node-test-app', 'daemon', 'devhost');
+ logger.warn('some warning');
+
+... and in `/var/log/daemon.log`:
+
+ Dec 5 07:08:58 devhost node-test-app[10045]: some warning
+`set` function takes three arguments: `tag`, `facility` and `hostname`. All
+of these are optional.
+
+`tag` and `hostname` arguments is just *RFC 3164* `TAG` and `HOSTNAME` of
+your messages.
+
+`facility` is little more than just name. Refer to *Section 4.1.1* of
+[RFC 3164](http://www.faqs.org/rfcs/rfc3164.html) it can be:
+
+ ## String Description
+ -----------------------
+ 0 kern kernel messages
+ 1 user user-level messages
+ 2 mail mail system
+ 3 daemon system daemons
+ 4 auth security/authorization messages
+ 5 syslog messages generated internally by syslog daemon
+ 6 lpr line printer subsystem
+ 7 news network news subsystem
+ 8 uucp UUCP subsystem
+ 16 local0 local use 0
+ 17 local1 local use 1
+ 18 local2 local use 2
+ 19 local3 local use 3
+ 20 local4 local use 4
+ 21 local5 local use 5
+ 22 local6 local use 6
+ 23 local7 local use 7
+
+You can set `facility` by `String` or `Number`:
+
+ logger.init('node-test-app', 3);
+ logger.init('node-test-app', 'daemon');
-As noticed before *ain* implements all `console` functions.
+Also you can set `TAG`, `Facility` and `HOSTNAME` separatelly by `setTag`,
+`setFacility` and `setHostname` functions. All of them is chainable too.
+
+You can get all destinations by theese properties:
+
+* `tag` TAG
+* `facility` Numerical representation of RFC 3164 facility
+* `hostname` HOSTNAME
+
+## Logging
+
+As noticed before *ain* implements all `console` functions. Severity level is
+referenced to [RFC 3164](http://www.faqs.org/rfcs/rfc3164.html):
+
+ # String Description
+ -----------------------
+ 0 emerg Emergency: system is unusable
+ 1 alert Alert: action must be taken immediately
+ 2 crit Critical: critical conditions
+ 3 err Error: error conditions
+ 4 warn Warning: warning conditions
+ 5 notice Notice: normal but significant condition
+ 6 info Informational: informational messages
+ 7 debug Debug: debug-level messages
+
+*Ain* `console`-like functions behaviour is fully compatible to *node.js* and
+logs messages with different severity levels:
+
+* `log` - notice (5)
+* `info` - info (6)
+* `warn` - warn (4)
+* `error` - err (3)
+* `dir` - notice (5)
+* `time`, `timeEnd` - notice (5)
+* `trace` - err (3)
+* `assert` - err (3)
+
+To log message with desired severity level you can use `send` function:
+
+ logger.send('message', 'alert');
+
+`send` function takes two arguments: message and optional severity level. By
+default, severity level is *notice*.
+
+## Additional loggers
+
+After importing *ain* already has default logger. Everything that was
+described above - just about it.
+
+If you need log message with different `TAG`, `facility` and `HOSTNAME`
+without touching default logger, you can get independent instance of logger
+by `get` function.
+
+ var logger = require('ain').set('node-test-app', 'daemon', 'devhost');
+ logger.warn('some warning');
+
+ var anotherLogger = logger.get(logger.tag, 'local0', logger.hostname);
+ anotherLogger.log('another messgage');
+
+`get` function takes three arguments - as well as `set` function and return
+new logger object. This object is just new instance of "logger" and has all
+*ain* functions (including `get`).
+
+
Please sign in to comment.
Something went wrong with that request. Please try again.