Location: PHPKode > projects > SyStats > doc/Parser.html
<html>
<head>
	<title>SyStats - Parser Configuration and Usage</title>
	<link href="styles.css" rel="stylesheet" type="text/css"/>
</head>
<body>

<center>
<div id="Frame">

	<h1>3. Parser Configuration and Usage</h1>
	<span id="Version">Last update : 22/09/2004 (for SyStats 0.9.9)</span>
	
	<h2>Table of Content</h2>
	
	<div id="TOC">
		<div class="TOC1"><a href="#Purpose">3.1 Purpose</a></div>
		<div class="TOC1"><a href="#RequiredFiles">3.2 Required Files</a></div>
		<div class="TOC1"><a href="#Configuration">3.3 Configuration</a></div>
		<div class="TOC1"><a href="#Usage">3.4 Usage</a></div>
		<div class="TOC1"><a href="#Automation">3.5 Automation</a></div>
		<div class="TOC2"><a href="#TaskScheduler">3.5.1 Microsoft Windows Task Scheduler</a></div>
		<div class="TOC2"><a href="#CronJobs">3.5.2 Linux Cron Jobs</a></div>
	</div>
	
	
	<h2 id="Purpose">3.1 Purpose</h2>

	<p>
	The purpose of the parser is to read the game server's log file and interpret the log entries into game actions
	that happened on the server. It is responsible for recognizing player names, kill events, dynamites, player class
	changing, game start, game end, etc. Each of these events generate one or more database queries to update
	information concerning one or more players.
	</p>

	<p>
	Some administrators have asked me if they can host SyStats if they have access to a Apache/PHP/MySQL web server.
	Although this is a good start, and actually a requirement on its own as well, it is not the only requirement to
	use SyStats. You must have access to the game server's log file and be able to execute the SyStats parser to read
	this log file and translate it into the database.
	</p>


	<h2 id="RequiredFiles">3.2 Required Files</h2>
	
	<p>
	Running the SyStats parser requires only two files. These files can be found in the /bin directory of the SyStats package.
	The parser binary (SyStats.exe under Windows and 'systats' or 'systats-static' under Linux) and the configuration file (systats.conf).
	The first step before running the parser is to prepare the configuration file. The following section describes this configuration step.
	</p>
	
	<h2 id="Configuration">3.3 Configuration</h2>

		<table cellspacing="0">
			<tr>
				<th colspan="5">*************************** GENERAL CONFIGURATION OPTIONS ***************************</th>
			</tr>
			<tr>
				<th>Option</th>
				<th>Description</th>
				<th>Type</th>
				<th>Possible Values</th>
				<th>Version</th>
			</tr>
			<tr class="Row">
				<td>MessageFile</td>
				<td>
					Name of the file that will receives all the messages logged by the SyStats parser. 
					If a file already exist with this file name, it will be overwritten.
				</td>
				<td>String</td>
				<td>Filename</td>
				<td><br/></td>
			</tr>
			<tr class="RowAlt">
				<td>MessageLevel</td>
				<td>
					Specify the level of message you wish to be displayed in the message file.<br/>
					Possible levels are:
					<ul>
						<li><code>ERROR</code> : display only error messages</li>
						<li><code>WARNING</code> : display all warning and error messages</li>
						<li><code>INFO</code> : display all info, warning and error messages</li>
						<li><code>DEBUG</code> : display all messages (this setting is recommended 
						for debugging purposes as it generates a lot of information)</li>
					</ul>
				</td>
				<td>String</td>
				<td>ERROR, WARNING, INFO, DEBUG</td>
				<td><br/></td>
			</tr>
			<tr class="Row">
				<td>Actions</td>
				<td>Define the actions that must be taken by the parser.
					Separate each action by a space.
					Valid values are the following :
					<ul>
						<li><code>'parselog'</code> : Parse the log file specified in LogFile and updates the database's stats
						<li><code>'globals'</code> : Calculate and update the global stats (present in the 'General Statistics' on the main page)
						<li><code>'awards'</code> * : Calculate and update the awards table 
						<li><code>'ranks'</code> * : Calculate and update the 'ranks' table
					</ul>
					* these update actions are costly on the database and should be executed not too frequently
				</td>
				<td>String</td>
				<td>parselog, globals, ranks, awards</td>
				<td>0.9.9b7</td>
			</tr>
			<tr class="RowAlt">
				<td>Database</td>
				<td>
					Specify database connection information
					The connection string should look like this <code>user:hide@address.com:port/database</code>
				</td>
				<td>String</td>
				<td><br/></td>
				<td><br/></td>
			</tr>
			<tr class="Row">
				<td>GameType</td>
				<td>
					Type of the game running on the server.
				</td>
				<td>String</td>
				<td>ET, RTCW, RTCW-osp, RTCW-shrub</td>
				<td><br/></td>
			</tr>

			<tr>
				<th colspan="5">*************************** AWARDS COMPUTING OPTIONS ***************************</th>
			</tr>
			<tr>
				<th>Option</th>
				<th>Description</th>
				<th>Type</th>
				<th>Possible Values</th>
				<th>Version</th>
			</tr>
			<tr class="Row">
				<td>AwardMinTime</td>
				<td>
					Minimum amount (in hours) of play time that a player must gather in order
					to be listed in the awards list on the main page.
				</td>
				<td>Numeric</td>
				<td>Number of hours</td>
				<td><br/></td>
			</tr>

			<tr>
				<th colspan="5">*************************** LOG PARSING OPTIONS ***************************</th>
			</tr>
			<tr>
				<th>Option</th>
				<th>Description</th>
				<th>Type</th>
				<th>Possible Values</th>
				<th>Version</th>
			</tr>

			<tr class="Row">
				<td>LogFile</td>
				<td>
					Name of the game's log file to be parsed (most likely etserver.log for 
					Enemy Territory or server.log for Return to Castle Wolfenstein).
				</td>
				<td>String</td>
				<td>Filename</td>
				<td><br/></td>
			</tr>
			<tr class="RowAlt">
				<td>ETLastCampaignMaps</td>
				<td>
					Specify the last map(s) for the Enemy Territory Campaigns.
					For example, if your server is using both African and European campaigns, 
					<ul>
						<code>ETLastCampaignMaps = fueldump goldrush</code>
					</ul>
					This is used to trigger database update for XP points (XP points are 
					cumulative and are stored only at the end of the campaign or when the player disconnects)
				</td>
				<td>String</td>
				<td>map list</td>
				<td><br/></td>
			</tr>
			<tr class="Row">
				<td>XPSave</td>
				<td>
					Specify whether or not XP is saved upon disconnection (depending on your shrubet/ETPro configuration)
					Make sure you set the correct value for your server configuration or the XP you will see in the
					stats will not be accurate.
					Valid values are the following:
					<ul>
						<li><code>campaign</code> : specify that XP is saved if the player rejoins before the end of the campaign
						<li><code>server</code> : specify that XP is always saved until the server restarts
						<li><code>no</code> : specify that XP is never saved (lost upon disconnection of the player)
					</ul>
				</td>
				<td>String</td>
				<td><code>campaign, server, no</code></td>
				<td><br/></td>
			</tr>
			<tr class="RowAlt">
				<td>PlayerTracking</td>
				<td>
					Specify how players are tracked
					Valid values are the following:
					<ul>
						<li><code>guid</code> : track player by their GUID (works only with ETpro or shrubet)
						<li><code>name</code> : track player by their name 
						(if 'playerA' renames to 'NoobPlayer', two player entities are created, each having its own stats)
						<li><code>alias</code> : track player by their alias
						(if 'playerA' renames to 'NoobPlayer', the name change will be saved and no other player entity will be created)
					</ul>
				</td>
				<td>String</td>
				<td><code>guid, name, alias</code></td>
				<td><br/></td>
			</tr>
			<tr class="Row">
				<td>DisplayProgress</td>
				<td>
					Specify whether of not to display the progress of the log parsing
				</td>
				<td>Boolean</td>
				<td><code>true, false</code></td>
				<td><br/></td>
			</tr>
			<tr class="RowAlt">
				<td>IncrementalParsing</td>
				<td>
					Specify whether (true) or not (false) the parser should perform
					incremental parsing of the log file.
					Incremental parsing will remember the place where it finished parsing the
					log file and start back to that place upon another invocation.
					This is a replacement to log file rotation.
				</td>
				<td>Boolean</td>
				<td><code>true, false</code></td>
				<td><br/></td>
			</tr>
			<tr class="Row">
				<td>GameParams <br/>(unused)</td>
				<td>
					Enter the game parameters (separated by spaces) that you wish to be saved into the database.
					"mapname" is always saved as a reference to the game map.
					For example, enter the following string "<code>gamename g_gametype version</code>" to save all these three game parameters.
				</td>
				<td>String</td>
				<td><br/></td>
				<td><br/></td>
			</tr>
			<tr class="RowAlt">
				<td>PlayerExclude</td>
				<td>
					Enter the list of player names to filter out from the log.
					For example, do not process events for ETPlayer and WolfPlayer.
					Note : Player names are case incensitive and will be checked once color codes are removed.
				</td>
				<td>String</td>
				<td><br/></td>
				<td><br/></td>
			</tr>
			<tr class="Row">
				<td>PlayerFilter</td>
				<td>
					Enter a list of strings that must not be present in a player's name.
					For example, do not process events for players that have profanious words.
					Note : Strings are case incensitive and will be checked once color codes are removed.
					Therefore "Fuckhead" and "F^0u^3cKHead" will both be removed.
				</td>
				<td>String</td>
				<td><br/></td>
				<td><br/></td>
			</tr>
			<tr class="RowAlt">
				<td>ParseChat</td>
				<td>
					Import chat messages from players (used to compute statistics on the number of messages 
					as well as the last message send by the player).
				</td>
				<td>Boolean</td>
				<td><code>true, false</code></td>
				<td><br/></td>
			</tr>
			<tr class="Row">
				<td>RoundMinPlayers</td>
				<td>
					Minimum number of players to count the win/loss statistic.
					If a round ends with less that this specified number of players, the 
					number of rounds, wins and losses will not be updated. However, player
					statistics like kills, deaths, dynamites, etc. are still being updated 
					during these rounds.
				</td>
				<td>Numeric</td>
				<td><br/></td>
				<td><br/></td>
			</tr>
			<tr class="RowAlt">
				<td>SaveState</td>
				<td>
					Specify whether or not the game server's state must be saved/resumed upon parsing
					the log file. The game server's state includes information about the map
					currently playing when the last parsing stopped, the time offset when that
					round started, all the information about connected players, their class, team, etc.
				</td>
				<td>Boolean</td>
				<td><code>true, false</code></td>
				<td>0.9.9b7</td>
			</tr>
			<tr class="Row">
				<td>ResumeState</td>
				<td>
					Specify whether or not the game server's state must be resumed upon parsing
					the log file. The game server's state includes information about the map
					currently playing when the last parsing stopped, the time offset when that
					round started, all the information about connected players, their class, team, etc.
				</td>
				<td>Boolean</td>
				<td><code>true, false</code></td>
				<td>0.9.9b7</td>
			</tr>
			<tr class="RowAlt">
				<td>StateLocation</td>
				<td>
					Specify where to store the game server's state. For frequent parsing (< 10 minutes) 
					or when using the -line option of the parser, it is recommended to use 'file' state saving. 
					In other cases, you should use 'database'.
					Valid values are the following:
					<ul>
						<li><code>file</code> : save the game server's state into text files (you must not remove/modify these files)
						<li><code>database</code> : save the game server's state into database tables
					</ul>
				</td>
				<td>String</td>
				<td><code>file, database</code></td>
				<td>0.9.9b7</td>
			</tr>
		</table>

	<h2 id="Usage">3.4 Usage</h2>
	
	<p>
	Running the parser is pretty simple. You need to open up a command prompt (under Windows) 
	or a shell (under Linux) and type the following command:
	<pre>
		systats systats.conf
	</pre>

	<p>
	<div class="New">New in SyStats 0.9.9 beta7</div>
	By default the parser uses the systats.conf that is present in the same directory as the program. Therefore,
	you can ommit the 'systats.conf' argument if you are using the file within the same directory.

	<p>
	Also, it is possible to overwrite options in the configuration file with command line arguments using the following
	syntax:
	<pre>
		systats systats.conf -Actions "parselog globals" -MessageFile parse_globals.log
		systats systats.conf -Actions "ranks awards" -MessageFile ranks_awards.log
	</pre>


	<p>	
	<img src="Images/Parser Usage.jpg" class="ClickableImage" width="250" height="124" alt="Parser Usage" onclick="window.open('Images/Parser Usage.jpg', '_blank', 'location=no,toolbar=no,menubar=no,scrollbars=yes');"/>
	
	<p>
	If you are unsure on how to open and use a Windows command prompt, consult the <a href="FAQ.html">FAQ</a>.
	</p>

	<h2 id="Automation">3.5 Automation</h2>
	
	<h3 id="TaskScheduler">3.5.1 Microsoft Windows Task Scheduler</h3>
	<p>
	If you are planning to use the SyStats parser under Microsoft Windows and you have an always running 
	game server on which you want to periodically update the stats, I recommend you setup a scheduled 
	task that will periodically fire up the parser at some specific time. The following section shows 
	you the simple steps needed to setup SyStats as a Windows Scheduled Task. This tutorial is made
	on my Windows XP machine. I assume that other versions of Microsoft Windows have similar ways to setup
	the scheduled tasks. Just play around.
	</p>
	
	<p>
	The first step is to open up the list of currently scheduled tasks:
	</p>
	
	<img src="Images/Task Scheduler/Start.jpg" class="ClickableImage" width="250" height="127" alt="Start Task Scheduler" onclick="window.open('Images/Task Scheduler/Start.jpg', '_blank', 'location=no,toolbar=no,menubar=no,scrollbars=yes');"/>
	<img src="Images/Task Scheduler/AddTask.jpg" class="ClickableImage" width="250" height="205" alt="Add Scheduled Task" onclick="window.open('Images/Task Scheduler/AddTask.jpg', '_blank', 'location=no,toolbar=no,menubar=no,scrollbars=yes');"/>
	</p>
	
	<p>
	Afterwards, click on 'Add Scheduled Task' and follow the steps. The first step prompts you to select 
	the program to be run periodically. Simply click on 'Browse' and select the SyStats.exe file from the 
	SyStats package. The next steps allow you to select how often you want the program to be called. At this
	moment, the highest frequency you can select is 'Daily'. You can also set the time at which you want the 
	stats to be generated.
	</p>
	<img src="Images/Task Scheduler/Select SyStats.jpg" class="ClickableImage" width="250" height="194" alt="Select SyStats Parser" onclick="window.open('Images/Task Scheduler/Select SyStats.jpg', '_blank', 'location=no,toolbar=no,menubar=no,scrollbars=yes');"/>
	<img src="Images/Task Scheduler/Frequency.jpg" class="ClickableImage" width="250" height="180" alt="Task Frequency" onclick="window.open('Images/Task Scheduler/Frequency.jpg', '_blank', 'location=no,toolbar=no,menubar=no,scrollbars=yes');"/>
	<img src="Images/Task Scheduler/Date.jpg" class="ClickableImage" width="250" height="180" alt="Execution Time" onclick="window.open('Images/Task Scheduler/Date.jpg', '_blank', 'location=no,toolbar=no,menubar=no,scrollbars=yes');"/>
	
	<p>
	The next step allows to specify with which user must the program be run. You can use your own user 
	account and password to execute the program. Afterwards, make sure you check the 'Open advanced 
	properties for this task when I click Finish' checkbox. On the dialog that pops up, type in the path 
	to the systats.conf right after the name of the SyStats executable. If the path to systats.conf contains 
	white spaces, enclose it with "" like the following : D:\WORK\SyStats\systats\bin\SyStats.exe "E:\My Directory\systats.conf".
	</p>
	
	<img src="Images/Task Scheduler/Conf.jpg" class="ClickableImage" width="250" height="276" alt="Parser Configuration" onclick="window.open('Images/Task Scheduler/Conf.jpg', '_blank', 'location=no,toolbar=no,menubar=no,scrollbars=yes');"/>
	<img src="Images/Task Scheduler/Advanced Schedule.jpg" class="ClickableImage" width="250" height="205" alt="Advanced Schedule" onclick="window.open('Images/Task Scheduler/Avanced Schedule.jpg', '_blank', 'location=no,toolbar=no,menubar=no,scrollbars=yes');"/>
	
	<p>
	Once this is done, you're all setup and stats should be compiled automatically in the background.
	</p>
	
	
	<h3 id="CronJobs">3.5.2 Linux Cron Jobs</h3>
	<p>
	I don't want to go into details about Linux cron jobs since I'm not a Linux administrator. I'm simply
	a power user at home. :) Interfaces to add/modify/delete cron jobs differ from one distribution to another
	and I assume that you are familiar with your current distribution.
	</p>
	
	<p>
	Here's a little cron job that was submitted to me by Marc Vanbrabant from fragland.net: 
	<pre>
	#!/bin/bash
	/home/gamed/systats/bin/systats-static /home/gamed/systats/bin/systats.conf
	cat /home/gamed/.etwolf/etmain/etserver.log>>/home/gamed/.etwolf/etmain/etserverfull.log >/home/gamed/.etwolf/etmain/etserver.log
	</pre>

	He also mentions that he had set up this cron job to execute every 30 minutes (which sounded like a reasonable and yet performant enough interval).
	</p>
	
</div>
</center>
</body>
</html>
Return current item: SyStats