Tournament Scheduler - Pyosch/powertac-server GitHub Wiki
The idea behind Tournament Scheduler is to provide a simple, easy-to-use tool for creating tournaments and for running experiments on brokers. The Tournament Scheduler is a Java ServerFaces web application that provides a method for brokers to register for upcoming tournaments and communicate game specifics such as start time and logins to the brokers. The Tournament Scheduler also provides a way to run a series of experiments within controlled conditions to test brokers.
The Tournament Scheduler has various responsibities:
- Register brokers for upcoming tournaments
- Communicate authentication and start time information to brokers (via REST api)
- Set up groups of experiments with a high degree of control on game parameters (such as random seeds)
- Store locations of game logs from tournaments and experiments
- Provide easy to understand visualization of game winners for tournaments and experiments according to the game spec
- Provide visualization of games in-progress
- Communication with Jenkins as a Backend server controller to start the server, to clean up failed games, and to clean up successful games (via Jenkins REST api)
Tournament Scheduler Installation
A complete guide to installing your own instance of the Tournament Scheduler is provided here. This guide provide specific step by step instructions for installation include tomcat 7 configuration and jenkins configuration.
Broker Registration
In order for a broker to participate in a competition, the group wishing to submit a broker must register with the Tournament Scheduler. The registration process is a simple web form to provide basic information about your group and broker. Once registered with the Tournament Scheduler you will be provided with an authentication token that your broker will use to communicate with the Tournament Scheduler. This token must be copied into the configuration file of the broker. If you are using the core classes from the sample broker, the token is the value of the property samplebroker.core.powerTacBroker.authToken.
In a tournament setting, brokers do not log in directly to a simulation server, because there may be a number of servers running different games, and they will very likely exit and be restarted between games. Instead, brokers will connect to the Tournament Scheduler via a REST api and request to be connected to a game. In general, there will not be a game waiting for this broker, and so the broker will be asked to delay for some period and try again. Once a game is ready for the broker, the Tournament Scheduler will respond with the URL for the game server, the name of the queue on which the broker must listen for messages from the server, and the name of the queue used to communicate with the server. The broker must then send the BrokerAuthentication message to server input queue; the server's response to the login will be returned on the broker queue. This is outlined in the following timing diagram, in which http interactions are shown in blue, and jms interactions in red. Since the broker and server share two secrets (the names of the two queues), the only reason for a rejected login from the server is if the broker attempts to log in after a game has already started. In this case, a BrokerReject message will be returned on the broker's queue.
Game Visualization
Once a game has begun, the Tournament Scheduler will provide a graphical visualization of the ongoing game that can be watched live. The visualization aspect will allow insight into the performance of the brokers relative to each other. The visualization will include all relevant game information.
Since there are potentially multiple servers running on a set of specific machines, the cleanest way to hook up visualizers to them is to load one visualizer for each machine that could run a game. Each visualizer must be configured with the URL of its server and the name of its queue (queue names must be hidden from brokers so they are not tempted to "listen in"), and the corresponding server must be configured to use a remote visualizer.
Configuring the visualizer
Because the visualizer runs in a servlet context and cannot read a properties file, ndividual visualizers are configured while creating their respective war files from the maven command line. To create a war, it's mvn clean compile -DvisualizerService.serverUrl='server-url' -DvisualizerService.queueName='name-of-visualizer-queue' war:war
Configuring the server
There are two configuration options that must be set on the server to talk to a remote visualizer:
server.visualizerProxyService.remoteVisualizer = true
server.visualizerProxyService.visualizerQueueName = name-of-visualizer-queue
Note that it does not work to set remoteVisualizer = true for a bootstrap session, unless there's a visualizer waiting to suck up the data. In fact, this setting does not work in general without an active visualizer subscribed to the queue.
Post Game
After each game, the Tournament Scheduler will provide public temporary links to the game logs for analysis. The Tournament Scheduler will also indicate the scores and winning broker of the game.
Post Tournament
The Tournament Scheduler will post the finishing places of all brokers on a tournament results page.
Interaction with server and brokers
Here's a simple timing diagram that shows how a broker talks to the TS and server, and how the TS uses the backend controller to interface with the server
Broker Login Page REST Api
To participate in tournaments, brokers will communicate with the Tournament Scheduler via a RESTful api. This page contains the specification for the api.
REST Specification
To make REST calls on the Tournament Scheduler, you will use the brokerLogin.jsp page, as the example below:
Required Parameters:
- authToken={your-broker's-authorization-token} - This allows your broker to authenticate with the tournament scheduler and verify its identity. Keep this secret.
- requestJoin={name-of-tournament-you-wish-to-join} - When you sign up for a tournament you will be given an official name to place here. The tournament scheduler will keep track of a broker's games automatically.
Optional Parameters:
- type={json|xml} - Specify the format you wish the response from the tournament scheduler for this REST call.
