Date: Aug 2024

Version: 3.1

Supervisor

Overview

The supervisor provides a query interface API that can be used for monitoring the state of the node. It is possible to query things like db status, bdb status, product availability and more. If it is necessary to push status information to an external monitoring tool it can be solved by writing a scheduled rule and queries the node for system information.

Administration

The supervisor only provides requestors about current state of the node so there is no real need for authentication procedures. However, we have added an IP-block in the supervisor query interface so that we at least can avoid processing unessecary questions. The supervisor administration interface can be reached by navigating to: Processing->Supervisor.

The supervisor will always allow connections from 127.0.0.1. The rest of the ip-addresses that should be allowed should be added in this administration GUI. The format of the ip-address should always be N.N.N.N where N either can be a value between 0-255 or a *. There is actually not a test if the number is > 255 but it will make the filter useless. Also, remember that if you are using a proxy, the ip-package might contain an ip-address different than what you expect.

The supervisor GUI shows the ip-address from where you are connecting so if you are in doubt, you can always login to the supervisor GUI and see what ip-address you should put in the filter.

Query interface

Basic usage is to send a http-get query towards the supervisor and parse, check the response. The following query

wget -q -O- "http://localhost:8080/BaltradDex/supervisor.htm?reporters=bdb.object.status&sources=seang&objects=SCAN&minutes=5"

would result in the following response

<?xml version="1.0" encoding="UTF-8"?>
 
<system-status>
<reporter name="bdb.object.status" value="sources=seang&amp;objects=SCAN&amp;minutes=5" status="OK"/>
</system-status>

which says that the bdb.object.status reporter determined that a seang SCAN has arrived within the last 5 minutes.

Each reporter supports different attributes and these combinations is described by each reporter. It is possible to add more than one reporter in the same query and that is controlled by the reporters attribute. This means that if you for example combine two different reporters you should consider that the reporters might use the same attribute which might not be the wanted behaviour. Each reporter will produce a separate <reporter /> entry that can be parsed separately.

As an example, if you want to know the db, bdb and bdb object status, this query

wget -q -O- "http://localhost:8080/BaltradDex/supervisor.htm?reporters=bdb.status,db.status,bdb.object.status&sources=seang&objects=SCAN&minutes=5"

will produce

<?xml version="1.0" encoding="UTF-8"?>
 
<system-status>
<reporter name="bdb.status" value="" status="OK"/>
<component name="db.status" value="" status="OK"/>
<reporter name="bdb.object.status" value="sources=seang&amp;objects=SCAN&amp;minutes=5" status="OK"/>
</system-status>

that says that the baltrad db, postgres connection are working ok and that we got a SCAN from seang within the last 5 minutes.

Return codes

The <reporter> tag contains a status attribute that specifies what the result of the operation was. This result can actually more than one if the reporter identifies a conflicting state. For example, if asking for two radar sources in the same query and one of the radar sources has delivered within asked time but the other radar source hasn't. In that case, the result would be OK|COMMUNICATION_PROBLEM or similar.

status code	Description
OK	All seems ok
COMMUNICATION_PROBLEM	There is some problem related to communication
MEMORY_PROBLEM	We have identified that we might be leaking memory
EXCHANGE_PROBLEM	We have problems exchanging data
PROCESSING_PROBLEM	An error occured when trying to process data

Formatting of responses

Currently, the only supported formatter is the xml formatter. In the future we hope that you will have access to various kinds of formatters that is more suitable for your use. The formatter is specified by a separate attribute called named format and the value would be xml. However, this is default behaviour so it can be omitted.

If you want to manually specify the formatter, then the request url would be:

http://..../BaltradDex/supervisor.htm?format=xml&reporter=......

The format of the returned xml message will always be in the format:

<?xml version="1.0" encoding="UTF-8"?>
 
<system-status>
[<reporter name="..." value="..." status="..."/>]*
</system-status>

Reporters API

There are several reporters delivered with the system and this list will probably grow with time.

Reporter name: db.status

This reporter will just verify that a query can be executed towards the postgres database.

Arguments

N/A

Example usage

Query:

wget -q -O- "http://localhost:8080/BaltradDex/supervisor.htm?reporters=db.status"

Response:

<?xml version="1.0" encoding="UTF-8"?>
 
<system-status>
<reporter name="db.status" value="" status="OK"/>
</system-status>

Reporter name: bdb.status

This reporter will verify that the node has connection with the bdb server.

Arguments

N/A

Example usage

Query:

wget -q -O- "http://localhost:8080/BaltradDex/supervisor.htm?reporters=bdb.status"

Response:

<?xml version="1.0" encoding="UTF-8"?>
 
<system-status>
<reporter name="bdb.status" value="" status="OK"/>
</system-status>

Reporter name: radar.connection.status

This reporter can be used to control if a radar has been able to provide the composites and volumes with data without causing a timeout. If, for example, a composite is expecting a scan from searl and this scan does not arrive within the timeout. Then, this reporter will know about that. This reporter is a faster version of a product tester but not as accurate as the bdb object status reporter.

Arguments

Name	Description
sources	A comma separated list of source names, e.g. searl,seang

Example usage

Query:

wget -q -O- "http://localhost:8080/BaltradDex/supervisor.htm?reporters=radar.connection.status&sources=searl,seang"

Response:

<?xml version="1.0" encoding="UTF-8"?>
 
<system-status>
<reporter name="radar.connection.status" value="sources=searl,seang" status="OK"/>
</system-status>

Reporter name: bdb.object.status

This reporter is currently the most advanced reporter mechanism. It queries the baltrad db for availability of objects (SCAN,PVOL,COMP,...) for sources (searl, seang, ...) and areas (swegmaps_2000, ...) within a specific time limit in minutes. This means that you are able to query for almost anything within the database and verify if you have got it in time. However, the caveat to this is that it is a quite expensive version of reporter so make sure that you don't affect perforance drastically by calling this reporter too frequently. You might notice that the performance for handling incomming data will decrease if you continuously call this reporter.

Arguments

Name	Description
minutes	The time limit backward in time to check in minutes. E.g. 5. Default 5
objects	A comma separated list of what/object types that should be looked up, for example SCAN,PVOL,COMP
sources	A comma separated list of sources (used with SCAN,PVOL,...), for example searl,seang
areas	A comma separated list of sources (used with COMP,...), for example swegmaps_2000

You can combine for example SCAN,PVOL and COMP together with a list of sources and areas.

Example usage

Query if a SCAN from seang and a COMP for area swegmaps_2000 has arrived within the last 5 minutes.

wget -q -O- "http://localhost:8080/BaltradDex/supervisor.htm?reporters=bdb.object.status&sources=seang&areas=swegmaps_2000&objects=SCAN,COMP&minutes=5"

Response:

<?xml version="1.0" encoding="UTF-8"?>
 
<system-status>
<reporter name="bdb.object.status" value="sources=seang&amp;areas=swegmaps_2000&amp;objects=SCAN&amp;minutes=5" status="OK"/>
</system-status>