Журналы отладки: диагностика проблем и мониторинг состояния

Что вы сможете сделать после изучения

Включить журналы отладки для записи подробной информации о всех запросах и ответах
Понимать различные уровни журналирования и сценарии их применения
Интерпретировать содержимое журналов для быстрого определения причины проблем
Использовать переменные окружения для временного включения отладки без изменения конфигурации
Управлять файлами журналов, избегая чрезмерного использования дискового пространства

Ваши текущие затруднения

При возникновении проблем вы можете столкнуться с:

Неясными сообщениями об ошибках без понимания конкретной причины
Неуверенностью в том, успешно ли запрос достиг Antigravity API
Подозрениями на проблемы с выбором аккаунта, ограничением скорости или преобразованием запросов
Невозможностью предоставить ценную диагностическую информацию при обращении за помощью

Когда использовать этот метод

Журналы отладки подходят для следующих сценариев:

Сценарий	Необходимость	Причина
Диагностика ограничения скорости 429	✅ Нужно	Узнать, какой аккаунт и модель ограничены
Диагностика ошибок аутентификации	✅ Нужно	Проверить обновление токена, процесс OAuth
Диагностика преобразования запросов	✅ Нужно	Сравнить исходный и преобразованный запросы
Диагностика стратегии выбора аккаунта	✅ Нужно	Увидеть, как плагин выбирает аккаунт
Мониторинг повседневной работы	✅ Нужно	Статистика частоты запросов, успехов/неудач
Длительная работа	⚠️ Осторожно	Журналы будут постоянно расти, требуется управление

Предварительная проверка

Перед началом этого урока убедитесь, что вы:

✅ Установили плагин opencode-antigravity-auth
✅ Успешно прошли OAuth-аутентификацию
✅ Можете отправлять запросы с использованием моделей Antigravity

Руководство по быстрой установке | Руководство по первому запросу

Основная идея

Принцип работы системы журналов отладки:

Структурированные журналы: каждая запись содержит временную метку и тег для удобной фильтрации и анализа
Уровни записи:
- Level 1 (basic): запись метаинформации запросов/ответов, выбора аккаунта, событий ограничения скорости
- Level 2 (verbose): полная запись тела запроса/ответа (до 50 000 символов)
Маскировка безопасности: автоматическое скрытие конфиденциальной информации (например, заголовка Authorization)
Отдельные файлы: при каждом запуске создаётся новый файл журнала во избежание путаницы

Обзор содержимого журналов:

Тип журнала	Тег	Пример содержимого
Трассировка запроса	`Antigravity Debug ANTIGRAVITY-1`	URL, headers, предпросмотр body
Трассировка ответа	`Antigravity Debug ANTIGRAVITY-1`	Код состояния, время выполнения, body ответа
Контекст аккаунта	`[Account]`	Выбранный аккаунт, индекс, семейство моделей
Ограничение скорости	`[RateLimit]`	Детали ограничения, время сброса, задержка повтора
Распознавание модели	`[ModelFamily]`	Разбор URL, извлечение модели, определение семейства

Пошаговое руководство

Шаг 1: Включение базовых журналов отладки

Зачем После включения базовых журналов отладки плагин будет записывать метаинформацию всех запросов, включая URL, headers, выбор аккаунта, события ограничения скорости, помогая диагностировать проблемы без раскрытия конфиденциальных данных.

Действия

Отредактируйте файл конфигурации плагина:

macOS/LinuxWindows

bash

nano ~/.config/opencode/antigravity.json

powershell

notepad %APPDATA%\opencode\antigravity.json

Добавьте или измените следующую конфигурацию:

json

{
  "$schema": "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/main/assets/antigravity.schema.json",
  "debug": true
}

Сохраните файл и перезапустите OpenCode.

Ожидаемый результат:

После запуска OpenCode в каталоге конфигурации появится новый файл журнала
Формат имени файла журнала: antigravity-debug-YYYY-MM-DDTHH-MM-SS-mmmZ.log
После отправки любого запроса в файле журнала появятся новые записи

Расположение файлов журналов

Linux/macOS: ~/.config/opencode/antigravity-logs/
Windows: %APPDATA%\opencode\antigravity-logs\

Шаг 2: Интерпретация содержимого журналов

Зачем Понимание формата и содержимого журналов позволяет быстро находить проблемы.

Действия

Отправьте тестовый запрос, затем просмотрите файл журнала:

bash

<!-- macOS/Linux -->
tail -f ~/.config/opencode/antigravity-logs/antigravity-debug-*.log

<!-- Windows PowerShell -->
Get-Content "$env:APPDATA\opencode\antigravity-logs\antigravity-debug-*.log" -Wait

Ожидаемый результат:

log

[2026-01-23T10:30:15.123Z] [Account] Request: Account 1 (1/2) family=claude
[2026-01-23T10:30:15.124Z] [Antigravity Debug ANTIGRAVITY-1] POST https://cloudcode-pa.googleapis.com/...
[2026-01-23T10:30:15.125Z] [Antigravity Debug ANTIGRAVITY-1] Streaming: yes
[2026-01-23T10:30:15.126Z] [Antigravity Debug ANTIGRAVITY-1] Headers: {"user-agent":"opencode-antigravity-auth/1.3.0","authorization":"[redacted]",...}
[2026-01-23T10:30:15.127Z] [Antigravity Debug ANTIGRAVITY-1] Body Preview: {"model":"google/antigravity-claude-sonnet-4-5",...}
[2026-01-23T10:30:18.456Z] [Antigravity Debug ANTIGRAVITY-1] Response 200 OK (3330ms)
[2026-01-23T10:30:18.457Z] [Antigravity Debug ANTIGRAVITY-1] Response Headers: {"content-type":"application/json",...}

Разбор журнала:

Временная метка: [2026-01-23T10:30:15.123Z] — формат ISO 8601, точность до миллисекунд
Выбор аккаунта: [Account] — плагин выбрал аккаунт 1, всего 2 аккаунта, семейство моделей claude
Начало запроса: Antigravity Debug ANTIGRAVITY-1 — ID запроса равен 1
Метод запроса: POST https://... — HTTP-метод и целевой URL
Потоковый режим: Streaming: yes/no — используется ли SSE-потоковый ответ
Заголовки запроса: Headers: {...} — Authorization автоматически скрыт (показывается [redacted])
Тело запроса: Body Preview: {...} — содержимое запроса (до 12 000 символов, остальное обрезается)
Статус ответа: Response 200 OK (3330ms) — HTTP-код состояния и время выполнения
Заголовки ответа: Response Headers: {...} — headers ответа

Шаг 3: Включение подробных журналов (Verbose)

Зачем Подробные журналы записывают полное тело запроса/ответа (до 50 000 символов), что подходит для диагностики глубоких проблем с преобразованием запросов и разбором ответов.

Действия

Измените конфигурацию на уровень verbose:

json

{
  "debug": true,
  "OPENCODE_ANTIGRAVITY_DEBUG": "2"
}

Или используйте переменную окружения (рекомендуется, не требует изменения конфигурации):

macOS/LinuxWindows

bash

export OPENCODE_ANTIGRAVITY_DEBUG=2
opencode

powershell

$env:OPENCODE_ANTIGRAVITY_DEBUG="2"
opencode

Ожидаемый результат:

В файле журнала появится полное тело запроса/ответа (не обрезанный preview)
Для больших ответов будут показаны первые 50 000 символов с указанием количества обрезанных символов

log

[2026-01-23T10:30:15.127Z] [Antigravity Debug ANTIGRAVITY-1] Response Body (200): {"id":"msg_...","type":"message","role":"assistant",...}

Предупреждение о дисковом пространстве

Подробные журналы записывают полное содержимое запросов/ответов, что может привести к быстрому росту файлов журналов. После завершения отладки обязательно отключите режим verbose.

Шаг 4: Диагностика проблем с ограничением скорости

Зачем Ограничение скорости (ошибка 429) — одна из самых распространённых проблем. Журналы покажут, какой именно аккаунт и модель ограничены, и сколько нужно ждать.

Действия

Отправьте несколько параллельных запросов для срабатывания ограничения скорости:

bash

<!-- macOS/Linux -->
for i in {1..10}; do
  opencode run "Test $i" --model=google/antigravity-claude-sonnet-4-5 &
done
wait

Просмотрите события ограничения скорости в журнале:

bash

grep "RateLimit" ~/.config/opencode/antigravity-logs/antigravity-debug-*.log

Ожидаемый результат:

log

[2026-01-23T10:30:20.123Z] [RateLimit] 429 on Account 1 family=claude retryAfterMs=60000
[2026-01-23T10:30:20.124Z] [RateLimit] message: Resource has been exhausted
[2026-01-23T10:30:20.125Z] [RateLimit] quotaResetTime: 2026-01-23T10:31:00.000Z
[2026-01-23T10:30:20.126Z] [Account] Request: Account 2 (2/2) family=claude
[2026-01-23T10:30:20.127Z] [RateLimit] snapshot family=claude Account 1=wait 60s | Account 2=ready

Разбор журнала:

Детали ограничения: 429 on Account 1 family=claude retryAfterMs=60000
- Аккаунт 1 (семейство моделей claude) получил ошибку 429
- Необходимо подождать 60 000 миллисекунд (60 секунд) перед повтором
Сообщение об ошибке: message: Resource has been exhausted — квота исчерпана
Время сброса: quotaResetTime: 2026-01-23T10:31:00.000Z — точное время сброса квоты
Переключение аккаунта: плагин автоматически переключился на аккаунт 2
Глобальный снимок: snapshot — показывает статус ограничения всех аккаунтов

Шаг 5: Настройка каталога журналов

Зачем По умолчанию файлы журналов хранятся в каталоге ~/.config/opencode/antigravity-logs/. Если вы хотите хранить журналы в другом месте (например, в каталоге проекта), можно настроить пользовательский каталог.

Действия

Добавьте параметр log_dir в файл конфигурации:

json

{
  "$schema": "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/main/assets/antigravity.schema.json",
  "debug": true,
  "log_dir": "/path/to/your/custom/logs"
}

Или используйте переменную окружения:

bash

export OPENCODE_ANTIGRAVITY_LOG_DIR="/path/to/your/custom/logs"
opencode

Ожидаемый результат:

Файлы журналов записываются в указанный каталог
Если каталог не существует, плагин создаст его автоматически
Формат имени файла журнала остаётся прежним

Рекомендации по путям

Разработка и отладка: хранить в корневом каталоге проекта (.logs/)
Продакшен: хранить в системном каталоге журналов (/var/log/ или ~/Library/Logs/)
Временная отладка: хранить в каталоге /tmp/ для удобной очистки

Шаг 6: Очистка и управление файлами журналов

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

Действия

Проверьте размер каталога журналов:

bash

<!-- macOS/Linux -->
du -sh ~/.config/opencode/antigravity-logs/

<!-- Windows PowerShell -->
Get-ChildItem "$env:APPDATA\opencode\antigravity-logs\" | Measure-Object -Property Length -Sum

Очистите старые журналы:

bash

<!-- macOS/Linux -->
find ~/.config/opencode/antigravity-logs/ -name "antigravity-debug-*.log" -mtime +7 -delete

<!-- Windows PowerShell -->
Get-ChildItem "$env:APPDATA\opencode\antigravity-logs\antigravity-debug-*.log" |
  Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-7) } |
  Remove-Item

Ожидаемый результат:

Размер каталога журналов уменьшится
Останутся только файлы журналов за последние 7 дней

Автоматическая очистка

Можно добавить скрипт очистки в cron (Linux/macOS) или Планировщик задач (Windows) для периодического выполнения.

Контрольная точка ✅

После выполнения вышеуказанных шагов вы должны уметь:

[ ] Включать журналы отладки через файл конфигурации
[ ] Использовать переменные окружения для временного включения отладки
[ ] Интерпретировать содержимое журналов, находить детали запросов/ответов
[ ] Понимать назначение различных уровней журналирования
[ ] Настраивать пользовательский каталог журналов
[ ] Управлять и очищать файлы журналов

Типичные ошибки

Файлы журналов постоянно растут

Симптом: дисковое пространство занято файлами журналов

Причина: длительное включение журналов отладки, особенно в режиме verbose

Решение:

После завершения отладки немедленно отключите debug: false
Настройте скрипт периодической очистки (как в шаге 6)
Мониторьте размер каталога журналов, установите пороговые оповещения

Файлы журналов не найдены

Симптом: включено debug: true, но каталог журналов пуст

Причина:

Неверный путь к файлу конфигурации
Проблемы с правами доступа (невозможно записать в каталог журналов)
Переменная окружения переопределила конфигурацию

Решение:

Убедитесь, что путь к файлу конфигурации правильный:

bash

# Поиск файла конфигурации
find ~/.config/opencode/ -name "antigravity.json" 2>/dev/null

Проверьте, не переопределила ли переменная окружения конфигурацию:
bash
```
echo $OPENCODE_ANTIGRAVITY_DEBUG
```
Проверьте права доступа к каталогу журналов:
bash
```
ls -la ~/.config/opencode/antigravity-logs/
```

Содержимое журналов неполное

Симптом: в журнале не видно тела запроса/ответа

Причина: по умолчанию используется базовый уровень (Level 1), который записывает только preview тела (до 12 000 символов)

Решение:

Включите уровень verbose (Level 2):
json
```
{
  "OPENCODE_ANTIGRAVITY_DEBUG": "2"
}
```
Или используйте переменную окружения:
bash
```
export OPENCODE_ANTIGRAVITY_DEBUG=2
```

Утечка конфиденциальной информации

Симптом: беспокойство о наличии конфиденциальных данных в журналах (например, токена Authorization)

Причина: плагин автоматически маскирует заголовок Authorization, но другие заголовки могут содержать конфиденциальную информацию

Решение:

Плагин уже автоматически маскирует заголовок Authorization (показывается [redacted])
При передаче журналов проверьте наличие других конфиденциальных заголовков (например, Cookie, Set-Cookie)
При обнаружении конфиденциальной информации удалите её вручную перед передачей

Невозможно открыть файл журнала

Симптом: файл журнала занят другим процессом, невозможно просмотреть

Причина: OpenCode записывает в файл журнала

Решение:

Используйте команду tail -f для просмотра журнала в реальном времени (не блокирует файл)
Если нужно редактировать, сначала закройте OpenCode
Используйте команду cat для просмотра содержимого (не блокирует файл)

Резюме урока

Журналы отладки — мощный инструмент для диагностики проблем, записывающий детали запросов/ответов, выбор аккаунта, события ограничения скорости
Есть два уровня журналирования: basic (Level 1) и verbose (Level 2)
Переменные окружения позволяют временно включить отладку без изменения файла конфигурации
Плагин автоматически маскирует конфиденциальную информацию (например, заголовок Authorization)
При длительной работе необходимо периодически очищать файлы журналов

Анонс следующего урока

В следующем уроке мы изучим Обработка ограничения скорости.
Вы узнаете:
Механизм обнаружения ограничения скорости и стратегии повторных попыток
Принцип работы алгоритма экспоненциальной задержки
Как настроить максимальное время ожидания и количество повторов
Обработка ограничения скорости в сценариях с несколькими аккаунтами

Приложение: Справочник по исходному коду

Нажмите, чтобы развернуть позиции исходного кода

Время обновления: 2026-01-23

Функция	Путь файла	Строки
Модуль Debug	`src/plugin/debug.ts`	Весь файл
Инициализация отладки	`src/plugin/debug.ts`	98-118
Трассировка запросов	`src/plugin/debug.ts`	189-212
Запись ответов	`src/plugin/debug.ts`	217-250
Маскировка заголовков	`src/plugin/debug.ts`	255-270
Журналы ограничения скорости	`src/plugin/debug.ts`	354-396
Схема конфигурации	`src/plugin/config/schema.ts`	64-72

Ключевые константы:

Имя константы	Значение	Описание
`MAX_BODY_PREVIEW_CHARS`	12000	Длина предпросмотра body на уровне Basic
`MAX_BODY_VERBOSE_CHARS`	50000	Длина предпросмотра body на уровне Verbose
`DEBUG_MESSAGE_PREFIX`	`"[opencode-antigravity-auth debug]"`	Префикс журналов отладки

Ключевые функции:

initializeDebug(config): инициализация состояния отладки, чтение конфигурации и переменных окружения
parseDebugLevel(flag): разбор строки уровня отладки ("0"/"1"/"2"/"true"/"verbose")
getLogsDir(customLogDir?): получение каталога журналов, поддержка пользовательского пути
createLogFilePath(customLogDir?): генерация пути к файлу журнала с временной меткой
startAntigravityDebugRequest(meta): начало трассировки запроса, запись метаинформации
logAntigravityDebugResponse(context, response, meta): запись деталей ответа
logAccountContext(label, info): запись контекста выбора аккаунта
logRateLimitEvent(...): запись событий ограничения скорости
maskHeaders(headers): маскировка конфиденциальных заголовков (Authorization)

Параметры конфигурации (из schema.ts):

Параметр	Тип	По умолчанию	Описание
`debug`	boolean	`false`	Включить журналы отладки
`log_dir`	string?	undefined	Пользовательский каталог журналов

Переменные окружения:

Переменная окружения	Значение	Описание
`OPENCODE_ANTIGRAVITY_DEBUG`	"0"/"1"/"2"/"true"/"verbose"	Переопределяет конфигурацию debug, управляет уровнем журналирования
`OPENCODE_ANTIGRAVITY_LOG_DIR`	string	Переопределяет конфигурацию log_dir, указывает каталог журналов

Журналы отладки: диагностика проблем и мониторинг состояния ​

Что вы сможете сделать после изучения ​

Ваши текущие затруднения ​

Когда использовать этот метод ​

Основная идея ​

Пошаговое руководство ​

Шаг 1: Включение базовых журналов отладки ​

Шаг 2: Интерпретация содержимого журналов ​

Шаг 3: Включение подробных журналов (Verbose) ​

Шаг 4: Диагностика проблем с ограничением скорости ​

Шаг 5: Настройка каталога журналов ​

Шаг 6: Очистка и управление файлами журналов ​

Контрольная точка ✅ ​

Типичные ошибки ​

Файлы журналов постоянно растут ​

Файлы журналов не найдены ​

Содержимое журналов неполное ​

Утечка конфиденциальной информации ​

Невозможно открыть файл журнала ​

Резюме урока ​

Анонс следующего урока ​

Приложение: Справочник по исходному коду ​

Журналы отладки: диагностика проблем и мониторинг состояния

Что вы сможете сделать после изучения

Ваши текущие затруднения

Когда использовать этот метод

Основная идея

Пошаговое руководство

Шаг 1: Включение базовых журналов отладки

Шаг 2: Интерпретация содержимого журналов

Шаг 3: Включение подробных журналов (Verbose)

Шаг 4: Диагностика проблем с ограничением скорости

Шаг 5: Настройка каталога журналов

Шаг 6: Очистка и управление файлами журналов

Контрольная точка ✅

Типичные ошибки

Файлы журналов постоянно растут

Файлы журналов не найдены

Содержимое журналов неполное

Утечка конфиденциальной информации

Невозможно открыть файл журнала

Резюме урока

Анонс следующего урока

Приложение: Справочник по исходному коду