Редактирование: логи-обзор

Путь: 10_Логи_и_диагностика/логи-обзор.md

Содержимое (Markdown)

# Логи и диагностика — обзор

## Что такое лог и зачем он нужен

**Лог** — текстовый журнал событий системы. Нужен, чтобы:
- восстановить хронологию действий;
- понять, что отправляла система (запрос) и что вернул сервер (ответ);
- быстро найти причину ошибки;
- собрать данные для разработчиков (`X-Request-Id`, тело запроса/ответа).

## Расположение логов

Все серверные логи находятся в папке `app_logs` на сервере.

| Лог-файл | Назначение |
|---|---|
| `loyalty_api_e.log` | Ошибки запросов нового плагина |
| `loyalty_api_rr.log` | Запросы по заказам |
| `bonuses_update_ajax` | Лог по начислению бонусов |
| `guest_loader_e.log` | Ошибки загрузчика гостей |
| `loyaltydata_api_e` | Ошибки передачи данных через API лояльности |
| `loyaltydata_api_rr` | Технические запросы по лояльности (загрузка номенклатуры) |
| `iiko_data_api` | Запросы от iiko для старой версии плагина |
| `Loyalty_api` | Запросы от R-Keeper |
| `iikodeposiapi_fields` | Запросы из виджета сертификатов |
| `iikodepositapi_errors` | Ошибки запросов по виджету сертификатов |
| `iikodeposiapi_req` | Заполняется во время ошибок создания |

## Структура запроса и ответа в логе

Логи нового плагина содержат блоки запроса и ответа с разделителями:

```
Запрос:
[ВРЕМЯ] INFO - ==> POST REQUEST FROM SOURCE: [Метод] TO URL: https://...
[ВРЕМЯ] INFO - === BODY ===
{JSON-тело запроса}
[ВРЕМЯ] INFO - === END OF BODY ===
[ВРЕМЯ] INFO - === X-Request-Id: ===

Ответ:
[ВРЕМЯ] INFO - <== RESPONSE FROM SOURCE: [Метод]: STATUS CODE OK REASON: OK
[ВРЕМЯ] INFO - === JSON RESPONSE === {JSON-тело ответа}
[ВРЕМЯ] INFO - === ENDOF RESPONSE ====
```

**Ключевые поля:**
- `BODY` — какие данные отправлены;
- `status`, `code`, `message` — есть ли явная ошибка;
- исключения `ERROR` после ответа (`NullReferenceException`, `ArgumentOutOfRangeException`) — плагин не смог обработать ответ.

### Пример записи серверного лога (loyalty_api)

В серверном логе вызов и его результат связаны общим `hash`:

```
2026-06-05T00:05:15+03:00: GetGuest: hash = 827d0122..., params = {"card_number":"18531","phone":null}
2026-06-05T00:05:15+03:00: GetGuest: hash = 827d0122..., params = {"id":51551023,"phone":"+79776172199","cards":["18531"],"total_balance":0}
2026-06-05T00:06:01+03:00: MakePreTransaction: hash = 356d05fc..., transactions result = {"transaction_id":3022442}
```

> В реальных логах присутствуют `token`, телефоны и email гостей — это рабочие персональные данные клиентов, обращаться с ними по правилам обработки ПДн.

## HTTP-коды и JSON-статусы

| Код | Значение |
|---|---|
| `200 OK` | Принят (но внутри JSON может быть `status: error`) |
| `4xx` | Проблема клиента / некорректный запрос |
| `5xx` | Проблема сервера |
| `{"status":"error","code":520}` | Неизвестная внутренняя ошибка сервера |

## Практические шаги работы с логами

1. Не читать файл целиком — использовать поиск и фильтры.
2. Искать явные ошибки по ключевым словам: `"status":"error"`, номер карты, телефон.
3. Смотреть тело запроса (`BODY`) — важны пустые или странные поля.
4. Изучать ответ — код/текст ошибки, содержимое JSON.
5. Проверять исключения после ответа — часто указывает, что плагин не смог обработать ответ.
6. Смотреть контекст 3–10 строк до и после ошибки.

## Признаки проблем

| Признак | Вероятная причина |
|---|---|
| `{"status":"error","code":520,"message":"Unknown Error"}` | Внутренняя ошибка сервера — нужен `X-Request-Id` |
| `NullReferenceException` / `ArgumentOutOfRangeException` | Плагин ожидал данные, получил `null` |
| `external data is null` | У заказа нет связанной информации о госте |
| Одна и та же ошибка регулярно | Приоритет для разработки |
| Временной рассинхрон запроса и ответа | Сетевые / таймаутные проблемы |

Отмена