Pr.BuildingBlocks.Cms.Logging 2.0.0

Pr.BuildingBlocks.Cms.Logging

Współdzielona konfiguracja obserwowalności dla mikroserwisów CMS: Sentry + structured console logging, z bezpiecznymi domyślnymi wartościami nadpisywalnymi przez appsettings.json lub kod.

Co dostarcza

• Sentry (Sentry.AspNetCore) — aktywowane wyłącznie gdy ustawiony jest DSN.
  • Środowisko wyprowadzane z ASPNETCORE_ENVIRONMENT (poprawne tagowanie per klaster).
  • Filtr odrzucający spodziewane wyjątki biznesowe (BaseException i pochodne: typy z Pr.BuildingBlocks.Cms.Core, np. NotFoundException, oraz klasy serwisów dziedziczące po nich, np. CategoryNotFoundException w pr.categories.cms), żeby nie zalewały Sentry błędami 4xx — domyślnie włączony. Działa po typie wyjątku, więc obejmuje każdy log z takim wyjątkiem: z middleware HTTP, z Wolverine („Invocation of … failed!”) i z kodu serwisu. Wyłączasz go flagą FilterBusinessExceptions = false.
  • Bezpieczne domyślne: SendDefaultPii=false, MaxRequestBodySize=None, TracesSampleRate=0.05, MinimumEventLevel=Warning.
  • Opcjonalny profiling (Sentry.Profiling) sterowany flagą EnableProfiling (+ ProfilesSampleRate > 0).
• Structured console logging — JSON na produkcji (parsowalne w log aggregation), czytelny simple w Development, ze scope'ami i znacznikiem UTC. Ustawiane jako nadpisywalny default; wyłączane flagą EnableStructuredConsoleLogging.
• Domyślny poziom logowania — Logging:LogLevel:Default = Warning dla całej aplikacji: wycisza wszystkie logi Information (framework, EF Core SQL, messaging Wolverine, kod aplikacji); zostają Warning+. Nadpisywalny default; wyłączany flagą EnableDefaultLogLevels.

Użycie

using Pr.BuildingBlocks.Cms.Logging;

var builder = WebApplication.CreateBuilder(args);

// Domyślna konfiguracja; DSN brany z Sentry:Dsn / Sentry__Dsn.
builder.AddObservability();

var app = builder.Build();

// Middleware tracingu Sentry (no-op gdy Sentry nieaktywne).
app.UseObservability();

Nadpisywanie domyślnych

Precedencja ustawień LoggingOptions (od najniższej): domyślne z kodu → sekcja Sentry w appsettings.json → callback.

Domyślne Logging:* (formatter konsoli, poziom Warning) działają inaczej — wstrzykiwane są jako źródło konfiguracji o najniższym priorytecie, więc dowolna sekcja Logging:* serwisu je nadpisuje. Callback ich nie dotyczy: steruje wyłącznie flagami, które decydują czy default w ogóle zostanie ustawiony.

1. Przez appsettings.json:

{
  "Sentry": {
    "Dsn": "https://...@sentry.io/...",
    "TracesSampleRate": 0.2
  },
  "Logging": {
    "Console": { "FormatterName": "simple" },
    "LogLevel": {
      "Default": "Warning",
      "Pr.Cms.MojSerwis": "Information"
    }
  }
}

Uwaga: wszystkie property LoggingOptions bindują się z sekcji Sentry — również te niezwiązane z Sentry. Wyłączenie domyślnego poziomu logowania przez konfigurację to "Sentry": { "EnableDefaultLogLevels": false }, analogicznie EnableStructuredConsoleLogging.

W prod DSN zwykle podajesz przez Sentry__Dsn.

Gdy serwis świadomie chce widzieć wyjątki biznesowe w Sentry (np. na czas diagnozy), ustawia "Sentry": { "FilterBusinessExceptions": false } albo zmienną Sentry__FilterBusinessExceptions=false. Wyjątki, które nie dziedziczą po BaseException (np. własne *NotFoundException : ApplicationException), filtr przepuszcza — żeby zniknęły z Sentry, muszą dziedziczyć po BaseException albo jego pochodnej.

Zmiana zachowania w wersji 2.0.0

Do wersji 1.2.0 filtr wyjątków biznesowych był domyślnie wyłączony i każdy wyjątek 4xx trafiał do Sentry jako błąd. Od tej wersji jest domyślnie włączony. Serwis, który polegał na starym zachowaniu, ustawia FilterBusinessExceptions = false. Serwis, który miał już FilterBusinessExceptions = true, może tę linię usunąć.

2. Przez kod (najwyższy priorytet):

builder.AddObservability(options =>
{
    options.TracesSampleRate = 0.2;
    options.EnableProfiling = true;
    options.ProfilesSampleRate = 0.1;
});

Walidacja (TracesSampleRate/ProfilesSampleRate w [0,1], MaxBreadcrumbs >= 0, profiling wymaga dodatniego sample rate) rzuca ArgumentException z jasnym komunikatem na etapie rejestracji.

API

// Konfiguracja (Program.cs, przed Build()).
public static WebApplicationBuilder AddObservability(
    this WebApplicationBuilder builder,
    Action<LoggingOptions>? configure = null);

// Pipeline (po Build()).
public static WebApplication UseObservability(this WebApplication app);

Pełna lista ustawień (nazwy property = klucze sekcji Sentry): zob. LoggingOptions.

Zależności

• Sentry.AspNetCore, Sentry.Profiling
• Pr.BuildingBlocks.Cms.Core (kontrakt BaseException)
• Microsoft.AspNetCore.App (shared framework)