Skip to content

Latest commit

 

History

History
77 lines (50 loc) · 4.82 KB

Readme.statuspage.md

File metadata and controls

77 lines (50 loc) · 4.82 KB
Raw

FGCom-mumble - a flightsim radio simulation framework based on mumble

Status website for FGCom-mumble

The status page aims to provide an overview about currently connected clients, their positions and radio frequencies as well as occuring ATIS broadcasts.

For this, the webpage consists of three components:

  • A PHP website, showing the current status out of a shared data interface.
  • A special bot that collects current client information and feeds it to a shared data interface.
  • The shared data interface.

The reason for this setup is, that the information should be gathered asynchronuosly so the webpage can answer as fast as possible. The possibility of overloading of the mumble infrastructure trough excessive web requests is also avoided.
To display all information of the radio state, we need some deeper view into the clients data, which cannot be provided from the ICE-bus at this time (an idea might be to collect this information from the clients comments, once the mumble-API allows changing them. This would remove the need for a bot generating that info for us).

Setup requirements

  • a Webserver supporting PHP
  • PHP >= 7.0.0 (probably php5 might work too)
  • gnuplot (optionally; for visualizing usage stats)
  • Lua: See Readme.server.md

Deployment

Webpage

Just define a new webroot and set it to the directory containing index.php. Configure your webserver to deliver index.php via the PHP interpreter.

Copy the config.dist.ini to config.ini. You also may want to adapt the webpage configuration file.

JSON output for integration

When enabled in the config, the statuspage can output JSON formatted data at http://<host>:<port>/?raw. The format is currently the same as the shared data interface (see below).

mumble status bot

The bot will usually be started from the bot manager script, but in case you want to start it manually, fgcom-status.bot.lua -h gives usage information.

The bot will initialize the database at startup, if not done yet. For this he will wipe clean an existing database. then he asks all other FGCom clients to provide their data to the bot, who will add it to the database.

usage statistics

The status bot can also write usage statistics to a file. Use --stats <file> to specify which file should be appended.
The generated file can be parsed trough gnuplot to generate a graph png image, see the stats2png.gnuplot file for instructions.

If enabled from the statuspage's config.ini, a link can be added to the status page footer, leading to a dynamically autogenerated gnuplot usage statistic image.

The displayed timeframe defaults to the last week, but may be altered using the following GET-parameters (Timestamps are in YYYYmmdd[HHMM] format and refer to UTC):

  • last: ammount of hours to display from now into the past
  • from: fixing the selected timeframe start to this timestamp (last will be ignored obviously)
  • to: fixing the selected timeframe end to this timestamp

The usage statistics file is ever growing. To keep disk usage and gnuplots runtime under control, you can easily truncate the usage file by deleting lines from the head of the file. Most easily you can do this by using a cronjob (the example below keeps the most actual 2600000 lines; ie. about three months with default 60s update interval):

# m h  dom mon dow   command
30  3  *   *   1     tail -n 2600000 /tmp/fgcom-usage.stats > /tmp/fgcom-usage.stats.trunc; mv /tmp/fgcom-usage.stats.trunc /tmp/fgcom-usage.stats

Shared data interface

The shared data interface is currently a simple file containing json records. The bot and the webpage must be pointed to the same file. The bot is the data povider, the webpage the consumer.

The default path is /tmp/fgcom-web.db so the database lives in memory and usually won't survive a reboot. You probably want to change that in the statusbot and statuspage configs in order to get persistence, especially for the highscore.

Schema description

There is just a single table containing metadata and a table with the information per connected client. In addition to that, the timestamp-collumn "updated" will contain the last time the data was updated. The webpage will skip old entries.

The format is a JSON structure: {"clients":[<clients_data-1>, <clients_data-n>],"meta":{<metadata_struct>}}

  • "clients": array holds elements representing one user record each: {"type":"client", "callsign":"Calls-1", "radios":[<radio1>, <radio-n>"], "lat":12.3456, "lon":20.11111, "alt":1234.45, "updated":1111111122}
  • "radio" holds the state of a radio: {"frequency":"123.45000", "dialedFRQ":"123.45", "operable":1, ...}
  • "meta": metadata table {"highscore_num":12,"highscore_date":1599719381}