Skip to content

Release v2.3.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 21 Jan 02:15
· 60 commits to main since this release
v2.3.0
61b3521

Release Notes v2.3.0

Data de lançamento: 20/01/2026

🆕 Novidades

Tooark.Observability - Novo Pacote

Novo pacote de observabilidade para aplicações .NET, fornecendo integração simplificada com OpenTelemetry para coleta de traces, metrics e logs com configuração via appsettings.json e defaults sensatos.

Classes de Configuração (Options)

Classe Descrição
ObservabilityOptions Configurações principais de Observability
TracingOptions Configurações de rastreamento (tracing)
MetricsOptions Configurações de métricas
LoggingOptions Configurações de logging
OtlpOptions Configurações do exportador OTLP
OtlpBatchOptions Configurações do processador Batch (OTLP)
DataSensitiveOptions Configurações de sanitização de dados sensíveis para Tracing

Enumerações

Enum Descrição
EProtocolOtlp Protocolo de comunicação OTLP (grpc, http)
EProcessorType Tipo de processador de exportação (batch, simple)

Extensões de Injeção de Dependência

Método Descrição
AddTooarkOpenTelemetry() Configura OpenTelemetry com traces, metrics e logs
AddTooarkObservability() Configura Observability + OpenTelemetry

Dependências

Pacote Descrição
Tooark.Exceptions Exceções customizadas
OpenTelemetry SDK base do OpenTelemetry
OpenTelemetry.Exporter.Console Exporter para console (desenvolvimento)
OpenTelemetry.Exporter.OpenTelemetryProtocol Exporter OTLP (gRPC/HTTP)
OpenTelemetry.Extensions.Hosting Integração com Host do .NET
OpenTelemetry.Instrumentation.AspNetCore Instrumentação automática ASP.NET Core
OpenTelemetry.Instrumentation.Http Instrumentação automática HttpClient
OpenTelemetry.Instrumentation.Runtime Métricas do runtime .NET

Principais Funcionalidades

Configuração via appsettings.json

O pacote permite configuração completa via appsettings.json:

{
  "Observability": {
    "Enabled": true,
    "ServiceName": "MeuServico",
    "ServiceVersion": "1.0.0",
    "Otlp": {
      "Enabled": true,
      "Endpoint": "http://localhost:4317",
      "Protocol": "grpc"
    }
  }
}

Configuração Mínima

{
  "Observability": {
    "ServiceName": "MeuServico",
    "Otlp": {
      "Enabled": true,
      "Endpoint": "http://localhost:4317"
    }
  }
}

Configuração Serverless

Para ambientes serverless (AWS ECS, GCP Cloud Run, Azure Container Apps):

{
  "Observability": {
    "ServiceName": "MeuServico",
    "Otlp": {
      "Enabled": true,
      "Endpoint": "http://otel-collector:4317",
      "ServerlessOptimized": true
    }
  }
}

Program.cs

using Tooark.Observability.Injections;

var builder = WebApplication.CreateBuilder(args);

// Adiciona OpenTelemetry com configurações do appsettings.json
builder.Services.AddTooarkOpenTelemetry(builder.Configuration);

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

Configuração Programática

builder.Services.AddTooarkOpenTelemetry(builder.Configuration, options =>
{
    options.ServiceName = "MeuServicoCustomizado";
    options.Tracing.SamplingRatio = 0.5;

    options.ConfigureTracing = builder =>
    {
        // Configuração adicional de tracing
    };

    options.ConfigureMetrics = builder =>
    {
        // Configuração adicional de métricas
    };

    options.ConfigureLogging = loggerOptions =>
    {
        // Configuração adicional de logging
    };
});

Características do Pacote

Tracing

  • ASP.NET Core Instrumentation: captura automaticamente traces de requisições HTTP de entrada
  • HTTP Client Instrumentation: captura traces de requisições HTTP de saída (HttpClient)
  • Filter Paths: por padrão ignora: /health, /healthz, /ready, /traces, /metrics, /logs, /favicon.ico
  • RecordException: exceções são registradas automaticamente nos spans
  • Sampling: configurável via SamplingRatio (0.0 = 0%, 1.0 = 100%)

Sanitização de Dados Sensíveis

Quando DataSensitive = false (padrão):

  • Query Parameters: removidos do atributo http.target
  • Headers Sensíveis: mascarados nos spans (Authorization, Cookie, API keys, etc.)

Metrics

  • ASP.NET Core Instrumentation: métricas de requisições HTTP de entrada
  • HTTP Client Instrumentation: métricas de chamadas HTTP de saída
  • Runtime Instrumentation: métricas do runtime .NET (GC, threads, etc.)

Logging

  • Integra com Microsoft.Extensions.Logging
  • Exporta logs via OTLP junto com traces e metrics
  • Correlaciona automaticamente logs com traces (TraceId/SpanId)

Exportadores

Exportador Ativação Tipo
OTLP Otlp.Enabled = true + Otlp.Endpoint configurado Push
Console Ambiente Development + UseConsoleExporterInDevelopment + OTLP desabilitado Push

Nota: Este pacote não expõe endpoints HTTP para coleta de métricas (como /metrics do Prometheus). Usa apenas o modelo push via OTLP.

Testes Adicionados

Tooark.Tests/Observability

Novos testes unitários para o pacote Tooark.Observability:

Arquivo Descrição
Enums/EProcessorTypeTests.cs Testes para enum EProcessorType
Enums/EProtocolOtlpTests.cs Testes para enum EProtocolOtlp
Injections/TooarkDependencyInjectionTests.cs Testes para AddTooarkObservability
Injections/TooarkDependencyInjectionOpenTelemetryTests.cs Testes para AddTooarkOpenTelemetry
Injections/TooarkDependencyInjectionTracingTests.cs Testes para configuração de Tracing
Injections/TooarkDependencyInjectionMetricsTests.cs Testes para configuração de Metrics
Injections/TooarkDependencyInjectionLoggingTests.cs Testes para configuração de Logging
Options/ObservabilityOptionsTests.cs Testes para ObservabilityOptions
Options/TracingOptionsTests.cs Testes para TracingOptions
Options/MetricsOptionsTests.cs Testes para MetricsOptions
Options/LoggingOptionsTests.cs Testes para LoggingOptions
Options/OtlpOptionsTests.cs Testes para OtlpOptions
Options/OtlpBatchOptionsTests.cs Testes para OtlpBatchOptions
Options/DataSensitiveOptionsTests.cs Testes para DataSensitiveOptions

Documentação

README.md Atualizado

O arquivo README.md do pacote Tooark.Observability foi criado com documentação completa incluindo:

  • Tabela de classes e métodos disponíveis
  • Exemplos de configuração via appsettings.json (completa, mínima e serverless)
  • Exemplos de uso com Program.cs
  • Tabelas de todas as opções de configuração com tipos e valores padrão
  • Integração com coletores (OpenTelemetry Collector, Jaeger, Grafana Cloud, Azure Monitor)
  • Recomendações para ambientes serverless
  • Exemplos de traces e métricas customizadas

Uso

Instalação

dotnet add package Tooark.Observability

Configuração Básica

  1. Adicione a seção Observability no appsettings.json
  2. Chame AddTooarkOpenTelemetry() ou AddTooarkObservability() no Program.cs
  3. Configure o endpoint OTLP do seu coletor (Jaeger, OTEL Collector, Grafana, etc.)

Impacto

  • Sem breaking changes - Pacote totalmente novo
  • Compatibilidade - Compatível com .NET 8.0+
  • Modelo Push - Não expõe endpoints HTTP para scraping (Prometheus-style)

Atenção

  • Versão v2.* será mantida para correções de bugs e melhorias menores.
  • Novas funcionalidades e mudanças maiores serão lançadas na série v3.*.

Informações Adicionais

  • Tag relacionado: v2.3.0
  • Data de lançamento: 2026-01-20
Assets 2
Loading