Periskop Scala Client

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 += "io.github.periskop-dev" %% "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.

Using push gateway

You can also use pushgateway in case you want to push your metrics instead of using pull method. Use only in case you really need it (e.g a batch job) as it could degrade the performance of your application. In the following example, we assume that we deployed an instance of periskop-pushgateway on http://localhost:6767:

val exporter = new ExceptionExporter(exceptionCollector)
exceptionCollector.add(new RuntimeException("ups!"))
exporter.pushToGateway("http://localhost:6767")

Contributing

Please see CONTRIBUTING.md.