The configuration file is the central file that controls the benchmark run. This file contains the benchmark-specific configuration parameters and their default values. The default values will be displayed in a form when a user schedules a run for the first time. The user can change the values and subsequent runs will always show the most recently used values. See the run.xml for the sample web1 benchmark to understand what this file contains. The parameters in this file can be retrieved in the driver code as described in the Driver Framework Developers Guide.
The configuration file is named "run.xml" by default. But as you'll find out later, this name is not mandatory. The configuration file can have any arbitrary name. An initial benchmark configuration file must be placed in the deploy directory of your benchmark project. The build script will automatically package this file into the META-INF of the deployable image and deploy it on request. The values in the initial benchmark configuration file are used as the default values when a user submits his/her first run.
Sample configuration file:
Faban makes use of namespaces to represent Faban-specific elements in the configuration file. Faban also suggests certain namespace aliases for the Faban namespaces in order to make them easily identifyable. While the aliases are just a guideline, the namespaces are a must for Faban to recognize its elements in the configuration file. The table below outlines the Faban suggested aliases and the corresponding namespaces:
| Alias | Namespace | Purpose |
|---|---|---|
| fa | http://faban.sunsource.net/ns/faban | Generic Faban elements |
| fh | http://faban.sunsource.net/ns/fabanharness | Elements used by the Faban harness |
| fd | http://faban.sunsource.net/ns/fabandriver | Elements used by the Faban driver framework |
Like any XML file, the structure of the configuration file starts with a root element. Faban is not specific about the name of the root element itself and we usually name it after the benchmark.
Inside the root element are the first level child elements. Faban requires at least two elements here:
We use the term system role or system type interchangeably. All first level child elements except fh:jvmConfig define a system role or type in the rig. They define the logical topology of the benchmark configuration. Roles such as "webServer," "dbServer," or just "server" are common. Note that the runConfig element already defines the "Driver" role implicitly. The order of these elements have significance on how the statistics are presented. The type or role listed first is always presented first, in order to have a uniform view of the system statistics, no matter which rig it is actually running on. The drivers are always listed last as the driver statistics have the least significance to the results of the benchmark run. Furthermore, a rig may have an inarbitrary number of drivers or clients causing them to clutter the statistics when presented anywhere but last. For example, in a test rig containing systems acting as drivers (workload drivers or clients), web servers, and database servers, ordering the webServer role before the dbServer role will cause the statistics to always show the web servers on the top, followed by the database servers.
Faban does not mandate the structure of each role. However, if you want Faban to manage the hosts in a certain role, Faban needs to fine the fa:hostConfig element as an immediate child element thereof. We'll discuss the fa:hostConfig element next.
The fa:hostConfig element is a significant element worth a closer look. The structure of the fa:hostConfig element is as follows:
The fa:host element, or host list, lists the systems performing the role defined by the parent element of fa:hostConfig, space separated. For example, if the fa:hostConfig element is a child of a webServer element, the fa:host field would list the web servers in this rig.
The fa:hostPorts element is used to list the systems the same way as the fa:host element. In addition, it allows for listing port numbers to identify server instances. The port numbers are separated from the corresponding host name by a colon. A host running multiple server instances may be listed many times, each with a different port number.
Either the fa:host or fa:hostPorts element is required. If both elements are there, the fa:hostPorts supercedes the fa:host element. The fa:host element or host list is implicitly generated to contain unique host names and is always available for access through the ParamRepository API, even if it is not listed in the configuration file.
The fh:enabled element specifies whether a system in the host list is enabled or disabled. The input can take the form of a single true/false or space-separated true/false list corresponding to the host list. We will commonly leave this value to a single 'true' unless there are special cases where a host needs to be disabled.
The fh:cpus element is reserved for future use - to specify a subset of cpus to be enabled in the system. It currently has no functionality.
The fh:tools
element lists the tools to use for statistics collection for this
type/role of host. Tools can be specified as toolset or individual
tools. The tools can contain any option and must be
separated by a semi-colon following the Unix command conventions - no
matter what operating system you are using on the server. For example
the element's value of "vmstat 10; iostat 10" will cause Faban to
collect vmstat and iostat with an interval of 10 on this system
type/role during the steady state of the run and present the output
through the statistics page. There is no API to invoke the tools. The
tools are automatically invoked by the Faban harness when specified in
this configuration entry/element. If tools field is left blank, then
the default
toolset
will be executed. Toolset is a powerful new feature discussed under Services/Tools Deployment.
If you do not
want to run any
tools, you must explicitly specify "NONE" in the tools field.
The fh:userCommands
allows the user to specify commands, separated by semi-colon to run on
systems before starting the run. If there is any output from the
userCommands, it will be listed in the system information page which is
linked from the statistics page.
The fh:service element links the service to a system role for each run. The name of the service must match the service id of a deployed service. It also allows the user to specify the service configurations, whether to restart the service with the run or not, and tools to start for the service. Any number of service elements are allowed in a host role. The service elements are usually specified right after the fa:hostConfig element for a host role. The structure of the fh:service element is as follows:
The fh:name element specifies the service to load. It must be one of the deployed services. The service name must match the service id as declared in the services-tools.xml deployment descriptor for that service.
The fh:enabled element specifies whether to load this service. This element is optional and defaults to true. In circumstances where a service is optional, depending on the configuration, it is desirable to have the service element in the configuration file and enable or disable the service by setting the value of this element to true or false instead of changing the structure of the configuration file altogether.
The fh:tools element specifies the observerability tools to start for that service. Like the fh:tools element under fh:hostConfig, it will start individual tools or toolsets as specified. If fh:tools is left blank, the "default" toolset will be started for the service. To run no tools, specify "NONE" in fh:tools. But unlike the fh:hostConfig tools element, the tools specified for a service are associated with the service configuration. For example, the mysqlstats tool specified for a MySQL service will use the service configuration to find the right MySQL instance to connect and gather statistics. If the mysqlstats tool were specified under fh:hostConfig, it would not know which MySQL instance to connect and will therefore fail.
The fh:restart element specifies whether the service should be restarted for the run. If a service is started/restarted for the run, it will consequently be stopped after the run finishes.
The fh:config element, and especially its child elements specify the configuration parameters for the service. The child element's name specify the parameter name and the value is the associated value. These will be passed to the services and associated tools as properties available from the ServiceContext and ToolContext, respectively.
A significant set of elements in the fa:runConfig element is
used for the Faban driver framework. Depending on whether the benchmark
is an integration or a native Faban driver, the elements required by
Faban may vary. The http://faban.sunsource.net/ns/fabandriver
namespace
defines the elements used exclusively by the Faban driver framework.
Such elements, also called the 'fd' elements for the namespace alias
they commonly use, are discussed in the Faban driver framework
documentation. We will only discuss the fa:runConfig structure that is
meaningful to the Faban harness, below.
The fh:description element provides a description the Faban harness will display alongside the results in the result list.
The fa:hostConfig element, described above, list the systems to be used as the driver or client system, and the tools to run on these systems.
the fa:scale element drives the scale of the test. This scale is a relative indicator of the load applied to the system under test or SUT. The exact interpretation of the scale depends on the actual workload. If the driver is implemented using the Faban driver framework, the scale will be defined in the @BenchmarkDriver annotation of each benchmark driver.
The fa:runControl block defines the time in seconds, that is used for each phase of the benchmark run. The fa:rampUp element defines the ramp up time. The fa:steadyState is the measurement period of the run. And the fa:rampDown defines the ramp down time. These fields are used by the Faban driver framework to control the run as well as for the Faban harness to start and stop stats collection tools.
The fh:timeSync element, a boolean (true/false) element, controls whether the Faban harness would attempt to do a physical clock sync on all systems in the rig. The main benefit of enabling the sync is to ensure the log messages are displayed in chronological order. The Faban driver framework implicitly does a virtual clock sync by remembering time offsets from the master - a much more accurate method . The physical clock sync has no effect on this feature. The downside of enabling the physical clock sync is the requirement of root or administrator privileges on the target system. If the Faban user is not permitted to set the time, the harness may wait for a timeout and log the issue.
The DefaultFabanBenchmark2 uses the fd:agents child element of each driverConfig element to specify how the driver agents get started. This only applies to drivers implemented using the Faban driver framework. The fd:agents field can have two types of entries: