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

Обнаружение

Ваш сервис OrderInventory отвечает на orders.inventory.check, а ShippingQuote — на shipping.quote. Для вызова приходилось заранее знать эти субъекты. Здесь это требование снимается.

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

Для этого не нужно добавлять код. Как только AddService вернулся на странице your-first-service, фреймворк подписался на эти субъекты за вас. Здесь показано, как ими пользоваться.

Три команды обнаружения​

Обнаружение — получение сведений о существующих сервисах и обслуживаемых ими запросах через фиксированный набор субъектов с префиксом $SRV. Каждый сервис отвечает на три команды:

  • PING проверяет наличие сервиса. Ответ содержит имя сервиса, идентификатор экземпляра и версию. Используется для поиска сервисов и измерения времени кругового обхода.
  • INFO сообщает, на что отвечает сервис. Ответ добавляет описание и список конечных точек с субъектами и группами очередей.
  • STATS сообщает, как работает сервис. Ответ добавляет счётчики по конечным точкам. Их прочитаем на следующей странице; пока достаточно знать о команде.

Команды и их субъекты записываются прописными буквами. Сам сервис не публикует в $SRV: он подписывается там и отвечает на ваши запросы с помощью знакомого механизма запросов и ответов.

Три уровня адресации​

Каждая команда работает на трёх уровнях, сужая область от всех сервисов до одного экземпляра:

СубъектКто отвечает
$SRV.INFOВсе сервисы аккаунта
$SRV.INFO.OrderInventoryВсе экземпляры с именем OrderInventory
$SRV.INFO.OrderInventory.<id>Один экземпляр с этим идентификатором

Те же уровни работают для PING и STATS. Первый позволяет перечислить содержимое незнакомой системы. Второй ограничивает запрос одним именем сервиса. Третий обращается к одному экземпляру — работающей копии сервиса с идентификатором, сгенерированным фреймворком.

Попросите OrderInventory описать себя на уровне имени и прочитайте список конечных точек из ответа:

#!/bin/bash
# Ask the OrderInventory service to describe itself. INFO is a discovery
# verb every service answers automatically on the $SRV subject tree. The
# name level ($SRV.INFO.OrderInventory) reaches every running instance of
# OrderInventory, and each one replies with its name, id, version, and the
# list of endpoints it serves.
#
# Discovery is broadcast: a plain request would return only the first
# reply, so the CLI waits a short window and collects every responder.
# That is why the timeout matters here.
nats request '$SRV.INFO.OrderInventory' '' --replies=0 --timeout=1s

# The reply for each instance is JSON like:
#
# {
# "type": "io.nats.micro.v1.info_response",
# "name": "OrderInventory",
# "id": "JJTBR2MN3JSAYBI5ST7E32",
# "version": "1.0.0",
# "endpoints": [
# { "name": "check",
# "subject": "orders.inventory.check",
# "queue_group": "q" }
# ]
# }
#
# Read the endpoints array to learn what the service answers and on which
# subject -- no documentation lookup required.
#
# The same information, formatted, comes from the CLI ops shortcut:
nats service info OrderInventory

Ответ сообщает, что конечная точка check слушает orders.inventory.check в группе очереди "q". Раньше вы настроили это вручную, а теперь любой клиент может получить сведения от работающего сервиса, не полагаясь на документацию.

Сетевой формат $SRV.PING/INFO/STATS и схемы ответов JSON описаны в справочнике. Здесь нам нужно только поведение.

Обнаружение использует широковещательные запросы без балансировки​

Одна деталь работает иначе, чем можно ожидать. Созданные конечные точки отвечают в группе очереди, поэтому каждый запрос получает ровно один экземпляр. Команды обнаружения не используют такую группу. Запрос $SRV.INFO.OrderInventory достигает каждого экземпляра OrderInventory, и каждый отвечает.

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

Анимация показывает, как один запрос $SRV.INFO.OrderInventory расходится ко всем трём экземплярам и возвращаются три ответа INFO. Последний адресный запрос $SRV.STATS.OrderInventory.id2 достигает только id2: третий уровень адресации направляет запрос одному экземпляру.

Обращение к одному экземпляру​

Если идентификатор уже известен из ответа PING или INFO, можно обратиться только к этому экземпляру. Так можно изучать или сравнивать отдельную копию сервиса среди множества работающих.

Третий уровень достигает ровно одного экземпляра, поэтому ожидается один ответ и цикл сбора с ограничением по времени не нужен:

#!/bin/bash
# The third discovery level adds the service id, addressing exactly one
# instance instead of all of them. Use it when several instances of
# OrderInventory are running and you want to inspect one in particular.
#
# Pick an id from an earlier INFO or PING reply, then target it. Replace
# the id below with one your own service printed.
INSTANCE_ID="JJTBR2MN3JSAYBI5ST7E32"

# $SRV.STATS.OrderInventory.<id> reaches only the instance with that id,
# so a single reply is expected -- no deadline loop needed for one
# instance.
nats request "\$SRV.STATS.OrderInventory.$INSTANCE_ID" '' --timeout=1s

# PING at the instance level is the lightweight check: it confirms that
# one specific instance is alive and reports its name, id, and version.
nats request "\$SRV.PING.OrderInventory.$INSTANCE_ID" '' --timeout=1s

Сбор ответов через CLI​

Для интерактивной работы CLI nats выполняет цикл сбора широковещательных ответов за вас. nats service list перечисляет все найденные сервисы и экземпляры; nats service info выводит конечные точки сервиса; nats service ping измеряет время кругового обхода до каждого отвечающего экземпляра:

nats service list
nats service info OrderInventory
nats service ping

Внутри выполняются те же запросы $SRV, а ответы собираются до истечения времени ожидания. При разработке это самый быстрый способ увидеть запущенные сервисы; ваши собственные инструменты используют программные команды, показанные выше.

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

При первых запросах обнаружения распространены две ошибки. Обе связаны с широковещательным поведением.

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

#!/bin/bash
# Ask the OrderInventory service to describe itself. INFO is a discovery
# verb every service answers automatically on the $SRV subject tree. The
# name level ($SRV.INFO.OrderInventory) reaches every running instance of
# OrderInventory, and each one replies with its name, id, version, and the
# list of endpoints it serves.
#
# Discovery is broadcast: a plain request would return only the first
# reply, so the CLI waits a short window and collects every responder.
# That is why the timeout matters here.
nats request '$SRV.INFO.OrderInventory' '' --replies=0 --timeout=1s

# The reply for each instance is JSON like:
#
# {
# "type": "io.nats.micro.v1.info_response",
# "name": "OrderInventory",
# "id": "JJTBR2MN3JSAYBI5ST7E32",
# "version": "1.0.0",
# "endpoints": [
# { "name": "check",
# "subject": "orders.inventory.check",
# "queue_group": "q" }
# ]
# }
#
# Read the endpoints array to learn what the service answers and on which
# subject -- no documentation lookup required.
#
# The same information, formatted, comes from the CLI ops shortcut:
nats service info OrderInventory

Верно и обратное: если нужен определённый экземпляр, используйте уровень $SRV.STATS.OrderInventory.<id> вместо фильтрации широковещательных ответов. Он обращается к экземпляру напрямую и возвращает один ответ.

$SRV — зарезервированный префикс субъектов: не публикуйте туда собственные сообщения. Всё дерево $SRV принадлежит фреймворку: сервисы подписываются там для ответов PING, INFO и STATS. Ваши публикации под $SRV мешают этому механизму и искажают результаты обнаружения. Используйте собственные префиксы (orders.*, shipping.*) и оставьте $SRV фреймворку. Кто может видеть $SRV через границы аккаунтов — отдельный вопрос из главы Безопасность.

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

Теперь систему можно обнаруживать, а не запоминать. Команды PING, INFO и STATS под $SRV позволяют перечислить все сервисы аккаунта, узнать конечные точки сервиса и обратиться к одному экземпляру по идентификатору. Вы также знаете ограничение: обнаружение широковещательное, поэтому нужно собирать ответы до заданного срока, а не брать первый.

OrderInventory и ShippingQuote продолжают работать. Сами они не изменились; вы лишь научились спрашивать их о себе.

Что дальше​

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

Переходите к странице Наблюдаемость.

См. также​