Наблюдение
С предыдущей страницы у вас есть бакет INVENTORY, где widget-blue равен 42. Get показывает остаток сейчас. Складской панели нужно узнавать его в момент изменения, без циклического опроса.
Для этого служит наблюдение. Здесь складская панель начнёт наблюдать за INVENTORY; вы увидите две части данных, всегда приходящие по порядку, а затем ограничите наблюдение подмножеством ключей с помощью фильтра.
Что передаёт наблюдение
Наблюдение сначала передаёт текущее значение каждого подходящего ключа как начальный снимок, затем все последующие изменения по мере возникновения. Один вызов даёт обе части: состояние бакета сейчас и изменения с этого момента.
Запустите складскую панель для наблюдения за всем бакетом. Выполните команду в отдельном терминале и оставьте её работающей:
- CLI
- C
#!/bin/bash
# Watch the whole INVENTORY bucket. This is the warehouse dashboard:
# it wants every stock change as it happens, with no polling.
#
# On start, watch first replays the current value of every key in the
# bucket as an initial snapshot, then blocks and streams live changes
# until you stop it (Ctrl-C). Run this in its own terminal.
nats kv watch INVENTORY
# Expected output: one line per existing key (the snapshot), e.g.
#
# [2026-05-22 10:14:22] PUT INVENTORY > widget-blue: 42
#
# then it waits. Leave it running and put a new count from another
# terminal:
#
# nats kv put INVENTORY widget-blue 41
#
# The watch prints the live update the moment it lands:
#
# [2026-05-22 10:15:03] PUT INVENTORY > widget-blue: 41
// Watch the whole INVENTORY bucket. The watch first delivers the
// current value of every key (the snapshot), then streams every
// later change as it lands.
kvEntry *e = NULL;
s = kvStore_WatchAll(&w, kv, NULL);
while (s == NATS_OK)
{
s = kvWatcher_Next(&e, w, 60000);
if (s != NATS_OK)
break;
// A NULL entry marks the end of the snapshot. Skip it and
// keep reading: everything after it is a live change.
if (e == NULL)
continue;
printf("%s: %.*s\n", kvEntry_Key(e),
kvEntry_ValueLen(e), (const char*) kvEntry_Value(e));
kvEntry_Destroy(e);
e = NULL;
}
Сначала приходит снимок. Наблюдатель сразу выводит текущее значение каждого существующего ключа; пока это одна строка с widget-blue и 42. Затем блокируется в ожидании.
Теперь измените количество в другом терминале:
nats kv put INVENTORY widget-blue 41
Строка появляется в терминале наблюдения сразу после put, без опроса и задержки. Панель получает изменение, как только сервис inventory записывает его.
Сервис inventory также добавляет ещё два артикула, поэтому дальше в бакете будет несколько ключей:
nats kv put INVENTORY widget-red 17
nats kv put INVENTORY gadget-pro 5
Каждый put появляется в терминале наблюдения сразу после записи, как и изменение widget-blue.
Порядок «снимок, затем текущие изменения» важен. Новая панель, подключившаяся в середине дня, не остаётся без данных: сначала получает полную текущую картину, затем отслеживает изменения. Наблюдение совмещает чтение состояния и получение обновлений, поэтому выбирать между ними не нужно.
В основе наблюдения — временный упорядоченный потребитель базового потока, воспроизводящий последнее значение каждого ключа и затем новые записи. Настраивать и обслуживать его не нужно: открытие наблюдения создаёт потребителя, закрытие удаляет. Позиции и доставка потребителей рассматриваются в главе JetStream; для изучения нижнего слоя см. Зачем нужен поток. Здесь важно поведение: снимок, затем текущие изменения.
Сигнал завершения начальных данных
Между снимком и текущими обновлениями есть граница, которую наблюдатель обозначает явно. После последней записи снимка и до первого текущего изменения приходит один сигнал завершения начальных данных: запись nil без ключа и значения. Она сообщает лишь, что снимок завершён и далее идут текущие изменения.
CLI молча обрабатывает сигнал и продолжает вывод, поэтому в терминале он не виден. В клиентском коде граница обрабатывается явно, но способ зависит от библиотеки. Go и Python передают nil/None в том же потоке, что и обычные записи: распознайте границу и продолжайте чтение. JavaScript устанавливает флаг isUpdate у записей, Java вызывает endOfData(), C# принимает параметр OnNoData, а в Rust маркера нет: при открытии выбирается снимок с обновлениями либо только обновления. Идея везде одна — граница между снимком и изменениями; различается сигнал. Ниже показан вариант с записью nil:
- CLI
- C
#!/bin/bash
# The end-of-initial-data signal in practice.
#
# A client watch delivers the snapshot, then ONE nil entry to mark the
# snapshot/live boundary, then live updates. A program that reads the
# watch must consume that nil entry and keep going, not treat it as the
# end of the stream. The CLI consumes it for you and keeps printing;
# the comment below shows what a client loop must do.
#
# Run the watch and confirm it does not stop after the snapshot:
nats kv watch INVENTORY
# The CLI prints the snapshot, silently steps over the nil end-of-initial
# -data entry, and keeps waiting for live changes. In client code the
# equivalent loop is:
#
# for entry in watcher:
# if entry is None: # end-of-initial-data marker
# continue # snapshot done; keep reading live updates
# handle(entry.key, entry.value, entry.revision)
#
# Stopping the loop on the nil entry would miss every live change. Keep
# reading.
// Watch the whole bucket: the snapshot comes first, then live
// changes.
s = kvStore_Watch(&w, kv, ">", NULL);
while (s == NATS_OK)
{
kvEntry *e = NULL;
s = kvWatcher_Next(&e, w, 5000);
if (s != NATS_OK)
break;
// A NULL entry is the end-of-initial-data signal: the snapshot
// is complete and everything after it is a live change. Consume
// it and keep reading — breaking here would miss every live
// update, which is the reason to watch.
if (e == NULL)
{
printf("snapshot complete, now live\n");
continue;
}
printf("%s @ rev %" PRIu64 ": %s\n",
kvEntry_Key(e), kvEntry_Revision(e), kvEntry_ValueString(e));
kvEntry_Destroy(e);
}
Сигнал полезен не только для учёта. Панель может показывать загрузку до nil, затем переходить в режим текущих данных, зная, что получила полную картину. Прогрев кэша может заполнить его из снимка, считать nil признаком готовности и перейти к приращениям. Граница несёт информацию для действий.
С ней связана и самая частая ошибка наблюдения; ниже, в разделе подводных камней, приведён исполняемый пример.
Наблюдение за подмножеством
Наблюдение за всем бакетом передаёт каждый ключ, но часто требуется меньше. Необязательный фильтр ключей сопоставляется так же, как тема NATS: ключ состоит из токенов, разделённых точками; * соответствует ровно одному полному токену, а > — одному или нескольким токенам в конце. Ключи отображаются на токены тем: это модель тем, на которой построен базовый поток.
Здесь артикулы состоят из одного токена: widget-blue — один токен, а дефис — обычный символ. Поэтому widget-* вообще не является подстановкой и ничего не находит: * имеет особое значение лишь как целый токен. Для такого разделения ключи нужно проектировать с точками, например widget.blue и widget.red, чтобы widget.* подходил обоим.
Для плоских имён артикулов ограничьте наблюдение точным ключом. Панель синего товара наблюдает только за widget-blue:
- CLI
- C
#!/bin/bash
# Watch a subset of the bucket, not every key.
#
# A watch filter is matched against the key the same way a subject is:
# '*' stands for exactly one whole token and '>' for the rest. The SKU
# keys here are single tokens (widget-blue is one token; the hyphen is an
# ordinary character), so a prefix like 'widget-*' is NOT a wildcard and
# matches nothing. To watch a subset of flat keys, name an exact key:
nats kv watch INVENTORY widget-blue
# Expected: the snapshot shows only widget-blue at its current value, then
# it waits. A later put to gadget-pro or widget-red never reaches this
# watcher; a put to widget-blue does:
#
# [2026-05-22 10:16:40] PUT INVENTORY > widget-blue: 41
// Watch a subset of the bucket. The filter is matched like a
// subject: '*' stands for a whole dot-separated token, so
// "widget-*" is not a wildcard and matches nothing. With flat
// SKU keys, name an exact key instead.
kvEntry *e = NULL;
s = kvStore_Watch(&w, kv, "widget-blue", NULL);
while (s == NATS_OK)
{
s = kvWatcher_Next(&e, w, 60000);
if (s != NATS_OK)
break;
// NULL marks the end of the snapshot; keep reading.
if (e == NULL)
continue;
// Only widget-blue arrives here: the filter applies to both
// the snapshot and the live changes.
printf("%s: %.*s\n", kvEntry_Key(e),
kvEntry_ValueLen(e), (const char*) kvEntry_Value(e));
kvEntry_Destroy(e);
e = NULL;
}
Снимок теперь содержит лишь widget-blue, а текущие обновления относятся только к нему. Put для gadget-pro или widget-red не приходит наблюдателю, put для widget-blue приходит. Фильтр действует на обе части, поэтому отфильтрованное наблюдение — меньший и более дешёвый вид бакета, а не получение всех изменений с последующей фильтрацией.
Есть и другие параметры тех же двух частей: IncludeHistory воспроизводит полную историю каждого ключа вместо текущего снимка, IgnoreDeletes пропускает удалённые ключи, UpdatesOnly отключает снимок и оставляет текущие изменения, MetaOnly передаёт метаданные без значения. Их можно сочетать, кроме IncludeHistory и UpdatesOnly: первый запрашивает снимок с историей, второй вообще исключает снимок, поэтому клиент отклоняет пару. Эти клиентские параметры задают настройки создаваемого временного потребителя; их описание находится в разделе Справочник → Создание потребителя.
Подводные камни
При первом наблюдении за бакетом распространены две ошибки. Обе связаны с описанными понятиями: границей снимка и обновлений и природой самого наблюдения.
Не прекращайте чтение на сигнале границы. В Go и Python запись nil/None приходит в том же потоке, что и данные. Цикл, считающий nil концом потока и завершающийся, прочитает снимок и маркер, но пропустит все текущие изменения, ради которых и создавался наблюдатель. Исправление простое: пропускайте nil и продолжайте цикл, не выходите из него. В клиентах с флагом или обратным вызовом та же ошибка — считать конец снимка концом наблюдения.
Пример обработки выше одновременно служит демонстрацией: цикл проходит запись nil и продолжает работу.
- CLI
- C
#!/bin/bash
# The end-of-initial-data signal in practice.
#
# A client watch delivers the snapshot, then ONE nil entry to mark the
# snapshot/live boundary, then live updates. A program that reads the
# watch must consume that nil entry and keep going, not treat it as the
# end of the stream. The CLI consumes it for you and keeps printing;
# the comment below shows what a client loop must do.
#
# Run the watch and confirm it does not stop after the snapshot:
nats kv watch INVENTORY
# The CLI prints the snapshot, silently steps over the nil end-of-initial
# -data entry, and keeps waiting for live changes. In client code the
# equivalent loop is:
#
# for entry in watcher:
# if entry is None: # end-of-initial-data marker
# continue # snapshot done; keep reading live updates
# handle(entry.key, entry.value, entry.revision)
#
# Stopping the loop on the nil entry would miss every live change. Keep
# reading.
// Watch the whole bucket: the snapshot comes first, then live
// changes.
s = kvStore_Watch(&w, kv, ">", NULL);
while (s == NATS_OK)
{
kvEntry *e = NULL;
s = kvWatcher_Next(&e, w, 5000);
if (s != NATS_OK)
break;
// A NULL entry is the end-of-initial-data signal: the snapshot
// is complete and everything after it is a live change. Consume
// it and keep reading — breaking here would miss every live
// update, which is the reason to watch.
if (e == NULL)
{
printf("snapshot complete, now live\n");
continue;
}
printf("%s @ rev %" PRIu64 ": %s\n",
kvEntry_Key(e), kvEntry_Revision(e), kvEntry_ValueString(e));
kvEntry_Destroy(e);
}
Наблюдение — живое состояние, а не точечное чтение. Это временный упорядоченный потребитель: он существует, пока процесс держит его открытым, и исчезает при завершении процесса. Он нужен, чтобы следить за бакетом, но не для однократного получения текущего значения. Для этого используйте get с предыдущей страницы или history со следующей. Не имитируйте чтение открытием наблюдения, получением первой записи и закрытием: ради одного значения вы оплачиваете создание потребителя и снимка, хотя get вернул бы его напрямую.
Текущее состояние
Теперь у вас есть:
- Бакет
INVENTORYсо значениемwidget-blue, равным41после демонстрации put, а также добавленнымиwidget-redиgadget-pro. - Работающая складская панель: наблюдатель получил снимок, затем текущее обновление.
- Понимание сигнала завершения начальных данных: он обозначает границу снимка и обновлений, его нужно обработать, не считая концом.
- Наблюдение за одним ключом (
widget-blue) и правило:*фильтра соответствует целому токену, а не префиксу.
Что дальше
Следующая страница читает историю, создаваемую каждым put, и использует ревизии для безопасных одновременных обновлений: История и ревизии.
См. также
- Зачем нужен поток — модель потребителей, на которой построено наблюдение.
- Справочник → Создание потребителя — конфигурация потребителя, соответствующая параметрам наблюдения.