Reference

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

ParameterTypeDescription
exceptionExceptionThe 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.

SituationWhat is recorded
No classifier registered, or it returns nullUnclassified
The classifier throwsUnclassified; 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 recordIts 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 vocabularyUnclassified
The failure was rebuilt from a serialized record (a remote failure) and carries no classUnclassified; 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 junctionThe 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 branchThat 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,
        };
}

See also