Custom events

The custom events extension provides an API whereby a developer can create events for capturing arbitrary event data. The API also provides the ability to create the custom events at the application level, system level, or actor level. Please note that Lightbend Telemetry events use structured data, i.e. a map of key-values pairs, rather than message-based.

Why would one use custom events instead of a logging approach? One of the benefits of using the custom event approach is that it enables flexible rate limiting.

Custom event log levels

Events can be created at three different log levels:

  • Error
  • Warning
  • Info

The selected log level is used whenever the event is used and is selected via one of the methods:

  • createInfoEvent
  • createWarningEvent
  • createErrorEvent

Developer API

Accessing CinnamonEvents

To start using the Cinnamon events API you will first want to import the CinnamonEvents and Event classes:

Scala
import com.lightbend.cinnamon.akka.{ CinnamonEvents, CinnamonEvent }
Java
import com.lightbend.cinnamon.akka.CinnamonEvents;
import com.lightbend.cinnamon.akka.CinnamonEvent;

Creating system level custom events

System level custom events provide an excellent way to capture events at the ActorSystem level. To create custom events at this level, you use CinnamonEvents with the ActorSystem and call the createEvent follows:

Scala
val systemLevelEvent: CinnamonEvent = CinnamonEvents(system).createWarningEvent("systemWarningLevelEvent")
Java
CinnamonEvent systemWarningLevelEvent =
    CinnamonEvents.get(getSystem()).createWarningEvent("systemWarningLevelEvent");

Creating actor level custom events

Actor level custom events provide an excellent way to capture actor-specific behavior as events. To create custom events at this level, you use CinnamonEvents with the ActorContext and call the createEvent follows:

Scala
val actorLevelEvent: CinnamonEvent = CinnamonEvents(context).createInfoEvent("actorInfoLevelEvent")
Java
CinnamonEvent actorInfoLevelEvent =
    CinnamonEvents.get(getContext()).createInfoEvent("actorInfoLevelEvent");

Creating application level custom events

Application level custom events are associated with the application as a whole, rather than with the actor system. See Cinnamon metadata for setting the application name. To create custom events at the application level, you first need to use the CinnamonEvents extension with the ActorSystem or with the ActorContext, and then access the application-level metrics using the eventsForApplication method. You can then call the to create createEvent to custom application level events:

Scala
val appEvents = CinnamonEvents(system).eventsForApplication
val applicationLevelEvent: CinnamonEvent = appEvents.createErrorEvent("applicationErrorLevelEvent")
Java
CinnamonEvents appEvents = CinnamonEvents.get(getSystem()).eventsForApplication();
CinnamonEvent applicationErrorLevelEvent =
    appEvents.createErrorEvent("applicationErrorLevelEvent");

Using custom events

Using the custom events involves calling one of the methods supplied by the event class. The actorLevelEvent created above is used in this example to create events on the actor level:

Scala
actorLevelEvent.fire("key1" -> "value1", "key2" -> "value2")
Java
actorInfoLevelEvent.fireWithData("key1", "value1", "key2", "value2");

One can also use respective Maps for Java or Scala when invoking the fire method on an event. More information about the available methods can be found in the API documentation.

Destroying custom events

When finished with the event(s), you should call destroy. Calling destroy will, in turn, invoke the underlying event backend to run any cleanup tasks if required.

Scala
actorLevelEvent.destroy()
Java
actorInfoLevelEvent.destroy();

Custom event example

Here is an example of an actor-level custom event to log particular messages that an actor might receive.

import com.lightbend.cinnamon.akka.{ CinnamonEvents, CinnamonEvent }

case class EventIn(id: Long)
case class EventOut(id: Long)
case object EventDone

class CustomerEventActor extends Actor {
  val event: CinnamonEvent = CinnamonEvents(context).createInfoEvent("customerEvent")

  def receive: PartialFunction[Any, Unit] = {
    case EventIn(id) =>
      event.fire("InEventId" -> s"ID-$id")
      sender ! EventIn(id)
    case EventOut(id) =>
      event.fire("OutEventId" -> s"ID-$id")
      sender ! EventOut(id)
    case EventDone =>
      event.destroy()
      sender ! EventDone
      context stop self
  }
}