Nexx.Observability.Client 1.2.0

Nexx.Observability.Client

Cliente .NET 8 para envio de métricas e erros para a plataforma centralizada Nexx.Observability hospedada em Supabase.

Princípio Crítico

Observabilidade nunca deve derrubar o projeto principal.

Todas as operações são:

• Fire-and-forget: retornam imediatamente, não bloqueiam
• Silenciosas em falha: exceções são capturadas e descartadas
• Com retry automático: mensagens que falham são reprocessadas a cada 10 segundos
• Thread-safe: podem ser usadas em ambiente multi-threaded

Características Principais

✓ HTTPS obrigatório - Validação na inicialização (única exception permitida) ✓ Timeout de 5 segundos - Previne travamento da aplicação ✓ Buffer com fila de reprocessamento - Máximo 1000 mensagens pendentes ✓ Retry automático - Até 3 tentativas com intervalo de 10 segundos ✓ Flush final - Aguarda até 3 segundos ao descartar para enviar mensagens pendentes ✓ Sem dependências externas - Usa apenas APIs padrão do .NET 8 ✓ IDisposable - Limpeza correta de recursos

Instalação

dotnet add package Nexx.Observability.Client

Ou adicione ao seu .csproj:

<ItemGroup>
  <PackageReference Include="Nexx.Observability.Client" Version="4.0.0" />
</ItemGroup>

Configuração

1. Adicionar seção no appsettings.json

{
  "Observability": {
    "Url": "https://seu-projeto.supabase.co",
    "ApiKey": "sua-chave-de-api-aqui"
  }
}

Nota: A URL DEVE começar com https://. Conexões não-criptografadas não são permitidas.

2. Registrar no container de DI

Em Program.cs:

builder.Services.AddNexxObservability(builder.Configuration);

Uso

Injetar em seu serviço ou controller

public class ProcessamentoService
{
    private readonly NexxObservabilityClient _observability;

    public ProcessamentoService(NexxObservabilityClient observability)
    {
        _observability = observability;
    }

    public async Task ProcessarEncomedas()
    {
        try
        {
            int recebidas = 100;
            int processadas = 98;
            int comErro = 2;

            // ... processamento ...

            // Enviar métrica
            await _observability.EnviarMetricaAsync(
                tabela: "ProcessamentoEncomendas",
                recebidos: recebidas,
                processados: processadas,
                comErro: comErro,
                duracaoMs: 5000,
                objType: "Encomenda",
                loteNumero: 1,
                origem: "IntegracaoERP"
            );
        }
        catch (Exception ex)
        {
            // Enviar erro
            await _observability.EnviarErroAsync(
                tabela: "ProcessamentoEncomendas",
                mensagemErro: ex.Message,
                objType: "Encomenda",
                chaveRegistro: "ENC123456",
                stackTrace: ex.StackTrace,
                tipoErro: ex.GetType().Name,
                origem: "IntegracaoERP"
            );
        }
    }
}

Métodos Disponíveis

EnviarMetricaAsync

Envia uma métrica de processamento.

public async Task EnviarMetricaAsync(
    string tabela,           // Nome da tabela processada
    int recebidos,          // Quantidade de registros recebidos
    int processados,        // Quantidade processada com sucesso
    int comErro,            // Quantidade com erro
    int? duracaoMs = null,  // Duração em milissegundos (opcional)
    string? objType = null, // Tipo de objeto (ex: "Encomenda") (opcional)
    int? loteNumero = null, // Número do lote (opcional)
    string? origem = null   // Origem do processamento (opcional)
)

EnviarErroAsync

Envia detalhes de um erro.

public async Task EnviarErroAsync(
    string tabela,              // Nome da tabela onde o erro ocorreu
    string mensagemErro,        // Mensagem descritiva do erro
    string? objType = null,     // Tipo de objeto (opcional)
    string? chaveRegistro = null, // ID/chave do registro com erro (opcional)
    object? payload = null,     // Dados adicionais (opcional)
    string? stackTrace = null,  // Stack trace da exceção (opcional)
    string? tipoErro = null,    // Tipo/classe da exceção (opcional)
    int? statusHttp = null,     // Código HTTP se aplicável (opcional)
    string? origem = null       // Origem do erro (opcional)
)

EnviarLoteAsync

Envia um lote completo com métricas e lista de erros.

public async Task EnviarLoteAsync(
    string tabela,                      // Nome da tabela
    int recebidos,                     // Quantidade recebida
    int processados,                   // Quantidade processada
    int comErro,                       // Quantidade com erro
    int? duracaoMs = null,             // Duração em ms (opcional)
    string? objType = null,            // Tipo de objeto (opcional)
    IEnumerable<ErroPayload>? erros = null, // Lista de erros (opcional)
    string? origem = null              // Origem (opcional)
)

Modelo ErroPayload

public class ErroPayload
{
    public string? ChaveRegistro { get; set; }  // ID do registro
    public object? Payload { get; set; }        // Dados adicionais
    public string MensagemErro { get; set; }    // Mensagem do erro
    public string? StackTrace { get; set; }     // Stack trace
    public string? TipoErro { get; set; }       // Tipo da exceção
    public int? StatusHttp { get; set; }        // Código HTTP
}

Comportamento em Caso de Falha

Se o envio falhar por qualquer motivo:

1. A mensagem é adicionada a uma fila de reprocessamento interna
2. Um timer automático (a cada 10 segundos) tenta reenviar
3. Cada mensagem é tentada no máximo 3 vezes
4. Após 3 falhas, a mensagem é descartada silenciosamente
5. Se a fila atingir 1000 mensagens, as mensagens mais antigas são descartadas
6. Durante Dispose(), há um flush final (aguarda até 3 segundos)

Garantia: O cliente nunca lançará exceção que derrube sua aplicação.

Thread Safety

O cliente é 100% thread-safe e pode ser injetado como Singleton:

// Seguro usar em múltiplas threads simultaneamente
Task.Run(() => _observability.EnviarMetricaAsync(...));
Task.Run(() => _observability.EnviarErroAsync(...));

Limpeza de Recursos

O cliente implementa IDisposable:

using var client = new NexxObservabilityClient("https://...", "api-key");

// Usar...

// Ao sair do bloco using:
// - Timer de reprocessamento é cancelado
// - Fila pendente é processada (timeout de 3s)
// - HttpClient é descartado

Se usar injeção de dependência (recomendado), a limpeza é automática:

// Program.cs
builder.Services.AddNexxObservability(builder.Configuration);

// Ao encerrar a aplicação, o Dispose é chamado automaticamente

Exemplo Completo

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddNexxObservability(builder.Configuration);
builder.Services.AddScoped<ProcessamentoService>();

var app = builder.Build();

// appsettings.json
{
  "Observability": {
    "Url": "https://seu-projeto.supabase.co",
    "ApiKey": "seu-api-key"
  }
}

// ProcessamentoService.cs
public class ProcessamentoService
{
    private readonly NexxObservabilityClient _obs;

    public ProcessamentoService(NexxObservabilityClient obs)
    {
        _obs = obs;
    }

    public async Task ProcessarLoteAsync(List<Encomenda> encomendas)
    {
        var processadas = 0;
        var erros = new List<ErroPayload>();

        var inicio = DateTime.UtcNow;

        foreach (var enc in encomendas)
        {
            try
            {
                // Processar...
                processadas++;
            }
            catch (Exception ex)
            {
                erros.Add(new ErroPayload
                {
                    ChaveRegistro = enc.Id.ToString(),
                    MensagemErro = ex.Message,
                    StackTrace = ex.StackTrace,
                    TipoErro = ex.GetType().Name
                });
            }
        }

        var duracao = (int)(DateTime.UtcNow - inicio).TotalMilliseconds;

        // Enviar lote com todas as métricas e erros
        await _obs.EnviarLoteAsync(
            tabela: "ProcessamentoEncomendas",
            recebidos: encomendas.Count,
            processados: processadas,
            comErro: erros.Count,
            duracaoMs: duracao,
            objType: "Encomenda",
            erros: erros,
            origem: "IntegracaoERP"
        );
    }
}

Validações

• URL deve ser HTTPS: Se não for, ArgumentException é lançado na inicialização
• ApiKey não pode ser vazia: Se vazia, ArgumentException é lançado
• Configuração obrigatória: Se "Observability" não estiver no config, InvalidOperationException é lançado

Performance

• Timeout: 5 segundos máximo por requisição
• Buffer: Máximo 1000 mensagens na fila
• Retry: Cada 10 segundos, até 100 mensagens por ciclo
• Flush: Máximo 3 segundos ao descartar

Suporte

Para relatórios de bugs ou sugestões, entre em contato com o time Nexx.

Licença

MIT