Мониторинг

Эта страница — про ваш мониторинг AACsearch. Свой кластер мы мониторим сами — это статусная страница. Вам нужно смотреть на связку «приложение ↔ AACsearch»: какие ключи 429-ят, какие индексы дрейфуют, сколько стоит реиндекс.

Глубокая интеграция с observability (request id, Sentry, PostHog) — Observability.

Четыре сигнала

Если смотрите только на четыре цифры — смотрите на эти:

Каждый сигнал также доступен как oRPC-процедура, чтобы класть в свои дашборды. Процедуры и пороги:

Пороги совпадают с «жёлтым» дашборда — если алертите по жёлтому, алертите по нашим порогам. Жёстче — нормально.

Health-значок → действие

В списке Indexes — цветной значок на индекс. Что значит и что делать первым.

Зелёный

Всё в норме. Действий нет.

Жёлтый — ingest lag

Буфер флашит больше 5 минут. Смотрите:

1. Dashboard → Diagnostics. Свежие строки с ошибками — посмотрите сообщение.
2. Статусную страницу региона. Деградированный Typesense раздувает lag.
3. Своих writer-ов. Не запустили ли бэкфилл, который ×10 от обычной записи? Буфер делает свою работу — back-pressure на вас.

Жёлтый — error rate

Падает > 1 % flush-ей. По частоте:

1. Валидация документа. Новая форма поля не принимается. Diagnostics → ошибка указывает на документ.
2. Memory pressure у Typesense. На общем кластере — редко; на индексах вне плана — часто.
3. Сетевой blip. ETIMEDOUT-паттерн. Если статус кластера зелёный и ставка сама ушла — это был blip.

Красный — doc count drift

Typesense считает документов > 5 % мимо ожиданий буфера. Всегда проверять; обычно это:

• Прерванный реиндекс не подчистился.
• Большой delete-by-filter, у дашборда счётчик ещё не обновился.
• Баг приложения — пишет дубли или пропускает id.

Не узнали ни одного из трёх — тикет.

Завод метрик в свой стек

Простейший путь: воркер опрашивает searchIndex.getHealth для каждого индекса раз в минуту и пишет в pipeline метрик.

import { client } from "@repo/api/client";

for (const indexId of allIndexIds) {
	const health = await client.searchIndex.getHealth.call({ indexId });
	emit("aacsearch.index.docCountDrift", health.docCountDrift, { indexId });
	emit("aacsearch.index.ingestLagSeconds", health.ingestLagSeconds, { indexId });
	emit("aacsearch.index.errorRate", health.errorRate, { indexId });
}

Или через SDK getHealth из Node. Данные те же; чаще раза в 30 секунд не имеет смысла — значения не меняются быстрее.

Здоровье webhook-доставки

Если включены webhook-и, в Dashboard → Webhooks → Deliveries видно:

• Последние 1 000 попыток.
• 2xx / 4xx / 5xx распределение.
• p50 / p95 / p99 latency.
• Очередь retry (события, ждущие повтор).

Растущая очередь retry — ваш endpoint медленный или возвращает 5xx. Webhook-и ретраятся с exponential backoff 24 часа, потом — в dead-letter, который можно вручную проиграть.

Использование rate limit

У каждого ключа есть rateLimitPerMinute. В дашборде API keys → Usage — график на 24 часа.

Два вопроса:

1. Есть ли ключ, держащийся > 80 % бюджета? Этому ключу нужен либо более высокий лимит (саппорт), либо снижение нагрузки.
2. Случаются 429 в нормальном трафике? 429 в норме — лимит занижен; 429 только на пиках — допустимо, если клиент ретраит с backoff.

Подробнее — Лимиты.

Чем НЕ мониторить

• Latency поиска с устройств пользователей без синтетического baseline. Мобильные сети доминируют дисперсию; будете алертить на качество Wi-Fi в кофейнях.
• Sentry-алерт на каждый 4xx. 4xx — это API делает свою работу (валидация, лимит). Алертите на 5xx; устойчивые 4xx — в дашборд.
• HEAD-пинги /api/v1/indexes. Для нас дёшево, ваш rate limit ест. Используйте /api/v1/health без auth.

Синтетические probes

Не-аутентифицированный, rate-limit-exempt endpoint — GET /api/v1/health. Возвращает 200 { "status": "ok" }, когда API-gateway жив. Поиск это не проверяет; для проверки поиска запускайте реальный search по известному индексу из вашего региона с search-ключом и пишите latency.

Частые ошибки

• Раз в день смотреть на значок. Жёлтый → красный — 10 минут. Поллинг каждые 30–60 секунд — нормально; дашборд всё равно кеширует значения по 30 секунд.
• Алерт на абсолютный doc count. Абсолют двигается на каждом аплоаде. Алертите на drift.
• Игнор аудита. Половина «почему индекс вдруг другой формы?» — audit_log.action = update_index_settings вчера. См. Аудит.

См. также

• Observability — request id, корреляция Sentry, таксономия событий
• Статус и инциденты — наша сторона мониторинга
• Лимиты и квоты — что значит 429 и как из него выйти
• Troubleshooting — дерево решений по конкретным сбоям