Phobos.Tracing 2.0.0-beta4

Distributed tracing support for Akka.NET ActorSystems.

Install-Package Phobos.Tracing -Version 2.0.0-beta4

dotnet add package Phobos.Tracing --version 2.0.0-beta4

<PackageReference Include="Phobos.Tracing" Version="2.0.0-beta4"/>

paket add Phobos.Tracing --version 2.0.0-beta4

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

Release Notes

Major Update to Phobos 2.x** 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 / 2.0.0-beta3 and newer. 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-beta4 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 - however, we are going to keep these changes in a beta state for a short period in order to gather feedback from affected users. If you are concerned about trace noise inside your application, _please try this beta_ and report on your experience on the [Phobos Issue Tracker](https://github.com/petabridge/phobos-issues).