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

Наблюдение

С предыдущей страницы у вас есть бакет INVENTORY, где widget-blue равен 42. Get показывает остаток сейчас. Складской панели нужно узнавать его в момент изменения, без циклического опроса.

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

Что передаёт наблюдение​

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

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

#!/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

Сначала приходит снимок. Наблюдатель сразу выводит текущее значение каждого существующего ключа; пока это одна строка с 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:

#!/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.

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

С ней связана и самая частая ошибка наблюдения; ниже, в разделе подводных камней, приведён исполняемый пример.

Наблюдение за подмножеством​

Наблюдение за всем бакетом передаёт каждый ключ, но часто требуется меньше. Необязательный фильтр ключей сопоставляется так же, как тема NATS: ключ состоит из токенов, разделённых точками; * соответствует ровно одному полному токену, а > — одному или нескольким токенам в конце. Ключи отображаются на токены тем: это модель тем, на которой построен базовый поток.

Здесь артикулы состоят из одного токена: widget-blue — один токен, а дефис — обычный символ. Поэтому widget-* вообще не является подстановкой и ничего не находит: * имеет особое значение лишь как целый токен. Для такого разделения ключи нужно проектировать с точками, например widget.blue и widget.red, чтобы widget.* подходил обоим.

Для плоских имён артикулов ограничьте наблюдение точным ключом. Панель синего товара наблюдает только за widget-blue:

#!/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

Снимок теперь содержит лишь widget-blue, а текущие обновления относятся только к нему. Put для gadget-pro или widget-red не приходит наблюдателю, put для widget-blue приходит. Фильтр действует на обе части, поэтому отфильтрованное наблюдение — меньший и более дешёвый вид бакета, а не получение всех изменений с последующей фильтрацией.

Есть и другие параметры тех же двух частей: IncludeHistory воспроизводит полную историю каждого ключа вместо текущего снимка, IgnoreDeletes пропускает удалённые ключи, UpdatesOnly отключает снимок и оставляет текущие изменения, MetaOnly передаёт метаданные без значения. Их можно сочетать, кроме IncludeHistory и UpdatesOnly: первый запрашивает снимок с историей, второй вообще исключает снимок, поэтому клиент отклоняет пару. Эти клиентские параметры задают настройки создаваемого временного потребителя; их описание находится в разделе Справочник → Создание потребителя.

Подводные камни​

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

Не прекращайте чтение на сигнале границы. В Go и Python запись nil/None приходит в том же потоке, что и данные. Цикл, считающий nil концом потока и завершающийся, прочитает снимок и маркер, но пропустит все текущие изменения, ради которых и создавался наблюдатель. Исправление простое: пропускайте nil и продолжайте цикл, не выходите из него. В клиентах с флагом или обратным вызовом та же ошибка — считать конец снимка концом наблюдения.

Пример обработки выше одновременно служит демонстрацией: цикл проходит запись nil и продолжает работу.

#!/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.

Наблюдение — живое состояние, а не точечное чтение. Это временный упорядоченный потребитель: он существует, пока процесс держит его открытым, и исчезает при завершении процесса. Он нужен, чтобы следить за бакетом, но не для однократного получения текущего значения. Для этого используйте get с предыдущей страницы или history со следующей. Не имитируйте чтение открытием наблюдения, получением первой записи и закрытием: ради одного значения вы оплачиваете создание потребителя и снимка, хотя get вернул бы его напрямую.

Текущее состояние​

Теперь у вас есть:

  • Бакет INVENTORY со значением widget-blue, равным 41 после демонстрации put, а также добавленными widget-red и gadget-pro.
  • Работающая складская панель: наблюдатель получил снимок, затем текущее обновление.
  • Понимание сигнала завершения начальных данных: он обозначает границу снимка и обновлений, его нужно обработать, не считая концом.
  • Наблюдение за одним ключом (widget-blue) и правило: * фильтра соответствует целому токену, а не префиксу.

Что дальше​

Следующая страница читает историю, создаваемую каждым put, и использует ревизии для безопасных одновременных обновлений: История и ревизии.

См. также​