PR

.gitignore

@@ -1,2 +1,3 @@
-target
-/log
+target
+/log
+.idea/

.scalafmt.conf

@@ -0,0 +1,2 @@
+version=2.3.2
+trailingCommas = always

README.md

@@ -0,0 +1,195 @@
+# Structured logging framework 4 Cats
+
+This repo contains experiments with possible implementations of structured logging with `cats-effect`.
+
+## Goals
+
+ * log commands are side-effecting programs, based on `cats-effect`
+ * objects provided to log commands should appear as JSON in logs
+   * they're searchable in Kibana
+   * we won't duplicate the objects in message itself to reduce size
+ * logs will contain appropriate context
+   * the context can be programmatically augmented
+   * works in a stack-like manner, including shadowing
+   * works well with `cats-effect` and related libraries (is not bound to `ThreadLocal`/fat JVM thread like slf4j's MDC)
+ * other useful metadata in logs
+   * timestamp
+   * file name
+   * line number
+   * loglevel as both string and number
+   * ... to be specified
+ * JSON keys will be just strings, at lest for the beginning
+
+## Features
+
+ * thin wrapper over `slf4j`
+    * each logging statement is inlined on the same line using macros
+    * rest of the logging pipeline works as expected
+ * JSON logging
+    * uses `logstash-logback-encoder` for JSON log formatting
+    * uses Jackson for the encoding of log parameters by default (imported by Logback Logstash encoder anyway; can be overridden if necessary)
+ * CPU expensive or side-effectful actions can be passed to logs
+    * will be memoized == computed only once or never at all, if log level too low
+
+## Interface
+
+```scala
+trait LoggingContext[F[_]] {
+  type Self <: LoggingContext[F]
+  def withArg[A](name: String,
+                 value: => A,
+                 toJson: Option[A => String] = None): Self
+  def withComputed[A](name: String,
+                      value: F[A],
+                      toJson: Option[A => String] = None): Self
+  def withArgs[A](map: Map[String, A], toJson: Option[A => String] = None): Self
+  def use[A](inner: F[A]): F[A]
+}
+
+trait Logger[F[_]] {
+  type Self <: Logger[F]
+  def withArg[A](name: String,
+                 value: => A,
+                 toJson: Option[A => String] = None): Self
+  def withComputed[A](name: String,
+                      value: F[A],
+                      toJson: Option[A => String] = None): Self
+  def withArgs[A](map: Map[String, A], toJson: Option[A => String] = None): Self
+  // excerpt for `info` logging
+  def info: LoggerInfo[F]
+  //...
+}
+
+trait ContextLogger[F[_]] extends LoggingContext[F] with Logger[F] {
+  type Self <: ContextLogger[F]
+}
+class LoggerInfo[F[_]]() {
+  def apply(message: String): F[Unit] = macro ???
+  def apply(message: String, throwable: Throwable): F[Unit] = macro ???
+}
+```
+
+## Usage
+
+```scala
+def program(logger: ContextLogger[Task]): Task[Unit] = {
+  val ex = new InvalidParameterException("BOOOOOM")
+  for {
+    _ <- logger
+      .withArg("a", A(1, "x", Array[Byte](127)))
+      .withArg("o", o)
+      .info("Hello Monix")
+    _ <- logger.warn("Hello MTL", ex)
+    _ <- logger.withArg("x", 123).withArg("o", o).use {
+      logger.withArg("x", 9).info("Hello2 meow")
+    }
+  } yield ()
+}
+```
+
+### Multiple contexts
+```scala
+_ <- logger
+  .withArg("a", A(1, "x", Array[Byte](127)))
+  .withArg("o", o)
+  .info("Hello Monix")
+```
+```json
+{
+  "@timestamp": "2020-01-08T02:31:16.503+01:00",
+  "@version": "1",
+  "message": "Hello Monix",
+  "logger_name": "slf4cats.example.Main$",
+  "thread_name": "scala-execution-context-global-13",
+  "level": "INFO",
+  "level_value": 20000,
+  "a": {
+    "x": 1,
+    "y": "x",
+    "bytes": "fw=="
+  },
+  "o": {
+    "a": {
+      "x": 123,
+      "y": "Hello",
+      "bytes": "AQID"
+    },
+    "b": [
+      false,
+      true
+    ],
+    "c": {
+      "r": 456
+    }
+  },
+  "application": "loggingexperiment",
+  "caller_class_name": "slf4cats.example.Main$",
+  "caller_method_name": "$anonfun$program$5",
+  "caller_file_name": "Main.scala",
+  "caller_line_number": 66
+}
+```
+
+### Logging exception
+```scala
+_ <- logger.warn("Hello MTL", ex)
+```
+```json
+{
+  "@timestamp": "2020-01-08T02:31:16.520+01:00",
+  "@version": "1",
+  "message": "Hello MTL",
+  "logger_name": "slf4cats.example.Main$",
+  "thread_name": "scala-execution-context-global-13",
+  "level": "WARN",
+  "level_value": 30000,
+  "stack_trace": "java.security.InvalidParameterException: BOOOOOM\n\tat slf4cats.example.Main$.program(Main.scala:61)\n...",
+  "application": "loggingexperiment",
+  "caller_class_name": "slf4cats.example.Main$",
+  "caller_method_name": "$anonfun$program$9",
+  "caller_file_name": "Main.scala",
+  "caller_line_number": 67
+}
+```
+
+### Context overriding
+```scala
+_ <- logger.withArg("x", 123).withArg("o", o).use {
+  logger.withArg("x", 9).info("Hello2 meow")
+}
+```
+```json
+{
+  "@timestamp": "2020-01-08T02:31:16.539+01:00",
+  "@version": "1",
+  "message": "Hello2 meow",
+  "logger_name": "slf4cats.example.Main$",
+  "thread_name": "scala-execution-context-global-13",
+  "level": "INFO",
+  "level_value": 20000,
+  "x": [
+    1,
+    2,
+    3
+  ],
+  "o": {
+    "a": {
+      "x": 123,
+      "y": "Hello",
+      "bytes": "AQID"
+    },
+    "b": [
+      false,
+      true
+    ],
+    "c": {
+      "r": 456
+    }
+  },
+  "application": "loggingexperiment",
+  "caller_class_name": "slf4cats.example.Main$",
+  "caller_method_name": "$anonfun$program$16",
+  "caller_file_name": "Main.scala",
+  "caller_line_number": 69
+}
+```

build.sbt

@@ -4,14 +4,92 @@ version := "0.1"
 
 scalaVersion := "2.12.10"
 
-val circeVersion = "0.11.1"
-
-libraryDependencies ++= Seq(
-  "org.slf4j" % "slf4j-api" % "1.7.29",
-  "ch.qos.logback" % "logback-classic" % "1.2.3",
-  "net.logstash.logback" % "logstash-logback-encoder" % "6.2",
-  "io.circe" %% "circe-core" % circeVersion,
-  "io.circe" %% "circe-generic" % circeVersion,
-//  "org.typelevel" %% "cats-effect" % "2.0.0",
-  "dev.zio" %% "zio" % "1.0.0-RC16",
-)
+lazy val Version = new {
+  val slf4j = "1.7.29"
+  val logback = "1.2.3"
+  val jacksonScala = "2.10.2"
+  val logstashLogback = "6.2"
+  val monix = "3.1.0"
+  val catsMtl = "0.7.0"
+  val catsEffect = "2.0.0"
+  val meowMtl = "0.4.0"
+  val circe = "0.13.0-M2"
+}
+
+lazy val root = project
+  .in(file("."))
+  .settings(
+    name := "slf4cats",
+    publish / skip := true, // doesn't publish ivy XML files, in contrast to "publishArtifact := false"
+  )
+  .aggregate(
+    slf4catsApi,
+    slf4catsImpl,
+    slf4catsCirce,
+    slf4catsExample,
+  )
+
+lazy val slf4catsApi = project
+  .in(file("slf4cats-api"))
+  .settings(
+    name := "slf4cats-api",
+    libraryDependencies ++= Seq(
+      "org.slf4j" % "slf4j-api" % Version.slf4j,
+      "org.typelevel" %% "cats-effect" % Version.catsEffect,
+      "org.scala-lang" % "scala-reflect" % scalaVersion.value,
+    ),
+  )
+
+lazy val slf4catsImpl = project
+  .in(file("slf4cats-impl"))
+  .settings(
+    name := "slf4cats-impl",
+    libraryDependencies ++= Seq(
+      "net.logstash.logback" % "logstash-logback-encoder" % Version.logstashLogback,
+      "org.typelevel" %% "cats-mtl-core" % Version.catsMtl,
+      "org.typelevel" %% "cats-effect" % Version.catsEffect,
+    ),
+  )
+  .dependsOn(slf4catsApi)
+
+lazy val slf4catsMonix = project
+  .in(file("slf4cats-monix"))
+  .settings(
+    name := "slf4cats-monix",
+    libraryDependencies ++= Seq(
+      "io.monix" %% "monix" % Version.monix,
+      "com.olegpy" %% "meow-mtl-monix" % Version.meowMtl,
+    ),
+  )
+  .dependsOn(slf4catsImpl)
+
+lazy val slf4catsCirce = project
+  .in(file("slf4cats-circe"))
+  .settings(
+    name := "slf4cats-circe",
+    libraryDependencies ++= Seq(
+      "io.circe" %% "circe-core" % Version.circe,
+    ),
+  )
+  .dependsOn(slf4catsApi)
+
+lazy val slf4catsJackson = project
+  .in(file("slf4cats-jackson"))
+  .settings(
+    name := "slf4cats-jackson",
+    libraryDependencies ++= Seq(
+      "com.fasterxml.jackson.module" %% "jackson-module-scala" % Version.jacksonScala,
+    ),
+  )
+  .dependsOn(slf4catsApi)
+
+lazy val slf4catsExample = project
+  .in(file("slf4cats-example"))
+  .settings(
+    name := "slf4cats-example",
+    libraryDependencies ++= Seq(
+      "ch.qos.logback" % "logback-classic" % Version.logback,
+      "io.circe" %% "circe-generic" % Version.circe,
+    ),
+  )
+  .dependsOn(slf4catsMonix, slf4catsCirce, slf4catsJackson)

project/plugins.sbt

@@ -0,0 +1 @@
+addSbtPlugin("io.github.davidgregory084" % "sbt-tpolecat" % "0.1.10")