Phobos.Tracing 1.5.1

Distributed tracing support for Akka.NET ActorSystems.

Install-Package Phobos.Tracing -Version 1.5.1

dotnet add package Phobos.Tracing --version 1.5.1

<PackageReference Include="Phobos.Tracing" Version="1.5.1"/>

paket add Phobos.Tracing --version 1.5.1

Paket is a third-party, open source alternative to the NuGet client.

Release Notes

Minor Version Release of Phobos 1.x** Phobos 1.5 is the next minor version release of Phobos. It contains two major, important changes: 1. Overhaul of the Trace Filtering System and 2. Integrated with [Akka.Hosting](https://github.com/akkadotnet/Akka.Hosting), a new HOCONless way of configuring, running, and integrating Akka.NET with the other parts of your .NET applications. See the ["Introduction to Akka.Hosting - HOCONless, "Pit of Success" Akka.NET Runtime and Configuration" video with details here](https://www.youtube.com/watch?v=Mnb9W9ClnB0). This is accomplished through the new `Phobos.Hosting` NuGet package introduced in Phobos 1.5. And we've also fixed the following bugs: 1. https://github.com/petabridge/phobos-issues/issues/54 2. https://github.com/petabridge/phobos-issues/issues/53 New and Improved Trace Filtering** This release contains some **breaking changes** which we've introduced intentionally in order to get users concerned about noise control from the Phobos tracing system to migrate over to a new set of APIs that perform the job in a much more coherent fashion that what we have currently in Phobos 1.4. You can see some examples of end-user negative experience reports with the current v1.x and 2.x trace filtering implementations here: https://github.com/petabridge/phobos-issues/issues/46 https://github.com/petabridge/phobos-issues/issues/49 There have been many more like these over the past couple of years - separating noise from useful signals has been a persistent challenge with Phobos tracing and the changes we're introducing in Phobos v1.5 and 2.0 address this with a small new API: ```csharp /// <summary> /// Each <see cref="ActorSystem"/> can implement exactly one of these to control /// the decision-making around which traces to include and which ones to exclude. /// /// When this type is configured, it will replace all of the <see cref="IFilterRule"/>s /// that have been previously defined. /// </summary> /// <seealso cref="FilterDecision"/> public interface ITraceFilter { /// <summary> /// Evaluates a message processed by an actor and determines whether or not to include it in the current /// or a new trace. /// </summary> /// <param name="message">The message currently being processed by an actor.</param> /// <param name="alreadyInTrace">Whether or not this message is already part of an active trace.</param> /// <returns><c>true</c> if we are going to trace the message, <c>false</c> otherwise.</returns> /// <remarks> /// Should return <c>true</c> unless you are explicitly trying to filter a given message out of your trace. /// </remarks> bool ShouldTraceMessage(object message, bool alreadyInTrace); } ``` This is the `ITraceFilter` - and there is _exactly one of these_ for your entire `ActorSystem`. It allows you to decide whether or not to trace an actor's message processing activity based on: Message type; Message content; and Whether or not we are inside an active trace or not. This API is astonishingly succinct, much clearer than the previous `TracingConfigBuilder` API from before, extremely performant, and very effective at limiting noise inside your Phobos-enabled Akka.NET applications. An example from one of our own stress testing applications: ```csharp public sealed class ScenarioTraceFilter : ITraceFilter { public bool ShouldTraceMessage(object message, bool alreadyInTrace) { switch (message) { /* Only start new traces for these commands / case IScenarioProtocolMessage _: case Petabridge.Cmd.Command _: case Petabridge.Cmd.CommandResponse _: return true; default: // otherwise, only allow messages already in trace to be included return alreadyInTrace; } } } ``` This class allows new traces to only be started handful of [Petabridge.Cmd](https://cmd.petabridge.com/) types and any messages and our custom `IScenarioProtocol` messages. Any additional messages _will not_ be included in a trace unless there is already an active trace present. You can add this `ITraceFilter` to your applications like so: ```csharp var phobosSetup = PhobosSetup.Create(new PhobosConfigBuilder() .WithMetrics(m => m.SetMetricsRoot(metrics)) // binds Phobos to same IMetricsRoot as ASP.NET Core .WithTracing(t => t.SetTracer(tracer) .SetTraceFilter(new ScenarioTraceFilter()) )) // binds Phobos to same tracer as ASP.NET Core .WithSetup(BootstrapSetup.Create() .WithActorRefProvider(PhobosProviderSelection .Local)); // last line activates Phobos inside Akka.NET ``` Phobos still supports the old `TracingConfigBuilder` pattern and the `WithIncludeMessage<T>` rules - however, all of those rules will be overidden and replaced when the `ITraceFilter` is used instead. We have broken the old `TracingConfigBuilder` method signatures in order to alert users to this important change. You can see the full details here: "[Filtering Tracing Data with Phobos](https://phobos.petabridge.com/articles/trace-filtering.html)" Akka.Hosting Integration and Simplified Configuration** Phobos can now be fully configured without any HOCON or mangling of `Setup` classes using the brand new `Phobos.Hosting` NuGet package, built on top of [Akka.Hosting](https://github.com/akkadotnet/Akka.Hosting). > [!TIP] > Unfamiliar with Akka.Hosting? See the ["Introduction to Akka.Hosting - HOCONless, "Pit of Success" Akka.NET Runtime and Configuration" video with details here](https://www.youtube.com/watch?v=Mnb9W9ClnB0). See **[Configuring Phobos 2.0 - Using Phobos.Hosting](xref:configuration#use-phoboshosting)** for full details.