Мониторинг

Arkvory даёт четыре источника сведений: конечные точки состояния, которые отвечают на вопрос «работает ли сервер», метрики Prometheus, строки журнала в JSON и диагностику консоли. На этой странице перечислено, что содержит каждый источник, а в конце приведён набор оповещений, с которого стоит начать.

Метрики, конечные точки состояния и события журнала описывают один процесс API. У обработчика и агента резервного копирования нет порта HTTP. Их состояние видно по строкам журнала, по метрикам очереди завершения и по состоянию резервного копирования.

Проверьте сервер сейчас

1. Запросите публичную конечную точку состояния. Ключ не нужен:

   curl -fsS http://127.0.0.1:8080/health/status

   Ответ {"status":"ready"} с HTTP 200 означает, что API достигает своей базы данных и каталога хранилища файлов.

2. Запросите полный ответ о готовности с ключом состояния, который создал установщик:

   sudo sh -c 'curl -fsS -H "Authorization: Bearer $(cat /opt/proanima-arkvory/config/health-token.txt)" http://127.0.0.1:8080/health/ready'

   $root = 'C:\ProgramData\ProAnima\Arkvory'
   $key = (Get-Content "$root\config\health-token.txt" -Raw).Trim()
   Invoke-RestMethod -Headers @{ Authorization = "Bearer $key" } http://127.0.0.1:8080/health/ready

3. Проверьте резервные копии:

   arkvoryctl backup status

   Команде нужен ключ восстановления или сессия администратора. Если активно критическое предупреждение, она завершается с кодом 9. Для проверок без участия человека используйте оповещения Prometheus ниже. См. Командная строка.

4. Проверьте службы и последние строки журнала. См. Журналы.

Команда arkvory status --root <корень> выводит установленную версию, режим установки и политику обновлений. Сервер она не опрашивает. Команда arkvoryctl doctor показывает сервер, репозиторий, возможности и права одного ключа. Это проверка клиента, а не проверка состояния сервера.

Состояние и готовность

На порту API отвечают три конечные точки. Ни одна из них не расходует лимит запросов ARKVORY_MAX_REQUESTS, поэтому нагрузка передач не может заставить сервер выглядеть неработающим. Все три продолжают отвечать, пока сервер завершает текущие запросы перед остановкой.

Путь	Ключ	Ответ	Для чего
/health/live	Нет	200 {"status":"ok"}, пока процесс отвечает	Проверка процесса
/health/status	Нет	200 {"status":"ready"} или 503 {"status":"unavailable"} либо {"status":"draining"} с Retry-After: 2	Балансировщики нагрузки и проверки доступности
/health/ready	Любой действующий ключ	200 с подробностями ниже или 503 с конвертом ошибки и Retry-After	Проверки развёртывания и проверка состояния в Compose

/health/status и /health/ready проверяют три вещи: база данных отвечает и содержит ровно те миграции, что и этот выпуск; папка blobs каталога хранилища файлов существует; процесс по-прежнему владеет своей блокировкой хранилища. Результат /health/status кэшируется на одну секунду, поэтому публичные проверки не могут умножить запросы к базе данных. Сервер, который завершает работу, сразу отвечает draining.

Без ключа /health/ready возвращает 401. У ключа deployment-health, который создаёт установщик, нет ни прав на репозитории, ни прав администратора. Его секрет находится в config/health-token.txt.

Ответ 200 от /health/ready содержит такие поля:

Поле	Значение
status	В ответе 200 всегда ready
writable	false, если свободного места на томе хранилища файлов меньше ARKVORY_STORAGE_RESERVE_BYTES, а также на шлюзе чтения. Чтение продолжает работать
replication	Только в кластере высокой доступности: copies, required и singleCopyUntil или null, если копии не удаётся прочитать. Пока копий не хватает, writable равно false
role	api или reader для шлюза чтения
sharedDownloads	Аренда шлюза чтения (slot, slots, active, leaseSeconds) или null
transfers	Для uploads и downloads: admission (active, waiting, capacity, perPrincipalCapacity, waitingCapacity, perPrincipalWaitingCapacity, timeoutMs, rejected, timedOut, cancelled) и bandwidth (bytesPerSecond, perPrincipalBytesPerSecond, burstBytes, perPrincipalBurstBytes, waiting, grantedBytes)

Одна неудачная проверка готовности никогда не перезапускает службу. См. Самовосстановление.

Метрики

GET /health/metrics возвращает метрики процесса API в текстовом формате Prometheus (версия 0.0.4). Читать их может любой действующий ключ, и они доступны, пока сервер завершает работу. Создайте для сборщика ключ сервиса с минимумом прав и храните его в файле, который читает только Prometheus.

scrape_configs:
  - job_name: arkvory
    metrics_path: /health/metrics
    scheme: https
    authorization:
      credentials_file: /etc/prometheus/arkvory.key
    static_configs:
      - targets: ['arkvory.example:443']

Задание должно называться arkvory: готовые правила оповещений выбирают его по имени.

Значения принадлежат процессу и после перезапуска начинаются с нуля. При этом меняется arkvory_process_start_time_seconds. Метки ограничены: route — шаблон маршрута, а не URL, а status_class — 2xx, 5xx и так далее.

Метрика	Метки	Значение
arkvory_http_requests_total	method, route, status_class	Закрытые ответы
arkvory_http_request_duration_seconds	те же	Гистограмма длительности от 5 мс до 1800 с. Прерванные передачи включены
arkvory_http_request_bytes_total, arkvory_http_response_bytes_total	method, route	Байты сокета, включая заголовки
arkvory_http_requests_in_flight		Принятые запросы, ответы на которые ещё открыты
arkvory_transfer_active, arkvory_transfer_queue_depth	direction	Принятые передачи и передачи, ожидающие места
arkvory_transfer_admission_failures_total	direction, reason	Передачи, отклонённые допуском: rejected (очередь заполнена), timed_out, cancelled
arkvory_download_sessions_active, arkvory_download_sessions_waiting	class	Сессии скачивания, занявшие место; ждущие — по классам
arkvory_download_queue_oldest_wait_seconds		Сколько ждёт самое долгое ждущее скачивание
arkvory_download_session_events_total	event	Сессии скачивания: допущены (admitted), в очереди (queued), завершены (completed), освобождены после паузы (released), уступили место (yielded), не пришли (no_show), отклонены сверх предела (refused)
arkvory_completion_jobs	state (queued, running)	Задания завершения загрузки в базе данных
arkvory_completion_oldest_queued_seconds		Ожидание самого старого готового к выполнению задания в очереди
arkvory_diagnostic_records_total	outcome (written, dropped, truncated, oversized)	Строки журнала по результату
arkvory_metrics_collection_failures_total	collector (jobs, backup, mirror, webhook, fleet)	Неудачные чтения метрик, которые берутся из базы данных
arkvory_backup_last_success_timestamp_seconds		Время снимка самой новой завершённой точки резервного копирования
arkvory_backup_agent_last_seen_timestamp_seconds		Последний сигнал агента резервного копирования
arkvory_backup_warnings	code	1, пока предупреждение активно, иначе 0
arkvory_mirror_last_sync_timestamp_seconds, arkvory_mirror_last_check_timestamp_seconds	repository, mode	Время, когда зеркало последний раз догнало источник, и время последнего чтения его потока изменений
arkvory_mirror_failing	repository, mode	1, пока последняя попытка синхронизации не удалась
arkvory_mirror_conflicts	repository, mode	Записи источника, отложенные из-за конфликта, пока остальное синхронизируется
arkvory_webhook_failing, arkvory_webhook_last_success_timestamp_seconds	subscription, repository	Доставка вебхука: 1, пока последняя попытка неудачна, и время последнего ответа 2xx
arkvory_tls_certificate_expiry_timestamp_seconds		Срок действия встроенного сертификата HTTPS. Есть только со встроенным HTTPS
arkvory_build_info	service, version	Всегда 1
arkvory_process_start_time_seconds, arkvory_process_resident_memory_bytes		Время запуска и резидентная память
arkvory_database_pool_connections, arkvory_database_pool_idle, arkvory_database_pool_waiting	pool (queries, sessions, locks)	Соединения пулов базы данных: открытые, свободные и ожидающие; если ожидающие долго больше нуля, пул мал
arkvory_fleet_site_up	site, name	На управляющей площадке: 1, если управляемая площадка ответила на последний опрос, иначе 0
arkvory_fleet_site_last_seen_timestamp_seconds	site, name	На управляющей площадке: когда управляемая площадка ответила последний раз
arkvory_fleet_mirror_lag_changes	site, repository	На управляющей площадке: на сколько изменений зеркало управляемой площадки отстаёт от источника; пока площадка не отвечает — по последним сведениям
arkvory_fleet_mirror_lag_alert_changes		На управляющей площадке: ARKVORY_FLEET_LAG_ALERT (по умолчанию 1000), отставание, при котором зеркало даёт оповещение; с ним сравнивает ArkvoryFleetMirrorBehind
arkvory_fleet_alerts	severity, kind	На управляющей площадке: оповещения страницы Площадки, включая эту установку

Метрики, которые берутся из базы данных (завершение, резервное копирование, зеркала), читаются не чаще чем раз в 5 секунд. Если чтение не удалось, сервер не показывает эти метрики вместо того, чтобы показывать старые значения, и arkvory_metrics_collection_failures_total растёт. Исключение — метрики управляемых площадок (arkvory_fleet_*): они сохраняют последнее чтение управляющей площадки, чтобы неудачное чтение не сбрасывало период for правил оповещений о площадках.

99-й процентиль запросов управления, без передач файлов:

histogram_quantile(0.99, sum by (le) (rate(arkvory_http_request_duration_seconds_bucket{route!~".*(content|parts).*"}[10m])))

Arkvory не экспортирует свободное место тома хранилища файлов или базы данных. Для томов используйте node_exporter, для PostgreSQL — postgres_exporter.

Журналы

API, обработчик, агент резервного копирования и инструменты обслуживания пишут в стандартный вывод по одному объекту JSON в строке. Сервер сам не пишет файлы журнала. Строки собирает менеджер служб вашей платформы.

Установка	Где читать	Ротация
Linux (пакеты, install.sh)	journalctl -u arkvory-api -u arkvory-worker -u arkvory-backup. Управляемая база данных — arkvory-database, программа обновления — arkvory-update	Задаётся в journald
Windows	logs\arkvory-api.out.log, arkvory-worker.out.log, arkvory-backup.out.log в корне установки. Вывод ошибок попадает в соседние файлы .err.log. Программа обновления пишет logs\updater.log, служба базы данных пишет в database\	20 МиБ на файл, 5 старых файлов хранятся
Docker Compose	docker logs --tail 100 proanima-arkvory-api-1 и то же для -worker-1 и -backup-1	20 МиБ на файл, 5 файлов на контейнер

Зависание завершает процесс записью process.stalled в стандартный вывод ошибок, поэтому смотрите также файл .err.log или журнал journald. Остальные файлы в logs\ описаны в разделе Windows.

Каждая строка начинается с одних и тех же полей:

Поле	Значение
timestamp	Время UTC в формате ISO 8601
level	debug, info, warning или error
service	api, worker, backup, migrate, gc или scrub
version, pid, hostname	Выпуск, процесс и узел
component	api, http, storage, worker, maintenance, backup, mirror, migrate, process или diagnostics
code	Имя события

Остальные поля берутся из фиксированного списка: идентификаторы (requestId, traceId, jobId, uploadId, artifactId, repository, principal, clientIp), числа (status, durationMs, bytesSent, bytesReceived, attempts) и поля причины (errorCode, errorName, errno, sqlstate, reason). ARKVORY_LOG_LEVEL задаёт самый низкий записываемый уровень.

Важные события

Событие (code)	Уровень	Значение и первое действие
api.listening	info	API принимает запросы. Поля address, port и tls
startup.failed	error	API не запустился. Причина названа в reason. См. Устранение неполадок
worker.unavailable	error	Обработчик не запустился или остановился с ошибкой
http.plaintext_exposed	warning	API слушает адрес, отличный от loopback, без TLS и без доверенного прокси
http.access	info	Одна строка на каждый завершённый или прерванный запрос
код ошибки запроса, например unavailable или internal	warning для 4xx, error для 5xx	Неудачный запрос с полями requestId, route, status и, для системных ошибок, errorName, errno или sqlstate
upload.input_timeout, upload.deadline	warning	Загрузка перестала присылать данные или заняла больше ARKVORY_UPLOAD_DEADLINE_MS
api.ownership_lost, worker.ownership_lost	error	Сессия базы данных, которая подтверждает владение хранилищем файлов, оборвалась. Процесс завершается и перезапускается
process.stalled	error	Сторожевой таймер завершил зависший процесс. Поле stalledSeconds
process.unhandled	error	Неожиданная ошибка завершила процесс
process.watchdog_failed	warning	Сторожевой таймер не смог запуститься. Служба работает без него
drain.started, drain.settled, drain.timeout, api.stopped	info или warning	Плавная остановка. drain.timeout означает, что запросы были оборваны
tls.reloaded, tls.reload_failed, tls.expiring	info или warning	Файлы сертификата прочитаны заново, не удалось их прочитать или они истекают меньше чем через 14 дней. tls.expiring повторяется раз в сутки
completion.completed, completion.failed, completion.lease_lost, completion.attempts_exhausted	info или error	Результат задания завершения загрузки, с полями jobId, uploadId и errorCode
backup.agent.started, backup.agent.standby, backup.agent.lease_lost	info или warning	Состояние агента резервного копирования
backup.request.failed, backup.request.requeued, backup.failed	error или warning	Задание резервного копирования не удалось или выполняется снова. Поле errorCode
mirror.step_failed, mirror.recovered	warning или info	Шаг синхронизации зеркала не удался (errorCode, attempts) или снова работает
mirror.conflict_set_aside, mirror.conflict_resolved	warning или info	Зеркало отложило запись источника из-за конфликта или снова не смогло её применить (artifactId, action, errorCode, attempts), либо запись разрешилась
webhook.step_failed, webhook.recovered	warning или info	Доставка вебхука не удалась (subscription, errorCode, attempts) или снова работает
migrate.started, migrate.completed, migrate.failed	info или error	Миграция базы данных при обновлении
diagnostics.dropped, diagnostics.oversized	warning	Строки отброшены, потому что читатель журнала слишком медленный, или строка оказалась слишком длинной

Медленный читатель журнала никогда не замедляет передачу. Когда вывод заблокирован, сервер отбрасывает строки, считает их и после освобождения вывода пишет diagnostics.dropped с их числом. Строка длиннее 4096 символов заменяется на diagnostics.oversized. Текстовые поля обрезаются до 256 символов.

ID запросов

Каждый ответ содержит заголовок X-Request-Id, а в каждом теле ошибки есть поле requestId. То же значение указано в строке http.access, в строке ошибки, в строках задания завершения, которое запустил запрос, и в записях аудита. Клиенту, который сообщает о проблеме, достаточно назвать только это значение.

journalctl -u arkvory-api -u arkvory-worker --since "1 hour ago" -o cat | grep 'REQUEST_ID'

Select-String -Path "$root\logs\*.log" -Pattern 'REQUEST_ID'

За обратным прокси сервер принимает входящий X-Request-Id только с адреса из ARKVORY_TRUSTED_PROXIES и только если это одно значение длиной от 8 до 128 символов (буквы, цифры, ., _, : и -). Пусть прокси перезаписывает заголовок, например proxy_set_header X-Request-Id $request_id; в nginx. Действительный заголовок W3C traceparent от любого клиента становится полем traceId. Он нужен только для поиска и ничего не разрешает.

Что никогда не попадает в журнал

В журнале нет паролей, ключей, токенов, заголовков Authorization, тел запросов, строк запроса, URL и текстов исключений. Ссылки на скачивание несут секрет в строке запроса, поэтому записывается только шаблон маршрута. Поле reason — единственный свободный текст. Оно очищается от секретов и обрезается до 240 символов. В строке есть principal (ID учётной записи или ключа) и clientIp. Относитесь к журналу как к персональным данным.

ARKVORY_ACCESS_LOG=false отключает http.access. Успешные запросы к /health/live и /health/status не записываются никогда. Уровни warning и error тоже скрывают строки доступа.

Диагностика в консоли

Администраторы видят состояние сервера в консоли без доступа к оболочке. См. Веб-консоль.

Где	Что видно
Резервные копии	В заголовке — состояния Копии в порядке, Есть предупреждения и Требуется вмешательство. Ниже — Последняя копия, Следующий запуск, Агент копирования, Хранилище копий и список предупреждений с действием для каждого
Обновления	Установленная и последняя версии, время последней проверки и состояние программы обновления на сервере
Хранение и очистка репозитория	Использование квоты и сообщения Хранилище приближается к квоте. Проверьте политику и запланируйте физическую очистку. и Хранилище близко к квоте или достигло её. Новые резервирования сверх квоты отклоняются., а также список Предупреждения, ошибки и события хранилища
Журнал действий сервисной учётной записи	Кто что создал, изменил, выпустил или отозвал
Карточка репозитория	Значок Зеркало и состояние Зеркало · ошибка синхронизации, если последняя синхронизация не удалась

Для списка Предупреждения, ошибки и события хранилища нужно право читать диагностику. Среди прочих событий в нём есть неудачные запросы ключей сервисов в этом репозитории с ID запроса, маршрутом и статусом.

Пороги квоты — 80 % для предупреждения и 95 % для критического состояния, если администратор их не изменил. У репозитория без квоты порогов нет.

Предупреждения о хранилище и диске

Сервер держит ARKVORY_STORAGE_RESERVE_BYTES (по умолчанию 1 ГиБ) свободного места на томе хранилища файлов для базы данных, журналов и системы. Когда места становится меньше этого резерва:

• /health/ready сообщает "writable": false, но по-прежнему отвечает 200.
• Загрузки завершаются неудачей с 507 и причиной storage_full. Скачивания и консоль продолжают работать.

Сервер сам не измеряет свободное место. Следите за томом хранилища файлов, томом базы данных и томом резервных копий своими средствами и оповещайте заранее, до достижения резерва. Резерв — это не квота. ARKVORY_CAPACITY_BYTES ограничивает сумму зарезервированного содержимого и не проверяет диск. См. Хранение.

Состояние резервного копирования

Агент резервного копирования отправляет сигнал при каждом продлении аренды. API превращает сигнал и историю заданий резервного копирования в предупреждения с фиксированными кодами. Что требует каждый код, см. в разделе Резервные копии.

Код	Серьёзность	Условие
agent_offline	критическая	Нет сигнала 2 минуты
backup_stale	критическая	Самой новой точке больше 26 часов, а план включён
vault_unavailable	критическая	Том хранилища копий не подключён, в нём нет vault.json или в него нельзя писать
verify_failed	критическая	Точка восстановления не прошла проверку
vault_not_configured, schedule_disabled, no_backup_yet, last_run_failed	предупреждение	Нет хранилища копий, план выключен, нет первой копии, последняя копия не удалась
vault_low_space	предупреждение	В хранилище копий свободно меньше 10 % или меньше удвоенного объёма новых байт последней точки
never_deep_verified	предупреждение	Полной проверки не было больше 8 дней

Метрика arkvory_backup_warnings несёт те же коды. Возраст копии отсчитывается от времени её снимка, а не от момента завершения.

Рекомендуемые оповещения

В выпуске есть готовые правила Prometheus в файле releases/<версия>/deploy/monitoring/arkvory-alerts.yml. Добавьте файл в rule_files в prometheus.yml. Пороги — это отправная точка. Настройте их по трафику, который вы измеряете.

Оповещение	Условие	Серьёзность
ArkvoryDown	Сбор метрик не удаётся 2 минуты	Критическая
ArkvoryHighServerErrorRate	Более 5 % ответов — 5xx в течение 10 минут	Предупреждение
ArkvorySlowMetadataRequests	99-й процентиль запросов управления выше 2 с в течение 15 минут	Предупреждение
ArkvoryCompletionBacklog	Самое старое задание завершения в очереди ждёт больше 10 минут	Предупреждение
ArkvoryTransferAdmissionRejections	Более 0,1 отклонённых или просроченных передач в секунду в течение 15 минут	Предупреждение
ArkvoryDiagnosticsDropped	За последние 15 минут строки журнала отбрасывались	Предупреждение
ArkvoryMetricsCollectionFailing	Не удалось прочитать метрику, которая берётся из базы данных	Предупреждение
ArkvoryTlsCertificateExpiring, ArkvoryTlsCertificateExpired	Встроенный сертификат истекает меньше чем через 14 дней или уже истёк	Предупреждение, критическая
ArkvoryBackupStale	Самой новой точке больше 26 часов	Критическая
ArkvoryBackupAgentOffline	Нет сигнала больше 2 минут, в течение 5 минут	Критическая
ArkvoryBackupWarning	vault_unavailable или verify_failed в течение 10 минут	Критическая
ArkvoryMirrorStale	Зеркало не догоняло источник час	Предупреждение
ArkvoryMirrorFailing	Последняя синхронизация зеркала не удалась, в течение 15 минут	Предупреждение
ArkvoryMirrorConflicts	У зеркала есть отложенные записи источника, в течение 30 минут	Предупреждение
ArkvoryRestartLoop	Процесс API перезапускался 3 и более раз за 30 минут	Предупреждение
ArkvoryWebhookFailing	Доставка вебхука не удаётся 15 минут	Предупреждение
ArkvoryFleetSiteDown	Управляемая площадка не отвечает управляющей 5 минут	Критическая
ArkvoryFleetMirrorBehind	Отставание зеркала управляемой площадки не меньше ARKVORY_FLEET_LAG_ALERT (по умолчанию 1000) в течение 30 минут	Предупреждение
ArkvoryFleetCritical	Страница «Площадки» управляющей площадки показывает критические оповещения 5 минут	Критическая

Добавьте эти оповещения сами, потому что Arkvory не экспортирует для них данные:

Оповещение	Источник	Зачем
Свободное место на томах хранилища файлов, базы данных и копий	node_exporter	Полный диск останавливает загрузки, базу данных и резервное копирование
PostgreSQL не работает или слишком много соединений	postgres_exporter	API завершается и перезапускается, пока базы данных нет
Публичное состояние не ready	Внешняя проверка /health/status	Сетевой путь, прокси и сертификат глазами клиента

Для томов и PostgreSQL в выпуске есть готовые правила для node_exporter и postgres_exporter в deploy/monitoring/arkvory-host-alerts.yml. Перед подключением файла замените выражения mountpoint на свои тома.

Проверьте оповещение один раз. Например, остановите arkvory-backup: ArkvoryBackupAgentOffline сработает примерно через 7–8 минут (2 минуты без сигнала, 5 минут в правиле и интервал сбора метрик).

Связанные страницы

• Самовосстановление
• Устранение неполадок
• Резервные копии
• Переменные окружения
• Ошибки