Функция AddMessage2Log() в Bitrix: использование, параметры и примеры

Функция AddMessage2Log() предназначена для записи сообщений (логирования) в специальный журнал системы 1С-Битрикс. Она может использоваться для отладки, отслеживания ошибок и других служебных целей. В результате вызова данной функции соответствующие данные заносятся в лог-файл, который по умолчанию хранится в директории сайта (обычно это /bitrix/logs/ или /bitrix/php_interface/ в зависимости от настроек).

Основные параметры функции

AddMessage2Log(
    string $message,
    string $module = "",
    int $traceDepth = 6,
    bool $bIgnoreLogDisable = false
);

• $message — обязательный параметр. Текст сообщения, которое вы хотите зафиксировать.
• $module (опциональный) — источник или название модуля, к которому относится сообщение.
• $traceDepth (опциональный) — глубина трассировки стека вызовов (по умолчанию 6).
• $bIgnoreLogDisable (опциональный) — при true запись в лог будет произведена даже при отключённом глобальном логировании.

Где функция вызывается при ошибках

Функция AddMessage2Log() может быть вызвана напрямую в вашем коде или автоматически при возникновении ошибок в некоторых системных функциях Bitrix. Например, в обработчиках системных событий (если там предусмотрено логирование), в ядре (при работе с исключениями), а также в обработчиках ошибок почтовых событий.

Примеры использования

Пример 1. Простое логирование ошибки

<?php
$orderId = 15;
if (!$orderId) {
    AddMessage2Log("Ошибка: отсутствует ID заказа", "sale");
}
?>

В файле журнала появится запись вида:

[DD.MM.YYYY HH:MM:SS] [sale] Ошибка: отсутствует ID заказа
File: /var/www/html/bitrix/modules/...
Line: <Номер строки>

Пример 2. Логирование отладочной информации

<?php
try {
    $result = customFunction(); 
} catch (Exception $e) {
    AddMessage2Log(
        "Исключение: ".$e->getMessage(),
        "my_custom_module",
        10
    );
}
?>

В логе отразится сообщение об исключении и более детальная трассировка (до 10 уровней).

Пример 3. Игнорируем глобальное отключение логирования

<?php
AddMessage2Log(
    "Критическая ошибка: база данных недоступна!",
    "db_module",
    6,
    true
);
?>

Сообщение будет записано даже при отключённом глобальном логировании.

Результат работы

После выполнения AddMessage2Log() вы увидите новую запись в одном из лог-файлов Bitrix. Запись содержит дату, время, текст сообщения, модуль (если был указан), путь к файлу, номер строки и, при необходимости, стек вызовов. Такое логирование позволяет оперативно анализировать и устранять проблемы на сайте.