Enable Metrics Data For The SWG Server - SWG-Source/swg-main GitHub Wiki

The Central Server uses the Stella Bellum Web API to send information via JSON requests to a specified web script containing server status information, although there are countless possibilities for future expansion.

Enabling the Metrics Server: To enable the Metrics Server Status features, include the following in your localOptions.cfg file:

[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 interpret the data packed into status.txt and to display readable user-friendly information (some programmatic suggestions of which are also found below).

$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:

$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:

$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.

$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:

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:

	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)');
	}