Логирование агентов Битрикс: BX_AGENTS_LOG_FUNCTION

Задача

Агенты выполняются в фоновых запросах и через административную панель. Когда задача тормозит или падает неочевидно, нужен лёгкий журнал времени между вызовами без переопределения ядра.

После объявления константы до подключения модуля agent (чаще всего в dbconn.php или общем bootstrap-файле) ядро передаёт в колбэк четыре параметра: массив агента, метку операции (start / finish), необязательный результат и флаг возврата после записи строки.

Пример логирования в файл

define('BX_AGENTS_LOG_FUNCTION', 'logAgentExecution');

function logAgentExecution($agent, $operation, $result = false, $return = false)
{
    clearstatcache();

    $handle = fopen($_SERVER['DOCUMENT_ROOT'] . '/agents_debug.log', 'ab');
    if (!$handle) {
        return $return;
    }

    static $timers = [];
    $moment = date('Y-m-d H:i:s');

    if ($operation === 'start') {
        $timers[$agent['ID']] = microtime(true);
        fwrite(
            $handle,
            sprintf(
                "%s AGENT #%s START %s [%s], interval=%s\n",
                $moment,
                $agent['ID'],
                $agent['NAME'],
                $agent['MODULE_ID'],
                $agent['AGENT_INTERVAL']
            )
        );
    } elseif ($operation === 'finish') {
        $elapsed = isset($timers[$agent['ID']])
            ? microtime(true) - $timers[$agent['ID']]
            : 0.0;
        fwrite(
            $handle,
            sprintf(
                "%s AGENT #%s FINISH %s сек %s [%s], interval=%s\n",
                $moment,
                $agent['ID'],
                number_format($elapsed, 4, '.', ' '),
                $agent['NAME'],
                $agent['MODULE_ID'],
                $agent['AGENT_INTERVAL']
            )
        );
        unset($timers[$agent['ID']]);
    }

    fclose($handle);
}

На что обратить внимание

• Файл лога нужно исключить из публичного доступа через веб или вынести за пределы DOCUMENT_ROOT.
• Высокая частота агентов быстро распухнет журнал — ротируйте или временно включайте лог только на диагностируемых средах.
• Функцию определяйте до выполнения кода модулей, иначе ранний агент может стартовать до объявления обработчика.