Repository files navigation

Shrimp-Log is smallClojureScript logging library.
It requiresNode.js and is built on top ofShrimp andRed Lobster.
Anyone looking for a mature logging library full of features should look elsewhere (e.g.Timbre).
The idea behind Shrimp-Log is to have a lightweight library with enough features for small projects onLumo.

If you useLeiningen add shrimp-log to the dependencies in yourproject.clj file.

:dependencies [...                [shrimp-log"0.1.0-SNAPSHOT"]]

For Lumo you could download the dependencies with Leiningen/Maven and specify the libraries on the CLI this way:

$ lumo -D org.clojars.pepzer/redlobster:0.2.2,shrimp:0.1.1-SNAPSHOT,shrimp-log:0.1.0-SNAPSHOT

To run a REPL you could either uselein figwheel (optionally with rlwrap):

$ rlwrap lein figwheel

With Node.js and npm installed open a shell, navigate to the root of the project and run:

$ npm install ws$ node target/out/shrimp-log.js

Then the REPL should connect in thelein figwheel window.

With Lumo installed just run thelumo-repl.cljsh script:

$ bash lumo-repl.cljsh

This will run the REPL and will also listen on the port12345 and hostlocalhost for connections.
You could connect with Emacs and Clojure Minor Mode.

To use the library require core and desired macros:

(require '[shrimp-log.core:refer [trace* debug* info* warn* error* spy*]])(use-macros '[shrimp-log.macros:only [trace debug info warn error spy]])(trace"test trace %d"1);; => 2017-10-27T20:35:24.135Z - TRACE [cljs.user] - test trace 1(trace*"readme""test trace %d"2);; => 2017-10-27T20:35:27.221Z - TRACE [readme] - test trace 2

All logging methods in shrimp-log have two variants, a macro and a function (that ends with*). A call totrace,debug,info,warn anderror only requires one argument, a message, that supports the format syntax and could be followed by any number of additional arguments.
The functionstrace*,debug*,info*,warn*anderror* require a tag as first argument, it could be anything, it's converted to string and the only "special" value is the qualified keyword::- that gets converted to just the namespace.

(let [r (range10)]  (info*::-"count is %d" (count r)));; => 2017-10-27T20:47:44.935Z - INFO [cljs.user] - count is 10

error/error* by default behave like the others, but the settingthrow-on-err? could be enabled to cause a throw after the log.
spy wraps an expression and logs the result besides returning it. The first argument tospy must be the log level, for the functionsspy* a tag is required as second argument before the expression. Pretty printing for the logged value is enabled by default and could be controlled through thepretty-print? setting.

(spy:debug (range10));; => 2017-10-27T21:01:27.691Z - DEBUG [cljs.user] -;; => (0 1 2 3 4 5 6 7 8 9)(spy*:info::spy (reduce #(assoc %1 %2 %1) {} (range4)));; => ...;; => 2017-10-27T21:00:13.365Z - INFO [:cljs.user/spy] -;; => {0 {},;; =>  1 {0 {}},;; =>  2 {0 {}, 1 {0 {}}},;; =>  3 {0 {}, 1 {0 {}}, 2 {0 {}, 1 {0 {}}}}}

Settings could be modified either by calling the methodset-opts! with key-value pairs:

(require '[shrimp-log.core:as l])(l/set-opts!:buffer-size100:out-file:log-file:pretty-printfalse)

Or by creating a file in the current working directory calledshrimp-log.clj and containing a Clojure map:

;; shrimp-log.clj{:buffer-size100:pretty-print?false:throw-on-err?true:log-level:warn}

Current available settings are the following:

This defines what logs are allowed, by default all levels are printed so this value is set to:trace. Possible values are:trace,:debug,:info,warn,:error and:none.

Currently the logger could only print to screen or to a file. This setting specifies the filename of the log file, there are two special keywords that could be used instead of a filename:

• :stdout which is the default and means that messages are printed on the console,
• :log-file that will cause the creation of a log file with the same name of the current folder and extension.log.

A boolean flag to enable/disable pretty printing forspy/spy*, defaults totrue.

A boolean flag, whentrue an error is thrown when callingerror/error* after the log has been printed, but only if the log level is not equal to:none.
The throw is asynchronous and couldn't be handled with a try/catch. This setting should be enabled only if the intended behaviour for an error message is to force the application to exit. Defaults tofalse.

This setting allows to change the format of the timestamp for logs, supported values are:

• :iso - ISO date string format, the default,
• :utc - UTC date string format,
• :locale - locale date string format,
• :date - only the date,
• :time - only the time,
• :locale-date - only the date (locale format).
• :locale-time - only the time (locale format).

This controls the dimension of the buffer for the log channel where all logs are sent before de-queue and print, any non-negative integer is allowed and it defaults to1024.
If the buffer is full subsequent log messages will be silently dropped, hence this setting should be modified accordingly to the rate log messages are produced.

This value in milliseconds defines the amount of time the logger will pause between two subsequent prints.:log-delay limits the rate of logging, an high value could cause the buffer to be filled hence:buffer-size should be modified accordingly. The default value for:log-delay is 10 milliseconds.

To run the tests with Leiningen use:

$ lein cljsbuild test

With Lumo:

$ bash lumo-test.sh

This is an early release, bugs should be expected and future releases could break the current API.

Giuseppe Zerbo,giuseppe (dot) zerbo (at) gmail (dot) com.

Copyright © 2017 Giuseppe Zerbo.
Distributed under theMozilla Public License, v. 2.0.