L2.Common 1.0.0

L2.Common

Pacote NuGet com métodos e configurações comuns para projetos de estudos, focado em observabilidade e logging estruturado.

📋 Funcionalidades

🔍 Observabilidade

• OpenTelemetry completo com tracing, métricas e logs
• Configuração automática de instrumentação para ASP.NET Core
• Suporte a OTLP (OpenTelemetry Protocol) para exportação
• Correlação automática entre logs e traces
• Middleware de logging estruturado para requisições HTTP

📚 Swagger/OpenAPI

• Configuração automática do Swagger UI
• Documentação XML integrada
• Interface customizada com filtros e duração de requisições
• Preparado para autenticação JWT (comentado)

🛠️ Utilitários

• Constantes e helpers reutilizáveis
• Interfaces bem definidas para injeção de dependência
• Configurações padronizadas para diferentes ambientes

🚀 Instalação

dotnet add package L2.Common

📖 Como Usar

Configuração Básica

using L2.Commom.Configurators;
using L2.Commom.Configurators.Otel;
using L2.Commom.Middlewares;

var builder = WebApplication.CreateBuilder(args);

// Configuração do OpenTelemetry
var serviceName = Assembly.GetExecutingAssembly().GetName().Name!;
var serviceVersion = Assembly.GetExecutingAssembly().GetName().Version?.ToString() ?? "1.0.0";
var environment = Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") ?? "Production";
var serviceInstanceId = Environment.MachineName;

builder.Services
    .AddOtelConfigurator(builder.Configuration, serviceName, serviceVersion, environment, serviceInstanceId, clearLoggingProviders: true)
    .UseOtelBuilder()
    .WithLogging();

// Configuração do Swagger
builder.Services.AddCustomSwagger();

builder.Services.AddControllers();

var app = builder.Build();

// Middleware de logging
app.UseMiddleware<LoggingMiddleware>();

// Swagger apenas em desenvolvimento
if (app.Environment.IsDevelopment())
    app.UseCustomSwagger();

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();

Configuração de Ambiente

Adicione as seguintes configurações no appsettings.json:

{
  "Observability": {
    "Otlp": {
      "Endpoint": "http://otel-collector:4317"
    }
  }
}

Ou defina a variável de ambiente:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317

🏗️ Estrutura do Projeto

L2.Common.Package/
├── Configurators/
│   ├── Otel/
│   │   ├── OpenTelemetryConfigurator.cs
│   │   ├── OtelBuilder.cs
│   │   ├── OtelConfigurator.cs
│   │   └── OtelConfiguratorExtensions.cs
│   └── SwaggerConfigurator.cs
├── Handlers/
│   └── TelemetryHandler.cs
├── Helpers/
│   └── Constants.cs
├── Interfaces/
│   ├── Configurators/Otel/
│   ├── Handlers/
│   └── IRequestLogger.cs
├── Logging/
│   └── RequestLogger.cs
└── Middlewares/
    └── LoggingMiddleware.cs

🔧 Configurações Avançadas

OpenTelemetry Customizado

// Configuração apenas de tracing
builder.Services.AddOtelConfigurator(config, serviceName, serviceVersion, environment, serviceInstanceId)
    .ConfigureTracing();

// Configuração apenas de métricas
builder.Services.AddOtelConfigurator(config, serviceName, serviceVersion, environment, serviceInstanceId)
    .ConfigureMetrics();

// Configuração completa com opções customizadas
builder.Services.AddOtelConfigurator(config, serviceName, serviceVersion, environment, serviceInstanceId)
    .ConfigureCompleteTelemetry(enableTracing: true, enableMetrics: true);

Atributos Customizados

var customAttributes = new Dictionary<string, object>
{
    ["team"] = "Meu Time",
    ["application.layer"] = "API",
    ["timezone"] = "America/Sao_Paulo"
};

builder.Services.AddOtelConfigurator(
    config, 
    serviceName, 
    serviceVersion, 
    environment, 
    serviceInstanceId,
    customAttributes: customAttributes);

📊 Logs Estruturados

O pacote gera logs estruturados automaticamente com as seguintes informações:

{
  "trace_id": "abc123...",
  "span_id": "def456...",
  "method": "GET",
  "path": "/api/weather",
  "status_code": 200,
  "duration_ms": 150,
  "user": "anonymous",
  "client_ip": "192.168.1.1"
}

🧪 Projeto de Teste

O repositório inclui um projeto de teste (L2.Common.ApiTest) que demonstra como usar o pacote:

cd L2.Common.ApiTest
dotnet run

Acesse o Swagger em: https://localhost:7000/swagger

📦 Dependências

• .NET 9.0
• OpenTelemetry.Exporter.Console (1.12.0)
• OpenTelemetry.Exporter.OpenTelemetryProtocol (1.12.0)
• OpenTelemetry.Extensions.Hosting (1.12.0)
• OpenTelemetry.Instrumentation.AspNetCore (1.12.0)
• OpenTelemetry.Instrumentation.Http (1.12.0)
• Swashbuckle.AspNetCore (9.0.4)

🤝 Contribuição

1. Faça um fork do projeto
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

👨‍💻 Autor

Danielle Oliveira

• GitHub: @danibrdev
• Repository: L2.Common

🆕 Changelog

v1.0.0

• Configuração inicial do OpenTelemetry
• Middleware de logging estruturado
• Configuração do Swagger
• Suporte a tracing, métricas e logs
• Correlação automática entre logs e traces