ErrorIntelligence.Core 1.0.0

Error Intelligence SDK

SDK para .NET que intercepta erros via ILogger e middleware ASP.NET Core, normaliza em um ErrorEvent e publica em uma fila. Um Orchestrator (Phase 2) consome a fila e roteia para agentes especializados que diagnosticam e tentam remediar o problema automaticamente.

Arquitetura

APLICAÇÃO
   │
   ├── com catch  → logger.LogError(ex, ...) → SDK (ILoggerProvider)
   └── sem catch  → Middleware → SDK
                         │
                         ▼
                   ErrorEvent (normalizado + enriquecido)
                         │
                         ▼
                IErrorPublisher (abstração)
                         │
                         ▼
              Azure Service Bus (queue)
                         │
                         ▼
                   ORCHESTRATOR          ← Phase 2
                         │
             ┌───────────┼───────────┐
             ▼           ▼           ▼
          DB Agent   Code Agent  Infra Agent

Princípio central: o SDK é burro — só captura e publica. A inteligência fica no Orchestrator e nos Agentes. A aplicação nunca quebra se a fila estiver offline.

Projetos

Instalação

Requisitos: .NET 8 ou superior

# Core + ASP.NET Core
dotnet add package ErrorIntelligence.AspNetCore

# Publisher (Azure Service Bus)
dotnet add package ErrorIntelligence.Publisher.ServiceBus

Como usar

Setup via appsettings.json (recomendado)

Adicione a seção no arquivo de configuração:

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

Para dev local sem Managed Identity, substitua FullyQualifiedNamespace por ConnectionString.

No Program.cs, apenas três linhas:

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

app.UseErrorIntelligence(); // deve vir antes dos outros middlewares

Pronto. Zero código de configuração — tudo vem do appsettings.json.

Setup via código (alternativa explícita)

// Managed Identity (produção)
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";
});

// OU Connection String (dev local)
// options.ConnectionString = "Endpoint=sb://...";

app.UseErrorIntelligence();

2. Código de aplicação — zero mudanças

O SDK funciona sem alterar nenhum catch existente:

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

// Exceções sem catch são capturadas automaticamente pelo middleware

ErrorEvent — contrato da mensagem

Cada erro publicado na fila tem o seguinte formato:

{
  "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"
  }
}

Resiliência

O publisher do Service Bus não quebra a aplicação em nenhuma circunstância:

Configuração de resiliência

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

Permissões — Managed Identity

O SDK não tem identidade própria. Ele usa a identidade da aplicação que o hospeda via DefaultAzureCredential. Portanto, quem precisa ter permissão é a aplicação, não o SDK.

Responsabilidades

Como DefaultAzureCredential resolve a identidade

Em produção no Azure, pega automaticamente a Managed Identity do host. Localmente, usa az login. A ordem de tentativa é:

1. EnvironmentCredential      → variáveis AZURE_CLIENT_ID / AZURE_CLIENT_SECRET
2. WorkloadIdentityCredential → AKS com Workload Identity
3. ManagedIdentityCredential  → App Service / Container Apps / VM / AKS pod
4. VisualStudioCredential     → dev local via Visual Studio
5. AzureCliCredential         → dev local via az login  ← mais comum
6. AzurePowerShellCredential  → dev local via Connect-AzAccount

Atribuindo a role (infra / DevOps)

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

# Principal ID da Managed Identity da aplicação (exemplo: App Service)
$principalId = az webapp identity show \
  --name minha-api \
  --resource-group meu-rg \
  --query principalId -o tsv

# Atribuir role no namespace inteiro
az role assignment create \
  --assignee $principalId \
  --role "Azure Service Bus Data Sender" \
  --scope $sbId

# OU somente na fila específica (mais restritivo — recomendado)
az role assignment create \
  --assignee $principalId \
  --role "Azure Service Bus Data Sender" \
  --scope "$sbId/queues/error-intelligence"

Dev local com az login

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

O DefaultAzureCredential usa suas credenciais do CLI. Certifique-se de que seu usuário também tem a role Azure Service Bus Data Sender, ou use ConnectionString no appsettings.Development.json:

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

O .NET carrega o Development por cima do appsettings.json base quando ASPNETCORE_ENVIRONMENT=Development — em produção o Managed Identity prevalece automaticamente.

Deduplicação

Quando um catch chama logger.LogError(ex, ...) e depois faz throw, o SDK usa AsyncLocal para marcar que o erro já foi publicado. O middleware detecta essa flag e não republica o mesmo erro.

Service throw
   │
   ├── catch → logger.LogError → SDK publica → [flag: publicado]
   │
   └── throw → middleware → [flag detectada] → SKIP (sem duplicata)

Workers e Console Apps

Para aplicações sem HTTP (Worker Services, Console), instale apenas o Core:

// Sem UseErrorIntelligence() — o middleware é só para HTTP
builder.Services.AddErrorIntelligence(options => { ... });
builder.Services.AddServiceBusErrorPublisher(options => { ... });

O ILogger continuará interceptando LogError e LogCritical normalmente. Para capturar exceções não tratadas em workers:

AppDomain.CurrentDomain.UnhandledException += (sender, args) =>
{
    // publisher pode ser resolvido via DI e chamado aqui
};

Roadmap

Phase 1 — SDK (concluída ✅)

• ILoggerProvider intercepta LogError / LogCritical
• Middleware captura exceções sem catch
• ErrorEvent normalizado com contexto rico
• Publisher Azure Service Bus com Polly (retry + circuit breaker)
• Managed Identity + Connection String
• Deduplicação via AsyncLocal
• 13 testes unitários

Phase 2 — Orchestrator

• Worker Service que consome a fila
• Classificação por tipo de exceção
• Interface IErrorAgent (chain-of-responsibility)
• Roteamento para agente especializado

Phase 3 — Agentes Especializados

• DB Agent — SqlException, DbException
• Infrastructure Agent — TimeoutException, TaskCanceledException
• Integration Agent — HttpRequestException 5xx
• Code Agent — NullReferenceException, ArgumentException
• LLM Router — classificação inteligente para erros desconhecidos (Azure OpenAI)

Testes

dotnet test

Passed: 13 / 13