AT.BackEnd.Observability 1.0.0

AT.BackEnd.Observability

Paquete NuGet interno y transversal que centraliza logging estructurado, tracing, métricas y health checks para los bounded contexts de AF.BackEnd (AF.BackEnd.Api, AF.BackEnd.Auth.Api, AF.BackEnd.Notifications.Api) detrás de una única superficie de API: AddAtObservability / UseAtObservability.

El core no depende de ningún writer de logging concreto (Serilog, log4net, NLog). Solo usa Microsoft.Extensions.Logging.Abstractions y el stack OpenTelemetry.*. Un adaptador concreto (p. ej. Serilog) vive en un paquete separado (AT.BackEnd.Observability.Serilog), no en este.

Instalación

dotnet add package AT.BackEnd.Observability

Configuración (appsettings.json)

{
  "Observability": {
    "ServiceName": "AF.BackEnd.Api",
    "ServiceVersion": "1.0.0",
    "OtlpEndpoint": "http://localhost:4317"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

Observability:ServiceName es obligatorio — cada bounded context configura el suyo. Ese mismo nombre se usa como ActivitySource/meter canónico (ver más abajo), así que debe ser consistente en todo el servicio.

Uso en Program.cs

using AT.BackEnd.Observability.DI;
using AT.BackEnd.Observability.HealthChecks;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAtObservability(builder.Configuration);

builder.Services.AddAtHealthChecks()
    .AddCheck<DatabaseHealthCheck>("database", tags: [HealthCheckConventions.ReadyTag]);

var app = builder.Build();

app.UseAtObservability();
app.MapAtHealthChecks();

app.Run();

Esto expone:

• /health/live — sin dependencias, siempre responde si el proceso está vivo.
• /health/ready — ejecuta únicamente los checks tageados con HealthCheckConventions.ReadyTag.
• Un header/log correlacionado por request vía X-Correlation-Id (CorrelationIdMiddleware), accesible en cualquier punto del código — incluso fuera de un request HTTP — vía ICorrelationIdAccessor.
• Traces y métricas exportados por OTLP hacia el endpoint configurado, con la instrumentación automática de ASP.NET Core, HttpClient y SqlClient ya habilitada.

Instrumentación manual (traces y métricas propias)

Para que las actividades/métricas que el bounded context cree manualmente no se descarten silenciosamente, deben usar el mismo nombre que Observability:ServiceName — así quedan automáticamente enlazadas por AddAtObservability:

using AT.BackEnd.Observability.Tracing;
using AT.BackEnd.Observability.Metrics;

public sealed class OrderService(IMeterFactory meterFactory)
{
    private static readonly ActivitySource Source = ActivitySources.GetOrCreate("AF.BackEnd.Api");
    private readonly Meter _meter = meterFactory.Create(MeterNames.For("AF.BackEnd.Api"));

    public void CreateOrder(int orderId)
    {
        using var activity = Source.StartActivity("CreateOrder");
        activity?.SetTag("order.id", orderId);
        // ...
    }
}

Correlación fuera de HTTP

ICorrelationIdAccessor está basado en AsyncLocal, no en HttpContext.Items — funciona también en consumers de mensajería (p. ej. AF.BackEnd.Notifications) que no tienen un request HTTP activo.

🎓 Créditos

Nombre del Paquete: AT.BackEnd.Observability Versión: 1.0.0

Autor

• Nombre: Dayser José Granados Pineda
• Correo Electrónico: djpgranados@gmail.com | daysergranados@hotmail.com

Licencia

Este paquete está bajo la licencia MIT License

Copyright (c) 2025 Dayser José Granados Pineda

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE..

Contacto

Si tienes comentarios, problemas o solicitudes, ¡no dudes en ponerte en contacto conmigo!