tersesystems / blindsight

Blindsight is a Scala logging API with DSL based structured logging, fluent logging, semantic logging, flow logging, and context aware logging.

Version Matrix


Maven central License Apache-2.0

Travis CI Scala Steward badge

Suffering in silence, you check the logs for fresh telemetry.

You think: That can't be right.

-- Blindsight, Peter Watts

Blindsight is "observability through logging" where observability is defined as baked in high cardinality structured data with field types. The name is taken from Peter Watts' excellent first contact novel, Blindsight.

Blindsight is a logging library written in Scala that wraps SLF4J to add useful features that solve several outstanding problems with logging:


The only hard dependency is the SLF4J API, but the DSL functionality is only implemented for Logback with logstash-logback-encoder.

Blindsight is a pure SLF4J wrapper: it delegates all logging through to the SLF4J API and does not configure or manage the SLF4J implementation at all.

Versions are published for Scala 2.11, 2.12, and 2.13.


See Setup for how to install Blindsight.

Because Blindsight uses a very recent version of Logstash that depends on Jackson 2.11.0, you may need to update your dependencies for the jackson-scala-module if you're using Play or Akka.

libraryDependencies += "com.fasterxml.jackson.module" %% "jackson-module-scala" % "2.11.0"


Benchmarks are available here.


To use a Blindsight Logger:

import com.tersesystems.blindsight._

val logger = LoggerFactory.getLogger
logger.info("I am an SLF4J-like logger")

or in block form for diagnostic logging:

logger.debug { debug => debug("I am an SLF4J-like logger") }

Structured DSL:

import com.tersesystems.blindsight._
import com.tersesystems.blindsight.DSL._

logger.info("Logs with argument {}", bobj("array" -> Seq("one", "two", "three")))

Statement Interpolation:

val dayOfWeek = "Monday"
val temp = 72 

// macro expands this to:
// Statement("It is {} and the temperature is {} degrees.", Arguments(dayOfWeek, temp))
val statement: Statement = st"It is ${dayOfWeek} and the temperature is ${temp} degrees."


Marker/Argument Type Classes:

case class Lotto(
  id: Long,
  winningNumbers: List[Int],
  winners: List[Winner],
  drawDate: Option[java.util.Date]
) {
  lazy val asBObject: BObject = "lotto" ->
      ("lotto-id"          -> id) ~
        ("winning-numbers" -> winningNumbers) ~
        ("draw-date"       -> drawDate.map(_.toString)) ~
        ("winners"         -> winners.map(w => w.asBObject))

object Lotto {
  implicit val toArgument: ToArgument[Lotto] = ToArgument { lotto => Argument(lotto.asBObject) }

val winners =
  List(Winner(23, List(2, 45, 34, 23, 3, 5)), Winner(54, List(52, 3, 12, 11, 18, 22)))
val lotto = Lotto(5, List(2, 45, 34, 23, 7, 5, 3), winners, None)

logger.info("message {}", lotto) // auto-converted to structured output


implicit val nodeObjectToArgument: ToArgument[NodeObject] = ToArgument[NodeObject] { nodeObject =>

implicit val nodeObjectToMarkers: ToMarkers[NodeObject] = ToMarkers { nodeObject =>

implicit val nodeObjectToStatement: ToStatement[NodeObject] = ...

class Foo extends LDContext { // LDContext contains all the type safe bindings
  def sayHello(): Unit = {
    val willPerson = NodeObject(
      `@type`    -> "Person",
      `@id`      -> willId,
      givenName  -> "Will",
      familyName -> "Sargent",
      parent     -> parentId,
      occupation -> Occupation(
        estimatedSalary = MonetaryAmount(Currency.getInstance("USD"), 1),
        name = "Code Monkey"

    logger.info("as an argument {}", willPerson) // as an argument
    logger.info(Markers(willPerson), "as a marker") // as a marker
    logger.semantic[NodeObject].info(willPerson) // or as a statement

Fluent logging:

  .message("The Magic Words are")
  .argument(Arguments("Squeamish", "Ossifrage"))

Semantic logging:

// log only user events

// Works well with refinement types
import eu.timepit.refined.api.Refined
import eu.timepit.refined.string._
import eu.timepit.refined._
logger.semantic[String Refined Url].info(refineMV(Url)("https://tersesystems.com"))

Flow logging:

import com.tersesystems.blindsight.flow._

implicit def flowBehavior[B]: FlowBehavior[B] = new SimpleFlowBehavior

val arg1: Int = 1
val arg2: Int = 2
val result:Int = logger.flow.trace(arg1 + arg2)

Conditional logging:

logger.withCondition(booleanCondition).info("Only logs when condition is true")

logger.info.when(booleanCondition) { info => info("when true") }

Context aware logging:

import DSL._

// Add key/value pairs with DSL and return a logger
val markerLogger = logger.withMarker(bobj("userId" -> userId))

// log with generated logger
markerLogger.info("Logging with user id added as a context marker!")

// can retrieve state markers
val contextMarkers: Markers = markerLogger.markers

Entry Transformation:

val logger = LoggerFactory.getLogger
               .withEntryTransform(e => e.copy(message = e.message + " IN BED"))

logger.info("You will discover your hidden talents")

Event Buffer:

val queueBuffer = EventBuffer(1)
val logger      = LoggerFactory.getLogger.withEventBuffer(queueBuffer)

logger.info("Hello world")

val event = queueBuffer.head


val scriptHandle = new ScriptHandle {
  override def isInvalid: Boolean = false // on file modification, etc
  override val script: String =
    """import strings as s from 'std.tf';
      |alias s.ends_with? as ends_with?;
      |library blindsight {
      |  function evaluate: (long level, string enc, long line, string file) ->
      |    if (ends_with?(enc, "specialMethodName")) then true
      |    else false;
  override def report(e: Throwable): Unit = e.printStackTrace()
val scriptManager = new ScriptManager(scriptHandle) 
val location = new ScriptAwareLocation(scriptManager)

def specialMethodName = {
  // inside the specialMethodName method here :-)
  logger.debug.when(location.here) { log => 
    log("script allows selective logging by method or by line")


import com.tersesystems.blindsight.inspection.InspectionMacros._

decorateIfs(dif => logger.debug(s"${dif.code} = ${dif.result}")) {
  if (System.currentTimeMillis() % 17 == 0) {
    println("branch 1")
  } else if (System.getProperty("derp") == null) {
    println("branch 2")
  } else {
    println("else branch")


There's an example application at https://github.com/tersesystems/play-blindsight that integrates with Honeycomb Tracing using the flow logger:



See the documentation for more details.


Blindsight is released under the "Apache 2" license. See LICENSE for specifics and copyright declaration.