Отправка информации гнезда агенту

Если агент содержит одну или несколько групп атрибутов гнезда, то агент открывает гнездо и ожидает данные от клиентов.

Программа, отправляющая агенту данные гнезда, соединяется с портом, который задан в агенте. Порт - это либо значение, заданное свойством конфигурации агента, либо эфемерный порт, автоматически выделенный TCP/IP. Дополнительную информацию о портах и конфигурации гнезда смотрите в разделе Конфигурация гнезда.

Получаемые данные должны быть в формате структурированного XML. При использовании источника данных гнезда возможны следующие информационные потоки XML:

Отправка агенту одной или нескольких строк данных для группы атрибутов выборки
Отправка агенту строки данных для группы атрибутов, которая создает события
Отправка агенту кода ошибки вместо данных
Отправка агенту регистрации префикса операции
Получение от агента требования операции
Отправка агенту ответа операции

Отправка данных

Группа атрибутов конфигурируется для получения данных выборки или данных событий. При создании группы атрибутов вы задаете опцию, которая указывает режим работы группы при получении данных:

Создает одну строку данных
Создает несколько строк данных
Создает события

Если вы выбрали Создает одну строку данных или Может создавать несколько строк данных, то это группа атрибутов выборки. Если вы выбрали Создает события, то группа атрибутов отправляет в среду мониторинга событие при каждом получении строки.

При просмотре данных выборки в Tivoli Enterprise Portal или консоли IBM® Cloud Application Performance Management вы видите последний набор собранных строк. Данные, показанные для группы атрибутов событий - это содержимое локального кэша, который обслуживается агентом. Для данных событий агент добавляет в кэш новую запись, пока не будет достигнут размер, при котором самые старые записи удаляются. Для данных выборки агент заменяет содержимое кэша при каждой отправке данных.

Если вы выбрали Создает события или Создает одну строку данных, то нужно отправлять в каждом сообщении агенту для этой группы атрибутов только одну строку данных. Можно отправить сколько угодно событий, но каждое событие нужно отправлять в отдельном сообщении.

Обычно данные выборки собираются агентом по требованию, но клиент гнезда предоставляет обновленные выборки по своему расписанию. Группу атрибутов выборки можно изменять (одна строка или несколько строк) с любой частотой. Когда Tivoli Monitoring или консоль IBM Cloud Application Performance Management запрашивает данные, агент предоставляет новейшие данные.

Если в Tivoli Enterprise Portal или консоли IBM Cloud Application Performance Management пропущены строки данных для группы атрибутов Гнездо, то просмотрите ошибки в файле журнала. Кроме того, просмотрите ошибки в файле журнала, если данные в группе атрибутов отличаются от ожидаемых. Источник данных гнезда пытается обработать во входных данных все, что возможно. Например, если клиент отправляет три правильно сформированных строки и одну недопустимую (например, неправильно сформированный XML), то вы увидите следующее:

Три строки данных в группе атрибутов
Для неправильно сформированной строки в файл журнала агента записывается ошибка.
Пока возвращаются допустимые строки, для состояния объекта производительности будет указано NO_ERROR.

И в случае данных событий, и в случае данных выборки данные отправляются агенту как один поток данных XML от клиента гнезда. Данные, отправленные клиентом гнезда, всегда должны заканчиваться символом новой строки: '\n'. Агент читает данные, пока не встретит символ новой строки, а затем пытается обработать прочитанное. Все полученные данные, обработать которые невозможно, отбрасываются. Ниже приведен пример отправки агенту двух строк данных для группы атрибутов abc:

<socketData><attrGroup name="abc"><in><a v="1"/><a v="no"/><a v="5"/></in><in> \
<a v="3"/><a v="yes"/><a v="5"/></in></attrGroup></socketData>\n

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

Если группа атрибутов задана в подузле, то при отправке данных агенту нужно указать ID экземпляра подузла. ID экземпляра подузла указывается в атрибуте subnode элемента socketData. Следуйте правилам конфигурирования ID экземпляров подузлов для клиента гнезда, так как клиент не может запрашивать ID экземпляров или свойства конфигурации. Данные, отправленные в несконфигурированный подузел, игнорируются.

Ниже приведен пример:

<socketData subnode="app1"><attrGroup name="abc"><in><a v="1"/><a v="no"/><a v="5"/></in><in> \
<a v="3"/><a v="yes"/><a v="5"/></in></attrGroup></socketData>\n

В этом примере данные отправляются в подузел с ID экземпляра "app1". "app1" - это не имя управляемой системы, а идентификатор экземпляра, указанный при конфигурировании экземпляра подузла.

Показанные ниже элементы XML составляют данные гнезда:

socketData: Корневой элемент. Он содержит один дополнительный атрибут subnode, который задает ID экземпляра подузла.
attrGroup: Этот элемент задает группу атрибутов, для которой предназначены данные гнезда. Атрибут name обязательный, и он используется, чтобы задать имя группы атрибутов.
в: Этот элемент требуется, чтобы указать новую строку данных. Все значения атрибутов для строки данных должны быть потомками элемента in.
элемента: Элемент a задает значение атрибута. Атрибут v обязательный, и он используется, чтобы задать значение атрибута.

Отправка ошибок вместо данных

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

<socketData><attrGroup name="abc"/><error rc="1000"/></attrGroup></socketData>\n

Код ошибки должен быть задан в агенте в списке, общем для всех групп атрибутов гнезда. Если агент получает код ошибки, то заданное сообщение об ошибке записывается в файл журнала агента. Кроме того, в группе атрибутов Состояние объекта производительности есть атрибут Код ошибки, которому присваивается значение Тип кода ошибки. Тип кода ошибки задается для отправляемого кода ошибки.

В предыдущем примере нужно задать в агенте значение кода ошибки 1000. Ниже приведен пример определения кода ошибки.

Табл. 1. Пример кода ошибки
Значение кода ошибки	Тип кода ошибки	Сообщение
1000	APP_NOT_RUNNING	Программа не работает

При отправке кода ошибки в файл журнала агента будет записано примерно следующее сообщение:

(4D7FA153.0000-5:customproviderserver.cpp,1799,"processRC") От клиента получен код ошибки 1000. \ Сообщение: K1C0001E Программа не работает

Если вы выберете в Tivoli Enterprise Portal запрос Состояние объекта производительности, то в столбце Код ошибки для строки группы атрибутов abc будет показано APP_NOT_RUNNING.

Отправка ошибки в группу атрибутов выборки удаляет все данные, полученные ранее для этой группы атрибутов. Если в группу атрибутов отправлены данные, то код ошибки больше не будет показан в группе атрибутов Состояние объекта производительности. Чтобы убрать код ошибки из этой таблицы, можно также отправить код ошибки 0.

Отправка ошибки в группу атрибутов, которая создает события, не очищает кэш ранее отправленных событий.

Обработка требований выполнения действий

Клиент гнезда может зарегистрироваться для получения требований выполнения действий от агента, если команда действия соответствует определенному префиксу. Все не соответствующие действия обрабатываются агентом. Префикс не должен конфликтовать с действиями, которые выполняет агент, поэтому используйте в качестве префикса код продукта агента. Выполнения действий, предоставляемые Agent Builder, получают имена в соответствии с источником данных, который используется выполнением действия. Например, выполнение действия JMX_INVOKE работает с источником данных JMX. Другой пример - выполнение действия SSHEXEC, которое использует провайдер данных сценария SSH. Поскольку эти действия на используют код продукта, код продукта можно безопасно использовать как префикс выполнения действия.

Клиент гнезда должен быть долго выполняемым и должен оставлять гнездо открытым. Он должен отправлять требование регистрации для префикса и ожидать требования от гнезда. У агента не должно быть срока ожидания для гнезда долго выполняемого клиента, даже при отсутствии потока данных. Ниже приведен пример требования регистрации:

<taskPrefix value="K42"/>\n

В этом примере любая команда выполнения действия, которая получена агентом и начинается с "K42", перенаправляется клиенту гнезда, который инициировал регистрацию. Ниже приведен пример требования выполнения действия, которое может получить клиент гнезда:

<taskRequest id="1"><task command="K42 refresh" user="sysadmin"/></taskRequest>\n

id - это уникальный идентификатор, который агент использует для отслеживания требований, отправляемых клиенту. Если клиент гнезда отвечает на операцию, то он должен предоставить этот идентификатор в атрибуте id элемента taskResponse.

Клиент гнезда должен обработать действие и отправить ответ. Пример ответа:

 <taskResponse id="1" rc="1"/>\n

Если действие выполнено успешно, то возвращается значение атрибута rc 0. Значение rc должно быть целым числом, и любое значение, отличное от 0, рассматривается как ошибка. Значение кода возврата операции записывается в файл журнала агента и показывается в запросе Состояние выполнения действия, который включен в агент. В диалоге, который открывается в Tivoli Enterprise Portal после выполнения действия, код возврата не показан. В этом диалоге указано, возвратила ли команда выполнения действия успех или неудачу. Чтобы определить фактический код возврата при возникновении ошибки, нужно просмотреть журнал агента или запрос Состояние выполнения действия.

Разработчик агента должен задокументировать, создать и импортировать все действия, поддерживаемые клиентами гнезда, которые используются агентом. Если пользователь отправляет клиенту гнезда неподдерживаемые действия, то нужно разработать клиент для обработки этих сценариев подходящим способом. Если пользователи определяют дополнительные действия, запускающиеся с зарегистрированным префиксом, то действия передаются клиенту. Клиент должен быть разработан для обработки этих сценариев подходящим способом.

Существует срок ожидания, управляющий временем, в течение которого агент ожидает ответ клиента гнезда. Это переменная среды CDP_DP_ACTION_TIMEOUT, заданная в агенте; значение по умолчанию - 20 секунд.

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