Setup

Blindsight depends on SLF4J using a service loader pattern, which is typically Logback or Log4J 2. This means you should also plug in one of the service loader implementations, provided below.

Examples

You can check out a “starter project” at https://github.com/tersesystems/blindsight-starter.

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

Logstash

The recommended option for Logback is to use blindsight-logstash.

Structured Logging is provided through the DSL on the logger and provides a mapping for Argument and Markers through Logstash Markers and StructuredArguments. Source information (line, file, enclosing) is rendered as logstash markers.

Add the given dependencies:

sbt

libraryDependencies += "com.tersesystems.blindsight" %% "blindsight-logstash" % "1.5.2"

Maven

<properties>
  <scala.binary.version>2.13</scala.binary.version>
</properties>
<dependencies>
  <dependency>
    <groupId>com.tersesystems.blindsight</groupId>
    <artifactId>blindsight-logstash_${scala.binary.version}</artifactId>
    <version>1.5.2</version>
  </dependency>
</dependencies>

Gradle

def versions = [
  ScalaBinary: "2.13"
]
dependencies {
  implementation "com.tersesystems.blindsight:blindsight-logstash_${versions.ScalaBinary}:1.5.2"
}

See Github for the latest version.

The version of logstash-logback-encoder depends on Jackson 2.11, which is newer than the packaged version used by many Scala libraries such as Play and Akka which depend on an older version of jackson-module-scala. If you see library incompatibility errors, add an explicit dependency on 2.11 to your project:

sbt

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

Maven

<properties>
  <scala.binary.version>2.13</scala.binary.version>
</properties>
<dependencies>
  <dependency>
    <groupId>com.fasterxml.jackson.module</groupId>
    <artifactId>jackson-module-scala_${scala.binary.version}</artifactId>
    <version>2.11.0</version>
  </dependency>
</dependencies>

Gradle

def versions = [
  ScalaBinary: "2.13"
]
dependencies {
  implementation "com.fasterxml.jackson.module:jackson-module-scala_${versions.ScalaBinary}:2.11.0"
}

It is recommended (but not required) to use Terse Logback on the backend. Please see the documentation for what modules are appropriate for your use case.

Generic

If you are using another SLF4J compatible framework like Log4J 2 or SLF4J Simple, or don’t want to use the Logstash binding, you should use blindsight-generic, which has a service loader binding that depends solely on slf4j-api. This package does not register a service provider.

The generic package is useful in situations where you want a custom LoggerFactory, for example in scripting.

This package does not have the already configured implementation for ArgumentResolver or MarkersResolver, which means that you must implement these yourself.

sbt

libraryDependencies += "com.tersesystems.blindsight" %% "blindsight-generic" % "1.5.2"

Maven

<properties>
  <scala.binary.version>2.13</scala.binary.version>
</properties>
<dependencies>
  <dependency>
    <groupId>com.tersesystems.blindsight</groupId>
    <artifactId>blindsight-generic_${scala.binary.version}</artifactId>
    <version>1.5.2</version>
  </dependency>
</dependencies>

Gradle

def versions = [
  ScalaBinary: "2.13"
]
dependencies {
  implementation "com.tersesystems.blindsight:blindsight-generic_${versions.ScalaBinary}:1.5.2"
}

See Github for the latest version.

JSON-LD

JSON-LD support can be added for richer structured logging.

sbt

libraryDependencies += "com.tersesystems.blindsight" %% "blindsight-jsonld" % "1.5.2"

Maven

<properties>
  <scala.binary.version>2.13</scala.binary.version>
</properties>
<dependencies>
  <dependency>
    <groupId>com.tersesystems.blindsight</groupId>
    <artifactId>blindsight-jsonld_${scala.binary.version}</artifactId>
    <version>1.5.2</version>
  </dependency>
</dependencies>

Gradle

def versions = [
  ScalaBinary: "2.13"
]
dependencies {
  implementation "com.tersesystems.blindsight:blindsight-jsonld_${versions.ScalaBinary}:1.5.2"
}

See Github for the latest version.

Ring Buffer

Blindsight comes with the option to add event buffering to a logger, so that logged entries can be accessible from the application. This can be very useful for debugging and for verifying test output.

A bounded in-memory ring buffer implementation based on org.jctools.queues.MpmcArrayQueue from the JCTools project is provided. This implementation is thread-safe and performant. If you need another implementation (for example, you want to use an off-heap buffer or buffer to disk), then the EventBuffer interface is relatively straightforward to implement.

sbt

libraryDependencies += "com.tersesystems.blindsight" %% "blindsight-ringbuffer" % "1.5.2"

Maven

<properties>
  <scala.binary.version>2.13</scala.binary.version>
</properties>
<dependencies>
  <dependency>
    <groupId>com.tersesystems.blindsight</groupId>
    <artifactId>blindsight-ringbuffer_${scala.binary.version}</artifactId>
    <version>1.5.2</version>
  </dependency>
</dependencies>

Gradle

def versions = [
  ScalaBinary: "2.13"
]
dependencies {
  implementation "com.tersesystems.blindsight:blindsight-ringbuffer_${versions.ScalaBinary}:1.5.2"
}