RCL - Remote Client Logging
A websocket bridge allowing persistent debug logging from client to server/local node instance
jsoverson.github.com/rcl
Official doc atGetting started
Include the logging client in your application
For AMD/RequireJS, It is still recommended that you add it as a script
source for easy removal with grunt-preprocess
require
rcl
npm package
Install the $ sudo npm install -g rcl
rcl
Run $ rclRunning "rcl" task info - socket.io started[2012-09-25 09:14:48.863] [DEBUG] rcl - Connected on port 8888
Log to your heart's content
rcl;rcl;
Logs will show up in your console, rcl (if running), and any client connected to your rcl instance.
Usage
Include the client source file in your client application and you can use the following commands immediately
rclrclrclrclrcl
Getting the client source file
You can download it at raw.github.com/jsoverson/rcl/master/src/rcl.js or you can output the version that matches your npm install via
$ rcl rcl.js > path/for/rcl.js
Specify a different host to connect to
rcl;
Configure log levels
rcl;
Turn off logging
rclserver = false; // || truerclclient = false; // || true
Sprintf like formatting
For console logging, the support is the native console's capabilities. Terminal and web client support use string-format syntax (mostly the same).
How to strip logging
Two grunt tasks have been extracted from this project and packaged independently, grunt-strip and grunt-preprocess. Both have more documentation at their project sites, but basic usage is below.
Both are designed to be run as part of a build chain, usually after concatenation and before minification.
Installing grunt tasks
Add grunt-strip
and grunt-preprocess
to your package.json's dependencies hash, or run
$ npm install --save grunt-strip grunt-preprocess
Remember to load these tasks as part of your gruntfile
grunt;grunt;
grunt-preprocess
Removing the script source using Syntax
<!-- exclude --><!-- endexclude -->
Configuration in your Gruntfile
preprocess : main : src : 'src/index.html' dest : 'build/index.html'
See grunt-preprocess for advanced configurations
grunt-strip
Removing the log statements using Example grunt configuration
strip : main : src : 'src/main.js' dest : 'build/main.built.js' nodes : 'rcl''console'
See grunt-strip for advanced configurations
FAQ
Why use RCL?
You are programming in a language stretched beyond its design across environments spanning years of standards and are delivering your source code directly to the client to be run outside of your control.
It's hard but so, so awesome and you are a brilliant genius to have gotten this far.
At the base, RCL is just a websocket bridge to log from your browser to another client. It could be anything, but right now is something like a server, another browser tab, or a mobile device.
RCL aggregates and classifies your log messages so that they are configurable in verbosity, using log4js on the server side for more flexibility.
Does my application break if rcl is not running?
No, you will still get console messages in your browser.
Why is this not recommended for production logging?
Because logging will bloat your code, expose intent behind your logic, and be an extra burden on the client. But, that said, if production logging is important enough to you, then try it out and we'd love to hear how it works.
Our primary frustration for large JavaScript projects is the lack of extensive logging during development and testing. This is a solution to that works very well and allows for fewer issues to occur in production.
One avenue being considered is to have grunt-strip support removing properties of nodes so that only certain log levels can be removed.
rcl
as a grunt plugin
RCL was initially written with grunt in mind and can be used as a grunt plugin in a task chain.
Install next to your gruntfile with
$ npm install rcl
Add this line to your gruntfile
grunt;
Example task chain
grunt;
Configuration as grunt plugin
rcl : port : 3000 wait : true
log4js configuration
Please visit the project page for documentation log4js-node
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using [grunt][grunt].
Release History
- v0.3.4 Fix for usage via AMD and requirejs
- v0.3.3 Fixes to client
- v0.3.2 Small fallback for client error
- v0.3.1 Fixed some rcl client bugs
- v0.3.0 Abstracted grunt from direct cli use. Removed async for better usage as a grunt task.
- v0.2.4 Client use fix
- v0.2.3 Bugfixes
- v0.2.2 Fixed new use cases
- v0.2.0 Initial release
License
Copyright (c) 2012 Jarrod Overson
Licensed under the MIT license.