Configuration

Rally runs fine without any configuration file. You need one only when the defaults do not fit you, for example when you want another database, custom logging or a different task engine behaviour.

The file is called rally.conf and it is in the INI format that oslo.config uses.

Where Rally looks for the file

If you do not say which file to use, Rally checks these directories in this order:

1. <sys.prefix>/etc/rally/

2. ~/.rally/

3. /etc/rally/

The first rally.conf it finds wins. The others are ignored, there is no merging between them. If none of them exists, Rally just uses the built-in defaults.

Pointing Rally at a file

Use --config-file to name a file yourself:

$ rally --config-file ./my-rally.conf task start task.yaml

The option can be repeated. The files are merged option by option: when two files set the same option, the later file wins, while an option set only in an earlier file keeps its value. Once --config-file is given, the rally.conf from the directories above is not read.

Use --config-dir to point at a directory. Rally reads every *.conf file in it in alphabetical order and merges them the same way. These files are read after all the --config-file ones, so they win over them. Unlike --config-file, it does not replace the rally.conf found in the directories above, the directory is merged on top of it.

Both are global options, so they go before the category:

$ rally --config-file ./my-rally.conf task start ...   # works
$ rally task start --config-file ./my-rally.conf ...   # No such option

See Command Line Interface for the rest of the global options.

Available options

All options with their descriptions and default values are listed in the sample configuration file:

[DEFAULT]

#
# From oslo.log
#

# If set to true, the logging level will be set to DEBUG instead of
# the default INFO level. (boolean value)
# Note: This option can be changed without restarting.
#debug = false

# The name of a logging configuration file. This file is appended to
# any existing logging configuration files. For details about logging
# configuration files, see the Python logging module documentation.
# Note that when logging configuration files are used then all logging
# configuration is set in the configuration file and other logging
# configuration options are ignored (for example, log-date-format).
# (string value)
# Note: This option can be changed without restarting.
# Deprecated group/name - [DEFAULT]/log_config
#log_config_append = <None>

# Defines the format string for %%(asctime)s in log records. Default:
# %(default)s . This option is ignored if log_config_append is set.
# (string value)
#log_date_format = %Y-%m-%d %H:%M:%S

# (Optional) Name of log file to send logging output to. If no default
# is set, logging will go to stderr as defined by use_stderr. This
# option is ignored if log_config_append is set. (string value)
# Deprecated group/name - [DEFAULT]/logfile
#log_file = <None>

# (Optional) The base directory used for relative log_file  paths.
# This option is ignored if log_config_append is set. (string value)
# Deprecated group/name - [DEFAULT]/logdir
#log_dir = <None>

# Use syslog for logging. Existing syslog format is DEPRECATED and
# will be changed later to honor RFC5424. This option is ignored if
# log_config_append is set. (boolean value)
#use_syslog = false

# Enable journald for logging. If running in a systemd environment you
# may wish to enable journal support. Doing so will use the journal
# native protocol which includes structured metadata in addition to
# log messages.This option is ignored if log_config_append is set.
# (boolean value)
#use_journal = false

# Syslog facility to receive log lines. This option is ignored if
# log_config_append is set. (string value)
#syslog_log_facility = LOG_USER

# Use JSON formatting for logging. This option is ignored if
# log_config_append is set. (boolean value)
#use_json = false

# Log output to standard error. This option is ignored if
# log_config_append is set. (boolean value)
#use_stderr = true

# (Optional) Set the 'color' key according to log levels. This option
# takes effect only when logging to stderr or stdout is used. This
# option is ignored if log_config_append is set. (boolean value)
#log_color = false

# The amount of time before the log files are rotated. This option is
# ignored unless log_rotation_type is set to "interval". (integer
# value)
#log_rotate_interval = 1

# Rotation interval type. The time of the last file change (or the
# time when the service was started) is used when scheduling the next
# rotation. (string value)
# Possible values:
# Seconds - <No description provided>
# Minutes - <No description provided>
# Hours - <No description provided>
# Days - <No description provided>
# Weekday - <No description provided>
# Midnight - <No description provided>
#log_rotate_interval_type = days

# Maximum number of rotated log files. (integer value)
#max_logfile_count = 30

# Log file maximum size in MB. This option is ignored if
# "log_rotation_type" is not set to "size". (integer value)
#max_logfile_size_mb = 200

# Log rotation type. (string value)
# Possible values:
# interval - Rotate logs at predefined time intervals.
# size - Rotate logs once they reach a predefined size.
# none - Do not rotate log files.
#log_rotation_type = none

# Format string to use for log messages with context. Used by
# oslo_log.formatters.ContextFormatter (string value)
#logging_context_format_string = %(asctime)s.%(msecs)03d %(process)d %(levelname)s %(name)s [%(global_request_id)s %(request_id)s %(user_identity)s] %(instance)s%(message)s

# Format string to use for log messages when context is undefined.
# Used by oslo_log.formatters.ContextFormatter (string value)
#logging_default_format_string = %(asctime)s.%(msecs)03d %(process)d %(levelname)s %(name)s [-] %(instance)s%(message)s

# Additional data to append to log message when logging level for the
# message is DEBUG. Used by oslo_log.formatters.ContextFormatter
# (string value)
#logging_debug_format_suffix = %(funcName)s %(pathname)s:%(lineno)d

# Prefix each line of exception output with this format. Used by
# oslo_log.formatters.ContextFormatter (string value)
#logging_exception_prefix = %(asctime)s.%(msecs)03d %(process)d ERROR %(name)s %(instance)s

# Defines the format string for %(user_identity)s that is used in
# logging_context_format_string. Used by
# oslo_log.formatters.ContextFormatter (string value)
#logging_user_identity_format = %(user)s %(project)s %(domain)s %(system_scope)s %(user_domain)s %(project_domain)s

# List of package logging levels in logger=LEVEL pairs. This option is
# ignored if log_config_append is set. (list value)
#default_log_levels = amqp=WARN,boto=WARN,sqlalchemy=WARN,suds=INFO,oslo.messaging=INFO,oslo_messaging=INFO,iso8601=WARN,requests.packages.urllib3.connectionpool=WARN,urllib3.connectionpool=WARN,websocket=WARN,requests.packages.urllib3.util.retry=WARN,urllib3.util.retry=WARN,keystonemiddleware=WARN,routes.middleware=WARN,stevedore=WARN,taskflow=WARN,keystoneauth=WARN,oslo.cache=INFO,oslo_policy=INFO,dogpile.core.dogpile=INFO

# Enables or disables publication of error events. (boolean value)
#publish_errors = false

# The format for an instance that is passed with the log message.
# (string value)
#instance_format = "[instance: %(uuid)s] "

# The format for an instance UUID that is passed with the log message.
# (string value)
#instance_uuid_format = "[instance: %(uuid)s] "

# Interval, number of seconds, of log rate limiting. (integer value)
#rate_limit_interval = 0

# Maximum number of logged messages per rate_limit_interval. (integer
# value)
#rate_limit_burst = 0

# Log level name used by rate limiting. Logs with level greater or
# equal to rate_limit_except_level are not filtered. An empty string
# means that all levels are filtered. (string value)
# Possible values:
# CRITICAL - <No description provided>
# ERROR - <No description provided>
# INFO - <No description provided>
# WARNING - <No description provided>
# DEBUG - <No description provided>
# '' - <No description provided>
#rate_limit_except_level = CRITICAL

# Enables or disables fatal status of deprecations. (boolean value)
#fatal_deprecations = false

#
# From rally
#

# A mktemp(1)-like format string that will be used to pattern the
# generated random string. It must contain two separate segments of at
# least three 'X's; the first one will be replaced by a portion of the
# owner ID (i.e task/subtask ID), and the second will be replaced with
# a random string. (string value)
#context_resource_name_format = <None>

# Print debugging output only for Rally. Off-site components stay
# quiet. (boolean value)
#rally_debug = false

# Size of raw result chunk in iterations (integer value)
# Minimum value: 1
#raw_result_chunk_size = 1000

# A mktemp(1)-like format string that will be used to pattern the
# generated random string. It must contain two separate segments of at
# least three 'X's; the first one will be replaced by a portion of the
# owner ID (i.e task/subtask ID), and the second will be replaced with
# a random string. (string value)
#scenario_resource_name_format = <None>

# Control how a scenario run() argument annotated with a type that
# Rally cannot map to a JSON Schema is handled. When False (default),
# such an argument is treated as unconstrained (any value is accepted)
# and a warning is logged. When True, building the scenario's argument
# schema raises an error instead. (boolean value)
#strict_type_annotations = false


[database]

#
# From oslo.db
#

# If True, SQLite uses synchronous mode. (boolean value)
#sqlite_synchronous = true

# The back end to use for the database. (string value)
#backend = sqlalchemy

# The SQLAlchemy connection string to use to connect to the database.
# (string value)
#connection = <None>

# The SQLAlchemy connection string to use to connect to the slave
# database. (string value)
#slave_connection = <None>

# The SQLAlchemy asyncio connection string to use to connect to the
# database. (string value)
#asyncio_connection = <None>

# The SQLAlchemy asyncio connection string to use to connect to the
# slave database. (string value)
#asyncio_slave_connection = <None>

# Whether or not to assume a reader context needs to guarantee it can
# read data committed by a writer assuming replication lag is present;
# defaults to True. When False, a reader context works the same as
# async_reader and will select the slave database if present. When
# using a galera cluster, this can be set to False only if you set
# mysql_wsrep_sync_wait to 1 (this will guarantee that the reader will
# wait until writesets are committed).Note that this may incur a
# performance degradation within the galera cluster. Note also that
# this parameter has no effect if you do not set any slave_connection.
# (boolean value)
#synchronous_reader = true

# The SQL mode to be used for MySQL sessions. This option, including
# the default, overrides any server-set SQL mode. To use whatever SQL
# mode is set by the server configuration, set this to no value.
# Example: mysql_sql_mode= (string value)
#mysql_sql_mode = TRADITIONAL

# For Galera only, configure wsrep_sync_wait causality checks on new
# connections.  Default is None, meaning don't configure any setting.
# (integer value)
#mysql_wsrep_sync_wait = <None>

# Connections which have been present in the connection pool longer
# than this number of seconds will be replaced with a new one the next
# time they are checked out from the pool. (integer value)
#connection_recycle_time = 3600

# Maximum number of SQL connections to keep open in a pool. Setting a
# value of 0 indicates no limit. (integer value)
#max_pool_size = 5

# Maximum number of database connection retries during startup. Set to
# -1 to specify an infinite retry count. (integer value)
#max_retries = 10

# Interval between retries of opening a SQL connection. (integer
# value)
#retry_interval = 10

# If set, use this value for max_overflow with SQLAlchemy. (integer
# value)
#max_overflow = 50

# Verbosity of SQL debugging information: 0=None, 100=Everything.
# (integer value)
# Minimum value: 0
# Maximum value: 100
#connection_debug = 0

# Add Python stack traces to SQL as comment strings. (boolean value)
#connection_trace = false

# If set, use this value for pool_timeout with SQLAlchemy. (integer
# value)
#pool_timeout = <None>

# Enable the experimental use of database reconnect on connection
# lost. (boolean value)
#use_db_reconnect = false

# Seconds between retries of a database transaction. (integer value)
#db_retry_interval = 1

# If True, increases the interval between retries of a database
# operation up to db_max_retry_interval. (boolean value)
#db_inc_retry_interval = true

# If db_inc_retry_interval is set, the maximum seconds between retries
# of a database operation. (integer value)
#db_max_retry_interval = 10

# Maximum retries in case of connection error or deadlock error before
# error is raised. Set to -1 to specify an infinite retry count.
# (integer value)
#db_max_retries = 20

# Optional URL parameters to append onto the connection URL at connect
# time; specify as param1=value1&param2=value2&... (string value)
#connection_parameters =