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

Отладка доставки

Вы публикуете orders.created, но упаковщик не упаковывает заказ. Публикация вернулась без ошибки, сообщение покинуло клиента, однако ничего не пришло. В Core NATS у этого три причины:

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

Обычная публикация не даёт обратной связи для различения случаев. Это отправка без ожидания: издатель не видит число получателей и само наличие доставки. Запрос хотя бы сообщает об отсутствии подписчиков через no responders, а односторонняя публикация молчит. Здесь описаны три инструмента, показывающих происходящее для разных причин.

Просмотр сообщений через перехват трафика​

Быстрее всего проверить отправку и точную тему непосредственным наблюдением трафика. Подпишитесь на многосегментный символ >: сервер пришлёт копию каждой публикации вашей учётной записи. Такая подписка > для наблюдения, а не бизнес-логики, называется перехватом трафика (wire tap).

#!/bin/bash

# Wire tap: subscribe to the multi-token wildcard > and the server sends you
# a copy of every message published in your account, on its exact subject.
# This is the fastest way to answer "did my message go out at all, and on
# which subject?" -- the subject printed is the literal one the publisher
# used, so a stray token or a typo shows up the moment you publish.
#
# nats sub prints one line per message: [#N] Received on "<subject>", then the
# payload. Request-reply traffic shows the reply inbox too, as
# [#N] Received on "<subject>" with reply "_INBOX...".
nats sub ">"

# On a busy account, a > tap receives every message in it. Narrow the tap to
# the subject family you're investigating so you receive only what matters --
# here, everything under orders at any depth, and nothing else.
nats sub "orders.>"

Каждая строка показывает точную тему публикации:

12:30:25 Subscribing on >
[#1] Received on "orders.us.created"
{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}

Если ожидалось orders.created, а виден orders.us.created, проблема в теме, а не интересе. Так находятся лишний сегмент и пробел, незаметно меняющий маршрутизацию. Если при публикации ничего не видно, сообщение не покинуло издателя.

Перехват показывает и запросы с ответами, включая создаваемые клиентом темы inbox: _INBOX — обычная тема протокола. Уже строки тем показывают полный обмен:

[#2] Received on "orders.inventory.check" with reply "_INBOX.9tQ3pZ.aQ1"
[#3] Received on "_INBOX.9tQ3pZ.aQ1"

Сообщение №2 — запрос с темой ответа; №3 — ответ в этот inbox. Наличие обоих подтверждает полный обмен.

В активной учётной записи > создаёт большой трафик. Не успевающий подписчик отключается как медленный потребитель. Ограничьте наблюдение нужным семейством, например orders.>, чтобы видеть только важные темы.

Список подписок на сервере​

Если сообщение ушло в правильную тему, но не пришло, проверьте интерес. Сервер хранит подписки в графе интереса в памяти; нужно прочитать его.

На локальном сервере используйте обычный HTTP-порт мониторинга. Запустите сервер с nats-server -m 8222; /subsz перечисляет текущие подписки.

#!/bin/bash

# See where interest actually lives, over the plain-HTTP monitoring port.
# This needs the server started with a monitoring port: nats-server -m 8222

# /subsz lists the subscriptions the server holds right now. subs=1 adds the
# per-subscription detail (account, subject, cid) on top of the summary counts.
# acc=$G scopes the counts to your own account; without it num_subscriptions
# spans every account, including the system account. Even scoped, a few
# $SYS.REQ.* service subscriptions the server keeps in every account show up.
curl -s 'http://localhost:8222/subsz?subs=1&acc=$G' | jq

# The test parameter answers "who would receive a publish to THIS subject?"
# It returns only the subscriptions whose subject would match a message
# published to orders.us.created -- wildcard subscriptions (orders.>,
# orders.*.created) included. An empty subscriptions_list means nobody is
# subscribed, so a message published now would be dropped.
curl -s 'http://localhost:8222/subsz?subs=1&acc=$G&test=orders.us.created' | jq

# /connz shows the connections behind those subscriptions, so you can tell a
# missing subscription from a subscriber whose connection was cut. The
# Monitoring chapter documents its full parameter set.
curl -s 'http://localhost:8222/connz?subs=true' | jq

subs=1 добавляет subscriptions_list: для каждой подписки указаны учётная запись, тема и идентификатор соединения (cid). acc=$G ограничивает счётчики вашей учётной записью; без него num_subscriptions охватывает все, включая системную. Даже с ограничением список содержит служебные подписки $SYS.REQ.*, которые сервер держит в каждой учётной записи. Параметр test прямо отвечает на вопрос доставки: задайте точную тему публикации, и /subsz вернёт только подходящие подписки, включая шаблоны.

{
"num_subscriptions": 6,
"total": 1,
"offset": 0,
"limit": 1024,
"subscriptions_list": [
{ "account": "$G", "subject": "orders.>", "sid": "5", "msgs": 0, "cid": 8 }
]
}

Здесь num_subscriptions показывает шесть подписок учётной записи $G, а total — одну подходящую для orders.us.created: аудит orders.> на соединении 8. Пустой subscriptions_list означает отсутствие подписчиков; публикация в этот момент будет отброшена. Для сохранения заказа до готовности подписчика нужен поток, добавляемый JetStream поверх тех же тем.

Чтобы отличить отсутствующую подписку от разорванного соединения, посмотрите соединения. /connz перечисляет их, а ?subs=true добавляет подписки каждого; подробно — на странице точек мониторинга. Если считающий себя подключённым подписчик отсутствует в /connz, соединение потеряно, а интерес удалён.

CLI nats читает то же состояние через NATS командами nats server request subscriptions и nats server request connections. Обе используют запросы системной учётной записи $SYS. В обычном nats-server есть учётная запись $SYS, но нет её пользователя, а системные темы отвечают лишь подключённым к $SYS клиентам. Поэтому на локальном сервере nats server request subscriptions выдаёт server request failed, ensure the account used has system privileges and appropriate permissions. nats server request connections отвечает, но показывает только соединения вашей учётной записи. Полный обзор сервера доступен с учётными данными системной учётной записи, как в промышленных и кластерных развёртываниях.

Трассировка пути одного сообщения​

Перехват показывает темы, список подписок — интерес. Трассировка сообщений показывает оба аспекта для одной темы: всех подходящих подписчиков и переходы на пути к ним. Запустите nats trace с темой.

#!/bin/bash

# Trace the path of one message to a subject. Requires NATS Server 2.11 or
# newer. nats trace publishes a special traced message and prints every hop it
# takes and every subscriber it matches, including why it matched.
#
# Without --deliver the traced message is NOT handed to matching subscribers:
# the trace reports who WOULD receive it without actually delivering it. It's a
# probe, not a real publish, so it never triggers your subscribers' side effects.
nats trace orders.us.created

# Add --deliver to also deliver the traced message to matching subscribers,
# turning the probe into a real publish that they receive.
nats trace orders.us.created --deliver

nats trace требует сервер NATS 2.11 или новее. Команда публикует специальное трассируемое сообщение и выводит рассчитанный сервером маршрут. Если подписчиков нет, трассировка сообщает об этом:

Tracing message route to subject orders.us.created

Client "NATS CLI Version development" cid:16 server:"n1" version:"2.11.6"
--X No active interest

Legend: Client: --C Router: --> Gateway: ==> Leafnode: ~~> JetStream: --J Error: --X

При совпадении подписки строка --C указывает получателя и заканчивается совпавшей темой, например subject:"orders.>". На каждого подходящего подписчика выводится одна --C, поэтому виден точный набор получателей настоящей публикации.

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

Выбор инструмента по симптому​

Начните с наблюдаемого симптома и выберите средство проверки.

СимптомИнструмент
Неясно, покинуло ли сообщение клиента или какая тема использованаПерехват: nats sub ">", затем публикация и наблюдение
Сообщение уходит, но ожидаемый подписчик ничего не получаетСписок подписок: /subsz?subs=1&acc=$G&test=<subject> для проверки совпадений
Подписчик уверен в подписке, но ничего не получаетСоединения: /connz?subs=true для проверки открытого соединения
Нужен точный список возможных получателей публикацииТрассировка: nats trace <subject>

Если test= и nats trace сейчас показывают подписчика, а сообщение не пришло, в момент публикации его не было. Это временное различие — доставка не более одного раза: Core NATS доставляет лишь подключённым в момент публикации и не повторяет попыток.

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

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

Трассировка проверяет собственное сообщение, а не прошлую публикацию. nats trace отправляет новое сообщение и показывает его маршрут. Она ничего не доказывает о более раннем сообщении, а без --deliver вообще не достигает подписчиков. Читайте результат как ответ на вопрос «что было бы сейчас», а не «что произошло раньше».

Порт мониторинга по умолчанию без аутентификации. Любой имеющий доступ к :8222 может прочитать темы и соединения через /subsz и /connz. На ноутбуке это допустимо, но не открывайте порт в общей или публичной сети. Защита описана в разделе Безопасность; учитывайте её, чтобы не оставить порт открытым.

Что уже сделано​

Для каждой причины недоставки заказа Acme теперь есть инструмент:

  • Перехват (nats sub ">") показывает факт отправки и тему.
  • Список подписок (/subsz с test= для точной темы) показывает подходящий интерес, а /connz — наличие соединения подписчика.
  • Трассировка (nats trace) показывает точный список возможных получателей без доставки, если её явно не запросить.

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

Что дальше​

Вы завершили знакомство с шаблонами Core NATS и их отладкой. Страница Куда двигаться дальше собирает модель воедино и направляет к следующим главам, начиная со слоя хранения сообщений, отбрасываемых Core NATS.

См. также​