soundcloud / periskop-scala

Scala low level client for Periskop

Version Matrix

Periskop Scala Client

Build Status Maven Central

Periskop requires collecting and aggregating exceptions on the client side, as well as exposing them via an HTTP endpoint using a well defined format.

This library provides low level collection and rendering capabilities. Higher level libraries can be built be for better integration with specific libraries and frameworks.

Usage

Add periskop-scala to your SBT dependencies:

libraryDependencies += "com.soundcloud" %% "periskop-scala" % "<version>"

Create an exception collector instance:

val exceptionCollector = new ExceptionCollector

Collect some exceptions:

// An Exception Without Context
exceptionCollector.add(new RuntimeException("ups!"))

// A Message Without Context
exceptionCollector.addMessage("key", "some message")

// An Exception With Context
exceptionCollector.addWithContext(
  ExceptionWithContext(
    throwable = new RuntimeException("another ups!"),
    severity = Severity.Warning,
    httpContext = Some(HttpContext(
      requestMethod = "GET",
      requestUrl = "http://example.com/path?foo=bar",
      requestHeaders = Map("Accept" -> "text/plain"),
      requestBody = Some("body")
    )))
)

// A Message With Context
exceptionCollector.addWithContext(
  ExceptionMessage(
    aggregationKey = "key2",
    message = "some other message",
    severity = Severity.Info,
    httpContext = Some(HttpContext(
      requestMethod = "GET",
      requestUrl = "http://example.com/path?foo=bar",
      requestHeaders = Map("Accept" -> "text/plain"),
      requestBody = Some("body")
    )))
)

Export the exceptions to a format understandable by Periskop:

val exporter = new ExceptionExporter(exceptionCollector)
exporter.export

The exported exceptions need to be exposed via an HTTP endpoint in order for Periskop to be able to scrape them. See Periskop Documentation for more information on how to configure a Periskop server.

Contributing / Release a new version

Please see CONTRIBUTING.md and RELEASE.md