A logging framework that brings compile-time safety to your log statements. Specify which data is encodable and how exactly the encoding should take place. Then the compiler prevents you from creating invalid log statements.

WARNING This library is currently in the prototyping phase. Don't expect working code and don't even try to use it!

Basic Idea

Add this to your build.sbt:

libraryDependencies += "de.kaufhof.ets" %% "ets-logging-core" % "0.1.0-SNAPSHOT"

Given some domain objects:

sealed trait Epic extends Product
object Epic {
  case object FeatureA extends Epic
  case object FeatureB extends Epic
}
case class VariantId(value: String)
case class Variant(id: VariantId, name: String)
case class TestClass(a: Int, b: String)

Start defining a set of Keys you wish to use within your logs events:

import de.kaufhof.ets.logging._
import de.kaufhof.ets.logging.syntax._

import java.time.Instant
import java.util.UUID

object StringKeys extends LogKeysSyntax[String] with DefaultStringEncoders {
  val Logger:        Key[Class[_]] =      Key("logger")      .withImplicitEncoder
  val Level:         Key[Level] =         Key("level")       .withImplicitEncoder
  val Message:       Key[String] =        Key("msg")         .withImplicitEncoder
  val Timestamp:     Key[Instant] =       Key("ts")          .withExplicit(Encoder.fromToString)
  val VariantId:     Key[VariantId] =     Key("variantid")   .withExplicit(Encoder[VariantId].by(_.value))
  val VariantName:   Key[String] =        Key("variantname") .withImplicitEncoder
  val SomeUUID:      Key[UUID] =          Key("uuid")        .withImplicitEncoder
  val RandomEncoder: Key[Random] =        Key("randenc")     .withExplicit(Encoder[Random].by(_.nextInt(100)))
  val RandomEval:    Key[Int] =           Key("randeval")    .withImplicitEncoder
  val Epic:          Key[Epic] =          Key("epic")        .withExplicit(Encoder[Epic].by(_.productPrefix))
}

LogKeysSyntax[String] contains a small DSL to setup keys. That includes all neccessary syntax to specify Key s and associate Encoder s to it. Key instances require an id of type string and an Encoder. Encoder s are used to encode values into String as indicated by the type parameter in this case. DefaultStringEncoders is a set of implicit Encoder definitions for the most common types. Some of the most common types are; Int, Long, Double, UUID and so forth. These most common type Encoders facilitate selecting an Encoder for the domain specific Key s. Existing Encoder instances can be used to derive new Encoder instances, like depicted above.

Next provide a configuration combining the previously defined Keys and an optional set of Decomposer instances.

object StringLogConfig extends DefaultLogConfig[String, Unit] with DefaultStringEncoders {
  override type Combined = String
  override def combiner: LogEventCombiner[String, String] = StringLogEventCombiner
  override def appender: Appender = StdOutStringLogAppender
  override def rootLevel: Level = Level.Info

  object Decomposers extends Decomposer2DecomposedImplicits[String] {
    import syntax._
    implicit lazy val variantDecomposer: Decomposer[Variant] = variant =>
      Decomposed(
        Keys.VariantId ~> variant.id,
        Keys.VariantName ~> variant.name
    )
    implicit lazy val epicDecomposer: Decomposer[Epic] = epic => Decomposed(Keys.Epic ~> epic)
  }

  val syntax = ConfigSyntax(StringKeys, Decomposers)
  override def predefKeys: PredefKeys = syntax.Keys
}

Provide a logger instance called log via mixin into your class/trait/object using the above config. Then use it to log different attributes in combination with a message:

object Main extends StringLogConfig.LogInstance {
  val variant: Variant = Variant(VariantId("VariantId"), "VariantName")
  val uuid: UUID = java.util.UUID.fromString("723f03f5-13a6-4e46-bdac-3c66718629df")

  // use standard log methods with severity for the log level and a message
  log.info("test234")
  log.debug("test123") // will be omitted due to configured rootLevel
  // provide additional information with an arbitrary amount of key value pairs, called attributes
  log.error("test345", Keys.VariantId ~> variant.id, Keys.SomeUUID -> uuid)
  // use the generic event method to construct arbitrary log events without any predefined attributes
  log.event(Keys.VariantId ~> variant.id, Keys.SomeUUID -> uuid, Keys.Timestamp ~> Instant.MIN)
  // inputs to encoders are contravariant and therefore directly accept instances of the key-types's subtypes
  log.info("""yay \o/""", Keys.Epic -> Epic.FeatureA)
  // or pass any amount of decomposable objects
  // this requires an implicit decomposer to be in scope
  // then the decomposer will decompose the available attributes for you
  import encoding.string.StringLogConfig.syntax.decomposers._
  log.event(variant)
  // inputs to decomposers are contravariant as well and therefore accept instances of the input-types's subtypes
  log.info("""yay \o/""",  Epic.FeatureA)
}

Also take look into the short self-contained complete compliable example under: test/Main.scala

Possible output for string encoding as shown above could then look like this:

level -> Info | logger -> de.kaufhof.ets.logging.test.Main$README$ | msg -> test234 | ts -> 2019-01-25T19:39:52.594Z
level -> Error | logger -> de.kaufhof.ets.logging.test.Main$README$ | msg -> test345 | ts -> 2019-01-25T19:39:52.629Z | uuid -> 723f03f5-13a6-4e46-bdac-3c66718629df | variantid -> VariantId
logger -> de.kaufhof.ets.logging.test.Main$README$ | ts -> -1000000000-01-01T00:00:00Z | uuid -> 723f03f5-13a6-4e46-bdac-3c66718629df | variantid -> VariantId
epic -> FeatureA | level -> Info | logger -> de.kaufhof.ets.logging.test.Main$README$ | msg -> yay \o/ | ts -> 2019-01-25T19:39:52.636Z
logger -> de.kaufhof.ets.logging.test.Main$README$ | ts -> 2019-01-25T19:39:52.643Z | variantid -> VariantId | variantname -> VariantName
epic -> FeatureA | level -> Info | logger -> de.kaufhof.ets.logging.test.Main$README$ | msg -> yay \o/ | ts -> 2019-01-25T19:39:52.650Z
level -> Info | logger -> de.kaufhof.ets.logging.test.Main$Slf4j$ | msg -> test234 | ts -> 2019-01-25T19:39:52.707Z
level -> Info | logger -> test | msg -> Log with slf4j | ts -> 2019-01-25T19:39:52.723Z
level -> Info | logger -> de.kaufhof.ets.logging.test.Main$Configurable$ | message -> test-configurable | timestamp -> 2019-01-25T19:39:52.924Z

Configurable

In some situations it is necessary to encode into different types depending on the runtime configuration. As a developer it would be convenient to see a compact string output but during local development. However, in production it is often required to log JSON instead of string. The de.kaufhof.ets.logging.test.encoding.configurable.TupledLogConfig show cases this at test/encoding/configurable.scala. It makes use of the DefaultPairEncoders[String, Json] to encode into a tuple (String, Json). The used encoders help to make sure that attributes given to the logger do only compile if both encoders are available. Encoders are passed into a combiner which actually evaluates the values and applies the encoding. The used TupleToEitherCombiner allows to resort to only one of both alternatives at runtime. The interesting part to decide this is the takeLeft(e: LogEvent[(String, Json)]): Boolean method. Implement an appropriate expression to decide which alternative the combiner should keep.

override def combiner: EventCombiner = new TupleToEitherCombiner[String, Json] {
  // setup logic to either take left or right
  override def takeLeft(e: LogEvent[(String, Json)]): Boolean = true

  override def combiner1: LogEventCombiner[String, String] = StringLogEventCombiner
  override def combiner2: LogEventCombiner[Json, Json] = JsonLogEventCombiner
}

Module Layout

The project is organized as a maven multi module project. The idea is that the ets-logging-core doesn't deliver any dependencies. Code fragments that require any dependencies are delivered as sub modules. Any sub module requires the ets-logging-core to work properly. Not all planned sub modules are already available yet. Artificats available only during prototyping will disappear once the project is stable.

<repository-root>
├── ets-logging-apisandbox       !!! only during prototyping !!! organized with sbt
├── ets-logging-parent           parent pom project to share configs between sub modules
├── ets-logging-core             general api without dependencies
├── ets-logging-actor            akka.actor.Actor specific predefined keys and encoders
├── ets-logging-playjson         play.JsValue encoders
├── ets-logging-circejson        circe.Json encoders
├── ets-logging-catsio           cats.effect.IO appender
├── ets-logging-slf4j            org.slf4j.spi.SLF4JServiceProvider implementation to gather events from sfl4j
├── ets-logging-logstash         !!! not available yet !!! slf4j.Marker encoders
├── ets-logging-mdc              !!! not available yet !!! derive decomposer from case classes
├── ets-logging-shapeless        !!! not available yet !!! derive decomposer from case classes
└── ets-logging-usage            example usage combining all modules

ets-logging-apisandbox

This is the place to lay down the target api. Furthermore, it is used to test some api aspects. Aspects include: General API Look And Feel, Type inference, Performance, Physical Module Layout, Example Configuration. To cover all aspects, all required dependencies are available at once in a single sbt build. Aspects are covered in separate packages as single scala files. Physical modules that emerge are developed as objects within those files. Names are still very volatile.

ets-logging-slf4j

This module helps to integrate emitted log4j log events into the ets-logging framework.

Necessary steps:

• Implement an EtsSlf4jSpiProvider
• Setup ServiceLoader SPI binding

The simplest setup just takes a previously created LogConfig instance:

class Slf4jProvider extends EtsSlf4jSpiProvider[String, Unit] {
  override def config: DefaultLogConfig[String, Unit] = StringLogConfig
}

Override some default settings by overriding the respective methods:

class Slf4jProvider extends EtsSlf4jSpiProvider[String, Unit] {
  override def config: DefaultLogConfig[String, Unit] = StringLogConfig

  override def logMarker: EtsSlf4jSpiProvider.LogAttributeResolver[E] = {
   case m: ExtendedTestMarker => StringKeys.ExtendedTestMarker -> m
   case m: TestMarker => StringKeys.TestMarker -> m
  }

  override def levelForLogger(name: String, marker: Marker): Level = {
    if (marker.isInstanceOf[ExtendedTestMarker] && name == "myLogger") {
      Level.Debug
    } else {
      super.levelForLogger(name, marker)
    }
  }
}

To register a valid ServiceLoader SPI binding create a file called org.slf4j.spi.SLF4JServiceProvider. Put the fully-qualified class name of the class' implementation into it. Place the file on the classpath under META-INF/services. These commands illustrate the necessary steps for a maven like project residing in a directory called <project>.

mkdir -p <project>/src/main/resources/META-INF/services/
cd <project>/src/main/resources/META-INF/services/
echo "de.kaufhof.ets.logging.test.Slf4jProvider" > org.slf4j.spi.SLF4JServiceProvider

There is a runnable version of this example at test/encoding/slf4j.scala. Take de.kaufhof.ets.logging.test.Main.Slf4j as a reference to how it is being used.