Configuring PBench

Creating a Stage File

Create a JSON file for each stage of a benchmark.

Always begin the file with a description.

Set the catalog and schema using catalog and schema.

Use queries and query_files to define the SQL queries to run in a stage.

Use next to define the order of stage files in a benchmark.

For more information, see Parameters.

Defining the Order of Stages

Use the next parameter in a stage file to define the order of stage files in a benchmark.

For example, consider the four files stage1.json, stage2.json, stage3.json, and stage4.json:

• stage1.json has the following entry for next:

  "next": [
    "stage2.json",
    "stage3.json"
  ]

  stage2 and stage3 are started in parallel when stage1 completes.

  stage2 and stage3 inherit parameters from stage1. See Inherited Parameters in Stage Files.

• stage2.json and stage3.json have the following entry for next:

  "next": [
    "stage4.json"
  ]

  stage4 inherits its parameters from the stage that starts it:

  • if stage3 completes before stage2, then stage3 passes inheritable parameters to stage4
  • if stage2 completes before stage3, then stage2 passes inheritable parameters to stage4

  See Inherited Parameters in Stage Files.

  When both stage2 and stage3 are finished, stage4` is started.

• stage4.json is the last stage of the benchmark run and has no next parameter entry.

Inherited Parameters in Stage Files

A child stage inherits some parameters from its parent stage if those parameters are not explicitly set in the child file. If a child stage has multiple parents, the child stage inherits those parameters from the first of the parent stages that finishes, which starts the child stage.

The parameters that a child stage inherits from a parent stage are:

• abort_on_error
• catalog
• cold_runs
• save_column_metadata
• save_json
• save_output
• schema
• session_params
• timezone
• warm_runs

New values for catalog, schema, session_params, and timezone assigned in a stage are not applied unless a stage also sets start_on_new_client = true.

For more information, see Parameters.

Creating a Query File

A query file is a file containing one or more - usually several - SQL queries that are called by the query_files parameter of a stage file. For a query file example, see query_01.sql.

Configuring InfluxDB and MySQL Connections

Save the connection information for InfluxDB and MySQL databases in configuration files, then use those configuration files with pbench run with the --influx and --mysql command options.

InfluxDB

NOTE:
An example configuration template for InfluxDB named influxdb.template.json can be found in the PBench repository. Copy influxdb.template.json to the directory local to PBench and edit it as appropriate.

Create a file named influxdb.json similar to the following example and edited as appropriate in the directory local to PBench.

Use --influx influxdb.json with pbench run to call the new file.

{
  "url": "https://example.com)",
  "org": "myorg",
  "bucket": "benchmark",
  "token": "*******=="
}

MySQL

NOTE:
An example configuration template for MySQL named mysql.template.json can be found in the PBench repository. Copy mysql.template.json to the directory local to PBench and edit it as appropriate.

Create a file named mysql.json similar to the following example and edited as appropriate in the directory local to PBench.

Use --mysql mysql.json with pbench run to call the new file.

{
  "username": "presto",
  "password": "*******",
  "server": "localhost",
  "database": "test"
}

For more information, see Running PBench.