TCIS.Observability.Classification 1.0.8-rc.11

TCIS.Observability.Classification

A lightweight, zero-dependency .NET library that provides a standardized Exception Classification Taxonomy for enterprise applications. It categorizes runtime exceptions by Failure Category, Operational Owner, Infrastructure Dependency, Support Level, and Machine Error Code.

Key Features

• Standardized Exception Taxonomy: Categorizes failures into Infrastructure, Developer, Business, Security, or Unknown.
• Operational Ownership & Escalation: Identifies the responsible team (Ops, Dev, Business, Security) and Support Level (L1, L2, L3).
• Dependency Tracking: Maps failures to underlying infrastructure (Database, Cache, Kafka, RabbitMQ, Redis, Http, etc.).
• Smart Exception Unwrapping: Automatically inspects InnerException chains up to depth 8 while respecting terminal domain/protocol boundaries (e.g., TCIS validation exceptions, gRPC RPC exceptions, SOAP faults).
• Loose-Coupled Rules Engine: Includes built-in rules for standard .NET BCL exceptions and type-name matching without requiring hard references to specific database or messaging packages.
• SIEM / Log Tagging: Formats classification metadata into compact, greppable log prefixes for Serilog, Grafana, and Kibana.

Architecture Overview

                      [ Runtime Exception ]
                                │
                                ▼
                   CompositeExceptionClassifier
                                │
                      (Smart Unwrap Chain)
                                │
                                ▼
            ┌───────────────────┴───────────────────┐
            │                                       │
            ▼                                       ▼
    BclExceptionRule                      TypeNameExceptionRule
     (Priority: 900)                         (Priority: 950)
    .NET Core BCL Errors                  Dynamic Type Matching
            │                                       │
            └───────────────────┬───────────────────┘
                                │
                                ▼
                     ExceptionClassification
               ┌─────────────────────────────────┐
               │ Category  : Infrastructure      │
               │ Owner     : Ops                 │
               │ Dependency: Database            │
               │ Support   : L3 (On-Call)        │
               │ ErrorCode : INFRA_DB_TIMEOUT    │
               └─────────────────────────────────┘

Installation

Add the project reference or NuGet package:

dotnet add package TCIS.Observability.Classification

Registration & Dependency Injection

Register exception classification services in Program.cs:

using TCIS.Observability.Classification;

var builder = WebApplication.CreateBuilder(args);

// Register default exception classifier and built-in rules
builder.Services.AddExceptionClassification();

// (Optional) Register custom domain exception rules
builder.Services.AddExceptionClassifierRule<MyCustomDomainExceptionRule>();

Usage Examples

Shared diagnostic severity policy

TExceptionLogPolicy.Decide(exception, classification, cancellationRequested) returns an immutable Models.ExceptionLogDecision for diagnostics owned by TCIS:

ExceptionClassification classification = classifier.Classify(exception);
var decision = TExceptionLogPolicy.Decide(exception, classification,
    cancellationRequested: cancellationToken.IsCancellationRequested);
// The adapter puts decision.Level, LogType and Outcome on its diagnostic record.
// Keep the original exception details and classification on that same record.

A classification without an exception represents a failed protocol/status result. TCIS taxonomy prefixes take precedence over coarse type-based classification: CONFIG_, SYS_ and INFRA_ remain errors even if a rule calls their exception business. An unrequested cancellation or timeout remains an error. Adapters retain configured success levels and source-specific access/audit roles; this policy does not emit logs, configure a sink, alter framework log levels or mutate the exception/classification. Security diagnostic classification remains separate from business classification; protected security/audit records continue through their dedicated policies.

1. Classifying Exceptions in Services or Middleware

using TCIS.Observability.Classification;

public class OrderService
{
    private readonly IExceptionClassifier _classifier;
    private readonly ILogger<OrderService> _logger;

    public OrderService(IExceptionClassifier classifier, ILogger<OrderService> logger)
    {
        _classifier = classifier;
        _logger = logger;
    }

    public async Task ProcessOrderAsync(OrderRequest request)
    {
        try
        {
            await ExecuteOrderPipelineAsync(request);
        }
        catch (Exception ex)
        {
            ExceptionClassification classification = _classifier.Classify(ex);

            // Log operational metadata
            _logger.LogError(ex, "[{Provider}] Order processing failed: {LogPrefix}", 
                "order-service", 
                classification.ToOperationalLogPrefix());

            if (classification.Retryable)
            {
                // Schedule retry for transient infrastructure failures
            }

            throw;
        }
    }
}

2. Creating Custom Classification Rules

To add domain-specific classification rules, implement IExceptionClassifierRule:

using TCIS.Observability.Classification;

public class CustomPaymentExceptionRule : IExceptionClassifierRule
{
    public int Priority => 500; // Lower number = higher priority

    public bool TryClassify(Exception exception, out ExceptionClassification? classification)
    {
        if (exception is PaymentGatewayTimeoutException gatewayEx)
        {
            classification = new ExceptionClassification(
                Category: ExceptionCategory.Infrastructure,
                Owner: ExceptionOwner.Ops,
                Dependency: ExceptionDependency.Http,
                Retryable: true,
                ErrorCode: "PAYMENT_GATEWAY_TIMEOUT",
                PublicMessageKey: MessageKeys.SystemTemporarilyUnavailable,
                ExceptionType: gatewayEx.GetType().Name,
                SupportLevel: SupportLevel.L3
            );
            return true;
        }

        classification = null;
        return false;
    }
}

Exception Categories & Support Tiers

License

Internal Enterprise Library — TCIS Core Platform Framework.

Ecosystem logging contract

See severity, readiness, diagnostic ownership and migration.