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

Уведомления и события

Две предыдущие страницы читали состояние по запросу. Вы обращаетесь через curl к порту мониторинга :8222 и получаете текущие показатели. Это работает, если известно, что и когда спросить. События между опросами таким способом не обнаружить.

Отставание shipping — показатель, который можно опрашивать: оно растёт, и очередной сбор это покажет. Но исчерпание попыток доставки проблемного заказа — разовое событие. К следующему опросу момент уже прошёл, а изменившийся счётчик стал частью общей суммы. Нужно, чтобы NATS сообщил о событии сразу.

Для этого NATS публикует два вида событий: уведомления в темах $JS.EVENT.ADVISORY.* и системные события в $SYS.*. Оба приходят как обычные сообщения по подписке. Вы не запрашиваете их: сервер отправляет их сам.

Уведомления​

Уведомление (advisory) — кратковременное JSON-сообщение, которое JetStream публикует один раз в момент значимого события потока или потребителя. Это обычное сообщение NATS в известной теме. Подпишитесь на неё так же, как на любую другую.

Уведомления находятся в одном дереве тем:

$JS.EVENT.ADVISORY.>

Каждое уведомление JetStream публикуется под этим префиксом. Последняя часть темы указывает событие и связанные сущности. Когда сообщение потребителя shipping исчерпывает попытки доставки, сервер публикует уведомление здесь:

$JS.EVENT.ADVISORY.CONSUMER.MAX_DELIVERIES.ORDERS.shipping

Имена потока и потребителя входят в тему, поэтому подписчик может выбрать фильтр только нужных событий: все уведомления ORDERS или только исчерпание доставок shipping.

Подпишитесь на всё дерево уведомлений, чтобы получать события системы:

#!/bin/bash
# Subscribe to every JetStream advisory the cluster publishes.
# Advisories are transient: you only see events that fire while you are
# attached. Leave this running before the shipping consumer goes wrong.
nats subscribe '$JS.EVENT.ADVISORY.>'

# When a poison order exhausts its deliveries on the shipping consumer,
# one max_deliver advisory lands on this subject:
# $JS.EVENT.ADVISORY.CONSUMER.MAX_DELIVERIES.ORDERS.shipping
# The message body names the stream, the consumer, the failed sequence,
# and how many times delivery was attempted:
#
# {
# "type": "io.nats.jetstream.advisory.v1.max_deliver",
# "stream": "ORDERS",
# "consumer": "shipping",
# "stream_seq": 987,
# "deliveries": 5
# }

Когда проблемный заказ исчерпает лимит доставки, придёт одно сообщение. В теле указаны поток, потребитель, номер неудачного сообщения и число попыток доставки:

{
"type": "io.nats.jetstream.advisory.v1.max_deliver",
"stream": "ORDERS",
"consumer": "shipping",
"stream_seq": 987,
"deliveries": 5
}

Событие целиком таково: сообщение потока с номером 987 было доставлено пять раз, ни разу не подтверждено, и JetStream прекратил попытки. Само сообщение остаётся в ORDERS согласно политике хранения; прекращается только доставка в shipping. Уведомление max_deliver — единственный встроенный сигнал об этом. Очереди недоставленных сообщений нет, а уведомление публикуется один раз. Если в этот момент никто не подписан, вы не узнаете, что заказ 987 перестал доставляться.

max_deliver — один из нескольких типов уведомлений. JetStream также публикует consumer_action при создании или удалении потребителя, nak при явном отрицательном подтверждении и terminated при прекращении доставки сообщения. У каждого своя тема под $JS.EVENT.ADVISORY.> и собственное JSON-тело. Все типы и схемы описаны в Справочнике → уведомления JetStream. Здесь нужен только max_deliver, сообщающий о заказе, который не удалось обработать.

Уведомление о выборе лидера​

Одно уведомление стоит выделить. При смене лидера реплицируемого потока или потребителя JetStream публикует сообщение с именем нового лидера. Оно приходит по той же подписке $JS.EVENT.ADVISORY.>. Частые смены лидера заслуживают внимания.

Здесь мы наблюдаем факт смены. Почему она произошла — как прошли выборы, что такое кворум, какой узел победил — относится к устройству кластера. Это разобрано в Кластеризация → RAFT и лидеры. Здесь уведомление — полученный факт, без объяснения процесса.

Системные события​

Второй поток событий шире JetStream. Системное событие — сообщение сервера в темах $SYS.* о работе сервера и учётных записей: открытии и закрытии соединений, а также периодический сигнал активности сервера.

Прежде всего полезны события соединений. При каждом подключении клиента сервер публикует:

$SYS.ACCOUNT.ORDERS.CONNECT

При отключении публикуется соответствующее $SYS.ACCOUNT.ORDERS.DISCONNECT. Учётная запись входит в тему: $SYS.ACCOUNT.ORDERS.CONNECT позволяет наблюдать order-svc в ORDERS. Пользователь analytics-reader находится в ANALYTICS, поэтому его событие приходит в $SYS.ACCOUNT.ANALYTICS.CONNECT. Подписка на $SYS.ACCOUNT.*.CONNECT позволяет видеть подключения клиентов всех учётных записей без регулярного опроса /connz.

Кроме событий соединений, каждый сервер с фиксированным интервалом публикует сигнал STATSZ в $SYS.SERVER.<id>.STATSZ. Он содержит сводные показатели того же рода, что /varz, но сервер отправляет их сам. Так слушатель регулярно получает данные каждого узла east.

Системные события публикуются в системной учётной записи, а не в учётной записи приложения. Для подписки на $SYS.* подключитесь как системный пользователь: это отдельные полномочия, отсутствующие у order-svc из ORDERS. Настройка разобрана в Безопасность → Авторизация. Все темы $SYS.* перечислены в Справочнике → Уведомления. Здесь нужны только события подключения и отключения.

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

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

Эти ошибки относятся к уведомлениям и системным событиям. Все они связаны с одним свойством: сообщения проходят мимо, тогда как конечные точки мониторинга возвращают текущее состояние.

Уведомления не сохраняются автоматически. Каждое публикуется ровно один раз при событии и не записывается ни в один поток. Если в этот момент нет подписки, вы не узнаете о событии. Команда nats subscribe '$JS.EVENT.ADVISORY.>' в терминале подходит для демонстрации, но после закрытия терминала все последующие уведомления теряются. Не полагайтесь на наблюдающего человека или разовую подписку: направляйте уведомления в постоянно подписанное долговременное хранилище.

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

#!/bin/bash
# Pitfall fix: advisories are transient, so capture them in a stream that
# is always listening. Create a dedicated stream that records every
# advisory the cluster publishes, so none is missed while no one watches.
nats stream add ADVISORIES \
--subjects '$JS.EVENT.ADVISORY.>' \
--storage file \
--retention limits \
--max-age 168h \
--defaults

# Now the max_deliver advisory for a poison order is durable. Read back
# every advisory the stream has recorded, oldest first:
nats stream view ADVISORIES

# Or replay only the consumer max-delivery events:
nats stream view ADVISORIES --subject \
'$JS.EVENT.ADVISORY.CONSUMER.MAX_DELIVERIES.>'

Уведомление max_deliver — единственный встроенный сигнал прекращения доставки. У JetStream нет очереди недоставленных сообщений. Когда shipping исчерпывает попытки обработки проблемного заказа, доставка прекращается, а единственная запись об этом — уведомление. Подпишитесь на $JS.EVENT.ADVISORY.CONSUMER.MAX_DELIVERIES.> или сохраняйте его в потоке выше; иначе проблемные заказы пропадут из обработки незаметно. Действия с таким заказом, например перенаправление в отдельную тему, описаны в JetStream → Подтверждения.

Уведомление о выборе лидера сообщает смену, а не причину. Повторяющиеся уведомления для ORDERS указывают на нестабильность кластера, за которой стоит следить, но не объясняют её. Вопросы времени выборов, кворума и состояния участников рассматриваются в Кластеризация → RAFT и лидеры. Не пытайтесь диагностировать выборы по одному телу уведомления.

Что уже готово​

Теперь у вас есть ещё один способ наблюдения за ORDERS, не зависящий от опросов. Вы умеете:

  • Подписываться на $JS.EVENT.ADVISORY.> и получать max_deliver в момент исчерпания попыток доставки проблемного заказа потребителю shipping.
  • Читать тело уведомления (stream, consumer, stream_seq, deliveries), определяя заказ и число попыток.
  • Подписываться на $SYS.ACCOUNT.ORDERS.CONNECT и DISCONNECT, наблюдая подключения и отключения, а также читать STATSZ каждого узла.
  • Сохранять уведомления в долговременном потоке, чтобы не пропускать мимолётные события.

Вы прочитали состояние через порт мониторинга, вычислили отставание по состоянию потребителя и получили события, которых не запрашивали. Следующая страница превращает всё это в историю, графики и пороговые проверки.

Что дальше​

Следующая страница собирает рабочую цепочку: экспортёр опрашивает :8222, Prometheus сохраняет временные ряды, Grafana строит графики, а nats server check срабатывает при превышении порога отставания.

Перейдите к Prometheus и панелям.

См. также​