Class PhobosActorSettings

Internal settings used to determine how we are going to trace or monitor a specific actor

Inheritance

object

PhobosActorSettings

Implements

IEquatable<PhobosActorSettings>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Phobos.Actor.Configuration

Assembly: Phobos.Actor.dll

Syntax

public record PhobosActorSettings : IEquatable<PhobosActorSettings>

Constructors

PhobosActorSettings(bool, bool, TraceFilteringSettings?, bool, bool, bool, bool, bool, bool, bool, string?)

Creates a new PhobosActorSettings instance.

Declaration

public PhobosActorSettings(bool trace, bool monitor, TraceFilteringSettings? filterSettings = null, bool customFiltering = false, bool phobosNotInstalled = false, bool mailboxDepth = false, bool propagateSettingsToChildren = false, bool traceActorLifecycle = true, bool createTraceUponReceive = true, bool logMessageEvents = true, string? actorTypeName = null)

Parameters

Type	Name	Description
bool	trace	Toggles tracing on or off for this actor.
bool	monitor	Toggles monitoring on or off for this actor.
TraceFilteringSettings	filterSettings	Determines how this actor filters incoming messages for tracing purposes.
bool	customFiltering	When set to true, indicates that this actor is running with custom filtering.
bool	phobosNotInstalled	Optional. Use to indicate when Akka.Remote is enabled that the actors on the other side of the network don't have Phobos installed.
bool	mailboxDepth	Optional. When enabled turns on monitoring of the mailbox depth of this actor.
bool	propagateSettingsToChildren	When set to true, propagates the current monitoring settings down to children.
bool	traceActorLifecycle	When set to true, allow actors to trace their PreStart / PostRestart activities.
bool	createTraceUponReceive	When set to true, actors will create traces automatically upon processing messages.
bool	logMessageEvents	When set to true and when CreateTraceUponReceive is true, will automatically append waiting and message events to all automatically created spans during actor message processing.
string	actorTypeName	When set to a non-empty string, will customize the name of this actor type as it appears in Phobos traces and metrics

Fields

Empty

Default settings - has instrumentation disabled by default.

Declaration

public static readonly PhobosActorSettings Empty

Field Value

Type	Description
PhobosActorSettings

Properties

ActorTypeName

Used to customize the name of this actor type as it appears in Phobos traces and metrics.

This will override the default name Phobos derives from the actor's CLR type name.

Set to null or Empty to revert to the default CLR type name behavior.

Declaration

public string? ActorTypeName { get; init; }

Property Value

Type	Description
string

Examples

Here is an example of how to use the ActorTypeName:

public class MyActor : UntypedActor
{
    // Implementation here
}

var actorSettings = new PhobosActorSettings(trace: true, monitor: true).WithActorTypeName("Foo");
var actorRef = Sys.ActorOf(Props.Create<MyActor>().WithInstrumentation(actorSettings));

If we sent this actor a message:

1. Metrics would all have their actorType attribute set to `Foo` instead of 'Assembly.Namespace.MyActor'
2. Traces would all have their actorType attribute set to `Foo` instead of 'Assembly.Namespace.MyActor'

CreateTraceUponReceive

When set to false, actors will not create new spans automatically during message processing.

This setting, when set to false and when tracing is disabled will also prevent UsableContext from being automatically propagated.

Declaration

public bool CreateTraceUponReceive { get; init; }

Property Value

Type	Description
bool

Remarks

Used for noise control - developers who want to use this setting can manually create their own spans and propagate them through Phobos still. UsableContext will give you access to the context propagated from a previous trace - this can be used to create more usable spans.

HasCustomTraceFilteringSettings

Returns true if this actor has filtering settings that differ from the ActorSystem defaults.

Declaration

public bool HasCustomTraceFilteringSettings { get; init; }

Property Value

Type	Description
bool

LogMessageEvents

In Phobos 2.0 we introduced latency tracking which includes logging two discrete events on all automatically created Phobos spans:

• "waiting" - created when the message is first Tell(object, IActorRef)
• "message" - created when the message is first processed by the actor and contains the messages' content. Turning this setting to "off" disables the productions of these events on all akka.msg.recv spans created by Phobos.

Declaration

public bool LogMessageEvents { get; init; }

Property Value

Type	Description
bool

Remarks

Set to true by default.

Monitor

If true, this actor will monitor

Declaration

public bool Monitor { get; init; }

Property Value

Type	Description
bool

MonitorMailbox

Used to monitor the depth of the mailbox queue

Declaration

public bool MonitorMailbox { get; init; }

Property Value

Type	Description
bool

PhobosNotInstalled

Used when communicating with remote ActorSystem instances. When true, it means that Phobos is not installed on the target system.

Declaration

public bool PhobosNotInstalled { get; init; }

Property Value

Type	Description
bool

PropagateSettingsToChildren

Used in cases where we want to DISABLE tracing for an entire portion of the hierarchy.

Declaration

public bool PropagateSettingsToChildren { get; init; }

Property Value

Type	Description
bool

Trace

If true, this actor will use tracing on all message processing internally.

Declaration

public bool Trace { get; init; }

Property Value

Type	Description
bool

TraceActorLifecycle

When set to true indicates that actors who are enabled for tracing will trace their PreStart / PostRestart / PostStop / PreRestart activities.

Declaration

public bool TraceActorLifecycle { get; init; }

Property Value

Type	Description
bool

TraceFiltering

The settings used to filter incoming traces.

Declaration

public TraceFilteringSettings TraceFiltering { get; init; }

Property Value

Type	Description
TraceFilteringSettings

Methods

ForSystemActors(TracingSettings, MonitoringSettings)

Creates a default configuration for /system actors

Declaration

public static PhobosActorSettings ForSystemActors(TracingSettings tracing, MonitoringSettings monitoring)

Parameters

Type	Name	Description
TracingSettings	tracing	The phobos.tracing settings.
MonitoringSettings	monitoring	The phobos.monitoring settings.

Returns

Type	Description
PhobosActorSettings	Phobos default settings for /system actors.

ForUserActors(TracingSettings, MonitoringSettings)

Creates a default configuration for /user actors

Declaration

public static PhobosActorSettings ForUserActors(TracingSettings tracing, MonitoringSettings monitoring)

Parameters

Type	Name	Description
TracingSettings	tracing	The phobos.tracing settings.
MonitoringSettings	monitoring	The phobos.monitoring settings.

Returns

Type	Description
PhobosActorSettings	Phobos default settings for /user actors.

WithActorTypeName(string?)

Declaration

public PhobosActorSettings WithActorTypeName(string? actorTypeName)

Parameters

Type	Name	Description
string	actorTypeName

Returns

Type	Description
PhobosActorSettings

WithCreateTraceUponReceive(bool)

Set to true by default.

Creates message-processing spans automatically when tracing is enabled. When this setting is disabled users will be able to manually create traces from SpanContexts received during tracing and traces will still be propagated.

This setting, when set to false and when tracing is disabled will also prevent UsableContext from being automatically propagated.

Declaration

public PhobosActorSettings WithCreateTraceUponReceive(bool createSpanUponReceive)

Parameters

Type	Name	Description
bool	createSpanUponReceive

Returns

Type	Description
PhobosActorSettings

Remarks

REMARKS: this setting should really only be used when attempting to suppress large amounts of noise from the tracing system by manually controlling when traces are created.

WithFiltering(TraceFilteringSettings, bool)

Modifies the settings to change whether tracing is enabled or not.

Declaration

public PhobosActorSettings WithFiltering(TraceFilteringSettings filteringSettings, bool customTracing = true)

Parameters

Type	Name	Description
TraceFilteringSettings	filteringSettings	The tracing filtering settings.
bool	customTracing	Optional. Defaults to true. Determines if our trace filtering differs from the ActorSystem or not.

Returns

Type	Description
PhobosActorSettings	An immutable replica of the original PhobosActorSettings instance.

WithLogMessageEvents(bool)

In Phobos 2.0 we introduced latency tracking which includes logging two discrete events on all automatically created Phobos spans:

• "waiting" - created when the message is first Tell(object, IActorRef)
• "message" - created when the message is first processed by the actor and contains the messages' content. Turning this setting to "off" disables the productions of these events on all akka.msg.recv spans created by Phobos.

Declaration

public PhobosActorSettings WithLogMessageEvents(bool logMessageEvents)

Parameters

Type	Name	Description
bool	logMessageEvents

Returns

Type	Description
PhobosActorSettings

Remarks

Set to true by default. Set this value to false to reduce the amount of data produced per-span.

WithMonitoring(bool)

Modifies the settings to change whether monitoring is enabled or not.

Declaration

public PhobosActorSettings WithMonitoring(bool monitoring)

Parameters

Type	Name	Description
bool	monitoring	Toggles monitoring on or off.

Returns

Type	Description
PhobosActorSettings	An immutable replica of the original PhobosActorSettings instance.

WithPropagateToChildren(bool)

Modifies the settings to change whether we allow settings to propagate down to our children or not.

Declaration

public PhobosActorSettings WithPropagateToChildren(bool propagate)

Parameters

Type	Name	Description
bool	propagate	Toggles propagation on or off.

Returns

Type	Description
PhobosActorSettings	An immutable replica of the original PhobosActorSettings instance.

WithTraceActorLifecycle(bool)

Declaration

public PhobosActorSettings WithTraceActorLifecycle(bool traceActorLifecycle)

Parameters

Type	Name	Description
bool	traceActorLifecycle

Returns

Type	Description
PhobosActorSettings

WithTracing(bool)

Modifies the settings to change whether tracing is enabled or not.

Declaration

public PhobosActorSettings WithTracing(bool tracing)

Parameters

Type	Name	Description
bool	tracing	Toggles tracing on or off.

Returns

Type	Description
PhobosActorSettings	An immutable replica of the original PhobosActorSettings instance.

Implements

IEquatable<T>