NeedlrCancellationLogging

NexusLabs.Needlr.Logging

NeedlrCancellationLogging Class

Global, process-wide policy that Needlr source-generated logging methods consult when their exception argument is a cancellation. Provides an escape hatch from the opinionated default (Skip).

public static class NeedlrCancellationLogging

Inheritance System.Object 🡒 NeedlrCancellationLogging

Remarks

This is a deliberate global feature switch (comparable to an System.AppContext switch), not a service-locator: it must be reachable from allocation-free generated method bodies without threading state through every call site. Set the properties once at application startup — for example, to differ between Debug and Release builds.

The initial defaults are read once, lazily, the first time they are needed, from environment variables, and then cached for the lifetime of the process: - BehaviorEnvironmentVariable — skip (default), log, or demote (case-insensitive). - DemotedLevelEnvironmentVariable — a Microsoft.Extensions.Logging.LogLevel name (e.g. Debug).

Assigning any property overrides the environment-derived default from that point on.

Fields

NeedlrCancellationLogging.BehaviorEnvironmentVariable Field

The environment variable that supplies the initial Behavior default: skip, log, or demote (case-insensitive). Unrecognized or missing values fall back to Skip.

public const string BehaviorEnvironmentVariable = "__NEEDLR_CANCELLATION_LOGGING_BEHAVIOR";

Field Value

System.String

NeedlrCancellationLogging.DemotedLevelEnvironmentVariable Field

The environment variable that supplies the initial DemotedLevel default: any Microsoft.Extensions.Logging.LogLevel name (case-insensitive). Unrecognized or missing values fall back to Microsoft.Extensions.Logging.LogLevel.Debug.

public const string DemotedLevelEnvironmentVariable = "__NEEDLR_CANCELLATION_LOGGING_DEMOTED_LEVEL";

Field Value

System.String

Properties

NeedlrCancellationLogging.Behavior Property

Gets or sets how generated logging methods treat a cancellation exception. Defaults to the value of BehaviorEnvironmentVariable, or Skip when unset.

public static NexusLabs.Needlr.Logging.CancellationLoggingBehavior Behavior { get; set; }

Property Value

CancellationLoggingBehavior

NeedlrCancellationLogging.DemotedLevel Property

Gets or sets the level used when Behavior is Demote. Defaults to the value of DemotedLevelEnvironmentVariable, or Microsoft.Extensions.Logging.LogLevel.Debug when unset.

public static Microsoft.Extensions.Logging.LogLevel DemotedLevel { get; set; }

Property Value

Microsoft.Extensions.Logging.LogLevel

NeedlrCancellationLogging.IsCancellationPredicate Property

Gets or sets the predicate that decides whether an exception counts as a cancellation. The default treats any System.OperationCanceledException (which includes System.Threading.Tasks.TaskCanceledException) as a cancellation.

public static System.Func<System.Exception,bool> IsCancellationPredicate { get; set; }

Property Value

System.Func<System.Exception,System.Boolean>

Exceptions

System.ArgumentNullException
Thrown when set to null.

Methods

NeedlrCancellationLogging.IsCancellation(Exception) Method

Determines whether the supplied exception is considered a cancellation, according to IsCancellationPredicate. This is the entry point called by generated code.

public static bool IsCancellation(System.Exception? exception);

Parameters

exception System.Exception

The exception argument passed to a logging method; may be null.

Returns

System.Boolean
true when exception is non-null and the predicate classifies it as a cancellation; otherwise false.