$('a[name]').remove(); $('#ic-homepage__footer').before('

'); $("#tabs").tabs({ selected: 1 }); $("#ic-homepage__ic-tips").append( quickTipHTML() ); unhideOneProductTip(); $("#ic-homepage__product-tips").wrapInner('

'); $("#ic-homepage__feed-tips").wrapInner('

'); });

IBM Tivoli Monitoring > Version 6.3 > User's Guides > Agent Builder User's Guide > Monitor data by using a socket IBM Tivoli Monitoring, Version 6.3


Sending socket information to the agent

When your agent contains one or more socket attribute groups, the agent opens a socket and listens for data from clients.

The application that sends socket data to the agent connects to a port that is defined in the agent. The port is either the value that is set by an agent configuration property or an ephemeral port that is allocated automatically by TCP/IP. For more information about socket ports and configuration, see Socket configuration.

The data that is received must follow a structured XML format. The following XML information flows are possible using the socket data source:


Sending data

An attribute group is defined to receive sampled data or event data. When you create the attribute group, you specify an option that indicates whether the data to be received:

If you select Produces a single data row or Can produce more than one data row, that is a sampled attribute group. If you select Produces events, then your attribute group sends an event to Tivoli Monitoring each time that a row is received.

When you view sampled data in the Tivoli Enterprise Portal, you see the latest set of collected rows. The data that is displayed for an event attribute group is the contents of a local cache that is maintained by the agent. For event data, the agent adds the new entry to the cache until the size is reached when the oldest one is deleted. For sampled data, the agent replaces the contents of the cache every time you send data.

If you select Produces events or Produces a single data row, send only one row of data to the agent for that attribute group in each message. You can send as many events as you want, send each event in a separate message.

Normally sampled data is collected by the agent on request, but the socket client provides updated samples on its own schedule. You can update a sampled attribute group (single row or multiple row) as often as you require. When the data is requested by Tivoli Monitoring, the agent provides the latest data.

If there are missing rows of data for the socket attribute group in the Tivoli Enterprise Portal, check the errors in the log file. Also, if the data in the attribute group is not as expected, check the errors in the log file. The socket data source attempts to process whatever it can from the input. For example, if the client sends three well-formed rows and one that is not valid (for example, malformed XML), you see:

For both event and sampled data, the data is sent to the agent as a single XML data flow from the socket client. Data that is sent from a socket client must always be terminated with a newline character: '\n'. The agent reads data until it sees the newline character and then an attempt is made to process what was received. Any data received that cannot be processed is discarded. The following is a sample of how you would send two rows of data to the agent for an attribute group named abc:

This sample sends two rows of data to the agent where each row contains three attributes. The order of the attributes is important and must follow the order that is defined in your attribute group. The only exception to this is that the derived attributes must be skipped, regardless of where they are in your attribute group.

If the attribute group is defined in a subnode, then the subnode instance ID must be identified when data is sent to the agent. The subnode instance ID is identified using the subnode attribute in the socketData element. A convention must be adopted for configuring subnode instance IDs for use by the socket client since the client cannot query instance IDs or configuration properties. Data sent to a subnode which is not configured is ignored.

Here is a sample:

In this sample, the data is sent to the subnode with an instance ID equal to "app1". "app1" is not the managed system name, but the instance identifier that is specified when the subnode instance is configured.

The following XML elements make up the socket data:

socketData

The root element. It has one optional attribute that is called subnode that specifies the subnode instance ID.

attrGroup

This element identifies the attribute group that the socket data is for. The name attribute is required and is used to specify the attribute group name.

in

This element is required to identify a new row of data. All of the attribute values for a row of data must be children of the same in element.

a

The a element identifies an attribute value. The v attribute is required and is used to specify the attribute value.


Sending errors instead of data

Sometimes the application that posts socket data might not be able to collect the data necessary for an attribute group. In this case, instead of sending data to the agent, an error code can be returned. The error code gives you a way to tell the Tivoli Monitoring environment about your problem. An example error is:

The error code must be defined in the agent in a list that is common to all of the socket attribute groups. When the agent receives an error code, the defined error message is logged in the agent log file. In addition, the attribute group named Performance Object Status has an Error Code attribute is updated with the Error Code Type. The Error Code Type is defined for the error code you send.

For the previous example, you must define the Error Code Value of 1000 in the agent. See the following sample error code definition:


Sample error code

Error Code Value Error Code Type Message
1000 APP_NOT_RUNNING The application is not running

When the error code is sent, a message similar to the following is logged in the agent log file:

If you select Performance Object Status query from the Tivoli Enterprise Portal, the Error Code column for the row abc attribute group shows the value APP_NOT_RUNNING in that table.

Sending an error to a sampled attribute group clears any data that was previously received for that attribute group. Sending data to the attribute group causes the error code to no longer be displayed in the Performance Object Status attribute group. You can also send an error code of 0 to clear the error code from that table.

Sending an error to an attribute group that produces events does not clear the cache of events that were previously sent.


Handling take action requests

The socket client can register to receive take action requests from the agent when the action command matches a certain prefix. Any action that does not match is handled by the agent. The prefix must not conflict with actions that the agent is expected to handle, so use the agent product code as the prefix. Take actions provided with the Agent Builder are named after the data source that the take action uses. For example, the JMX_INVOKE take action operates on the JMX data source. Another example is the SSHEXEC take action which uses the SSH script data provider. Since these actions do not use the product code, the product code is a safe prefix to use as the take action prefix.

The socket client must be long running and leave the socket open. It must send a registration request for the prefix and listen for requests from the socket. The agent ensures that a timeout does not occur on the socket of a long-running client, even if no data is flowing. The following is a sample registration request:

In this sample, any take action command that is received by the agent that begins with "K42" is forwarded to the socket client that initiated the registration. The following shows a sample take action request that the socket client might receive:

The id is a unique identifier that the agent uses to track requests that are sent to clients. When the socket client responds to the task, it must provide this identifier in the id attribute of the taskResponse element.

The socket client must process the action and send a response. A sample response is:

If the action completes successfully, an rc attribute value of 0 is returned. The value of rc must be an integer, where any value other than 0 is considered a failure. The task return code value is logged to the agent log file and shown in the Take Action Status query that is included with the agent. The dialog that is displayed on the Tivoli Enterprise Portal after an action is run does not show the return code. That dialog indicates whether the take action command returned success or failure. The agent log or Take Action Status query must be viewed to determine the actual return code if a failure occurred.

It is the agent developer's responsibility to document, create, and import any actions that are supported by the socket clients that are used with an agent. If users send unsupported actions to the socket client, the client must be developed to handle those scenarios in an appropriate manner. If users define more actions that start with the registered prefix, they are passed to the client. The client must be developed to handle those scenarios in an appropriate manner.

There is a timeout that controls how long the agent waits for a response from the socket client. The setting is an environment variable that is defined in the agent that called CDP_DP_ACTION_TIMEOUT and the default value is 20 seconds.

The error code messages that are defined for socket data source attribute groups are not used for take actions. You can return the same return code values. However, the agent does not log the message that is defined or affect the Error Code field in the Performance Object Status attribute group.


Parent topic:

Monitor data by using a socket

+

Search Tips   |   Advanced Search