ArsenicLogger: Simple & Powerful logger with stack trace
Summary
Simple, easy to read log statements with stack trace in Node.js. There are a few other great loggers out there for Node.js, the inspiration to create our own was mainly driven by the need for both a stack trace and a colorized and easy to read output.
Installation
npm install arsenic-logger
Basic Usage
// Get a default logger instancevar Logger = ; // Start usingLogger;
Advanced Usage
// Get a default logger instancevar Logger = ; // Set some more advanced optionsLogger;Logger;Logger;Logger; // Beam your logs to papertrail (https://papertrailapp.com)Logger; // Filter log out to a function in a specific FilterLogger
Screen Shot
Options
The following options can be passed in when creating a Logger instance.
Field | Default | Description |
---|---|---|
maxDepth | 3 | The maximum depth of stack trace to display |
handleExceptions | false | Catch and log exceptions |
logTag | '' | A tag/label to use for this logger instance. Handy when combined with filtering or using ArsenicLogger |
echoMemory | false | Echo the current memory usage to the console (if console logging) |
echoCPU | false | Echo the CPU usage to the console (if console logging) |
locale | 'en' | Set the locale, used for formatting the timestamp |
timestampPattern | 'ddd MMM DD h:mm:ss YYYY' | The timestamp pattern, see Moment.js for options |
timestamps | true | Echo timestamps to the console, if console logging |
All of these options can also be set through through the following methods;
setTransport
By default the logger logs to the console, however you can specify the transport(s) you wish to use.
Console & Color Theme
The default choice, but you can enable using;
Logger;
ArsenicLogger uses the excellent chalk module to colorize the output. You can over-ride the default theme by passing your own (see chalk for options), for example;
var defaultTheme = log : chalkblack debug : chalkgreen input : chalkblue info : chalkblue warn : chalkyellow error : chalkred fatal : chalkboldred exception : chalkboldwhitebgRed time : chalkgray trace : chalkgray Logger;
File
Write to a file using the file transport. This guarantees atomic writes and protects against race conditions.
Logger;
PaperTrail
To enable PaperTrail, you need to specify the host and port number given to you by papertrail.
Logger;
Multiple transports
You can use more than one transports by simply passing an array of transport options, for example to use the console and papertrail you can do the following;
Logger;
setLevel(level)
Set the log level for this Logger instance. Options are; debug
, info
, warn
, error
, fatal
.
setGlobalLevel(level)
Set the log level for all logger instances. This will over-ride the log level on all Logger instances.
setLabel(label)
Set the tag/label for the current Logger instance. Very useful when combined with filtering. For example you could set a different tag per module of your code, and then set a filter to only view log outout from a specific module.
setFilter(opts)
The method setFilter
can be used to give fine control over what logs are sent to the console. This supports function names, filenames and tags.
LoggerLoggerLogger
These can be combined, such as;
// Echo ONLY logs that match the filename and tagLogger
Also, you can pass an array or a single string into any of these options. In that case, the effect will be an OR, e.g.
// Echo logs that have the tag my-tag or my-other-tagLogger
echoTimestamps(toggle)
Turns time stamps on or off. Only applicable if logging to the console.
// Turn timestamps onLogger; // Example output// [Tue Oct 9:40:24 2014] testing inside a function {from line 35 of test.js ... // Turn time stamps offLogger;
setTimestampFormat(format)
You can set the timestamp format using the following command. Internally the Logger uses the moment library and so supports any format supported by moment, you can see the supported formats here.
As a convenience, this also turns timestamps on, so no need to call echoTimestaps(true)
.
// Set timestamp formatLogger; // Example output//[Tue, 9AM] [debug] testing inside a function {from line 36 of test.js ...
setLocale(local)
Set the time locale. The Logger supports any localed support by moment, for example 'fr'.
Logger; // Example output// [mar. oct. 10:01:24 2014] [debug] testing inside a function {from line 37 of test.js ...
echoCPUUsage(toggle)
The Logger can echo cpu usage information to the command line using the following commands, which can be combined. Note: the arsenic logger service automatically is sent this information.
Logger
In a similar fashion, the current 15 minute average CPU usage is sent to the console, for example;
[1.43% error] errortest {from line 14 of test.js,......}
echoMemoryUsage(toggle)
The Logger can echo current memory and cpu usage information to the command line using the following commands, which can be combined. Note: the arsenic logger service automatically is sent this information.
Logger
This will add the amount of memory used by the heap at the time an entry was logged. For example, the follow result shows the process was consuming 3.16GB of heap space when the Logger.error("errortest")
method was called.
[3.16GB error] errortest {from line 14 of test.js....}
Tagging
You can over-ride the label used for the logger instance using the following commands. These add a custom tag and other advanced options by using the 'advanced' version of the logging commands;
Logger; Logger; Logger; Logger; Logger;
Where tags
includes custom tags. The other args
are the same as the basic version of the Logging commands.
tags
can be either a string, or an array of strings. e.g. 'TestTag'
or ['This','Or','That']
where it will match on any of the tags in the array.
Here is an example;
var someObject = ;someObjectname = 'fred';someObjectdata = 56789;someObjectdate = ; Logger;
You can now filter output based on log level and also these advanced values using setFilter
, for example;
Logger;Logger; var someObject = ;someObjectname = 'fred';someObjectdata = 56789;someObjectdate = ; var anotherObject = ;anotherObjectname = 'bob';anotherObjectdata = 278; Logger; Logger;
Here, because the level was set to debug
and a the filter was set to the tag "TestTag" the only output from this would be from the 2nd debug statement.
This can be particulalry useful for large projects where you want to only see the logs from a specific section of code at a time.
Requirements
Requires the excellent callsite module (https://github.com/visionmedia/callsite)
npm install callsite
And also the Path module (http://nodejs.org/api/path.html)
npm install path
Advanced
For a more full featured logger, check out winston.
Donate
If you like this, and use it, please consider donating to help support future development.
Example Usage
There are 5 levels of logging
log debug info warn error fatal
Here is an example of how to use the logger.
Logger = ; Logger; Logger;Logger;Logger;Logger; var someObject = ;someObjectname = 'testing';someObjectdata = 56789;someObjectdate = ; Logger; { Logger; } var someclass = { Logger; } ;someclass; Logger; // A fatal call, that will call process.exitLogger; // Feed uncaught exceptions to the LoggerLogger; { throw "This is an exception!"; } ; Logger;
Suggestions
Feel free to contact me at mike@arsenicsoup.com if you want to help or have suggestions.
Thanks!
License
(The MIT License)
Copyright (C) 2012 by Ad Astra Systems, LLC;
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.