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 can 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 anywhere).
  • 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:

<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 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 "?" 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.

<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 under 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 run>" port="<as specified in globals.conf - monitoring_port>" />

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 correspond to the three values separated by : (colon) in the text in hibernate.connection.url (schema: <...>@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="database_plugin" title="Database" 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 URLs.
• 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 Stateremains NOK here, if one of the status attributes is NOK.

Details

Overview

Information

• Configuration: Page ID overview
• You can receive an overview of all categories as well as of the components managed 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.

Detailed Overview

Information

• Configuration: Page ID detail
• Detailed 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 will then be replaced by the category name
• The category overview shows detailed information on all components managed in the category (here, shown for the Application category):

http://localhost:9092/monitoring=Application

Component Overview

Information

• Configuration: Page ID component - the [component] variable will then be replaced by the component name
• 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 will be set up automatically during the installation under both Windows and Linux.
• At the same time, the name of the service will be allocated as well.
• The operator can manage the service via the following scripts in the [Installationsort]/yajsw/bat directory (administrator rights are required):

Logging

Information

• In the log/ directory at the installation site, log files will be 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"}