treelog

by lancewalton

lancewalton / treelog

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

203 Stars 20 Forks Last release: Not found MIT License 334 Commits 17 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

treelog

Gitter

Build Status

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

For Scala 2.13.x and cats 2.0.0:

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

For Scala 2.12.x and cats 2.0.0:

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

For Scala 2.12.x amd 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 scalaz 7.2.x:

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

Older Releases

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")

Quick Start TL;DR

import treelog.LogTreeSyntaxWithoutAnnotations._
import scalaz._, Scalaz._

// syntax for logging something val one: DescribedComputation[Int] = 1 ~> "The number one"

// syntax for logging something and include the value in the log val oneA: DescribedComputation[Int] = 1 ~> (v => s"The value is $v")

// Extract the result ( a scalaz./ ) and log (a LogTree which is a type alias for scalaz.Tree[LogTreeLabel[A]]) val v: /[String, Int] = one.run.value val logtree: LogTree = one.run.written

// turn the LogTree into a String val logTreeString = logtree.shows

// In for comprehensions with a top level description val result: DescribedComputation[Int] = "Adding up" ~< { for { foo ("foo = " + _) bar ("bar = " + _) foobar ("foobar = " + _) } yield foobar }

println(result.run.written.shows) // prints: // Adding up // foo = 1 // bar = 2 // foobar = 3

Now don't be lazy and read the scaladoc.

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

Annotations

AnnotationsExample.scala shows how nodes in the log tree can be annotated with important information for your program to use later. This is useful, for example, when you want to audit a process that affects multiple entities, and you want to make sure that the audit trail is associated with each of the modified entities. You can use the annotation facility to carry the key (or something richer) for each modified entity.

Resources

  • Channing's blog at typelevel.
  • @oranda's project to give TreeLog a GUI, the ScalaJS ReactTreeView

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.