Phobos Setup and Installation

Phobos ships as a series of NuGet packages that target .NET Standard 2.0, which means that Phobos can be used in any Akka.NET application that targets .NET Framework 4.6.1 or higher or .NET Core 2.0 or higher.

Tip

New to Phobos? Follow our Phobos Quickstart Tutorial for a complete walk-through!

The easiest way to get started with Phobos is using the Phobos.Hosting package with Akka.Hosting:

// Install-Package Phobos.Hosting
services.AddAkka("MySystem", (builder, provider) =>
{
    builder.WithPhobos(AkkaRunMode.Local); // or AkkaRunMode.Remote / AkkaRunMode.Cluster
});

This configures Phobos instrumentation for your actors. You'll also need to configure the OpenTelemetry SDK with AddPhobosInstrumentation() for both tracing and metrics, plus your chosen exporters. See Configuring Phobos with Phobos.Hosting for the complete setup including OpenTelemetry SDK configuration.

Video Tutorial

This video walks you through, step-by-step, how to install Phobos inside an Akka.NET and ASP.NET application using Jaeger, Prometheus, and Grafana.

Step 1 - Configure NuGet Access

Once you've received access to your organization's Phobos NuGet key via Sdkbin following a completed purchase, you'll need to configure your NuGet sources.

For projects using continuous integration, configure your NuGet.config file in your solution root:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <solution>
    <add key="disableSourceControlIntegration" value="true" />
  </solution>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="phobos" value="{YOUR_SDKBIN_FEED_URL}" />
  </packageSources>
</configuration>
Important

Replace {YOUR_SDKBIN_FEED_URL} with your actual Phobos feed URL from Sdkbin. This URL includes your license key and is unique to your organization.

Visual Studio Package Manager Setup

To get your Phobos packages installed in your Visual Studio project, you will need to setup your private Petabridge NuGet Feed. You can do so following the steps below.

  1. Select Package Manger Settings in your Tools tab. Accessing the NuGet Package Manager in Visual Studio
  2. Add a Package source by selecting the plus symbol. Added a new package source in Visual Studio
  3. Give your source any name and add your Key, provided by Petabridge, to your Source option. Adding the Phobos NuGet feed via the NuGet Package Manager
  4. Install your desired package through your Package Manger Console. Installing the Phobos Packages

If you need more help getting your Phobos NuGet feed added to Visual Studio, please see the official Microsoft documentation on the subject.

Step 2 - Install NuGet Packages

For the simplest setup with Akka.Hosting:

dotnet add package Phobos.Hosting

Option B: Classic Installation (Without Hosting)

For applications not using Akka.Hosting or Microsoft.Extensions.Hosting:

  1. For Akka.Cluster applications:

    dotnet add package Phobos.Actor.Cluster

  2. For Akka.Remote applications (no clustering):

    dotnet add package Phobos.Actor.Remote

  3. For local ActorSystem only:

    dotnet add package Phobos.Actor

Available Phobos Packages

All Phobos packages are available from your private Sdkbin feed. You can find your feed URL in your Sdkbin account after purchasing a Phobos license.

Core Packages

Package Use Case Description
Phobos.Hosting Recommended One-line setup with Akka.Hosting
Phobos.Actor Local ActorSystem Core instrumentation for single-node applications
Phobos.Actor.Remote Akka.Remote Distributed tracing across remote actors
Phobos.Actor.Cluster Akka.Cluster Full cluster observability and tracing

Supporting Packages

Package Purpose
Phobos.Tracing Tracing interfaces and OpenTelemetry integration
Phobos.Monitoring Metrics collection and reporting
Phobos.TestKit Testing utilities and PhobosSpec base class

Step 3 - Configure Your ActorSystem

See our Quickstart Tutorial for a complete example, or jump to Configuring with Phobos.Hosting.

Without Hosting (Classic Setup)

For applications not using Microsoft.Extensions.Hosting, use the following approach with PhobosConfigBuilder:

// Create Phobos configuration using PhobosConfigBuilder
var phobosConfig = new PhobosConfigBuilder()
    .WithTracing(tracing => tracing
        .SetTraceUserActors(true)
        .SetTraceSystemActors(false)
        .SetTraceActorLifecycle(true)
        .VerboseTracing(false) // Only trace explicitly included messages
        .SetTraceFilter(new CustomTraceFilter()))
    .WithMetrics(metrics => metrics
        .SetMonitorUserActors(true)
        .SetMonitorSystemActors(false)
        .SetMonitorMailboxDepth(true)
        .SetMonitorEventStream(true));

// Create ActorSystem with Phobos using ActorSystemSetup
var phobosSetup = PhobosSetup.Create(phobosConfig);
var bootstrap = BootstrapSetup.Create()
    // ## IMPORTANT: THIS IS WHAT INJECTS PHOBOS INTO YOUR ACTORS ##
    // See also: PhobosProviderSelection.Remote (for Akka.Remote)
    //      and  PhobosProviderSelection.Cluster (for Akka.Cluster)
    .WithActorRefProvider(PhobosProviderSelection.Local);

// combine setups
var actorSystemSetup = phobosSetup.And(bootstrap);

var system = ActorSystem.Create("PhobosNoHosting", actorSystemSetup);

See Installing Phobos Without Akka.Hosting for detailed configuration options.

Step 4 - Configure OpenTelemetry Exporters

Phobos 2.x uses OpenTelemetry for telemetry data. We recommend using the OTLP exporter:

dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

OTLP works with most modern observability platforms including Jaeger, Grafana, Azure Monitor, and cloud providers. For configuration examples, see Phobos Integrations.

Step 5 - Setup Noise Filtering (Optional)

Reduce trace noise by filtering out non-essential messages. See Filtering Tracing Data for configuration options.