ErrorIntelligence.Core 1.1.1

Error Intelligence SDK

A .NET SDK that intercepts errors via ILogger and ASP.NET Core middleware, normalizes them into an ErrorEvent, and publishes to a queue. An Orchestrator (Phase 2) consumes the queue and routes to specialized agents that diagnose and attempt to remediate the problem automatically.

Architecture

APPLICATION
   │
   ├── with catch  → logger.LogError(ex, ...) → SDK (ILoggerProvider)
   └── without catch → Middleware → SDK
                            │
                            ▼
                     ErrorEvent (normalized + enriched)
                            │
                            ▼
                   IErrorPublisher (abstraction)
                            │
                            ▼
               Azure Service Bus (queue)
                            │
                            ▼
                      ORCHESTRATOR          ← Phase 2
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
          DB Agent     Code Agent    Infra Agent

Core principle: the SDK is dumb — it only captures and publishes. Intelligence lives in the Orchestrator and Agents. The application never breaks if the queue is offline.

Packages

Installation

Requirements: .NET 8 or higher

dotnet add package ErrorIntelligence.AspNetCore
dotnet add package ErrorIntelligence.Publisher.ServiceBus

Usage

Setup via appsettings.json (recommended)

{
  "ErrorIntelligence": {
    "ServiceName": "order-service",
    "Environment": "production",
    "ServiceBus": {
      "FullyQualifiedNamespace": "mynamespace.servicebus.windows.net",
      "QueueOrTopicName": "error-intelligence"
    }
  }
}

For local dev without Managed Identity, replace FullyQualifiedNamespace with ConnectionString.

In Program.cs, just three lines:

builder.Services.AddErrorIntelligence(builder.Configuration);
builder.Services.AddServiceBusErrorPublisher(builder.Configuration);

app.UseErrorIntelligence(); // must come before other middlewares

Setup via code (explicit alternative)

// Managed Identity (production)
builder.Services.AddErrorIntelligence(options =>
{
    options.ServiceName  = "order-service";
    options.Environment  = "production";
});

builder.Services.AddServiceBusErrorPublisher(options =>
{
    options.FullyQualifiedNamespace = "mynamespace.servicebus.windows.net";
    options.QueueOrTopicName        = "error-intelligence";
    // OR for local dev:
    // options.ConnectionString = "Endpoint=sb://...";
});

app.UseErrorIntelligence();

Application code — zero changes required

The SDK works without modifying any existing catch blocks:

// Captured via ILogger
try
{
    await orderService.ProcessAsync(orderId);
}
catch (Exception ex)
{
    logger.LogError(ex, "Error processing order {OrderId}", orderId);
    throw;
}

// Unhandled exceptions are automatically captured by the middleware

ErrorEvent — message contract

Each error published to the queue has the following format:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timestamp": "2026-08-28T14:32:00.000Z",
  "service": "order-service",
  "environment": "production",
  "host": "pod-xyz-123",
  "severity": "Error",
  "exceptionType": "System.Data.SqlClient.SqlException",
  "message": "Error processing order 42",
  "stackTrace": "...",
  "innerExceptionType": null,
  "innerExceptionMessage": null,
  "traceId": "00-abc123-def456-00",
  "correlationId": "corr-789",
  "request": {
    "method": "POST",
    "path": "/api/orders",
    "queryString": null,
    "statusCode": null,
    "userAgent": "..."
  },
  "context": {
    "OrderId": "42",
    "UserId": "user-99"
  }
}

Resilience

The Service Bus publisher never breaks the application under any circumstance:

Resilience configuration

builder.Services.AddServiceBusErrorPublisher(options =>
{
    options.FullyQualifiedNamespace             = "mynamespace.servicebus.windows.net";
    options.QueueOrTopicName                    = "error-intelligence";
    options.MaxRetryAttempts                    = 5;   // default: 3
    options.CircuitBreakerBreakDurationSeconds  = 120; // default: 60
});

Managed Identity

The SDK uses the host application's identity via DefaultAzureCredential. The application — not the SDK — needs the permission.

Required role

Assign Azure Service Bus Data Sender to the application's Managed Identity:

# Get Service Bus namespace resource ID
$sbId = az servicebus namespace show \
  --name mynamespace \
  --resource-group my-rg \
  --query id -o tsv

# Get the Managed Identity principal ID (example: App Service)
$principalId = az webapp identity show \
  --name my-api \
  --resource-group my-rg \
  --query principalId -o tsv

# Assign role on the specific queue (recommended — least privilege)
az role assignment create \
  --assignee $principalId \
  --role "Azure Service Bus Data Sender" \
  --scope "$sbId/queues/error-intelligence"

Local development

az login
az account set --subscription <your-subscription>

DefaultAzureCredential will use your CLI credentials. Alternatively, use ConnectionString in appsettings.Development.json:

{
  "ErrorIntelligence": {
    "ServiceBus": {
      "ConnectionString": "Endpoint=sb://mynamespace.servicebus.windows.net/;SharedAccessKeyName=..."
    }
  }
}

Deduplication

When a catch calls logger.LogError(ex, ...) and then throw, the SDK uses AsyncLocal to mark the error as already published. The middleware detects this flag and skips republishing.

Service throws
   │
   ├── catch → logger.LogError → SDK publishes → [flag: published]
   │
   └── throw → middleware → [flag detected] → SKIP (no duplicate)

Worker Services and Console Apps

For non-HTTP applications, install only Core — no UseErrorIntelligence() needed:

builder.Services.AddErrorIntelligence(options => { ... });
builder.Services.AddServiceBusErrorPublisher(options => { ... });

Publishing

Packages are published to NuGet.org via GitHub Actions using NuGet Trusted Publishing (passwordless OIDC — no API key stored as secret).

How it works

1. Push a git tag matching v* (e.g. v1.2.3)
2. GitHub Actions runs build-and-test first
3. On success, the publish job:
   • Requests an OIDC token from GitHub Actions
   • Exchanges it for a short-lived NuGet API key via NuGet/login@v1
   • Packs all 3 packages with the version extracted from the tag
   • Pushes them to nuget.org

# .github/workflows/publish.yml (simplified)
- name: NuGet login (Trusted Publishing)
  uses: NuGet/login@v1
  id: nuget-login
  with:
    user: AndreMieresNova

- name: Publish to NuGet
  run: |
    dotnet nuget push ./nupkgs/*.nupkg \
      --api-key "${{ steps.nuget-login.outputs.NUGET_API_KEY }}" \
      --source https://api.nuget.org/v3/index.json \
      --skip-duplicate

Releasing a new version

git tag v1.2.3
git push origin v1.2.3

That's it — all 3 packages are published automatically with no secrets required.

Running Tests

dotnet test

Passed: 13 / 13

For the project vision and upcoming phases, see ROADMAP.md.