RetailSolutions.Shared.Logs 1.3.1449

RetailSolutions.Shared.Logs

Biblioteca .NET para abstrações de logging com suporte a Serilog, Elasticsearch e Sentry — projetada para microsserviços e APIs ASP.NET Core.

Funcionalidades

• Configuração simplificada do Serilog com suporte a HostApplicationBuilder e WebApplicationBuilder
• Integração com Elasticsearch via Data Streams (abordagem recomendada para logs)
• Integração com Sentry para monitoramento e rastreamento de erros
• Enriquecimento automático de logs (exceções, ambiente, nome da aplicação, contexto)
• Enriquecimento de contexto HTTP: IP do cliente, Correlation ID, User-Agent
• Resiliência embutida — a aplicação não falha se o Elasticsearch estiver indisponível
• Log em arquivo com rotação por tamanho e retenção configurável
• Cliente Elasticsearch para operações customizadas de indexação e consulta
• Constantes padronizadas de log para consistência entre serviços

Instalação

.NET CLI

dotnet add package RetailSolutions.Shared.Logs

Package Manager

Install-Package RetailSolutions.Shared.Logs

PackageReference

<PackageReference Include="RetailSolutions.Shared.Logs" Version="1.0.0" />

Requisitos

• .NET 10.0 ou superior
• Elasticsearch 8.0+ (opcional)
• Conta Sentry (opcional)

Configuração do Serilog

HostApplicationBuilder (Worker Services, Console Apps)

using RetailSolutions.Shared.Logs;
using RetailSolutions.Shared.Logs.Elasticsearch;
using static RetailSolutions.Shared.Logs.SerilogExtension;

var builder = Host.CreateApplicationBuilder(args);

builder.AddSerilog(builder.Configuration, new SerilogConfiguration
{
    ApplicationName = "MeuServico",
    EnrichedClientInfo = false,
    Elasticsearch = new ElasticConfiguration
    {
        Enabled = true,
        Uri = "https://elasticsearch:9200",
        User = "elastic",
        Password = "senha",
        DataStreamName = "logs",
        IndexName = "meu-servico"
    },
    Sentry = new SentryConfiguration
    {
        Enabled = true,
        Dsn = "https://dsn@sentry.io/id",
        MinimumLevel = LogEventLevel.Warning,
        Environment = "Production",
        Release = "1.0.0"
    }
});

var app = builder.Build();
await app.RunAsync();

WebApplicationBuilder (ASP.NET Core APIs)

using RetailSolutions.Shared.Logs;
using RetailSolutions.Shared.Logs.Elasticsearch;
using static RetailSolutions.Shared.Logs.SerilogExtension;

var builder = WebApplication.CreateBuilder(args);

builder.AddSerilog(builder.Configuration, new SerilogConfiguration
{
    ApplicationName = "MinhaApi",
    EnrichedClientInfo = true  // habilita IP, CorrelationId, User-Agent
});

var app = builder.Build();
app.Run();

appsettings.json

O nível mínimo de log e overrides por namespace são configurados via Serilog padrão:

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning",
        "Microsoft.AspNetCore": "Warning"
      }
    }
  }
}

Sinks Disponíveis

Console

Habilitado por padrão. Formato:

2025-01-27 14:30:00.000 +00:00 [INF] Mensagem { Properties }

Elasticsearch

Usa Data Streams, com nome gerado automaticamente no padrão:

{DataStreamName}-{IndexName}-{Environment}

Exemplo: logs-meu-servico-Production

Resiliência: se o Elasticsearch estiver inacessível ou mal configurado, a aplicação continua funcionando normalmente. Erros são reportados via System.Diagnostics.Trace.

Sentry

Arquivo de Texto

new SerilogConfiguration
{
    ApplicationName = "MeuServico",
    Text = new TextConfiguration
    {
        File = true,
        Path = "logs",           // diretório
        FileName = "log.txt",    // nome do arquivo
        FileSizeLimitBytes = 10 * 1024 * 1024,  // 10 MB
        RetainedFileCountLimit = 31
    }
}

Enriquecimento de Logs

Todos os logs incluem automaticamente:

• ApplicationName — nome configurado em SerilogConfiguration.ApplicationName
• EnvironmentName — valor de DOTNET_ENVIRONMENT ou ASPNETCORE_ENVIRONMENT
• ExceptionDetail — detalhes completos de exceções via Serilog.Exceptions
• Contexto de log (LogContext)

Quando EnrichedClientInfo = true (recomendado para APIs):

• ClientIp — IP do cliente
• CorrelationId — header correlation-id (gerado automaticamente se ausente)
• User-Agent — header do cliente

Cliente Elasticsearch

Para operações diretas de indexação e consulta além do logging:

// Registro
builder.AddElasticsearchClient();

// Criação de índices na inicialização
var app = builder.Build();
await app.UseElasticsearchClient("meu-indice");
// ou múltiplos índices
await app.UseElasticsearchClient(new[] { "indice-a", "indice-b" });

Injeção de dependência

using RetailSolutions.Shared.Logs.Elasticsearch;

public class MeuServico
{
    private readonly IElastic _elastic;

    public MeuServico(IElastic elastic) => _elastic = elastic;

    public async Task SalvarAsync(string id, MeuDado dado)
    {
        await _elastic.SendDataToElasticAsync("meu-indice", id, dado);
    }

    public async Task<MeuDado> BuscarAsync(string id)
    {
        return await _elastic.GetDataFromElasticAsync<MeuDado>("meu-indice", id);
    }
}

Interface IElastic

A configuração do cliente usa a seção ElasticConfiguration do appsettings.json por padrão:

{
  "ElasticConfiguration": {
    "Enabled": true,
    "Uri": "https://elasticsearch:9200",
    "User": "elastic",
    "Password": "senha",
    "DataStreamName": "log",
    "IndexName": "microservices"
  }
}

Constantes de Log

Use LogConstants para padronizar nomes de propriedades e mensagens entre serviços:

using RetailSolutions.Shared.Logs;

_logger.LogInformation(LogConstants.LOG_SERVICE_STARTING_SERVICE, "NomeIntegracao");
_logger.LogWarning(LogConstants.LOG_WARNING_SEM_ARGUMENTOS);

// Estruturado
using (LogContext.PushProperty(LogConstants.LOG_ENDPOINT, endpoint))
{
    _logger.LogInformation(LogConstants.LOG_REQUEST);
}

Dependências

Licenca

Copyright © Retail Solutions. Todos os direitos reservados.

Autores: Renato Campos — Retail Solutions