Monitoring

General

Information

• The monitoring service is to enable the automated monitoring of the PLANTA service component.
• As an individual component, it may query the component for status information (HTTP query) and generate a corresponding HTML document displaying the status of every monitored component.
• Via the HTTP based interface, a connection to different monitoring systems ca be established.
• The objective of this documentation is to enable PLANTA users to set up and use the monitoring component.
• Furthermore, the use of status information in an automated monitoring infrastructure is to be enabled by describing the query syntax and the output formats.

Installation

Details

• In the Server Release packet, a monitoring component can now be selected upon installation.
• If the monitoring component and the server are selected at once during the installation, the parameters for the database and PLANTA server plug-in are entered already, so you will only have to make the following settings later:
  • Port of the monitoring component: On this port, the web interface can be accessed.
  • Network interface: Usually it can remain at the 0.0.0.0 default value (accessible everywhere).
  • Name of the service: Here, a unique name is required (please note this particularly when installing multiple instances!).
• When the server is installed as well, the port for the monitoring interface must be allocated during the installation.
• Otherwise, the installation directory of the already installed PLANTA server and a port for the monitoring interface must be specified since in this case, a PLANTA server setting is required.

Configuration

Connection and Plug-in Configuration via monitoring_configuration.xml

Information

• The configuration is carried out in XML syntax.

Details

• When starting the monitoring component, a check of the syntax according to the monitoring_configuration.xsd XML schema file is done.
  • Syntax errors are indicated in the log file.
• In the Configure main knot, the plug-in directory is defined via the directory attribute.
  • The default setting should be kept:

<!--
* Monitoring configuration
* directory: the path where all directories are placed
-->
<Configure directory="plugins">

• The web server used internally can be configured via the Server knot or its host and port attributes.
• If the monitoring service is to be accessible only locally, "localhost" is used, otherwise "0.0.0.0" permits access to all network interfaces.

<!--
Server configuration
* it is also possible to add multiple host/ports by adding another server-tag
* host-attribute: server-host where monitoring is accessable
* port-attribute: server-port
-->

<Server host="localhost" port="9092"/>
<Server host="0.0.0.0" port="9092"/>

• The URL schema is configurable.
• For this purpose, there is the UrlConfig element, which is illustrated exemplary in the configuration excerpt below.
• In the table_pattern attribute, a prefix is configured, which is the same for every page URL of the monitoring service.
  • The "?" query separator sign can only be used here.
• The json_suffix attribute controls the suffix with the help of which the JSON view can be reached.
• The "page" placeholder refers to the "Page" knots.
• For all categories and components, there are placeholders that are replaced by the name.

<!--
URL configuration
* category and component are variable parameters
* category = categoryname in node "Category"
* component = Plug-In-Title
-->
<UrlConfig table_pattern="/monitoring?monitoring[page]" json_suffix="/view=json">
<Page id="overview" url=""/>
<Page id="detail" url="=detail"/>
<Page id="category" url="=[category]"/>
<Page id="component" url="=component&amp;component=[component]"/>
</UrlConfig>

• In the PlugIn knot, a plug-in is configured, which checks the availability of a component.
• It is allocated to a category below which the plug-in can be grouped.
• The timeout settings enable the availability of the monitoring component in the event of slow or even blocked response from the plug-in.
• Further configuration knots are there for the internal configuration of the plug-in; this is plug-in specific.

<PlugIn filename="planta_plugin" title="PlantaServer" plugin_data_lifetime="20000" request_timeout="1000" hard_timeout="20000">
<Category>Application</Category>
<PlugInConfig host="127.0.0.1" port="27777"/>
</PlugIn>

Details on the plugin_data_lifetime, request_timeout and hard_timeout attributes (all values specified in milliseconds):

• • plugin_data_lifetime
    • If you want to relieve a component in the event of frequent or time intense queries, the monitoring service caches the data for the specified time frame.
  • request_timeout
    • For component query runtimes that exceed the specified time frame, the Timeout status is set and the query results are only fetched upon renewed user query.
  • hard_timeout
    • Like in request_timeout, the component request is canceled.
• A plug-in can also be configured multiple times, whereby different names are used in the title attribute.
  • This way, multiple PLANTA server instances or databases can be monitored.
• The delivery status of the configuration file already contains the configuration schemas of all plug-ins included in the delivery, so that they only have to be adjusted or copied.

Plug-in Specific Settings

PLANTA Server

Information

• In order to use the plug-in, the respective PLANTA service must be configured for monitoring.
• You can do this via the monitoring, monitoring_interface and monitoring_port parameters described here.
• According to the installation site or the configuration of the PLANTA service, the host and port attributes of the =PluginConfig" knot must be set.

<PluginConfig host="<Computer name/IP of the server, on which the PLANTA service is running>" port="<specify the monitoring_port - like in globals.conf>" />

Database

Information

• With this plug-in, the status of the database or its usability by the PLANTA service can be checked by a database user.
• The configuration values can and should be taken from the hibernate.cfg.xml configuration file.
• host, port and sid equate to the three values in the text in hibernate.connection.url (schema: <...>@host:port:sid), <...>@host:port:sid).
• user and password correspond to the respective values in hibernate.connection.username and hibernate.connection.password.
• license receives the three digit license key of the installation. This key must be available in DT345 System parameter
• Example

<PlugIn filename="planta_plugin" title="PlantaServer" plugin_data_lifetime="20000" request_timeout="1000" hard_timeout="20000">
<Category>Backend</Category>
<PlugInConfig host="orasrv.mycompany.com" port="1521" sid="orasrv" user="PL1" password="secret" license="100" />
</PlugIn>

Logging Configuration via =logback.xml

Information

• The monitoring component uses SLF4J as a frame work for log messages, while =Logback is used as a backend.
• Configuration details can be looked up in the Project documentation of logback.
• Through high verbosity, cause studies are possible in case of errors via the threshold value configuration.
  • Log threshold values (sorted by increasing verbosity)
    • error > warn > info > debug > trace
• To do so, the level attribute of the root knot must be set to a threshold value with higher verbosity, as described in the following section:

<root level="debug">
<appender-ref ref="FILE" />
<appender-ref ref="STDOUT" />
</root>

Details of Use

Information

• You can access information on the components via URL.
• The information can be opened in the HTML format (especially for manual viewing) as well as in JSON format (suitable for automatic processing).
• For JSON output, the configured json_suffix is used, which has been attached to the URL of the HTML output (/json in the default configuration).
• Below, the query options and output formats are illustrated by using the example of a monitoring server configured to localhost with 9092 port.

Explanation of the Return Format

Information

• In the following table, the headings of the returned HTML table, or the keys of the directory returned in the JSON query, are specified for the component view.
• All other views contain a subset of these attributes.
• The overview page summarizes the State and Component state attributes, so that State remains NOK here, if one of the status attributes is NOK.

Details

Heading/Key	Return Value	Description
Title	Name	Description of the component
Description	Text	Description of the component
Release date	Date/Timestamp	Approval timestamp
Release version	Version description
Build date	Date/Timestamp	Date of creation
Build version	Version description
State	OK/NOK/TIMEOUT	Status of the plug-in instance component
Component state	OK/NOK	Status of the component
Comment	Text	Additional information, e.g., exception
Response time	Duration in ms	Reaction time of the component plug-in
Required system properties	Text
Start time	Time stamp	Start date of the component, if available
Extended	Additional directory	Contains further plug-in-specific attributes

Overview

Information

• Configuration: Page ID overview
• You can receive an overview of all categories as well as the components administered therein, via:

http://localhost:9092/monitoring

• The status of the components is the main information here
• The actuality of this status is specified here to enable you to interpret its validity.

Detail Overview

Information

• Configuration: Page ID overview
• Detailled information on all components can be opened via /monitoring=detail:

http://localhost:9092/monitoring=detail

Category Overview

Information

• Configuration: Page ID category - the [category] variable is replaced by the category name then
• The category overview shows detailed information on all components administered in the category (here, shown for the Application category):

http://localhost:9092/monitoring=Application

Component Overview

Information

• Configuration: Page ID category - the [category] variable is replaced by the component name then
• If you want a single component to be monitored, you can open the component view, in which all recorded information is displayed (here shown for the component named PlantaServer):

http://localhost:9092/monitoring=component&component=PlantaServer

Operating Information

Service Administration

Information

• The service is set up automatically during the installation under both Windows and Linux.
• At the same time, the name of the service is allocated as well.
• The operator can administer the service via the following scripts in the [Installationsort]/yajsw/bat directory (administrator rights are required):

Action	Linux	Windows
Query of the current status	queryDaemon.sh	queryService.bat
Starting the service	startDaemon.sh	startService.bat
Stopping the service	stopDaemon.sh	stopService.sh
Installing the service	installDaemon.sh	installService.bat
Deleting the service	uninstallDaemon.sh	uninstallService.bat

Logging

Information

• In the log/ directory at the installation site, log files are created.
• They are configured with a preconfigured warn log threshold value with daily rotation.
• If the operation of the monitoring component causes problems, these log files are to be checked since they can show hints to the root of such problems.
• A comprehensive output of log messages can be achieved as described in the Logging configuration section.

Monitoring Interface of the PLANTA Server

Information

• The interface in the PLANTA server used by the monitoring service can also be used directly.
• This way, connections to other monitoring systems, like Nagios, can be enabled.
• Functions implemented by the monitoring service, are then not available, e.g., database monitoring or caching for elaborate monitoring functions.
• The server interface is activated and configured via the monitoring, monitoring_interface and monitoring_port parameters in the globals.conf configuration file.
• Example: on the test1.example.com server, the parameters are set as follows:
  • monitoring=true: activates the server interface.
  • monitoring_interface=0.0.0.0: enables access via all network interfaces.
  • monitoring_port=27777: Port to which the interface listens.
• On PLANTA servers that have been configured accordingly, server information can now be queried via the test1.example.com:27777/monitoring URL.
• A directory in JSON format is returned; for automatic evaluation, the string must be decoded.
• Return example:

{"Component State":"OK","Release Date":"Fri Feb 28 13:57:14 CET 2014",
"Start Time":"Wed Mar 05 21:55:25 CET 2014","Release Version":"46656",
"Build Date":"Fri Feb 28 13:57:14 CET 2014","Build Version":"46656"}