Логування

*Дата оновлення перекладу 2024-06-08

Логування

Symfony постачається з мінімалістичним логером PSR-3: Logger. У відповідності з дванадцятифакторною методологією додатку, він відправляє повідомлення, починаючи з рівня WARNING до stderr.

Мінімальний рівень логу може бути змінений шляхом установки змінної середовища SHELL_VERBOSITY:

???????? SHELL_VERBOSITY ??????????? ?????? ????
-1 ERROR
1 NOTICE
2 INFO
3 DEBUG

Мінімальний ріаень логу, виведення за замовчуванням та формат логу також можуть бути змінені шляхом передачі відповідних аргументів конструктору Logger. Щоб зробити це, перевизначіть визначення сервісу "logger" .

Логування повідомлення

Щоб логувати повідомлення, впровадьте логер за замовчуванням у ваш контролер або сервіс:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
use Psr\Log\LoggerInterface;
// ...

public function index(LoggerInterface $logger): Response
{
    $logger->info('I just got the logger');
    $logger->error('An error occurred');

    // повідомлення логів також можуть містити заповнювачі, які є іменами змінних,
    // обгорнутими у дужки, чиї значення передаються в якості другого аргументу
    $logger->debug('User {userId} has logged in', [
        'userId' => $this->getUserId(),
    ]);

    $logger->critical('I left the oven on!', [
        // включити додаткову інформацію "context" у ваші логи
        'cause' => 'in_hurry',
    ]);

    // ...
}

Додавання заповнювачів до повідомлень логів рекомендується тому, що:

  • Легше перевіряти повідомлення логів, оскільки багато інструментів логування групують повідомлення логів, які є однаковими, за винятком деяких значень змінних всередині них;
  • Перекладати такі повідомлення логів набагато легше;
  • Це краще з точки зору безпеки, оскільки екранування може бути здійснено за допомогою реалізації у контекстно-залежний спосіб.

Сервіс logger має різні методи для різних рівнів/пріоритетів логування. Див. LoggerInterface, щоб побачити список всіх методів логеру.

Monolog

Symfony бездоганно інтегрується з Monolog, найпопулярнішою PHP-бібліотекою логування, щоб створювати та зберігати повідомлення логів у багатьох різноманітних місцях та запускати різні дії.

Наприклад, використовуючи Monolog, ви можете сконфігурувати логер так, щоб від робив різні речі, засновуючись на рівні повідомлення (наприклад, відправляти email при виникненні помилки).

Виконайте цю команду, щоб встановити логер, заснований на Monolog, перед його використанням:

1
$ composer require symfony/monolog-bundle

Наступні розділи припускають, що Monolog встановлено.

Де зберігаються логи

За замовчуванням, логи записуються у файл var/log/dev.log коли ви знаходитеся у середовищі dev.

В середовищі prod, логи записуються у потік STDERR PHP, що краще за все працює у сучасних контейнерних додатках, розгорнутих на серверах без дозволів запису на диск.

Якщо ви віддаєте перевагу зберіганню логів виробництва у файлі, встановіть path обробника(ів) ваших логів за шляхом файлу для використання (наприклад, var/log/prod.log).

Обробники: Запис логів у різних локаціях

Логер має безліч обробників і кожний може бути використаний для запису логів у різноманітних локаціях (наприклад, файлах, базі даних, Slack, і т.д.).

Tip

Ви також можете конфігурувати "канали" логування, які схожі на категорії. Кожний канал може мати своїх власних обробників, що означає, що ви можете зберігати різні повідомлення логів у різних місцях. Див. Обробники каналів.

Symfony попередньо конфігурує деякі базові обробники у файлах конфігурації за замовчуванням monolog.yaml. Подивіться на них, щоб побачити справжні приклади.

Цей приклад використвує два обробники:stream (щоб записувати в файл) та syslog, щоб записувати логи, використовуючи функцію syslog:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# config/packages/monolog.yaml
monolog:
    handlers:
        # цей ключ "file_log" може бути чим завгодно
        file_log:
            type: stream
            # логувати в var/log/(environment).log
            path: "%kernel.logs_dir%/%kernel.environment%.log"
            # логувати *всі* повідомлення (debug - найнижчий рівень)
            level: debug

        syslog_handler:
            type: syslog
            # логувати повідомлення рівню помилок та вище
            level: error

Це визначає стек обробників і кожний обробник називається у порядку, в якому він визначений.

Note

Якщо ви хочете перевизначити конфігурацію monolog через інший файл конфігурації, вам необхідно буде перевизначити весь стек handlers. Конфігурація з двох файлів не може бути об'єднана, тому що порядок важливий, а злиття не дозволяє контролювати черговість.

Обробники, які змінюють записи логів

Замість того, щоб записувати файли логів будь-де, деякі обробники використовуються, щоб фільтрувати або змінювати записи логів перед тим, як відправляти їх іншим обробникам. Один потужний вбудобавний обробник під назвою fingers_crossed використовується в середовищі prod за замовчуванням. Він зберігає всі повідомлення логів під час запиту, але передає їх другому обробнику лише, якщо одне з повідомлень досягає рівня action_level. Візьмемо цей приклад:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# config/packages/monolog.yaml
monolog:
    handlers:
        filter_for_errors:
            type: fingers_crossed
            # якщо *один* лог - помилка або вище, передати *всі* в file_log
            action_level: error
            handler: file_log

        # тепер передані *всі* логи, але лише якщо один з них помилка або вище
        file_log:
            type: stream
            path: "%kernel.logs_dir%/%kernel.environment%.log"

        # все ще передаються *всі* логи, і все ще лише якщо логи - помилка або вище
        syslog_handler:
            type: syslog
            level: error

Тепер, навіть якщо один запис логу має рівень error або вище, то всі записи логів для цього запиту зберігаються у файл за допомогою обробника file_log. Це означає, що ваш файл логів міститиме всі деталі про проблематичний запит, що значно полегшить налагодження!

Tip

Обробник, який називається "file_log", не буде додано у стек, так як він використовується у якості вкладеного обробника fingers_crossed.

Всі вбудовані обрбобники

Monolog постачається з багатьма вбудованими обробниками для відправлення логів по пошті, відправки їх в Loggly, або для сповіщення вас у Slack. Вони документуються всередині самого MonologBundle. Для повного списку, див. Конфігурація Monolog.

Як чергувати ваші файли логів

Із часом, фали логів можуть стати величезними, як під час розробки, так і у виробництві. Кращою практикою вирішення є використання інструменту на кшталт команди Linux logrotate для чергування файлів логів до того, як вони стануть надто великими.

Ще одна опція - змусити Monolog чергувати файли за вас, використовуючи обробник rotating_file. Цей обробник створює новий файл логів кожний день, а також може видаляти старі файли автоматично. Щоб використати його, просто встановіть опцію type вашого обробника як rotating_file:

1
2
3
4
5
6
7
8
9
10
# config/packages/dev/monolog.yaml
monolog:
    handlers:
        main:
            type:  rotating_file
            path:  '%kernel.logs_dir%/%kernel.environment%.log'
            level: debug
            # максимальна кількість файлів логів, що зберігаються
            # за замовчуванням дорівнює нулю, що означає нескінченну кількість
            max_files: 10

Використання логеру всередині сервісу

Якщо ваш застосунок використовує автоконфігурацію сервісу , будь-який сервіс, клас якого реалізує Psr\Log\LoggerAwareInterface, отримуватиме виклик до свого методу setLogger() з сервісами логеру за замовчуванням переданими у якості сервісу.

Якщо ви хочете використовувати власні сервіси, попередьно сокнфігурований логер, який використовує певний канал (за замовчуванням app), ви можете або автомонтувати канали monolog , або використати тег monolog.logger із властивістю channel, як пояснюється у довіднику впровадження залежностей .

Додавання додаткових даних у кожний лог (наприклад, мітки унікального запиту)

Monolog також підтримує процесори: функції, які можуть динамічно додавати додаткову інформацію до ваших записів логів.

Див. Як додавати додаткові дані у повідомлення логів через процесор, щоб дізнатися деталі.

Обробка логів у довготривалих процесах

Під час довготривалих процесів логи можуть накопичуватися у Monolog і спричиняти деякі переповнення буферу, збільшення споживання пам'яті або навіть нелогічні логи. Дані у пам'яті Monolog можна очистити за допомогою методу reset() в екземплярі Monolog\Logger. Зазвичай цей метод слід викликати між кожною роботою або завданням, над яким працює довготривалий процес.