Logging

Logging

TODO: This documentation describes logging as it is the logging branch. I have added a pull request for those changes. If you want to follow along, you will need to use the branch or accept the pull request.

The Google Closure library provides extensive support for logging. A simple Clojure wrapper for this API is provided in the file src/lib/cljs/one/logging.cljs which contains the one.logging namespace.

The Library

Before explaining the details, let's start with a simple example. Start the sample application and a ClojureScript REPL. Open a JavaScript console so that you will be able to see log messages as they are printed below and then evaluate the following forms.

(in-ns 'one.logging)
(def example-logger (get-logger "wiki.examples"))
(info example-logger "Hello")

In the example above, we create a logger, giving it a name, and then use the logger to log the message "Hello" at the info logging level. You may have noticed that nothing happened. That is actually a feature. Log messages are not displayed until you explicitly indicate where they should be displayed and at what level.

Currently, log messages can be displayed in the JavaScript console or in a separate window.

Use the console-output function to create a log viewer which will display log messages in the JavaScript console. The start-display function will cause messages to start printing in the console.

(def console-out (console-output))
(start-display console-out)
(info example-logger "Hello")

You should now see log messages being printed to the console. The default format for printing log messages is:

[time] [logger name] message

The time that is displayed in the number of seconds since the application started.

Log Clojure data

You will often want to log Clojure data to the console.

(info example-logger {:a "message"})

This prints something like...

[138.626s] [wiki.examples] [object Object]

...which is not very helpful. To achieve the desired result, use pr-str to print the Clojure data to a string before printing to the console.

(info example-logger (pr-str {:a "message"}))

One of the many joys that you will experience while working with ClojureScript is the joy of copying a large printed data structure from the console into the REPL and then working with it as you would with any other Clojure data.

You can tell a log viewer to stop printing by calling the stop-display function.

(stop-display console-out)

If you executed the above command, you can reverse it again simply by running (start-display console-out) as before.

logging levels

In the examples above, we have been logging at the info level. The logging library supports seven levels:

• severe
• warning
• info
• config
• fine
• finer
• finest

By default, the output logging level is set to config. The current logging level will print all log messages at that level or higher.

The following form will print all log messages except for "FINE".

(do (severe example-logger "SEVERE")
    (warning example-logger "WARNING")
    (info example-logger "INFO")
    (config example-logger "CONFIG")
    (fine example-logger "FINE"))

Use the set-level function to change the logging level for a logger.

(set-level example-logger :fine)

Try logging all of the messages above with different logging levels.

Fancy logger window

If the browser you are using does not have a console window or your would like to view log messages in a separate window, you may use the fancy logging view.

(def fancy-out (fancy-output "Example Output Window"))

Use the start-display and stop-display functions to start and stop printing to this window.

The sample application

The sample application is set up to log all events. This is implemented in the file src/app/cljs/one/sample/logging which contains the one.sample.logging namespace.

Logging of all events is added to the application without having to modify any existing code.

(dispatch/react-to (constantly true)
                   (fn [t d] (log/info logger (str (pr-str t) " - " (pr-str d)))))

In the code above, a reaction is created which will react to any event and log it at the info logging level.

By default, log messages are not printed anywhere. To start viewing events in the console, create a console log viewer and start it as described above.

(start-display (console-output))

You should now see events as you interact with the application.