From d3b7a985ca9cfff4e1072f45e6f7e6e2d9dc6a8c Mon Sep 17 00:00:00 2001 From: IrishDarkshadow Date: Fri, 28 Aug 2020 16:35:08 +0100 Subject: [PATCH] Written by Aconite --- Enable-Metrics-Data-For-The-SWG-Server.md | 83 +++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 Enable-Metrics-Data-For-The-SWG-Server.md diff --git a/Enable-Metrics-Data-For-The-SWG-Server.md b/Enable-Metrics-Data-For-The-SWG-Server.md new file mode 100644 index 0000000..2a27184 --- /dev/null +++ b/Enable-Metrics-Data-For-The-SWG-Server.md @@ -0,0 +1,83 @@ +The Metrics Server is a component of the source that is responsible for transmitting data from the Central Server about the game environment. Presently, the Metrics Server uses the Stella Bellum Web API to send information via JSON requests to a specified web script and is focused on server status information, although there is countless possibilities for future expansion. + +**Enabling the Metrics Server:** To enable the Metrics Server Status features, include the following in your `localOptions.cfg` file: + +```ini +[CentralServer] + metricsDataURL=https://path-to-script.php + webUpdateIntervalSeconds=60 +``` +The `metricsDataURL` should be the absolute web path to the script you want the metrics server to send information to. The `webUpdateIntervalSeconds` should be the frequency in seconds at which you want the server to send the updates. It should not be necessary for this to be lower than 60 seconds, and could probably be higher. + +**Available Metrics Data:** The `CentralServer.cpp` file in the SRC controls the data that is sent by the metrics server. Currently, you can capture the following data: + +* `clusterName` The name of the cluster (server) +* `totalPlayerCount` The total number of players currently logged into the cluster +* `totalGameServers` The present number of spawned game servers +* `totalPlanetServers` The present number of spawned planet servers +* `totalTutorialSceneCount` The total number of spawned tutorial instances +* `lastLoadingStateTime` The Unix Timestamp at which the cluster was last in a loading state +* `clusterStartupTime` The Unix Timestamp at which the cluster was started +* `timeClusterWentIntoLoadingState` The Unix Timestamp at which the cluster went into a loading state. If the cluster is not loading, this equals 0. + +**Web Script for Getting the Data from the Metrics Server:** The following PHP script is a basic implementation wherein you would specify the location of this script as the `metricsDataURL` and then it would write the status every 60 seconds (as specified by the `webUpdateIntervalSeconds`) to a file called `status.txt` in the same directory, which you could then unpack and use elsewhere. + +You will need a separate script that is used to interpet the data packed into status.txt and to display readable user-friendly information (some programmatic suggestions of which are also found below). + +```php +$data_server = json_decode( file_get_contents( 'php://input' ), true ); + +$lastLoadingStateTime = $data_server['lastLoadingStateTime']; +$timeClusterWentIntoLoadingState = $data_server['timeClusterWentIntoLoadingState']; +$clusterName = $data_server['clusterName']; +$totalPlayerCount = $data_server['totalPlayerCount']; + +$return = array( + 'clusterName' => $clusterName, + 'totalPlayerCount' => $totalPlayerCount, + 'lastLoadingStateTime' => $lastLoadingStateTime, + 'timeClusterWentIntoLoadingState' => $timeClusterWentIntoLoadingState, + ); + +file_put_contents('status.txt', json_encode($return), LOCK_EX); +``` + +**Last Updated Time:** For several purposes as outlined hereunder, and to merely provide the time at which the status was last updated, you may wish to add the following to your status script: +```php +$lastUpdated = time(); +$return = array('lastUpdated' => $lastUpdated) // prepend to the end of the existing $return array +``` +To print this in a "X seconds ago format," you may wish to use something like: +```php +$newTime = time() - $lastUpdated; +$requestLastUpdated = idate('s', $newTime); +echo "Last Updated: " . $requestLastUpdated . " seconds ago."; +``` + +**Record Player Count:** An easy way to determine record player count is to keep an additional file called `players.txt` in the same directory as your `status.txt` file and your metrics script. By adding the following to your metrics script, you will store the record highest player count in `players.txt` and each time the metrics server refreshes the script, compare the `totalPlayerCount` to the record in `players.txt`, and if a new record is reached, it will update the `players.txt` record with that number. You can then display the record player count by reading whatever the number is stored in `players.txt`. +```php +$data_player = file_get_contents('players.txt'); +$highestPlayerCount = $data_player; +if($totalPlayerCount > $highestPlayerCount) { + file_put_contents('players.txt', $totalPlayerCount, LOCK_EX); +} +``` + +**Server Offline/Online** - The easiest way to determine if the server is offline or online is to compare the difference between the current time and the `lastUpdated` object in status.txt. If the lastUpdated object is older than 60 seconds, then the server is no longer sending updates and must be offline. In PHP, for example, this operation is performed with the following check: +```php +if (time() > $lastUpdated + 60) { /* server is offline */ } else { /* server is online */ } +``` +**Uptime/Downtime** - The difference between the current time and the `lastLoadingStateTime` object represents the uptime. The difference between the current time and the `lastUpdated` object represents the downtime. You may wish to use an if statement to use the phrases "uptime" and "downtime," respectively. + +To convert the timestamps into a readable format for uptime/downtime, you may wish to wrap them in a function like: +```php + function secondsToTime($seconds) { + $dtF = new \DateTime('@0'); + $dtT = new \DateTime("@$seconds"); + return $dtF->diff($dtT)->format('%a day(s), %h hour(s), %i minute(s)'); + } +``` + + + +