Administration and Logging

Administration and Logging

The Administration and Logging Module consists of these four parts:

• Logging Module (written in C++)
• Apache Cassandra Database
• REST Admin Module (written in JAVA)
• Web GUI

C++ Logging Module

The Logging Module writes all Messages that will appear in the system to a database. These messages will be shown on the Web GUI.

To run the Logging Module, you have to install the Cassandra C++ Driver, which could be found here:

• http://downloads.datastax.com/cpp-driver/

Normal users only need to download and install these to files:

• libuv_1.7.X-X_amd64.deb
• cassandra-cpp-driver_2.X.X-X_amd64.deb

Developer might want to install the developer or debug driver.

Once you have started (and enabled) the Logging Module, it will connect to the Apache Cassandra Database. After this, it will set a subscription to the Messages on the ZMF-Bus. For a better performance in large systems, you could change the subscription topic from all messages to a more specific one. Also you can use multiple instances to log a specific type of message on multiple hosts.

Below is the flow diagram of the Logging Module:

Cassandra Database

As mentioned before, we are using Apache Cassandra DB 2.0.X to store these messages. Cassandra is a high-performance NoSQL-Database. The query language is an SQL look alike called CQL. In a productive system - which creates high traffic - you should run Cassandra on multiple nodes (so called clusters). These nodes could be set at the config file. The config key is: ZSDN_LOGGING_MODULE_CASSANDRA_URL

A installation Guide for Debian-based systems can be found here:

• http://docs.datastax.com/en/cassandra/2.0/cassandra/install/installDeb_t.html

Note: to use CQL out of a module, you have to install the driver first!

Structure

Keyspace: logging Table: messages

id	messageType	senderType	senderId	timeStamp
uuid	blob	varint	varint	timestamp

How to Start

To start Cassandra, execute following command from shell:

bin/cassandra -f

or, if you have used the link as mentioned before to install Cassandra:

service cassandra stop 

To get the cqlbash run:

bin/cqlsh

To insert Data in a fresh Cassandra DB execute the commands below:

CREATE KEYSPACE IF NOT EXISTS logging WITH REPLICATION = { 'class' : 'SimpleStrategy', 'replication_factor' : 1 };```<br>```
CREATE TABLE IF NOT EXISTS logging.messages (id uuid, messageType blob, senderType varint, senderId varint, timeStamp timestamp, PRIMARY KEY (id, timeStamp));```<br>```
INSERT INTO logging.messages (id, messageType, senderType, senderId, timestamp) VALUES (uuid(), 0x010000000000000000000100, 1, 0, dateOf(now()));

For more information, we recommend to read some tutorials at the Apache Cassandra Wiki:

• https://wiki.apache.org/cassandra/GettingStarted

How to Start on CentOS

Connect to Server via SSH

ssh user@server

To start Cassandra:

sudo systemctl start cassandra

Shutdown Cassandra:

sudo service cassandra stop

To open cqlsh:

cqlsh

To start Tomcat

sudo systemctl start tomcat

To stop Tomcat

sudo service tomcat stop

JAVA REST Admin Module (RESTAdmin)

The JAVA administration module provides a REST interface which provides data and allows module control. It is a JAVA web application archive (WAR) which runs on the tomcat server. The project itself is a Maven web project, which uses the Apache Maven build automation tool for the projects dependencies and build lifecycles.

Technology

The RESTAdmin is utilizing the following packages:

• javax.servlet
• JAX-RS: Java API for RESTful Web Services
• Jersey RESTful Web Services framework

JAX-RS provides the base of the REST interface in JAVA while Jersey is a framework which implements the JAX-RS API. The application itself is a servlet utilizing javax.servlet.

Dependencies

The following dependencies are included through the projects Maven pom file: asm, gson, cassandra-driver-core, servlet-api, rest-assured, json-schema-validator, junit. The only non-maven dependency is jersey-bundle-1.19.jar which is located inside /RESTAdmin/WebContent/WEB-INF/lib/ and consist of a bundle of dependencies required for jersey.

As seen above, you don't have to install the cassandra (Java) driver by yourself.

Usage

The REST Admin Module is a WAR file and can be deployed on a tomcat server. Once correctly deployed, it starts automatically and can be accessed at http://localhost:8080/RESTAdmin/

REST Interface

The REST Admin Module provides a REST Interface. If the user doesn’t want to use the delivered front end, the user can create his own and use the REST Interface of the REST Admin Module.

Name	Type	URL	Result
Logging	GET	rest/messages	All logging messages
Logging filtered by starttime and endtime	GET	rest/messages/filtered?starttime={time}&endtime={endtime}	Messages filtered by time
Module registry	GET	rest/modules/	All modules with status
Single Module registry	GET	rest/modules?id={ModuleID}	Module with status
StartStop	PUT	rest/modules/control?id={ModuleID}&action={enable/disable/stop}
Topology	GET	rest/topo	Topology as JSON

Therefore the REST interface itself can be separated into the following 3 classes: RESTModules, RESTMessages, RESTTopology. The main application logic itself is inside the AdminModule class, which extends the jmf AbstractModule class and allows access to the functions of the jmf. An Instance managing class called ZMFmanager controls the creation and initialization of the AdminModule, as the application is a servlet and cannot be started in the regular way (main method).

Web GUI

In the REST Admin Module you will find an example implementation for a web gui. To get access, just run the REST Admin Module and open the URL /RESTAdmin/ in your Browser.

The Web GUI has three main functions:

• Logging
• Module Administration
• Topology View

Logging

Here the user can look at the messages that will be send through the ZMF-Bus as explained before. The first field is the Message Type this explains what message that specific message is. The second field is the Sender Type, which describes the kind of module that has published this message. The third field is the Sender ID so you could see which module the message published. In the last field you will find the timestamp of the message.

The The Logging tab is a JavaScript page which allows displaying and filtering of logged messages. It uses angularJS to create the table and for XHR. These Requests will be send to the REST interface of the JAVA administration module. The data in the response is a JSON object which has following structure:

json
{ 
    {
        id : '',
        messageType : '',
        senderId : ,
        senderType : ,
        timeStamp : ''
    }, {
        id : '48bc...',
        messageType : 'foo',
        senderId : 12,
        senderType : 1,
        timeStamp : '2015-07-14 15:00:00+0200'
    }
}

Module Administration

According to our "Module Lifecycle", not every module that is started once is also enabled. The Module Administration can give you an overview, which module is started and/or enabled. If a module is only started - but not enabled - the user can enable the module here. Also the user can disable a module or stop it. Please notice: you can't restart a module that is stopped via the Web GUI.

[
	{
		"name" : "<ModuleName>",
		"version" :  < Version > ,
		"UniqueId" : "<ModuleID>:<InstanceID>",
		"currentState" : "<State>"
	}, {
		"name" : "LinkDiscoveryModule",
		"version" : 0,
		"UniqueId" : "5:0",
		"currentState" : "Active"
	}
]

Topology View

The Topology View will allow you a global view on the network. The links between the nodes will change the color from black to red, depending on the load.

Sample JSON for Topology View:

{
	"nodes" : [{
			"name" : "<node name>",
			"id" : "<unique ID>"
		}, {
			"name" : "node 1",
			"id" : "unique_id_1"
		}
	],
	"links" : [{
			"source" : "<ID of source node>",
			"target" : "<ID of target node>",
			"value" :  <load on link>
		}, {
			"source" : "unique_id_1",
			"target" : "unique_id_2",
			"value" : 123
		}, {
			...
		}
	]
}