lancewalton / treelog

Allows logging in a tree structure so that comprehensive logging does not become incomprehensible

treelog

It is often necessary to understand exactly what happened in a computation: what went right, what went wrong, what was done with what, why it was done, and how a result was derived.

Such complex computations are trees, and so attempting to describe whats going on in a linear fashion is difficult to follow after the fact. What treelog offers is a means of writing a log together with a computation, with values computed on the way with all information relevant to the computation.

Logtree is a veritable complect of computation and description in perfect harmony.

TreeLog achieves this remarkable feat with a Writer monad writing to a Tree representing the hierarchical log of computation.

Getting TreeLog

Scala 2.13.x, 3.0.x and Cats 2.7.0:

libraryDependencies ++= Seq("com.casualmiracles" %% "treelog-cats" % "1.8.1")

TreeLog Examples

QuadraticRootsExample.scala and OptionsAndEithersExample.scala in the test package is the simplest way to see how to use TreeLog. FuturesExample.scala demonstrates how you can combine the results of several parallel computations.

The quadratic example does the extremely important job of logging the computation of roots of a quadratic equation. This:

root(Parameters(2, 5, 3)).run.written.shows

results in

Extracting root
Calculating Numerator
Calculating Determinant
Calculating b^2
Got b: 5.0
Got b^2: 25.0
Calculating 4ac
Got a: 2.0
Got c: 3.0
Got 4ac: 24.0
Got b^2 - 4ac: 1.0
Calculating sqrt(determinant)
Determinant (1.0) is >= 0
Got sqrt(determinant): 1.0
Got b: 5.0
Got -b: -5.0
Got -b + sqrt(determinant): -4.0
Calculating Denominator
Got a: 2.0
Got 2a: 4.0
Got root = numerator / denominator: -1.0

Or, in the case of a failure (when the roots are complex)

root(Parameters(2, 5, 10)).run.written.shows

gives

Extracting root: Failed
Calculating Numerator: Failed
Calculating Determinant
Calculating b^2
Got b: 5.0
Got b^2: 25.0
Calculating 4ac
Got a: 2.0
Got c: 10.0
Got 4ac: 80.0
Got b^2 - 4ac: -55.0
Calculating sqrt(determinant): Failed
Determinant (-55.0) is < 0: Failed

Older Releases

For Scala 2.12.x and scalaz 7.2.x:

libraryDependencies ++= Seq(
"com.casualmiracles" %% "treelog-scalaz-72x" % "1.4.3",
"org.scalaz" %% "scalaz-core" % "7.2.8")

For Scala 2.12.x and 2.11.x and scalaz 7.3.x:

libraryDependencies ++= Seq(
"com.casualmiracles" %% "treelog" % "1.4.10",
"org.scalaz" %% "scalaz-core" % "7.3.0-M18")

For Scala 2.12.x and cats 1.6.0:

libraryDependencies ++= Seq("com.casualmiracles" %% "treelog-cats" % "1.4.9")

For Scala 2.12.x and scalaz 7.1.x:

libraryDependencies ++= Seq(
"com.casualmiracles" %% "treelog-scalaz-71x" % "1.4.0",
"org.scalaz" %% "scalaz-core" % "7.1.11")

For Scala 2.11.x and scalaz 7.2.x:

libraryDependencies ++= Seq(
"com.casualmiracles" %% "treelog" % "1.3.0",
"org.scalaz" %% "scalaz-core" % "7.2.0")

For Scala 2.11.x and scalaz 7.1.x:

libraryDependencies ++= Seq(
"com.casualmiracles" %% "treelog" % "1.2.6",
"org.scalaz" %% "scalaz-core" % "7.1.7")

For Scala 2.10.x

libraryDependencies ++= Seq(
"com.casualmiracles" %% "treelog" % "1.2.2",
"org.scalaz" %% "scalaz-core" % "7.0.6")