Introduction to `Phobos.Actor`

The backbone of Phobos is really the Phobos.Actor module and its counterparts for remoting and clustering, Phobos.Actor.Remote and Phobos.Actor.Cluster. These packages are responsible for injecting all of the Phobos tracing and Phobos monitoring instrumentation directly into your actors.

Concepts

Assuming you're familiar with how Phobos tracing and Phobos monitoring both work, here's the important concepts behind Phobos.Actor:

Phobos Global Configuration - this is provided as a HOCON configuration section and it controls the default behavior of Phobos globally. You can read more about the Phobos.Actor global configuration options here. These configuration settings also affect which pieces of data can be captured automatically by Phobos.
Actor and ActorSelection-specific Phobos Configuration - Phobos ships with the ability to configure specific groups or families of actors to behave independently from the Phobos global configuration settings, using the akka.actor.deployment HOCON syntax or some extension methods Phobos applies to the Props class used to instantiate Akka.NET actors. Read more about the Phobos.Actor actor-specific configuration options here.
ActorSystem Instrumentation - Phobos makes its tracing, monitoring, and other instrumentation capabilities available at the ActorSystem level, which allows them to be accessing from outside Akka.NET actors and in other pieces of infrastructure such as ASP.NET, Topshelf, and more.
Actor-specific Instrumentation - the real heavy lifting behind Phobos is the actor-specific instrumentation, which can be accessed by Phobos users via C# and F# APIs. However, the lion's share of useful data is captured automatically by Phobos and doesn't require end-users to write any specific code at all.

If you're interested in learning about all of the knobs and dials that Phobos ships with we recommend that you explore the Phobos.Actor configuration section first. Otherwise, if you're interested in learning how to access and use all of this instrumentation from inside your own actors - read on!

Accessing Phobos Instrumentation from Inside Actors

It's relatively easy to access Phobos instrumentation from inside your Akka.NET actors. Once the Phobos binaries are installed and configured inside your application, you can use the IActorContext.GetInstrumentation() extension method from the Phobos.Actor namespace:


/// <summary>
///     Actor that can uses its Phobos instrumentation for custom logging and monitoring
/// </summary>
public class TracingInstrumentationActor : ReceiveActor
{
    private readonly IPhobosActorContext _instrumentation = Context.GetInstrumentation();

    public TracingInstrumentationActor()
    {
        Receive<string>(str =>
        {
            _instrumentation.ActiveSpan.Log("test").SetTag("isProduction", false);
            // rest of work
        });
    }
}

The GetInstrumentation() call returns an IPhobosActorContext instance which exposes all of the underlying instrumentation that this actor is using for both monitoring and tracing.

In the example above, we access the IPhobosActorContext.ActiveSpan property which returns the current OpenTracing.ISpan instance the actor is using to record all events pertaining to processing of the current string message. From there we can call any of the OpenTracing APIs to log additional events and metadata to this trace.

N.B. The IPhobosActorContext.ActiveSpan property and the IPhobosActorContext.Tracer.ActiveSpan property return the same ISpan instance; the former is simply short-hand for the latter.

Accessing Phobos Instrumentation from Outside Actors

There are many cases where it might be desirable to access Phobos' tracing and monitoring capabilities from outside of Akka.NET actors, such as wanting to start tracing requests from ASP.NET Core or other frameworks and tools you might use side-by-side with Akka.NET.

Phobos exposes some easy methods for doing this - all you need is a reference to the ActorSystem that launched Phobos.

Accessing the Phobos `ITracer`

It only takes a single method call to get access to the current ITracer used by Phobos throughout an Akka.NET ActorSystem:


var tracer = ActorTracing.For(Sys).Tracer;

// creates a span that is tied to the current ActorSystem address, but no particular actors
using (var span = tracer.BuildSpan("myOperation").WithTag("isProduction", false).StartActive())
{
    // other work
} // automatically completes the Span when `using` scope exits

The ActorTracing class comes with a static method that can be used to retrieve the ITracer implementation used by Phobos from the ActorSystem itself. All ITracer implementations are thread-safe, so you can freely use this tracer anywhere inside your application.

N.B. Once the ActorSystem.Terminate call completes, any ITracer instances used outside of the ActorSystem will cease to function. They are only valid so long as the ActorSystem that launched them is still active.

Accessing the Phobos `IMonitor`

Just like the ActorTracing example for accessing the ITracer used by the current ActorSystem, it's equally easy to get the current IMonitor instance used for monitoring purposes:


// access the monitor used to create and record metrics
var monitor = ActorMonitoring.For(Sys).Monitor;

// increment a counter tied to this ActorSystem and node by 2
// will show up as [Sys].foo inside the monitoring backend
monitor.IncrementCounter("foo", 2);

The ActorMonitoring class exposes a matching API identical in scope to its ActorTracing counterpart, and that can be used to access the global IMonitor associated with the ActorSystem that launched Phobos. All IMonitor implementations are thread-safe and can be safely shared and used in parts of your application that run outside of Akka.NET.

N.B. The normal IMonitor that gets used inside Akka.NET actors normally associates all recorded metrics with the specific actor the IMonitorwas accessed from. This is not the case with the IMonitor access via ActorMonitoring. The IMonitor associated with the ActorSystem only reports metrics associated with the current ActorSystem and its Akka.Remote address, if applicable.

Next: how to configure Phobos inside your Akka.NET applications.

Introduction to Phobos.Actor