reference.conf

# ================================== #
# Kamon-Pekko Reference Configuration #
# ================================== #

kamon.instrumentation.pekko {

  # If ask-pattern-timeout-warning is enabled, a WARN level log message will be generated if a Future generated by the
  # "ask" pattern fails with an AskTimeoutException and the log message will contain information depending of the
  # selected strategy. The possible values are:
  #
  #   - off: nothing gets logged.
  #   - lightweight: logs a warning when a timeout is reached using source location.
  #   - heavyweight: logs a warning when a timeout is reached using a stack trace captured at the moment the future was created.
  #
  ask-pattern-timeout-warning = off

  # Automatically creates Actor Groups that contain all actors of the same Class at the same level of the Actor System
  # tree. This will only be applied to actors that are not individually tracked, that are not part of another groups and
  # that match the "auto-grouping" filter below. This allows, for example, to automatically get metrics from anonymous
  # actors without messing with filters and risking cardinality explosions.
  #
  auto-grouping = on

  # Filters control how and if the instrumentation will track the behavior of Pekko Actors, Routers, Dispatchers and
  # Actor Groups. All filters have two groups of patterns: includes and excludes; inputs matching at least one of the
  # includes patterns and none of the excludes patterns will be accepted. You can read more about filters on the Kamon
  # documentation: https://kamon.io/docs/latest/core/utilities/
  #
  # The test string for the filters is always starting with the Actor System name, followed by the path to the
  # component being tested. For example, when testing for a "test" actor created at the root of the "pekko-example" Actor
  # System, the test string for the filter will be "pekko-example/user/test" and, when testing the default dispatcher for
  # that same Actor System the test string for the filters will be "pekko-example/pekko.actor.default-dispatcher".
  #
  filters {

    # Defines actor groups and the filters that match all actors that should be part of that group. To define a new
    # group, add a configuration like the following:
    #
    #   kamon.instrumentation.pekko.filters.groups {
    #     worker-actors {
    #       includes = [ "my-system/user/application/worker-*", "my-system/user/workers/**" ]
    #       excludes = [ ]
    #     }
    #   }
    #
    # The configuration key immediately inside the "groups" path corresponds to the group name and the configuration
    # inside of it should contain a Kamon filter (with the includes/excludes settings).
    groups {

      # Special filter used for auto-grouping. Auto-grouping will only act on actors that are not being explicitly
      # tracked as inidividual actors, do not belong to any other groups and match this filter.
      #
      auto-grouping {
        includes = [ "*/user/**" ]
        excludes = ${?kamon.instrumentation.pekko.filters.groups.auto-grouping.excludes} [ ]
      }
    }

    # Decids how Actors are going to be tracked and traced.
    #
    actors {

      # Decides whether the "**" filter can be used for the "track" and "start-trace" filters. Historically, users have
      # beeing using the "**" filters during testing because simplicitly and then go to production with the same filter
      # configuration which usually results in cardinality explosions and/or OOM errors. Since the introduction of auto
      # grouping, the instrumentation will do a much better work at providing metrics out of the box and forbids the use
      # of the "doomsday" wildcard. Enable and use at your own risk.
      #
      doomsday-wildcard = off

      # Decides which actors will have metric tracking enabled. Beware that most of the time what you really need is to
      # track Actor groups instead of individual actors because wildly targetting actors can lead to cardinality issues.
      #
      track {
        includes = ${?kamon.instrumentation.pekko.filters.actors.track.includes} [ ]
        excludes = [ "*/system/**", "*/user/IO-**" ]
      }

      # Decides which actors generate Spans for the messages they process, given that there is already an ongoing trace
      # in the Context of the processed message (i.e. there is a Sampled Span in the Context).
      #
      trace {
        includes = [ "*/user/**", "*/system/sharding**" ]
        excludes = ${?kamon.instrumentation.pekko.filters.actors.trace.excludes} [ ]
      }

      # Decides which actors generate Spans for the messages they process, even if that requires them to start a new
      # trace. Use with care, starting traces with a broad filter (e.g. using includes = [ "**" ]) can generate a huge
      # amount of traces from scheduled actions and underlying system components that most likely will not improve
      # observability of the system and burry useful traces underneath the noise.
      #
      start-trace {
        includes = ${?kamon.instrumentation.pekko.filters.actors.start-trace.includes} [ ]
        excludes = ${?kamon.instrumentation.pekko.filters.actors.start-trace.excludes} [ ]
      }
    }

    # Decides which routers should have metric tracking enabled.
    #
    routers {
      includes = [ "**" ]
      excludes = ${?kamon.instrumentation.pekko.filters.routers.excludes} [ ]
    }

    # Decides which dispatchers should have metric tracking enabled.
    #
    dispatchers {
      includes = [ "**" ]
      excludes = ${?kamon.instrumentation.pekko.filters.dispatchers.excludes} [ ]
    }
  }

  remote {

    # Controls whether tracking of the serialization, deserialization and message size metrics should be tracked for
    # messages going to and coming from a remoting channel.
    track-serialization-metrics = true
  }

  cluster-sharding {
    # Sets the interval at which the Shard metrics (sampling of hosted entities and processed messages across all
    # shards) will be sampled.
    shard-metrics-sample-interval = ${kamon.metric.tick-interval}
  }

  cluster {

    # !! EXPERIMENTAL !!
    #
    # Decides whether to expose the pekko.cluster.[members|datacenters] metrics. These metrics are considered
    # experimental and must be explicitly enabled until a future release when they graduate to stable. The name of
    # this setting might change in the future.
    track-cluster-metrics = no

  }
}
# Signals to pekko that it should load KamonRemoteInstrument
pekko.remote.artery.advanced.instruments += "org.apache.pekko.remote.artery.KamonRemoteInstrument"
kanela.modules {

  pekko {
    name = "Pekko Instrumentation"
    description = "Provides metrics and message tracing for Pekko Actor Systems, Actors, Routers and Dispatchers"
    enabled = yes

    instrumentations = [
      "kamon.instrumentation.pekko.instrumentations.EnvelopeInstrumentation",
      "kamon.instrumentation.pekko.instrumentations.SystemMessageInstrumentation",
      "kamon.instrumentation.pekko.instrumentations.RouterInstrumentation",
      "kamon.instrumentation.pekko.instrumentations.ActorInstrumentation",
      "kamon.instrumentation.pekko.instrumentations.ActorLoggingInstrumentation",
      "kamon.instrumentation.pekko.instrumentations.AskPatternInstrumentation",
      "kamon.instrumentation.pekko.instrumentations.EventStreamInstrumentation",
      "kamon.instrumentation.pekko.instrumentations.ActorRefInstrumentation",
      "kamon.instrumentation.pekko.instrumentations.DispatcherInstrumentation",
      "kamon.instrumentation.pekko.instrumentations.ActorMonitorInstrumentation",
      "kamon.instrumentation.pekko.instrumentations.SchedulerInstrumentation",
      "kamon.instrumentation.pekko.instrumentations.ClusterInstrumentation"
    ]

    within = [
      "^org.apache.pekko.dispatch..*",
      "^org.apache.pekko.event..*",
      "^org.apache.pekko.actor..*",
      "^org.apache.pekko.pattern..*",
      "^org.apache.pekko.cluster..*",
      "^org.apache.pekko.routing..*",
      "kamon.instrumentation.pekko.instrumentations..*"
    ]
  }

  pekko-remote {
    name = "Pekko Remote Instrumentation"
    description = "Provides distributed Context propagation and Cluster Metrics for Pekko"
    enabled = yes

    instrumentations = [
      "kamon.instrumentation.pekko.remote.MessageBufferInstrumentation",
      "kamon.instrumentation.pekko.instrumentations.remote.RemotingInstrumentation",
    ]

    within = [
      "org.apache.pekko.dispatch..*",
      "org.apache.pekko.util..*",
      "org.apache.pekko.remote..*",
      "org.apache.pekko.actor..*",
      "org.apache.pekko.cluster..*",
      "org.apache.pekko.serialization..*"
    ]
  }

  pekko-remote-sharding {
    name = "Pekko Remote Cluster Sharding Monitoring"
    description = "Provides cluster sharding metrics for Pekko"
    enabled = yes

    instrumentations = [
      "kamon.instrumentation.pekko.remote.ShardingInstrumentation"
    ]

    within = [
      "org.apache.pekko.dispatch..*",
      "org.apache.pekko.util..*",
      "org.apache.pekko.remote..*",
      "org.apache.pekko.actor..*"
      "org.apache.pekko.cluster..*"
      "org.apache.pekko.serialization..*"
    ]
  }
}