Fork me on GitHub

RCL

Remote Client Logging

Github

Tweet

What is RCL?

RCL is a browser library and server client that allows you to log extensively from a JavaScript application to a remote consumer.

What do I get?

Loads of beautiful logs viewable from multiple clients all the while not bloating your production code.

Development priority

grunt-strip and grunt-preprocess were developed in parallel to remove all your logging before production deployment.

Use rcl

Code example

And get this

Terminal output

And this


Getting started

Include the logging client in your application

<script src="path/to/rcl.js"></script>

Install the rcl npm package

$ sudo npm install -g rcl

Run rcl

$ rcl
Running "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.info("Hi, I am your app.");
rcl.debug("Foo is now : %s", 42);

Logs will show up in your console, rcl (if running), and any client connected to your rcl instance.


Usage

Include the source file in your client application and you can use the following commands immediately

rcl.info()
rcl.debug()
rcl.trace()
rcl.error()
rcl.warn()

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.connect('127.0.0.1','8888');

Configure log levels

rcl.logLevel(rcl.INFO);

Turn off logging

rcl.server = false; // || true
rcl.client = 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.


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.

For more information about Grunt, please visit gruntjs.com

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.npmTasks('grunt-strip');
grunt.npmTasks('grunt-preprocess');

Removing the script source using grunt-preprocess

Syntax

<!-- exclude -->
<script src="path/to/rcl.js"></script>
<!-- endexclude -->

Configuration in your Gruntfile

preprocess : {
  main : {
    src : 'src/index.html',
    dest : 'build/index.html'
  }
}

See grunt-preprocess for advanced configurations

Removing the log statements using grunt-strip

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.

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 tell us all how it works.

Our primary frustration for large JavaScript projects is the lack of extensive logging during development and testing. Better transparency in development leads to fewer bugs 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.loadNpmTasks('rcl');

Example task chain

grunt.registerTask('dev', 'server rcl watch');

Configuration as grunt plugin

rcl : {
    port : 3000,
      wait : true
}

log4js configuration

Please visit the project page for documentation log4js-node