Directory Integrator, Version 7.1.1
"RAC" stands for Remote Agent Controller, however the current name for this technology is Agent Controller.
The Agent Controller is a server that enables client applications to interact with agents under its domain: hthttp://help.eclipse.org/helios/index.jsp?topic=%2Forg.eclipse.tptp.platform.agentcontroller.doc.user%2Fconcepts%2Fac%2Fc_ac_ovr.html
A Generic Log Adapter (GLA) transforms proprietary log and trace data to the Common Base Event format (http://www.ibm.com/developerworks/library/specification/ws-cbe/). The rationale for a Generic Log Adapter is that reading log files is messy and making parsers for all types of logs is not scalable and one tends to customize anyway. A GLA can act as an agent of an Agent Controller so that clients can monitor remote application logs.
More information about Agent Controller and Generic Log Adapter can be found on http://www.eclipse.org/tptp/home/documents/index.php.
The RAC Connector can read data from and write data to RAC:
It registers as an agent within the local Agent Controller and sends it the Common Base Event objects, which it receives from the AssemblyLine.
The RAC Connector does not require the local Agent Controller to be running at the time it is initializing. As soon as the local Agent Controller is launched, the Logging Agent is registered and gets ready to be monitored by clients.
The important point is that the Connector will not report an error if the local Agent Controller is not active.
The Connector will not complain even if there is no Agent Controller installation on the local machine. Of course, no Logging Agent will be registered then.
As such, it contacts the Agent Controller on the remote machine, obtains a handle to a certain Logging Agent and starts receiving log data in the form of Common Base Event objects.
If the remote Agent Controller goes down the Connector hangs waiting for a response from the Agent Controller (this is due to the current client library realization). - thus any reconnect logic cannot be used.
The Connector uses an internal queue to store the incoming Common Base Events (CBEs). As a result the Connector can keep fetching CBEs even after the Agent Controller has gone down because the queue could still have events in it. Due to restrictions caused by the Agent Controller client library, the Connector can not process Common Base Event objects, which when serialized as XML are larger than 8Kb. If a data portion larger than 8Kb arrives, the Connector will not process any more events and will wait until the remote Logging Agent dies. This is a limitation of the client library implementation.
On termination, the Connector detaches from the remote agent. If this procedure is skipped for some reason (for example the JVM is killed), no other client will be able to monitor the agent. Moreover, the agent will still think that it is being monitored.
For example, if one runs the Connector from the Config Editor and manually stops the AssemblyLine, the Connector will not have a chance to detach from the Logging Agent. So if the Connector is run again, it will not receive any data from the agent, because the Agent Controller (and the agent) thinks that the agent is already being monitored.
Only one client can monitor a Logging Agent at a given time, so no two RAC Connectors in Iterator mode should be pointed at the same agent at the same time.
The Connector's title, shown in the Configuration panel is "RAC Connector". Parameters are:
The name of the remote Logging Agent to be monitored.
Host of the remote Agent Controller. Default value is "localhost".
Port of the remote Agent Controller. Default value is 10006.
The size of the queue, where the received events are buffered before the Connector manages to read them. Default value is 1024.
Timeout (in seconds) for each data reception after the remote agent dies. If this timeout expires, the agent's data is considered depleted and the Connector terminates. Default value is 5.
The name of the Logging Agent within the local Agent Controller. Default value is "tdi_logging_agent".
Time to wait (in seconds) for the agent to be monitored before data is sent to RAC. If zero, waits forever. Default value is 0.
The AddOnly mode of the RAC Connector requires that the binaries of the Agent Controller (.dll, .so) are available to the dynamic library loader of the operating system. The preferred way to achieve this is to include the binaries folder of the Agent Controller in the PATH environment variable on Windows platforms, and in the LD_LIBRARY_PATH environment variable on Linux platforms. This can be done either globally or just for the process of the Tivoli® Directory Integrator Server. For example:
LD_LIBRARY_PATH=/AgentController/lib
export LD_LIBRARY_PATHWhen operating in AddOnly mode, the first RAC Connector on the Tivoli Directory Integrator Server registers a Logging Agent with the local Agent Controller.
All Common Base Event objects received from the AssemblyLine, are serialized as XML and written to the Logging Agent. The Logging Agent stays operational as long as the master process of the Tivoli Directory Integrator server is alive. During its lifetime it can be monitored by clients even if the Connector which registered it has already closed. When the Tivoli Directory Integrator server stops (or crashes), however, the Agent Controller (RAC) terminates the Tivoli Directory Integrator Logging Agent's registration.
The Connector will wait a specified amount of time for a monitoring client to arrive before starting to write data to the Logging Agent. In particular, it can wait forever. This is specified by the Wait to be monitored Connector parameter. When a client starts monitoring the agent, the agent starts transferring data to the Agent Controller. The Agent Controller then sends the data to the client.
Waiting happens before each Connector write attempt.
If the waiting time expires and there is still no monitoring client, the Connector throws an Exception. However, if a client starts monitoring the agent while the Connector is waiting, the waiting is interrupted and the agent starts transferring data to the Agent Controller.
Depending on the Wait to be monitored Connector parameter value the Connector could potentially wait indefinitely for a client to start monitoring the agent. This would cause the entire AssemblyLine to block indefinitely. Precisely for this reason the following Connector method is available to you:
public boolean isLogging();This method returns true if there is a client monitoring/listening for data from this Connector and false otherwise. This method is accessible through JavaScript and can be invoked on the Connector object (that is, thisConnector.islogging().)
You can use this method in order to detect whether the Connector will block when the AssemblyLine execution reaches the Connector. If blocking is not desirable, but loosing data is unacceptable, then you could implement a solution which temporarily stores the data into a queue (possibly the Tivoli Directory Integrator Memory Queue) when the isLogging() method returns false.
In Iterator mode the RAC Connector acts as a client of a remote Agent Controller. It connects to the Agent Controller to obtain a handle to the Logging Agent, whose name is specified in the Connector's configuration. After that the Connector starts monitoring the Logging Agent. During the monitoring, the Connector receives data produced by the Logging Agent.
Data reception is handled asynchronously by the Agent Controller client library and queued there. The Connector is notified when data reception occurs, and when the Connector reads from the queue a buffer is received with the incoming binary data. The queue is blocking, so the Connector will wait if no data is available and the data processor will wait if there is no free space in the queue.
The received binary data contains a CommonBaseEvent object serialized as XML in UTF-8 encoding. In addition, the CommonBaseEvent is decoded from the buffer and made available to the Connector in the Input Map.
If there is no active agent with the specified name when the Connector contacts the Agent Controller, the Connector waits until such an agent is registered.
If at some point the agent gets deregistered (while the Connector is listening for events), the Connector will wait for another agent with the same name to appear. Essentially the Connector never stops unless its connection to the Agent Controller fails.
The Connector exposes a method, which provides access to the Common Base Event object obtained by the Connector on the current AssemblyLine iteration (the last event, processed by the 'getNextEntry' method of the Connector):
public CommonBaseEvent getCurrentCbeObject();The connector internally uses the CBE Function Component, and uses that particular FC's schema.