Expose race-id as command line parameter

With this commit we expose the race id as command line parameter. As the
internal name "trial id" and the related name "trial timestamp" are
inconsistent with this terminology we rename them to "race id" and "race
timestamp" respectively and add a backwards-compatibility layer that
will be removed again in elastic#777.

docs/command_line_reference.rst

@@ -159,6 +159,11 @@ Note that the default values are not recorded or shown (Rally does not know abou
 
 A track consists of one or more challenges. With this flag you can specify which challenge should be run. If you don't specify a challenge, Rally derives the default challenge itself. To see the default challenge of a track, run ``esrally list tracks``.
 
+``race-id``
+~~~~~~~~~~~
+
+A unique identifier for this race. By default a random UUID is automatically chosen by Rally.
+
 .. _clr_include_tasks:
 
 ``include-tasks``

docs/docker.rst

@@ -142,7 +142,7 @@ To further examine the contents we can bind mount it from another image e.g.::
     {
      "rally-version": "1.2.1.dev0",
      "environment": "local",
-     "trial-id": "1d81930a-4ebe-4640-a09b-3055174bce43",
+     "race-id": "1d81930a-4ebe-4640-a09b-3055174bce43",
 
 Specifics about the image
 -------------------------

docs/metrics.rst

@@ -11,8 +11,8 @@ Here is a typical metrics record::
 
     {
           "environment": "nightly",
-          "trial-timestamp": "20160421T042749Z",
-          "trial-id": "6ebc6e53-ee20-4b0c-99b4-09697987e9f4",
+          "race-timestamp": "20160421T042749Z",
+          "race-id": "6ebc6e53-ee20-4b0c-99b4-09697987e9f4",
           "@timestamp": 1461213093093,
           "relative-time": 10507328,
           "track": "geonames",
@@ -61,17 +61,17 @@ If you specify a car with mixins, it will be stored as one string separated with
 sample-type
 ~~~~~~~~~~~
 
-Rally runs warmup trials but records all samples. Normally, we are just interested in "normal" samples but for a full picture we might want to look also at "warmup" samples.
+Rally can be configured to run for a certain period in warmup mode. In this mode samples will be collected with the ``sample-type`` "warmup" but only "normal" samples are considered for the results that reported.
 
-trial-timestamp
-~~~~~~~~~~~~~~~
+race-timestamp
+~~~~~~~~~~~~~~
 
 A constant timestamp (always in UTC) that is determined when Rally is invoked.
 
-trial-id
-~~~~~~~~
+race-id
+~~~~~~~
 
-A UUID that changes on every invocation of Rally. It is intended to group all samples of a benchmark trial.
+A UUID that changes on every invocation of Rally. It is intended to group all samples of a benchmarking run.
 
 @timestamp
 ~~~~~~~~~~
@@ -81,7 +81,7 @@ The timestamp in milliseconds since epoch determined when the sample was taken.
 relative-time
 ~~~~~~~~~~~~~
 
-The relative time in microseconds since the start of the benchmark. This is useful for comparing time-series graphs over multiple trials, e.g. you might want to compare the indexing throughput over time across multiple benchmark trials. Obviously, they should always start at the same (relative) point in time and absolute timestamps are useless for that.
+The relative time in microseconds since the start of the benchmark. This is useful for comparing time-series graphs over multiple races, e.g. you might want to compare the indexing throughput over time across multiple races. Obviously, they should always start at the same (relative) point in time and absolute timestamps are useless for that.
 
 name, value, unit
 ~~~~~~~~~~~~~~~~~

docs/migrate.rst

@@ -4,6 +4,11 @@ Migration Guide
 Migrating to Rally 1.4.0
 ------------------------
 
+``trial-id`` and ``trial-timestamp`` are deprecated
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+With Rally 1.4.0, Rally will use the properties ``race-id`` and ``race-timestamp`` when writing data to the Elasticsearch metrics store. The properties ``trial-id`` and ``trial-timestamp`` are still populated but will be removed in a future release. Any visualizations that rely on these properties should be changed to the new ones.
+
 Custom Parameter Sources
 ^^^^^^^^^^^^^^^^^^^^^^^^
 

esrally/chart_generator.py

@@ -876,7 +876,7 @@ def gc(title, environment, race_config):
                 "show_legend": 1,
                 "show_grid": 1,
                 "drop_last_bucket": 0,
-                "time_field": "trial-timestamp",
+                "time_field": "race-timestamp",
                 "type": "timeseries",
                 "filter": TimeSeriesCharts.filter_string(environment, race_config),
                 "annotations": [
@@ -888,7 +888,7 @@ def gc(title, environment, race_config):
                                         "AND environment:\"%s\"" % (race_config.track, environment),
                         "id": str(uuid.uuid4()),
                         "color": "rgba(102,102,102,1)",
-                        "time_field": "trial-timestamp",
+                        "time_field": "race-timestamp",
                         "icon": "fa-tag",
                         "ignore_panel_filters": 1
                     }
@@ -968,7 +968,7 @@ def io(title, environment, race_config):
                 "show_legend": 1,
                 "show_grid": 1,
                 "drop_last_bucket": 0,
-                "time_field": "trial-timestamp",
+                "time_field": "race-timestamp",
                 "type": "timeseries",
                 "filter": TimeSeriesCharts.filter_string(environment, race_config),
                 "annotations": [
@@ -980,7 +980,7 @@ def io(title, environment, race_config):
                                         "AND environment:\"%s\"" % (race_config.track, environment),
                         "id": str(uuid.uuid4()),
                         "color": "rgba(102,102,102,1)",
-                        "time_field": "trial-timestamp",
+                        "time_field": "race-timestamp",
                         "icon": "fa-tag",
                         "ignore_panel_filters": 1
                     }
@@ -1082,7 +1082,7 @@ def segment_memory(title, environment, race_config):
                     }
                 ],
                 "show_legend": 1,
-                "time_field": "trial-timestamp",
+                "time_field": "race-timestamp",
                 "type": "timeseries",
                 "filter": TimeSeriesCharts.filter_string(environment, race_config),
                 "annotations": [
@@ -1094,7 +1094,7 @@ def segment_memory(title, environment, race_config):
                                         "AND environment:\"%s\"" % (race_config.track, environment),
                         "id": str(uuid.uuid4()),
                         "color": "rgba(102,102,102,1)",
-                        "time_field": "trial-timestamp",
+                        "time_field": "race-timestamp",
                         "icon": "fa-tag",
                         "ignore_panel_filters": 1
                     }
@@ -1226,7 +1226,7 @@ def query(environment, race_config, q):
                         "series_drop_last_bucket": 0
                     }
                 ],
-                "time_field": "trial-timestamp",
+                "time_field": "race-timestamp",
                 "index_pattern": "rally-results-*",
                 "interval": "1d",
                 "axis_position": "left",
@@ -1250,7 +1250,7 @@ def query(environment, race_config, q):
                                         "AND environment:\"%s\"" % (race_config.track, environment),
                         "id": str(uuid.uuid4()),
                         "color": "rgba(102,102,102,1)",
-                        "time_field": "trial-timestamp",
+                        "time_field": "race-timestamp",
                         "icon": "fa-tag",
                         "ignore_panel_filters": 1
                     }
@@ -1332,7 +1332,7 @@ def index(environment, race_configs, title):
                 "show_legend": 1,
                 "show_grid": 1,
                 "drop_last_bucket": 0,
-                "time_field": "trial-timestamp",
+                "time_field": "race-timestamp",
                 "type": "timeseries",
                 "filter": "environment:\"%s\" AND track:\"%s\" AND name:\"throughput\" AND active:true" % (environment, t),
                 "annotations": [
@@ -1344,7 +1344,7 @@ def index(environment, race_configs, title):
                                         "AND environment:\"%s\"" % (t, environment),
                         "id": str(uuid.uuid4()),
                         "color": "rgba(102,102,102,1)",
-                        "time_field": "trial-timestamp",
+                        "time_field": "race-timestamp",
                         "icon": "fa-tag",
                         "ignore_panel_filters": 1
                     }

esrally/config.py

@@ -359,7 +359,7 @@ def create_config(self, config_file, advanced_config=False, assume_defaults=Fals
                 env_name = self._ask_env_name()
 
             preserve_install = convert.to_bool(self._ask_property("Do you want Rally to keep the Elasticsearch benchmark candidate "
-                                                                  "installation including the index (will use several GB per trial run)?",
+                                                                  "installation including the index (will use several GB per race)?",
                                                                   default_value=False))
         else:
             # Does not matter for an in-memory store

esrally/mechanic/provisioner.py

@@ -459,7 +459,7 @@ def cleanup(self):
         # do not attempt to cleanup data paths. It does not work due to different permissions. As:
         #
         # (a) Docker is unsupported and not meant to be used by everybody, and
-        # (b) the volume is recreated before each trial run
+        # (b) the volume is recreated before each race
         #
         # this is not a major problem.
         cleanup(self.preserve, self.install_dir, [])