Installation¶
This is the detailed installation guide for Rally. If you are in a hurry you can check the quickstart guide.
Hardware Requirements¶
Use an SSD on the load generator machine. If you run bulk-indexing benchmarks, Rally will read one or more data files from disk. Usually, you will configure multiple clients and each client reads a portion of the data file. To the disk this appears as a random access pattern where spinning disks perform poorly. To avoid an accidental bottleneck on client-side you should therefore use an SSD on each load generator machine.
Prerequisites¶
Rally does not support Windows and is only actively tested on MacOS and Linux. Install the following packages first.
Python¶
- Python 3.4 or better available as python3 on the path. Verify with:
python3 --version
. - Python3 header files (included in the Python3 development package).
pip3
available on the path. Verify withpip3 --version
.
Debian / Ubuntu
sudo apt-get install gcc python3-pip python3-dev
RHEL 6/ CentOS 6
Tested on CentOS release 6.9 (Final).
Note
You will need to enable EPEL before.
sudo yum install -y gcc python34.x86_64 python34-devel.x86_64 python34-setuptools.noarch
# installs pip as it is not available as an OS package
sudo python3 /usr/lib/python3.4/site-packages/easy_install.py pip
RHEL 7 / CentOS 7
Note
You will need to enable EPEL before.
Tested on CentOS Linux release 7.4.1708 (Core).
sudo yum install -y gcc python34.x86_64 python34-devel.x86_64 python34-pip.noarch
Amazon Linux
sudo yum install -y gcc python35-pip.noarch python35-devel.x86_64
MacOS
We recommend that you use Homebrew:
brew install python3
git¶
Git is not required if all of the following conditions are met:
- You are using Rally only as a load generator (
--pipeline=benchmark-only
) or you are referring to Elasticsearch configurations with--team-path
. - You create your own tracks and refer to them with
--track-path
.
In all other cases, Rally requires git 1.9
or better. Verify with git --version
.
Debian / Ubuntu
sudo apt-get install git
Red Hat / CentOS / Amazon Linux
sudo yum install git
Note
If you use RHEL, install a recent version of git via the Red Hat Software Collections.
MacOS
git
is already installed on MacOS.
JDK¶
A JDK is required on all machines where you want to launch Elasticsearch. If you use Rally just as a load generator to benchmark remote clusters, no JDK is required. For details on how to install a JDK check your operating system’s documentation pages.
To find the JDK, Rally expects the environment variable JAVA_HOME
to be set on all targeted machines. To have more specific control, for example when you want to benchmark across a wide range of Elasticsearch releases, you can also set JAVAx_HOME
where x
is the major version of a JDK (e.g. JAVA8_HOME
would point to a JDK 8 installation). Rally will then choose the highest supported JDK per version of Elasticsearch that is available.
Note
If you have Rally download, install and benchmark a local copy of Elasticsearch (i.e., the default Rally behavior) be sure to configure the Operating System (OS) of your Rally server with the recommended kernel settings
Installing Rally¶
Simply install Rally with pip: pip3 install esrally
Note
Depending on your system setup you may need to prepend this command with sudo
.
If you get errors during installation, it is probably due to the installation of psutil
which we use to gather system metrics like CPU utilization. Ensure that you have installed the Python development package as documented in the prerequisites section above.
Non-sudo Install¶
If you don’t want to use sudo
when installing Rally, installation is still possible but a little more involved:
- Specify the
--user
option when installing Rally (step 2 above), so the command to be issued is:python3 setup.py develop --user
. - Check the output of the install script or lookup the Python documentation on the variable site.USER_BASE to find out where the script is located. On Linux, this is typically
~/.local/bin
.
You can now either add ~/.local/bin
to your path or invoke Rally via ~/.local/bin/esrally
instead of just esrally
.
VirtualEnv Install¶
You can also use Virtualenv to install Rally into an isolated Python environment without sudo.
- Set up a new virtualenv environment in a directory with
virtualenv --python=python3 .
- Activate the environment with
source /path/to/virtualenv/dir/bin/activate
- Install Rally with
pip install esrally
Whenever you want to use Rally, run the activation script (step 2 above) first. When you are done, simply execute deactivate
in the shell to exit the virtual environment.
PyEnv Install¶
Rally can be tested with different Python versions and it uses pyenv to manage them.
Please refer to PyEnv installation instructions.
Offline Install¶
If you are in a corporate environment where your servers do not have any access to the Internet, you can use Rally’s offline installation package. Follow these steps to install Rally:
- Install all prerequisites as documented above.
- Download the offline installation package for the latest release and copy it to the target machine(s).
- Decompress the installation package with
tar -xzf esrally-dist-*.tar.gz
. - Run the install script with
sudo ./esrally-dist-*/install.sh
.
Next Steps¶
After you have installed Rally, you need to configure it. Just run esrally configure
or follow the configuration help page for more guidance.