WebConsole is functionally divided into units referred to as Modules. Each module in WebConsole has a separate top level menu item in the main navigation menu on the left hand side of the page.

Complete documentation for each WebConsole module is provided as online help, accessible as a link on the left hand side of the WebConsole page.

WebConsole is composed of the modules described below.

For detailed instructions on installing and configuring WebConsole please refer to the Server Installation Guide.

The first time WebConsole is started you will need to add at least one user in order to operate a BigWorld server. To achieve this, from the front page of WebConsole, login with a username / password of admin. If you have never loaded the WebConsole homepage before, it should be visible at the url http://hostname:8080, where hostname is the network name of the machine you install WebConsole on.

Once logged in you should be presented with a webpage similar to the following.

3.1.3.1. Adding A New User

To add a new user, click on the "Add New User" menu item on the left hand side of the page. You will then be presented with a form to input as follows:

The table below summarises the input fields providing sample input:

Field	Description
Username	The username that for the new user.
Password	The password with which the new user will log in.
Confirm Password	The password from the previous field, retyped to ensure no mistake was made on entry.
Server User	The Linux user this account will be associated with. This will be the Linux user that the BigWorld server processes will be run as. If you are uncertain of this field, please talk to your system administrator to find out what your Linux user account is.

The following image shows a new user account AliceB being created and associated with the Linux user account alice:

Once all the user information has been entered, simply click the Add User button and you will be returned to the main user listing, which will include the new user:

WebConsole can be started using two methods, as a system wide service or from the command line.

Generally, only developers working on modifying the web page templates or underlying code will run WebConsole from the command line. In order to achieve this, make sure that the current directory is bigworld/tools/server/web_console, then issue the command:

$ ./start-web_console.py

There are some minor operational differences when running WebConsole in command line mode vs as a system service:

Running in development mode leaves the web server in a state where an automatic restart is triggered if there are any changes to the template files or Python code it is using.

The production configuration file does not exist by default in bigworld/tools/server/web_console, as it is partially generated during the installation process while using the install_tools.py script. The original production configuration file that the installation script uses is bigworld/tools/server/install/web_console.cfg.

Both configuration files need to specify the database to use. Before running WebConsole, make sure that the appropriate configuration file has a line that looks like this:

sqlobject.dburi="notrans_mysql://username:password@localhost:3306/bw_web_console"

Specifying the database

To modify the bigworld/tools/server/install/web_console.cfg file to a working configuration file, replace the line:

###BW_SQLURI###

with an sqlobject.dburi line as indicated above.

For information regarding TurboGears configuration files and content, we recommend the TurboGears documentation website http://docs.turbogears.org/1.0/Configuration.

If you have never run WebConsole before and choose to run it from the command line (as opposed to installing the system service), it is necessary to create a database for WebConsole within MySQL. To do this, connect to your MySQL database using the username and password that you have defined in dev.cfg, then issue the following command:

CREATE DATABASE bw_web_console;

As WebConsole is a convenient interface to your cluster environment, it may be useful to add new content to WebConsole that is unique to your companies requirements. To achieve this please refer to the Server Programming Guide chapter Web Console.

Except where overridden by the corresponding command line option, Message Logger reads its configuration from the file bigworld/tools/server/message_logger/message_logger.conf.

The configuration file is in standard Windows INI file format, and supports the following options:

Message Logger generates log files in a binary format in order to make the best use of disk space as possible. In order to access the binary logs, two Python modules are provided:

For examples on how to use these modules, browse the source code of the command-line message logger utilities described in Command Line Utilities.

Message Logger generates logs in a two level directory structure. The top level directory contains files that are common to all users, and contains one sub directory per user. The files in the top level directory are:

Each user's sub directory has a file containing its UID, as well as the following files:

The bigworld/tools/server/message_logger directory contains a variety of command line utilities providing the functionality of standard UNIX shell utilities for BigWorld message logs. Using these utilities you can operate on the binary logs using standard UNIX shell utilities and pipelines in the same way you can with ordinary text files.

The following tools are provided:

The detailed documentation for each utility is maintained as online help, which can be accessed via the --help option.

The following list provides some common examples of tasks you might wish to achieve using the Message Logger tools:

The Linux logrotate scripts are used to rotate (stop writing an old log file and start writing to a new file), archive (backup the old log file), and delete (log files deemed to be past an expiry time) log files on a daily basis, which can assist in conserving disk space. A logrotate configuration file, /etc/logrotate.d/bw_message_logger, is set up as part of the Server Tools installation. For more information about logrotate, please see the logrotate manpage:

$ man 8 logrotate

There are two issues to consider when customising the logrotate:

In order to assist Message Logger coping with heavy network and disk load in production environments, Message Logger supports logging subsets of machines within a server cluster. This is achieved by assigning a Message Logger process a list of machine groups that it should accept logs from, as well as assigning every machine in the cluster to a machine group. Both Message Logger and cluster machines may be assigned to multiple machine groups. In order to enable this feature both MessageLogger and BWMachined will need to be configured correctly throughout your cluster environment.

To limit a Message Logger process to only accept logs from a set of machine groups requires adding a comma separated list of group names to a groups entry in the file bigworld/tools/server/message_logger/message_logger.conf. For example, to assign a MessageLogger process to only accept logs from the machine groups QA_Cluster1 and QA_Cluster2 the following entry would be placed in message_logger.conf:

[message_logger]
...
groups = QA_Cluster1, QA_Cluster2

MessageLogger needs to be restarted in order to detect these changes, however once restarted an entry should appear in the MessageLogger log file /var/log/bigworld/message_logger.log similar to the following:

2008-11-12 11:37:20: INFO: Logger::init: MessageLogger machine groups specified. Only accepting logs from: QA_Cluster1, QA_Cluster2

For details on configuring BWMachined see Configuration.

The list below describes the requirement for running StatLogger:

StatLogger must be run on the same local network as the BigWorld server processes that it is intended to monitor due to the manner in which machine and server component discovery occurs.

StatLogger requires a valid MySQL user with access to create databases. Normally the creation and configuration of this MySQL user is handled during the tools installation process^[5], but an existing database user can be can used instead, by manually editing the configuration file. For details, see Configuration.

StatLogger outputs various status messages describing which machines and processes it discovers or loses (i.e., from the process or machine shutting down) from the network, each prefixed with a timestamp.

When running StatLogger manually from the command line the default is to display this information to the terminal on which it is run unless the -o option is specified.

When installed as a daemon, these messages output to the log file /var/log/bigworld/stat_logger.log by default. This log file is specified by the LOG_FILE variable in /etc/init.d/bw_stat_logger.

As Stat Logger is responsible for collecting a constant stream of data from an arbitrarily large BigWorld server cluster for historical tracking it is necessary to prevent the database size from growing out of proportion. In order to achieve this Stat Logger implements a mechanism of aggregating and merging data from high resolution time periods into lower resolution time scales the older the data becomes. This approach allows high resolution data to be maintained for recent events when diagnostics are most likely to occur but allows a broad view of server performance over a long scale to be maintained. More information on customising how StatLogger aggregates data can be found below in Aggregation Window Configuration.

Located in StatLogger's directory, the preference file preferences.xml is used to configure the script. The preference file can be used to configure:

Apart from the database user configuration, in most cases the provided standard settings should be sufficient for development and production environments.

The preferences.xml file configures database setup options, as well as what data StatLogger should collect from the server components and machines.

<preferences>
  ...
  <collect>
    <aggregation>
      *<window>
         <samples>           <num_samples_in_this_win>   </samples>
         <samplePeriodTicks> <num_of_ticks_per_sec>      </samplePeriodTicks>
       </window>
      ...

<preferences>
  ...
  <collect>
    <aggregation>

      <!-- Every sample (2secs) in most recent 24hrs. 43200 samples -->
      <window>
        <samples>           43200 </samples>
        <samplePeriodTicks> 1     </samplePeriodTicks>
      </window>

      <!-- Every 10th sample (20secs) in most recent 48hrs. 8760samples -->
      <window>
        <samples>           8760  </samples>
        <samplePeriodTicks> 10    </samplePeriodTicks>
      </window>

      <!-- Every 150th sample (5mins) in most recent 30 days. 8760 samples -->
      <window>
        <samples>           8760  </samples>
        <samplePeriodTicks> 150   </samplePeriodTicks>
      </window>

      <!-- Every 1800th sample (60mins) in most recent 365 days. 8760 samples -->
      <window>
        <samples>           8760  </samples>
        <samplePeriodTicks> 1800  </samplePeriodTicks>
      </window>

      <!-- Every 43200th sample (1day) in most recent 365 days. 365 samples -->
      <window>
        <samples>           365   </samples>
        <samplePeriodTicks> 43200 </samplePeriodTicks>
      </window>
    </aggregation>
   ...

<preferences>
  ...
  <collect>
    ...
    <processList>
      <process>
        <name>      CellApp </name>
        <matchtext> cellapp </name>
        <statisticList>
          ...
        </statisticList>
      </process>
      ...

<preferences>
  ...
  <collect>
    ...
    <processList>
      <process>
        <name>      CellApp </name>
        <matchtext> cellapp </name>
        <statisticList>
          <statistic>
            <name>        Cell Load                </name>
            <valueAt>     /load                    </valueAt>
            <maxAt>       1.0                      </maxAt>
            <logicalMax>  None                     </logicalMax>
            <type>        FLOAT                    </type>
            <consolidate> AVG                      </consolidate>
            <display>
              <colour>    #FF6600                  </colour>
              <show>      true                     </show>
              <description>      
                  The load of this CellApp.
              </description>
            </display>
          </statistic>
          <statistic>
            <name>        Num Entities Ever        </name>
            <valueAt>     /stats/totalEntitiesEver </valueAt>
            <maxAt>       10000.0                  </maxAt>
            <type>        FLOAT                    </type>
            <consolidate> MAX                      </consolidate>
            <display>
              <colour>    #663366                  </colour>
              <show>      false                    </show>
              <description>      
                  The number of entities created on the CellApp since server startup.
              </description>
            </display>
          </statistic>
          ...

StatLogger uses two active databases during its operation, however over an installation's life multiple databases may be created as StatLogger options are modified.

The two active databases required by StatLogger are:

By default, the meta database is named bw_stat_log_info and contains a single table called bw_stat_log_databases. The bw_stat_log_databases table stores the names of all the known statistics databases. The meta database is always created if it does not exist in the MySQL server.

The statistics databases by default are named bw_stat_log_data<n>, where <n> is the incremental database number. Users can choose to create statistics databases with specific names using the -n option when running StatLogger.

New statistics databases are created in the following situations:

There is typically no need to create new statistics databases unless isolated sets of statistics are needed. This may occur when performing tests with the BigWorld server. Once StatLogger has been configured to suit your environment only one statistics database should be needed.

Location: bigworld/tools/server/control_cluster.py

Control Cluster is a command line tool for managing a BigWorld cluster from a text only interface.

For detailed information on all the available commands, please refer to the Control Cluster help by using the --help option.

$ ./control_cluster.py --help

For detailed help information on a specific command simply provide the command name after the --help option. For example:

$ ./control_cluster.py --help getmany
getmany <processes> [watcher-path]

   Queries the specified watcher path on all processes of the specified type
   currently active in the cluster. The path can contain '*' wildcards.

Control Cluster provides functionality through a number of commands that can be used to interact within a BigWorld server environment. The commands can be discussed in terms of four functional areas.

$ ./control_cluster.py help start
start <machines>

   Start the server on the specified set of machines.  To start the server on
   all machines, you must explicitly pass 'all' for machine selection.

$ ./control_cluster.py help machine-selection

$ ./control_cluster.py help process-selection

For details on the tools available for interacting with server message logs, see Command Line Utilities.

When running SpaceViewer if you do not see your username listed in the main Space Viewer window, select the File → Refresh menu item. This is sometimes required as the list is not automatically updated.

Clicking the arrow icon to the left of user name expands the list to display all spaces available for that server instance.

In the example above, the dominicw server has 4 spaces. To view the top down map of a space, double click its entry on the list. This will start an SVLogger process which will log data from the selected space as well as a new client window that attaches itself to the logger. Closing the client window will cause the logger to terminate.

Multiple spaces can be viewed simultaneously, each in their own window. To view a space, double-click its entry on the space list displayed in Space Viewer.

The image below shows a space being managed by five cells. Cell 2 is currently selected as can be seen by the thick blue border and coloured circles representing all the entities within the cell. Entities that are being ghosted on cell 2 are displayed as greyed out circles.

Upon first loading the space window no cell is selected for viewing. The cell boundaries and the cell information (cell number, IP address, load) will always be shown, however to see the entities within a particular cell, as with cell 2 in the screenshot below, it must be selected with a single click.

Space window

In order to facilitate identification of entities, tooltip information is available for all non-ghosted entities. This information will appear if the cursor hovers over an entity marker for a sufficiently long time.

Entity tooltip

The entity type name is retrieved from file <res>/scripts/entities.xml.

Space Viewer allows you to customise the colours to be used when drawing the elements in the Space window. Any customisation is not saved and thus will not be in effect the next time the application is started. If you desire to permanently change the colours, this can be achieved by customising the Space Viewer source code.

Entities in the current cell are displayed with a coloured circle. The colour can be customised in the file bigworld/tools/server/space_viewer/style.py. The simplest way to modify the colours is to update the dictionary colours which contain RGB colour definitions for each entity type.

The code fragment below illustrates the definition of permanent entity colours:

# specify colour for specific entity types.
ENTITY_COLOURS = {
    "Avatar"  : ((111, 114, 247), 2.0), 
    "Guard"   : ((244, 111, 247), 1.0), 
    "Creature": ((124, 247, 111), 1.0), 
    "Merchant": ((114, 241, 244), 1.0)  
}

Example local file style.py

An alternate approach would be to replace the entire function getColourForEntity( entityID, entityTypeID ), using your own algorithm to colour the entities.

All other colours are defined by the dictionary colourOptions. This dictionary can be modified to any of the colours defined by the colours array.

As described at the start of this section, Space Viewer's two components can be run separately if required. This would usually take the form of running SVLogger over an extended period of time, connecting clients to it to monitor live state as necessary, then eventually shutting down the logger. Later, SVLogger can be connected to its previously recorded log (instead of a live server) and client windows can be attached to it to replay the log data.

$ ./svlogger -o /home/alice/space_logs

$ ./space_viewer --connect 192.168.1.24:20110