👁 Image
Eaf.OpenTelemetry 9.1.0

Eaf.OpenTelemetry

Descrição Técnica

O Eaf.OpenTelemetry é um módulo de observabilidade do Enterprise Application Foundation (EAF). Este módulo fornece implementação completa de OpenTelemetry para telemetria distribuída, tracing e métricas, permitindo monitoramento profundo de aplicações .NET com suporte a múltiplos exporters.

Este módulo segue os padrões do OpenTelemetry e se integra perfeitamente com ASP.NET Core, Entity Framework Core, Hangfire e HTTP requests.

Relação com o EAF e ASP.NET Boilerplate

Integração com ABP

• Abp: Framework base para injeção de dependência e configuração
• Abp.AspNetCore: Integração com ASP.NET Core

Dependências Externas

• OpenTelemetry: SDK principal do OpenTelemetry
• OpenTelemetry.Api: API principal do OpenTelemetry
• OpenTelemetry.Extensions.Hosting: Integração com ASP.NET Core Hosting
• OpenTelemetry.Instrumentation.AspNetCore: Instrumentação para ASP.NET Core
• OpenTelemetry.Instrumentation.EntityFrameworkCore: Instrumentação para Entity Framework Core
• OpenTelemetry.Instrumentation.Http: Instrumentação para HTTP
• OpenTelemetry.Instrumentation.Runtime: Instrumentação para .NET Runtime
• OpenTelemetry.Instrumentation.Hangfire: Instrumentação para Hangfire
• OpenTelemetry.Exporter.Prometheus.AspNetCore: Exporter para Prometheus
• OpenTelemetry.Exporter.OpenTelemetryProtocol: Exporter para OTLP
• OpenTelemetry.Exporter.Console: Exporter para Console

Principais Componentes

Instrumentação

• ASP.NET Core: Tracing de requests HTTP
• Entity Framework Core: Tracing de queries de banco de dados
• HTTP Client: Tracing de requisições HTTP externas
• Hangfire: Tracing de jobs em background
• Runtime: Métricas do .NET Runtime

Exporters

• OTLP: Exportação para backends compatíveis com OTLP (Jaeger, Zipkin, etc.)
• Prometheus: Exportação de métricas para Prometheus
• Console: Exportação para console (debugging)

Guia de Instalação

Pré-requisitos

• .NET 10.0 SDK ou superior
• ASP.NET Boilerplate 10.4.0

Instalação via NuGet

dotnet add package Eaf.OpenTelemetry --version 10.4.0

Instalação via Referência de Projeto

Adicione a referência ao seu arquivo .csproj:

<ProjectReference Include="..\Eaf.OpenTelemetry\Eaf.OpenTelemetry.csproj" />

Exemplo Básico de Uso

1. Registrando o Módulo

No Program.cs ou Startup.cs:

public class Startup
{
 public void ConfigureServices(IServiceCollection services)
 {
 services.AddEafOpenTelemetry(options =>
 {
 options.ServiceName = "MyApplication";
 options.ServiceVersion = "1.0.0";
 });
 }

 public void Configure(IApplicationBuilder app)
 {
 app.UseEafOpenTelemetry();
 }
}

2. Configurando Exporter OTLP

No appsettings.json:

{
 "OpenTelemetry": {
 "Exporter": "Otlp",
 "Otlp": {
 "Endpoint": "http://localhost:4317",
 "Headers": {
 "X-My-Header": "value"
 }
 }
 }
}

3. Configurando Exporter Prometheus

No appsettings.json:

{
 "OpenTelemetry": {
 "Exporter": "Prometheus",
 "Prometheus": {
 "Path": "/metrics",
 "ScrapeEndpoint": "/metrics"
 }
 }
}

4. Configurando Instrumentação

services.AddEafOpenTelemetry(options =>
{
 options.ServiceName = "MyApplication";
 options.ServiceVersion = "1.0.0";
 
 // Habilita instrumentação ASP.NET Core
 options.AddAspNetCoreInstrumentation();
 
 // Habilita instrumentação Entity Framework Core
 options.AddEntityFrameworkCoreInstrumentation();
 
 // Habilita instrumentação HTTP
 options.AddHttpClientInstrumentation();
 
 // Habilita instrumentação Hangfire
 options.AddHangfireInstrumentation();
 
 // Habilita métricas do runtime
 options.AddRuntimeInstrumentation();
 
 // Configura exporter
 options.AddOtlpExporter();
});

5. Usando Tracing Manual

public class MyService
{
 private readonly ActivitySource _activitySource;

 public MyService()
 {
 _activitySource = new ActivitySource("MyService");
 }

 public async Task DoWorkAsync()
 {
 using var activity = _activitySource.StartActivity("DoWork");
 activity?.SetTag("operation", "important");
 
 // Seu código aqui
 await Task.Delay(100);
 }
}

6. Adicionando Métricas Customizadas

public class MyService
{
 private readonly Counter<long> _requestCounter;

 public MyService(IMeterFactory meterFactory)
 {
 var meter = meterFactory.Create("MyService");
 _requestCounter = meter.CreateCounter<long>("requests", "requests");
 }

 public void ProcessRequest()
 {
 _requestCounter.Add(1, new("operation", "process"));
 }
}

Estrutura do Módulo

Eaf.OpenTelemetry/
├── AspNetCore/ # Instrumentação ASP.NET Core
├── OTEL_DIAGNOSTICS.json # Configurações de diagnóstico
└── Properties/ # Propriedades do assembly

Configurações Opcionais

Sampling

services.AddEafOpenTelemetry(options =>
{
 options.SetSampler(new ParentBasedSampler(new TraceIdRatioBasedSampler(0.1)));
});

Resource Attributes

services.AddEafOpenTelemetry(options =>
{
 options.SetResourceBuilder(ResourceBuilder
 .CreateDefault()
 .AddService("MyService", "1.0.0")
 .AddAttributes(new Dictionary<string, object>
 {
 ["deployment.environment"] = "production",
 ["host.name"] = Environment.MachineName
 }));
});

Batch Export

services.AddEafOpenTelemetry(options =>
{
 options.AddOtlpExporter(opt =>
 {
 opt.BatchExportProcessorOptions = new BatchExportProcessorOptions<Activity>
 {
 MaxQueueSize = 2048,
 ScheduledDelayMilliseconds = 5000,
 ExporterTimeoutMilliseconds = 30000,
 MaxExportBatchSize = 512
 };
 });
});

Testes

Os testes para este módulo estão localizados em:

test/Eaf.OpenTelemetry.Tests/

Para executar os testes:

dotnet test test/Eaf.OpenTelemetry.Tests/Eaf.OpenTelemetry.Tests.csproj

Licença

Este projeto faz parte do Enterprise Application Foundation (EAF) e está licenciado sob os mesmos termos do projeto principal.

Suporte

Para issues e perguntas, consulte o repositório principal do EAF: https://github.com/afonsoft/EAF