Configuration
If you've installed the any of the Phobos.Actor packages in your application, the following default HOCON configuration will be loaded automatically once Phobos is loaded by the ActorSystem:
##################################
# Phobos Reference Config File #
##################################
phobos{
tracing{
# Setting used to trigger tracing for all built-in /system actors by default.
# When set to "on," all /system actors will automatically be outfitted with tracing
# instrumentation.
trace-all-system-actors = off
# Setting used to trigger tracing for all /user actors by default.
# When set to "on," all /user actors will automatically be outfitted with tracing
# instrumentation.
trace-all-user-actors = on
# The global sample rate used by all actors by default when tracing; defaults to 100%.
# Can be set to a number between 0.0 (0%) and 1.0 (100%.)
#
# If the sample rate is below 1.0, Phobos will only include that
# percentage of traces in the sample. However, once a trace has started
# and is being propagated via message-sends to other actors, sampling
# will no longer have any effect as all messages that are being processed
# in relation to a current trace will always be recorded.
#
# In effect, the sample rate only determines _how likely a new trace_
# is to start being recorded at all.
sample-rate = 1.0
# Debugging settings used for testing the configuration of Phobos.Tracing
debug{
# When enabled: will log incoming tracing information
# on all actors capable of receiving trace events.
log-traces = off
}
# Setting used to instruct Phobos whether or not it should automatically append
# all captured log messages to the active ISpan during which they were produced.
#
# Turning this setting off may help improve performance slightly in some instances,
# but at the cost of missing useful debugging and diagnostic data.
#
# If you want to throttle down the amount of log messages being appended to outgoing
# spans, consider simply changing the `akka.loglevel` setting or others inside core Akka.NET.
append-logs-to-trace = on
# A list of fully qualified type names that we can exclude, include, or key on for traces
# in any actors that we have while tracing is enabled.
#
# This is designed to make it easier to unroll perpetual messaging graphs,
# such as Akka.Streams, and to help keep noise down in the tracing system overall.
filter {
# filtering mode - determines what we're going to do with the 'message-types' collection
# Supported values include 'blacklist' and 'whitelist'.
#
# Blacklist filtering - excludes any messages that matches the types provided in the
# `message-types` collection below from tracing. One interesting effect of Blacklist
# filtering is that it applies to ONGOING traces, meaning that it can effectively terminate
# a long trace. Phobos actually uses this to help deconstruct traces from Akka.Streams
# into understandable, linear traces.
#
# Whitelist filtering - only starts new traces when a message that matches the types
# found inside the `messages-types` collection is received. From that point onward,
# any other actors running with the same whitelist settings will continue to record
# messages processing events even if they are triggered by message types not found on this
# list. The whitelist is only takes effect when it comes time to START a new trace.
# It has no effect on ongoing traces.
mode = blacklist
# A comma-delimited set of fully-qualified type names (FQNs) to use in the filter criteria.
#
# i.e.
# message-types = [
# "Phobos.Docs.Samples.Tests.Tracing.IFilteredMessage, Phobos.Docs.Samples.Tests",
# "Phobos.Docs.Samples.Tests.Tracing.FlushCmd, Phobos.Docs.Samples.Tests"
# ]
#
# An imporant note about how the filter list works: if you provide an interface or a base
# class, any messages which match those types will also be similarly included. Therefore,
# it's possible to filter on an interface or an abstract class. The semantics work similarly
# to how actors in Akka.NET perform pattern-matching on incoming messages.
message-types = []
}
}
monitoring{
# Setting used to trigger monitoring for all built-in /system actors by default.
# When set to "on," all /system actors will automatically be outfitted with monitoring
# instrumentation.
monitor-all-system-actors = off
# Setting used to trigger monitoring for all /user actors by default.
# When set to "on," all /user actors will automatically be outfitted with monitoring
# instrumentation.
monitor-all-user-actors = on
# Toggles monitoring of mailbox queue depth for any actors who have monitoring enabled
monitor-mailbox-depth = off
# The global sample rate used by all actors by default when tracing; defaults to 100%.
# Can be set to a number between 0.0 (0%) and 1.0 (100%.)
#
# If the sample rate is below 1.0, Phobos will only include that
# percentage of metrics in the sample. Each attempt to measure a metrics
# is treated as an independent event.
sample-rate = 1.0
# When enabled, records all of the default events that pass through the eventstream
# (log events, dead letters, and unhandled messages) and writes that out to a Global
# counter for the ActorSystem as a whole.
monitor-eventstream = on
}
}
The comments for each HOCON setting are self-descriptive, but it's worth bearing in mind that these settings in the default phobos.tracing and phobos.montoring namespaces determine the default behavior that all actors will engage in when processing messages and recording any other automatically captured data; all of these values can be overridden for individual actors and actor selections.
Actor-Specific Configuration
Using the akka.actor.deployment namespace in HOCON, we can override the Phobos settings for individual actors or actor paths using wildcard ActorSelection syntax with Phobos:
######################################################
# Phobos Default Actor-Specific Deployment Options #
######################################################
akka.actor.deployment.default.phobos{
# When set to "on" this setting ensures that all children, grandchildren
# and so on of the actor deployed with this configuration receive the exact
# same settings as this actor unless explicitly overridden by their own
# deployment configuration.
propagate-settings-to-children = off
tracing{
# Toggles the entire tracing functionality of Phobos.Tracing on or off for this actor.
# If set to 'off' then this actor will not record any traces. However, traces can still
# be propagated through this actor to others.
enabled = on
# The sample rate used by this actor when tracing; defaults to 100%.
# Can be set to a number between 0.0 (0%) and 1.0 (100%.)
#
# If the sample rate is below 1.0, Phobos will only include that
# percentage of traces in the sample. However, once a trace has started
# and is being propagated via message-sends to other actors, sampling
# will no longer have any effect as all messages that are being processed
# in relation to a current trace will always be recorded.
#
# In effect, the sample rate only determines _how likely a new trace_
# is to start being recorded at all.
sample-rate = 1.0
# A list of fully qualified type names that we can exclude, include, or key on for traces
# in any actors that we have while tracing is enabled.
#
# This is designed to make it easier to unroll perpetual messaging graphs,
# such as Akka.Streams, and to help keep noise down in the tracing system overall.
filter {
# filtering mode - determines what we're going to do with the 'message-types' collection
# Supported values include 'blacklist' and 'whitelist'.
#
# Blacklist filtering - excludes any messages that matches the types provided in the
# `message-types` collection below from tracing. One interesting effect of Blacklist
# filtering is that it applies to ONGOING traces, meaning that it can effectively terminate
# a long trace. Phobos actually uses this to help deconstruct traces from Akka.Streams
# into understandable, linear traces.
#
# Whitelist filtering - only starts new traces when a message that matches the types
# found inside the `messages-types` collection is received. From that point onward,
# any other actors running with the same whitelist settings will continue to record
# messages processing events even if they are triggered by message types not found on this
# list. The whitelist is only takes effect when it comes time to START a new trace.
# It has no effect on ongoing traces.
mode = blacklist
# A comma-delimited set of fully-qualified type names (FQNs) to use in the filter criteria.
#
# i.e.
# message-types = [
# "Phobos.Docs.Samples.Tests.Tracing.IFilteredMessage, Phobos.Docs.Samples.Tests",
# "Phobos.Docs.Samples.Tests.Tracing.FlushCmd, Phobos.Docs.Samples.Tests"
# ]
#
# An imporant note about how the filter list works: if you provide an interface or a base
# class, any messages which match those types will also be similarly included. Therefore,
# it's possible to filter on an interface or an abstract class. The semantics work similarly
# to how actors in Akka.NET perform pattern-matching on incoming messages.
message-types = []
}
}
monitoring{
# Toggles the entire monitoring functionality of Phobos.Monitoring on or off for this actor.
# If set to 'off' then this actor will not record any metrics.
enabled = on
# The global sample rate used by all actors by default when tracing; defaults to 100%.
# Can be set to a number between 0.0 (0%) and 1.0 (100%.)
#
# If the sample rate is below 1.0, Phobos will only include that
# percentage of metrics in the sample. Each attempt to measure a metrics
# is treated as an independent event.
sample-rate = 1.0
# Toggles mailbox depth monitoring on or off for this actor.
monitor-mailbox-depth = off
}
}
Much like the global Phobos configuration, actor-specific configuration allows users to:
- Turn tracing and monitoring on or off;
- Set custom sample rates for monitoring and tracing;
- Set custom filters for tracing; and
- Turn on feature-specific settings, such as enabling actor queue depth monitoring with
monitor-mailbox-depth = on.
Propagating Settings to Children
One powerful feature of the actor-specific configuration is the phobos.propagate-settings-to-children setting. In effect, this setting makes it possible for Akka.NET users to guarantee that an entire segment of the actor hierarchy runs with its own independent configuration.
All child actors below the selected actor path in configuration will all run with the same settings without having to be explicitly configured. This is because the phobos.propagate-settings-to-children value, when set to on, will be applied to all children recursively by definition.