CVT Developer documentation
Documentation for the Cluster Visualization Tool that allows developers to get up to speed with its implementation.
Architecture
StatisticsBuffer
StatisticsManager / StatisticsEmitter
StatisticsRetriever
StatisticsRetrievalRegistry
StatisticsConfig
StatisticsSubsystem
StatisticsGateway
StatisticsAgentConnection
StatisticsStore
StatisticsRetrievalCriteria
StatisticsGatherer
Agents, Gateway and Gatherer
The below diagram should help.
There is an agent running on each of the node in the cluster where we want to collect statistics, i.e. basically on each L1 and L2. There is a Gateway running on the L2 which talks to all the agents running in the cluster (including the L2). There is a Gatherer running on the L2 presently which exposes a servlet with a REST-full service to the API's present in the Gatherer system. The Gatherer system talks to the Statistics Gateway which in turn talks to all other agents running in the cluster. The communication between the statistic gateway and the agents happen using the existing Terracotta JMX infrastructure.
What happens when L2 starts
Below is a brief diagram showing how things happen in context of statistics collection system:
- startHttpServer() : The diagram below briefly shows how the Gatherer Sub system is bound to the web context offering the Gatherer REST-full services. The servlet is exposed in a context specified by "/statistics-gatherer" as can be seen below. After creating the WebContext and setting the correct ServletHandler, the context is added to the Server. Afterwards the embedded web-server is started. The web-server and the servlet container used is a normal embedded Jetty web-server and is bound to localhost (i.e. L2, where StatisticsGatherer is running) and port number 9510.
- startDSOServer() : After starting the embedded http server, the DistributedObjectServer is started where the StatisticAgentSubSystem for this node is setup(), the StatisticGateway is brought up, and the JMX communications layer initializes. The diagram below shows a brief sequence diagram to show how things are in context of Statistics collection system.
- populateStatisticsRegistry() : In these method, all the StatisticRetrievaAction s (SRA) supported by the agent is registered in the agent's StatisticRetrievalRegistry. Each SRA is bound with a unique name in the agent and the StatisticGateway can interact with this agent to enable/disable/capture/retrieve any of the SRA supported by the agent.
What happens when L1 starts
.. coming up ...
StatisticsGathererSubSystem and StatisticGateway
The StatisticGathererSubSystem has a StatisticsGatherer and a StatisticsStore. Details of the StatisticsGatherer is given below:
public interface StatisticsGatherer {
public void connect(String managerHostName, int managerPort) throws TCStatisticsGathererException;
public void disconnect() throws TCStatisticsGathererException;
public void reinitialize() throws TCStatisticsGathererException;
public void createSession(String sessionId) throws TCStatisticsGathererException;
public void closeSession() throws TCStatisticsGathererException;
public String getActiveSessionId();
public String[] getSupportedStatistics() throws TCStatisticsGathererException;
public void enableStatistics(String[] names) throws TCStatisticsGathererException;
public void startCapturing() throws TCStatisticsGathererException;
public void stopCapturing() throws TCStatisticsGathererException;
public void setGlobalParam(String key, Object value) throws TCStatisticsGathererException;
public Object getGlobalParam(String key) throws TCStatisticsGathererException;
public void setSessionParam(String key, Object value) throws TCStatisticsGathererException;
public Object getSessionParam(String key) throws TCStatisticsGathererException;
public void addListener(StatisticsGathererListener listener);
public void removeListener(StatisticsGathererListener listener);
}
The StatisticGatherer in the StatisticsGathererSubSystem needs to first connect to the StatisticGateway before it can start to do anything. The gatherer is connected to the gateway through JMX which is implemented in the method connect() of StatisticGathererImpl. After connecting, a proxy is available to the gatherer which is used to delegate all other calls like createSession(), enableStatistics(), startCapture() ... etc. to the gateway. On reaching the gateway, the calls are again forwarded to the agents currently connected to the gateway through JMX.
Developing retrieval actions
[common-api] com.tc.statistics.StatisticRetrievalAction
- immutable, instances are created at startup and are reused
- unique names
- can take state at construction
- registered into StatisticsRetrievalRegistry at node startup
- ...
[common-api] com.tc.statistics.StatisticData
- construction: fluent interface, static factory methods
- names for individual data entities
- elements for multi-value data entities
Setting up Sigar
The following details the steps needed to install Sigar into a Terracotta
kit built from trunk.
build trunk into your local Maven repo like so:
 |
This is only necessary if the portions of terracotta-api that sigarstats depends on have changed and the publicly available terracotta-api hasn't been build and installed into the public repo yet. |
% cd $TRUNK
% tcbuild dist_maven maven.snapshot=true maven.version=2.6.0-SNAPSHOT
Download the Sigar distribution from here:
https://sourceforge.net/project/showfiles.php?group_id=172552&package_id=197466&release_id=573224
Extract the archive into a location that will now be referred to as
$SIGAR_HOME.
Copy sigar library into TRUNK source area:
% cp $SIGAR_HOME/sigar-bin/lib/sigar.jar $TRUNK/code/base/dependencies/lib/sigar-1.5.0.1.jar
Check-out the sigarstats branch into $SIGARSTATS_HOME:
Build the sigarstats project:
% cd $SIGARSTATS_HOME/trunk
% mvn clean compile jar:jar
Copy sigarstats library into TRUNK:
% cp target/sigarstats-1.0.0.jar $TRUNK/code/base/dependencies/lib
Update $TRUNK/code/base/deploy/ivy.xml to include:
<dependency name="sigarstats" rev="1.0.0" org="testing"/>
<dependency name="sigar" rev="1.5.0.1" org="testing"/>
Build TRUNK kit
% cd $TRUNK/code/base
% tcbuild dist
Copy appropriate native Sigar libs into kit:
For Mac:
% cp $SIGAR_HOME/sigar-bin/lib/libsigar-universal-macosx.dylib $TRUNK/code/base/build/dist/terracotta-cvt/lib
For Windows:
% cp $SIGAR_HOME/sigar-bin/lib/sigar-x86* $TRUNK/code/base/build/dist/terracotta-cvt/lib
Run demo server, clients, and AdminConsole. See real-time stats.
