Уведомления и события
Две предыдущие страницы читали состояние по запросу. Вы обращаетесь через 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.
Подпишитесь на всё дерево уведомлений, чтобы получать события системы:
- CLI
- C
#!/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
# }
// Subscribe to every JetStream advisory the cluster publishes.
// Advisories are transient: you only see events that fire while
// you are attached, so subscribe before the shipping consumer
// goes wrong.
s = natsConnection_SubscribeSync(&sub, conn, "$JS.EVENT.ADVISORY.>");
// When a poison order exhausts its deliveries on the shipping
// consumer, one max_deliver advisory lands on:
// $JS.EVENT.ADVISORY.CONSUMER.MAX_DELIVERIES.ORDERS.shipping
// Its JSON body names the stream, the consumer, the failed
// sequence, and how many times delivery was attempted.
while (s == NATS_OK)
{
natsMsg *msg = NULL;
s = natsSubscription_NextMsg(&msg, sub, 30000);
if (s == NATS_OK)
{
printf("[%s] %s\n", natsMsg_GetSubject(msg), natsMsg_GetData(msg));
natsMsg_Destroy(msg);
}
}
Когда проблемный заказ исчерпает лимит доставки, придёт одно сообщение. В теле указаны поток, потребитель, номер неудачного сообщения и число попыток доставки:
{
"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.>' в терминале подходит для демонстрации, но после закрытия терминала все последующие уведомления теряются. Не полагайтесь на наблюдающего человека или разовую подписку: направляйте уведомления в постоянно подписанное долговременное хранилище.
Решение — создать поток для тем уведомлений. Поток всегда подписан и сохраняет полученное, позволяя прочитать события значительно позже:
- CLI
- C
#!/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.>'
// Pitfall fix: advisories are transient, so capture them in a
// stream that is always listening. This stream records every
// advisory the cluster publishes and keeps a week of history.
jsStreamConfig cfg;
const char *subjects[] = {"$JS.EVENT.ADVISORY.>"};
jsStreamConfig_Init(&cfg);
cfg.Name = "ADVISORIES";
cfg.Subjects = subjects;
cfg.SubjectsLen = 1;
cfg.Storage = js_FileStorage;
cfg.Retention = js_LimitsPolicy;
cfg.MaxAge = 168LL * 60 * 60 * 1000000000LL; // 168h in ns
s = js_AddStream(&si, js, &cfg, NULL, &jerr);
// Now the max_deliver advisory for a poison order is durable.
// Read back every advisory the stream has recorded, oldest
// first, with an ephemeral no-ack consumer.
if (s == NATS_OK)
{
jsSubOptions so;
natsMsgList list = {NULL, 0};
jsSubOptions_Init(&so);
so.Stream = "ADVISORIES";
so.Config.AckPolicy = js_AckNone; // read-back only
s = js_PullSubscribe(&sub, js, "$JS.EVENT.ADVISORY.>", NULL,
NULL, &so, &jerr);
if (s == NATS_OK)
s = natsSubscription_Fetch(&list, sub, 100, 2000, &jerr);
if ((s == NATS_OK) || (s == NATS_TIMEOUT))
{
int i;
s = NATS_OK;
for (i = 0; i < list.Count; i++)
printf("[%s] %s\n",
natsMsg_GetSubject(list.Msgs[i]),
natsMsg_GetData(list.Msgs[i]));
natsMsgList_Destroy(&list);
}
}
Уведомление 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 и панелям.
См. также
- Справочник → уведомления JetStream — все темы уведомлений и их JSON-схемы.
- Справочник → системные события — все темы событий
$SYS.*и их JSON-схемы. - JetStream → Подтверждения — действия с сообщением, достигшим
max_deliver. - Кластеризация → RAFT и лидеры — выборы, о которых сообщает уведомление.