Scanner.Observability

Общие observability-хелперы для HTTP-сервисов bscanner.

Что входит в пакет

• middleware и helpers для correlation id
• request logging baseline с подавлением шумных путей
• обёртки для HTTP metrics через prometheus-net.AspNetCore
• helper для доменной метрики scan_item_result_total
• helper для логирования результатов сканирования

Базовое подключение в ASP.NET Core

using Scanner.Observability;

var app = builder.Build();

app.UseCorrelationId();
app.UseScannerRequestLogging();
app.UseAuthentication();
app.UseAuthorization();
app.UseScannerHttpMetrics();

app.MapHealthChecks("/health");
app.MapScannerMetrics();
app.MapReverseProxy();

Настройка correlation id

По умолчанию пакет:

• использует заголовок x-correlation-id
• переиспользует входной correlation id, если он пришёл в запросе
• генерирует новый id, если входного значения нет
• синхронизирует HttpContext.TraceIdentifier
• добавляет correlation id в response header

При необходимости поведение можно переопределить:

app.UseCorrelationId(options =>
{
    options.HeaderName = "x-request-id";
    options.UseIncomingHeader = true;
    options.IncludeInResponseHeader = true;
    options.SetTraceIdentifier = true;
});

Настройка request logging

По умолчанию request logging:

• пишет completion log и для успешных, и для ошибочных запросов
• подавляет шум от /health и /metrics
• сохраняет correlation_id в structured log fields

Если нужно не скрывать технические пути, а логировать их на пониженном уровне:

using Microsoft.Extensions.Logging;

app.UseScannerRequestLogging(options =>
{
    options.NoisePathLogLevel = LogLevel.Debug;
});

Metrics endpoint

Для HTTP metrics пакет даёт две обёртки:

• app.UseScannerHttpMetrics();
• app.MapScannerMetrics();

По умолчанию metrics endpoint публикуется на /metrics. Путь можно переопределить:

app.MapScannerMetrics(options =>
{
    options.EndpointPath = "/internal/metrics";
});

Documented Verification Harness

Минимальный verification harness для сервиса, который использует пакет:

1. Поднять сервис с UseCorrelationId(), UseScannerRequestLogging(), UseScannerHttpMetrics() и MapScannerMetrics().
2. Проверить, что GET /health отвечает как и до подключения пакета.
3. Проверить, что GET /metrics отвечает успешно и не ломает обычный pipeline приложения.
4. Выполнить обычный HTTP-запрос без входного correlation id.
5. Убедиться, что в логах появился completion log с correlation_id.
6. Убедиться, что шум от /health и /metrics либо подавлен, либо понижен до ожидаемого уровня.