Функция PHP syslog(): всё, что нужно знать

Функция syslog() отправляет сообщение системному логгеру — той же системе журналирования, которую используют операционная система и другие службы (назначение: /var/log/syslog или /var/log/messages на большинстве Linux-систем, Console / unified log на macOS и Event Log на Windows). В отличие от записи в файл с помощью error_log() или file_put_contents(), функция syslog() передаёт ваше сообщение демону, который может маршрутизировать, фильтровать, ротировать и пересылать его. На этой странице рассматриваются синтаксис, константы приоритета и средства журналирования, полный рабочий пример и типичные подводные камни.

Синтаксис

syslog(int $priority, string $message): bool

Функция принимает два параметра и возвращает true в случае успеха или false в случае ошибки:

• $priority — уровень серьёзности сообщения, выраженный в виде одной из констант LOG_*, перечисленных ниже.
• $message — текст для записи в журнал. Двухсимвольная последовательность %m заменяется строкой сообщения об ошибке текущего значения errno (последней системной ошибки), что иногда полезно, однако буквальные знаки процента следует экранировать как %%.

Уровни приоритета

Приоритет сообщает логгеру о серьёзности сообщения. От наиболее к наименее срочному:

Собственная конфигурация логгера определяет, какие приоритеты в итоге будут записаны, поэтому строка LOG_DEBUG может быть отброшена, а строка LOG_ERR — сохранена. Ваш код вызывает syslog() одинаково в обоих случаях.

Полный пример

Вызов openlog() не является строго обязательным — syslog() работает и без него, — однако предварительное открытие соединения позволяет задать идентифицирующий префикс и средство журналирования, что упрощает поиск и маршрутизацию сообщений.

<?php

// Open a connection: tag every line with "myapp", include the PID,
// and also echo to stderr. LOG_USER is the generic application facility.
openlog("myapp", LOG_PID | LOG_PERROR, LOG_USER);

syslog(LOG_INFO,    "User #42 logged in");
syslog(LOG_WARNING, "Disk usage above 80%%");   // %% = a literal percent sign
syslog(LOG_ERR,     "Payment gateway timed out");

closelog();

Итоговая строка в системном журнале выглядит примерно так:

Jun 21 14:03:11 host myapp[3187]: Payment gateway timed out

Функция openlog() принимает три аргумента: идентификатор, добавляемый к каждому сообщению в начало; битовую маску параметров (LOG_PID добавляет идентификатор процесса, LOG_PERROR дополнительно выводит в stderr, LOG_CONS переключается на консоль, если логгер недоступен); и средство журналирования (facility), которое категоризирует источник. Распространённые средства журналирования: LOG_USER (по умолчанию для обычных приложений), LOG_LOCAL0–LOG_LOCAL7 (зарезервированы для пользовательской маршрутизации), LOG_DAEMON и LOG_MAIL. Функция closelog() закрывает соединение — необязательно, но рекомендуется.

Когда следует использовать?

• Долго работающие службы и CLI-воркеры, в которых нет браузера для отображения ошибок и нужно, чтобы журналы попадали в то же место, что и остальные системные журналы.
• Централизованное журналирование — демон syslog может пересылать сообщения на удалённый коллектор (rsyslog, journald, стек ELK/Graylog), что обеспечивает агрегацию бесплатно.
• Маршрутизация по уровню серьёзности — выберите средство/приоритет и позвольте демону решать, что хранить, по чему оповещать и что отбрасывать.

Для обычного журналирования ошибок конкретного приложения, которое просто записывает в файл, как правило, проще использовать error_log(). Обращайтесь к syslog(), когда хотите, чтобы сообщение попало в системный конвейер журналирования на уровне ОС.

Типичные подводные камни

• Экранируйте буквальные знаки процента. Функция syslog() интерпретирует %m; неэкранированный % в сообщении может приводить к неожиданному выводу. Пишите %% для буквального знака процента.
• Сообщения могут быть отброшены без уведомления. Если конфигурация логгера фильтрует ваш приоритет/средство, ничего не появится — это вопрос конфигурации, а не ошибка PHP. Проверьте /etc/rsyslog.conf или journalctl, если строка пропала.
• Это не то же самое, что настройка error_log в PHP. Установка error_log = syslog в php.ini направляет внутренние ошибки PHP в syslog; вызов syslog() вручную записывает ваши собственные сообщения и не зависит от этой настройки.
• Одна строка на вызов. Передавайте одну строку; демон сам добавит временну́ю метку, имя хоста и тег. Не включайте \n в сообщение.

Связанные функции

• openlog() — открыть соединение и задать идентификатор и средство журналирования.
• closelog() — закрыть соединение syslog.
• error_log() — отправить сообщение в файл, по электронной почте или в настроенный журнал.

Заключение

syslog() — это точка входа PHP в системный конвейер журналирования операционной системы. Выбирайте значимый приоритет, при необходимости открывайте соединение с помощью openlog() для добавления идентификатора и средства журналирования, экранируйте буквальные знаки процента и помните, что именно демон, а не PHP, решает, что в итоге будет сохранено. Для простого журналирования в файл предпочитайте error_log(); для журналов уровня ОС с возможностью маршрутизации и централизации syslog() — правильный инструмент.

Практика