Отладка Битрикс D7. Дебаг. Bitrix\Main\Diag

 

Пространство имён: Bitrix\Main\Diag

\ В ядре D7 реализован комплекс инструментов для диагностики кода, обеспечивающий детальный анализ выполнения скриптов, мониторинг SQL-запросов и профилирование производительности.

---

1. Инспекция переменных

Метод Debug::dump()

Назначение: Заменяет стандартный var_dump() с расширенными возможностями форматирования.

\ Сигнатура:

Bitrix\Main\Diag\Debug::dump(mixed $var, ?string $name = null, bool $return = false): ?string  

Параметры:

• $var: Произвольная переменная или массив;
• $name: Метка для идентификации в выводе (опционально);
• $return: Если true, возвращает строку вместо прямого вывода.

Пример:

$data = ['user_id' => 1024, 'roles' => ['admin', 'editor']];  
Debug::dump($data, 'UserData');  

Вывод:

UserData:
array(2) {
  ["user_id"] => int(1024)
  ["roles"] => array(2) {
    [0] => string(5) "admin"
    [1] => string(6) "editor"
  }
}

---

2. Логирование данных

Методы dumpToFile() и writeToFile()

Назначение: Запись отладочной информации в файлы журнала.

Метод	Форматирование	Рекомендуемое использование
dumpToFile()	Аналог var_export()	Детальный дамп структур данных
writeToFile()	Аналог print_r()	Читабельное логирование значений

Сигнатура:

Debug::dumpToFile(mixed $var, ?string $name = null, string $file = 'test.log'): void  
Debug::writeToFile(mixed $var, ?string $name = null, string $file = 'test.log'): void  

Пример:

$metrics = ['memory_peak' => memory_get_peak_usage(), 'exec_time' => microtime(true)];  
Debug::writeToFile($metrics, 'Performance', '/logs/system_metrics.log');  

Содержимое файла:

Performance:
Array
(
    [memory_peak] => 2097152
    [exec_time] => 1620223810.1234
)

---

3. Профилирование производительности

Методы замера времени выполнения:

Debug::startTimeLabel(string $label);  // Старт замера  
Debug::endTimeLabel(string $label);    // Фиксация результата  
$metrics = Debug::getTimeLabels();     // Получение всех метрик  

Особенности:

• Поддерживает вложенные и множественные вызовы с одинаковым $label;
• Автоматически агрегирует общее время для повторяющихся меток;

• Возвращает данные в формате:

  [
  'SomeLabel' => [
    'start' => float(1620223810.1234), // Unix-время с микросекундами  
    'time'  => float(0.0025)           // Суммарное время в секундах  
  ]
  ]

Дополнительные утилиты:

$microtime = Helper::getCurrentMicrotime(); // Текущее время с микросекундами  
$stack = Helper::getBackTrace(5, DEBUG_BACKTRACE_IGNORE_ARGS); // Стек вызовов  

---

4. Мониторинг SQL-запросов

Механизм: Использование встроенного SQL-трекера для анализа запросов к БД.

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

$connection = \Bitrix\Main\Application::getConnection();  
$tracker = $connection->startTracker(true); // true = сброс предыдущих данных  

// Выполняем ORM-запросы  
$items = \Bitrix\Iblock\ElementTable::getList([...]);  

$connection->stopTracker();  

// Анализ результатов  
foreach ($tracker->getQueries() as $query) {  
    Debug::dumpToFile([  
        'sql'   => $query->getSql(),  
        'time'  => $query->getTime(),  
        'trace' => $query->getTrace()  
    ], 'SQL Debug');  
}  

Возвращаемые данные (SqlTrackerQuery):

• getSql(): Текст SQL-запроса;
• getTime(): Время выполнения (сек);
• getTrace(): Стек вызовов.

Важно:

• Трекер работает только с запросами через D7 ORM;
• Запросы через устаревшее API (например, CIBlockElement) не отслеживаются.

---

5. Расширенные сниппеты для отладки

Анализ строковых данных:

$problemString = "Special Char"; // С неразрывным пробелом (0xA0)  

Debug::dump([  
    'raw'          => $problemString,  
    'length'       => strlen($problemString),  
    'hex_codes'    => bin2hex($problemString),  
    'trimmed'      => trim($problemString),  
    'normalized'   => str_replace("\u{00A0}", ' ', $problemString)  
], 'String Analysis');  

Вывод:

String Analysis:
array(5) {
  ["raw"] => string(12) "Special Char"
  ["length"] => int(12)
  ["hex_codes"] => string(24) "5370656369616c c2a043686172"
  ["trimmed"] => string(12) "Special Char"
  ["normalized"] => string(11) "Special Char"
}

---

Рекомендации по использованию

1. Для продакшн-среды активируйте отладку только при наличии ошибок;
2. Используйте dumpToFile() вместо прямого вывода для скрытия служебной информации;
3. При анализе производительности учитывайте накладные расходы трекера SQL;
4. Для комплексного мониторинга интегрируйте с внешними инструментами (XHProf, New Relic).