adheart/logging

adheart/logging

Уніфіковане логування для PHP-проєктів на базі Monolog + Symfony Bundle:

• єдиний JSON-формат логів (SchemaFormatterV1);
• процесори для нормалізації повідомлень і trace-контексту;
• інтеграція з OpenTelemetry trace context;
• інвентаризація використання логерів через logging:scan.

Що ви отримуєте після інтеграції

• Автоматичне застосування форматера до Monolog handlers (setFormatter там, де підтримується).
• Автоматичне підключення вибраних процесорів до всіх Monolog loggers.
• Однакова структура подій у всіх сервісах (поля timestamp, level, message, context, service, trace, version).
• Опціонально: enrichment trace-контекстом з OpenTelemetry і заголовка cf-ray.

Сумісність

• PHP: ^8.2
• Monolog: ^2.3 || ^3.0
• Symfony components:
  • symfony/http-kernel: ^5.4 || ^6.4 || ^7.0
  • symfony/config: ^5.4 || ^6.4 || ^7.0

Додатково для logging:scan:

• symfony/console
• symfony/dependency-injection
• nikic/php-parser

Встановлення

composer require adheart/logging

Якщо це не Symfony Runtime з Flex, переконайтесь, що бандл зареєстрований вручну в config/bundles.php:

<?php

return [
    // ...
    Adheart\Logging\LoggingBundle::class => ['all' => true],
];

Швидкий старт (Symfony)

Створіть config/packages/logging.yaml:

logging:
  processors:
    - message_normalizer
  integrations:
    - otel_trace
  formatter:
    schema_version: '1.0.0'
    service_name: 'billing-api'
    service_version: '%env(string:RELEASE_ID)%'

Після цього:

• на всі monolog.logger* буде додано процесори;
• на всі monolog.handler* буде встановлено SchemaFormatterV1;
• логи підуть у стандартизованому JSON.

Базова перевірка після інтеграції

• Очистіть/прогрійте контейнер:

php bin/console cache:clear

• Згенеруйте тестовий лог із будь-якого місця в застосунку:

$logger->info('User logged in', ['user' => ['id' => '123']]);

• Перевірте raw-рядок у stdout/file-handler: має бути валідний JSON з полями service і version.

Вбудовані alias-и

Processors

• message_normalizer → Adheart\Logging\Core\Processors\MessageNormalizerProcessor
• trace → Adheart\Logging\Core\Processors\TraceContextProcessor

Trace providers

• otel → Adheart\Logging\Integration\OpenTelemetry\Trace\OpenTelemetryTraceContextProvider
• cf_ray → Adheart\Logging\Integration\OpenTelemetry\Trace\CfRayTraceContextProvider

Integrations

• otel_trace:
  • processors: trace
  • trace_providers: otel, cf_ray

Кастомізація через alias-и

Можна підключати свої сервіси без форку пакета:

logging:
  processors:
    - custom_processor
  integrations:
    - custom_trace
  aliases:
    processors:
      custom_processor: '@app.logging.processor.custom'
    trace_providers:
      app_provider: '@app.trace.provider'
    integrations:
      custom_trace:
        processors: ['trace']
        trace_providers: ['app_provider']

Команда інвентаризації логів

Якщо встановлені dev-залежності для сканера, доступна команда:

php bin/console logging:scan --summary

Приклади:

php bin/console logging:scan --format=json --summary
php bin/console logging:scan --logger-name=app --severity-min=error
php bin/console logging:scan --path-prefix=src/Billing --exclude-path-prefix=src/Billing/Legacy
php bin/console logging:scan --list-loggers

Детальна документація

• Покрокова інтеграція (детально)
• Production checklist
• Конфіг Symfony bundle
• Референс схеми логів v1