IFailureClassifier
Package Trax.EffectNamespace Trax.Effect.Services.FailureClassifierSource IFailureClassifier.cs
Decides what kind of failure an exception represents, so Trax records a FailureClass on every failed run. Optional: with none registered, every failure records Unclassified.
Signature
namespace Trax.Effect.Services.FailureClassifier;
public interface IFailureClassifier
{
FailureClass? Classify(Exception exception);
}Parameters
| Parameter | Type | Description |
|---|---|---|
exception | Exception | The original exception the run failed with, not a wrapper, so you can type-check it and read its structured data |
Returns
FailureClass?: Transient, Conflict, Permanent or Unclassified, or null to leave the failure unclassified.
FailureClass is in Trax.Core.Exceptions.
Behavior
There is no builder method: the classifier is registered in the container. Trax resolves one IFailureClassifier
from the train's service provider, so the last registration wins, and a run executed on a remote worker uses the
worker process's registration.
| Situation | What is recorded |
|---|---|
| No classifier registered, or it returns null | Unclassified |
| The classifier throws | Unclassified; the classifier's exception is logged and the run's failure is unaffected |
| The run was asked to stop (its token was cancelled, or its cancel flag was set) | Cancelled state; the classifier is not called |
An OperationCanceledException nothing asked for, such as an HttpClient timeout (TaskCanceledException) | Failed state; the classifier's answer, or Transient when it has none |
| The failure already carries a class (a remote worker sent one, or a calling-side junction preserved it) | The carried class; it wins over the local classifier |
Another exception type, including a subclass of TrainException, whose message is JSON shaped like a failure record | Its message is not read for a class; only an exception whose type is exactly TrainException carries one there, so the classifier decides as usual |
| A carried class outside the vocabulary | Unclassified |
| The failure was rebuilt from a serialized record (a remote failure) and carries no class | Unclassified; a rebuilt exception is never passed to the local classifier, because its original type is gone |
| The scheduler recorded the failure (dispatch failure, stale-run reaping) | Unclassified |
| A failure raised outside any junction | The classifier's answer |
A Parallel step failed (BranchesFailedException) | Each failed branch's class, taken as above for that branch's own failure (the class it carries, else the classifier's answer for its exception), combined: Permanent if any is, else Unclassified if any is or has none, else Conflict if any is, else Transient. A branch stopped because a sibling failed is not counted. The classifier is not asked about the BranchesFailedException itself |
A run cancelled while its Parallel branches ran (its token, or its cancel flag read by one branch) | Cancelled state, as for any requested cancellation |
An OperationCanceledException nothing asked for, raised inside a Parallel branch | That branch's failure, counted in the BranchesFailedException like any other |
The recorded class is Metadata.FailureClass, readable in OnFailed, persisted in the failure_class column, and exposed over GraphQL as failureClass.
Example
using System.Net;
using Trax.Core.Exceptions;
using Trax.Effect.Services.FailureClassifier;
services.AddSingleton<IFailureClassifier, ErpFailureClassifier>();
public class ErpFailureClassifier : IFailureClassifier
{
public FailureClass? Classify(Exception exception) =>
exception switch
{
HttpRequestException { StatusCode: HttpStatusCode.Conflict } => FailureClass.Conflict,
HttpRequestException { StatusCode: HttpStatusCode.TooManyRequests } => FailureClass.Transient,
HttpRequestException { StatusCode: HttpStatusCode.BadRequest } => FailureClass.Permanent,
_ => null,
};
}