Обнаружение
Ваш сервис 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 описать себя на уровне имени и прочитайте список конечных точек из ответа:
- CLI
- C
#!/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
// Ask every running instance of OrderInventory to describe itself.
// INFO is a discovery verb the framework answers automatically; the
// name level ($SRV.INFO.OrderInventory) reaches every instance, and
// each one replies with its name, id, version, and endpoint list.
//
// Discovery is broadcast: a plain request would return only the first
// reply. Subscribe to a private inbox, send the request there, and
// collect replies until none arrives within the deadline.
int instances = 0;
if (s == NATS_OK)
s = natsInbox_Create(&inbox);
if (s == NATS_OK)
s = natsConnection_SubscribeSync(&sub, conn, (const char *) inbox);
if (s == NATS_OK)
s = natsConnection_PublishRequestString(conn, "$SRV.INFO.OrderInventory",
(const char *) inbox, "");
while (s == NATS_OK)
{
natsMsg *info = NULL;
// Stop once no further instance replies within the deadline.
s = natsSubscription_NextMsg(&info, sub, 1000);
if (s != NATS_OK)
break;
// Each reply is an info_response JSON document; its "endpoints"
// array lists each endpoint's subject and queue group.
printf("info: %.*s\n",
natsMsg_GetDataLength(info), natsMsg_GetData(info));
instances++;
natsMsg_Destroy(info);
}
printf("collected %d instance(s)\n", instances);
Ответ сообщает, что конечная точка 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, можно обратиться только к этому экземпляру. Так можно изучать или сравнивать отдельную копию сервиса среди множества работающих.
Третий уровень достигает ровно одного экземпляра, поэтому ожидается один ответ и цикл сбора с ограничением по времени не нужен:
- CLI
- C
#!/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
// The third discovery level adds the service id, addressing exactly
// one instance instead of all of them. Pick an id from an earlier
// INFO or PING reply; replace the one below with your own.
const char *instanceID = "JJTBR2MN3JSAYBI5ST7E32";
natsMsg *reply = NULL;
char subject[256];
// $SRV.STATS.OrderInventory.<id> reaches only the instance with that
// id, so a single reply is expected -- no deadline loop needed.
snprintf(subject, sizeof(subject),
"$SRV.STATS.OrderInventory.%s", instanceID);
if (s == NATS_OK)
s = natsConnection_RequestString(&reply, conn, subject, "", 1000);
if (s == NATS_OK)
{
printf("stats: %.*s\n",
natsMsg_GetDataLength(reply), natsMsg_GetData(reply));
natsMsg_Destroy(reply);
reply = NULL;
}
// PING at the instance level is the lightweight check: it confirms
// that one specific instance is alive and reports its name, id, and
// version.
snprintf(subject, sizeof(subject),
"$SRV.PING.OrderInventory.%s", instanceID);
if (s == NATS_OK)
s = natsConnection_RequestString(&reply, conn, subject, "", 1000);
if (s == NATS_OK)
{
printf("ping: %.*s\n",
natsMsg_GetDataLength(reply), natsMsg_GetData(reply));
natsMsg_Destroy(reply);
}
Сбор ответов через 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:
- CLI
- C
#!/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
// Ask every running instance of OrderInventory to describe itself.
// INFO is a discovery verb the framework answers automatically; the
// name level ($SRV.INFO.OrderInventory) reaches every instance, and
// each one replies with its name, id, version, and endpoint list.
//
// Discovery is broadcast: a plain request would return only the first
// reply. Subscribe to a private inbox, send the request there, and
// collect replies until none arrives within the deadline.
int instances = 0;
if (s == NATS_OK)
s = natsInbox_Create(&inbox);
if (s == NATS_OK)
s = natsConnection_SubscribeSync(&sub, conn, (const char *) inbox);
if (s == NATS_OK)
s = natsConnection_PublishRequestString(conn, "$SRV.INFO.OrderInventory",
(const char *) inbox, "");
while (s == NATS_OK)
{
natsMsg *info = NULL;
// Stop once no further instance replies within the deadline.
s = natsSubscription_NextMsg(&info, sub, 1000);
if (s != NATS_OK)
break;
// Each reply is an info_response JSON document; its "endpoints"
// array lists each endpoint's subject and queue group.
printf("info: %.*s\n",
natsMsg_GetDataLength(info), natsMsg_GetData(info));
instances++;
natsMsg_Destroy(info);
}
printf("collected %d instance(s)\n", instances);
Верно и обратное: если нужен определённый экземпляр, используйте уровень $SRV.STATS.OrderInventory.<id> вместо фильтрации широковещательных ответов. Он обращается к экземпляру напрямую и возвращает один ответ.
$SRV — зарезервированный префикс субъектов: не публикуйте туда собственные сообщения. Всё дерево $SRV принадлежит фреймворку: сервисы подписываются там для ответов PING, INFO и STATS. Ваши публикации под $SRV мешают этому механизму и искажают результаты обнаружения. Используйте собственные префиксы (orders.*, shipping.*) и оставьте $SRV фреймворку. Кто может видеть $SRV через границы аккаунтов — отдельный вопрос из главы Безопасность.
Текущее состояние
Теперь систему можно обнаруживать, а не запоминать. Команды PING, INFO и STATS под $SRV позволяют перечислить все сервисы аккаунта, узнать конечные точки сервиса и обратиться к одному экземпляру по идентификатору. Вы также знаете ограничение: обнаружение широковещательное, поэтому нужно собирать ответы до заданного срока, а не брать первый.
OrderInventory и ShippingQuote продолжают работать. Сами они не изменились; вы лишь научились спрашивать их о себе.
Что дальше
INFO сообщает, на что отвечает сервис. STATS показывает, как он работает: число запросов, число ошибок и время обработки каждой конечной точки. На следующей странице прочитаем эти счётчики и посмотрим, как обработчик регистрирует ошибку.
Переходите к странице Наблюдаемость.
См. также
- Запросы и ответы — механизм доставки каждого ответа
$SRV. - Наблюдаемость — сведения STATS и их чтение.
- Справочник — сетевой формат
$SRVи схемы ответов.