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 is carried out according to the
monitoring_configuration.xsd
XML schema file.- Syntax errors are indicated in the log file.
- In the
Configure
main knot, the plug-in directory is defined via thedirectory
attribute.- The default setting should be kept:
<Configure directory="plugins">
- The web server used internally can be configured via the
Server
knot or itshost
andport
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 query separator "
- 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.
- For component query runtimes that exceed the specified time frame, the
hard_timeout
- Like in
request_timeout
, the component request is canceled.
- Like in
- 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
, andmonitoring_port
parameters described here. - According to the installation site or the configuration of the PLANTA service, the
host
andport
attributes of thePluginConfig
knot must be set.
<PluginConfig host="<Rechnername/IP des Servers, auf dem PLANTA-Service läuft>" port="<wie in globals.conf - monitoring_port angegeben>" />
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
, andsid
correspond to the three values separated by : (colon) in the text inhibernate.connection.url
(schema: <...>@host:port:sid).user
andpassword
correspond to the respective values inhibernate.connection.username
andhibernate.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, whileLogback
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
- Log threshold values (sorted by increasing verbosity)
- To do so, the
level
attribute of theroot
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
with9092
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
Heading/key | Return value | Description |
---|---|---|
Title | Name | Component name |
Description | Text | Component description |
Release date | Date/time stamp | Approval time stamp |
Release version | Version name | |
Build date | Date/time stamp | Time of creation |
Build version | Version name | |
State | OK/NOK/TIMEOUT | Status of the component plug-in instance |
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 time 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 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):
Action | Linux | Windows |
---|---|---|
Retrieving the current status | queryDaemon.sh | queryService.bat |
Launch of the service | startDaemon.sh | startService.bat |
Termination of the service | stopDaemon.sh | stopService.sh |
Installation of the service | installDaemon.sh | installService.bat |
Deletion of the service | uninstallDaemon.sh | uninstallService.bat |
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
, andmonitoring_port
parameters in theglobals.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 analysis, 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"}