vaslabs / talos

Lawful circuit breakers for Scala. Akka and monix circuit breaker implementations with monitoring.

Website GitHub

talos Build Status Maven Central Codacy Badge Codacy Badge Docker hub Scala Steward badge

Talos is enforcing some theory from literature concerning circuit breakers in the form of typeclasses and laws.

Read more around the theory here

The main deliverable of Talos is fine grained monitoring.

Usage

Talos is modularised. You can twist it and pick the dependencies that fit your need. But let's go step by step.

libraryDependencies += "org.vaslabs.talos" %% "taloscore" % "2.1.0"
libraryDependencies += "org.vaslabs.talos" %% "talosakkasupport" % "2.1.0"
libraryDependencies += "org.vaslabs.talos" %% "taloskamon" % "2.1.0"

The events library provides a way to stream events on what's happening in the circuit breakers. E.g. combining with the talosakkasupport you can do:

import akka.actor.typed.{ActorSystem, ActorRef}
import akka.actor.typed.scaladsl.adapter._
import akka.pattern.CircuitBreaker
import cats.effect.IO
import talos.circuitbreakers.TalosCircuitBreaker
import talos.circuitbreakers.akka._

import scala.concurrent.duration._

def createCircuitBreaker(name: String = "testCircuitBreaker")
                      (implicit system: ActorSystem[_]): AkkaCircuitBreaker.Instance = {
    AkkaCircuitBreaker(
      name,
      CircuitBreaker(
        system.scheduler.toClassic,
        5,
        2 seconds,
        5 seconds
      )
    )
}

If you have an existing solution based on Akka circuit breaker and you can extract the circuit breaker like this.

    val akkaCB: CircuitBreaker = talosCircuitBreaker.circuitBreaker.unsafeRunSync()

Otherwise you can use the TalosCircuitBreaker typeclass directly

    val action: IO[Unit] = talosCircuitBreaker.protect(IO(println("Running inside the circuit breaker")))
    action.unsafeRunSync()

Talos also supports the CircuitBreaker from monix

Complete usage example

How to code can be found here: https://github.com/vaslabs/talos/blob/master/examples/src/main/scala/talos/examples/ExampleApp.scala

Laws

If you wish to implement your own TalosCircuitBreaker typeclasses you can test them against the laws library:

libraryDependencies += "org.vaslabs.talos" %% "taloslaws" % "2.1.0" % Test

Run the demo

  • Spin up the docker images provided:
cd examples
docker-compose up

You can see the kamon status here and the prometheus metrics are exposed here .

How Tos

  1. Setup docker to work with Kamon: Look at build.sbt, find dockerCommonSettings
  2. Setup logging: Look in the example module in the resources for the logback.xml file.

Architecture

alt text

Note: The hystrix reporter is no longer supported (last supported version 1.0.0)