Storage and Querying

PHPBench allows benchmarking results to be persisted using a configured storage driver. You can inspect the results with either the show or report commands.

Configuring a Storage Driver

PHPBench will use XML storage by default, which is fine for most purposes. If you want advanced functionality (e.g. the ability to query benchmarks) then you can install the Doctrine DBAL extension.

The XML storage driver will place benchmarks in a folder called _storage by default, this can be changed in the configuration as follows:

{
    "xml_storage_path": "_storage"
}

Storing Results

In order to store benchmarking runs you simply need to give --store option when running your benchmarks:

$ phpbench run --store

Viewing the History

Once you have stored some benchmark runs you can use the history command to see what you have got:

$ phpbench log
run 875c827946204db23eadd4b10e76b7189e10dde2
Date:    2016-03-19T09:46:52+01:00
Branch:  git_log
Context: <none>
Scale:   1 subjects, 60 iterations, 120 revolutions
Summary: (best [mean] worst) = 433.467 [988.067] 504.600 (μs)
         ⅀T: 59,284.000μs μRSD/r: 9.911%

run 9d38a760e6ebec0a466c80f148264a7a4bb7a203
Date:    2016-03-19T09:46:39+01:00
Branch:  git_log
Context: <none>
Scale:   1 subjects, 30 iterations, 30 revolutions
Summary: (best [mean] worst) = 461.800 [935.720] 503.300 (μs)
         ⅀T: 28,071.600μs μRSD/r: 4.582%

...

Report Generation

You can report on a single given run ID using the show command:

$ phpbench show 9d38a760e6ebec0a466c80f148264a7a4bb7a203

You may also specify a different report with the --report option. In order to compare two or more reports, you should use the report command as detailed in the following section.

Meta UUIDs

It is possible to specify “meta” UUIDs, such as latest:

$ phpbench show latest

And also you may use the -<n> suffix to view the “nth” entry in the history from the latest:

$ phpbench show latest-1

Would show the second latest entry. Meta UUIDs can be used anywhere where you would normally specify a UUID, including queries.

Querying

Important

The XML storage driver does not support querying, if you require this functionality install the Doctrine DBAL extrension.

PHPBench uses a query language very similar to that of MongoDB. A simple example:

$ phpbench report --report=aggregate --query='subject: "benchMd5", run: 239"'

Would show the results in an aggregate report for the benchmarking subject benchMd5 from run 239.

A more complex example:

$ phpbench report --report=aggregate --query='$and: [ { subject: "benchMd5" }, { date: { $gt: "2016-02-09" } } ]'

This would generate a suite collection containing all the benchMd5 subjects created after 2016-02-09.

Logical Operators

Logical operators must have as a value an array of constraints.

$and

Return only the records which meet both of the given constraints:

$and: [ { field1: "value1" }, { field2: "value2" } ]

$or

Return only the records which meet at least one of the given constraints:

$or: [ { field1: "value1" }, { field2: "value2" } ]

Logical Comparisons

$eq

Note that that equality is assumed if the value for a field is a scalar:

subject: "benchMd5"

The verbose equality comparison would be:

subject: { $eq: "benchMd5" }

$neq

Non-equality comparison:

run: { $neq: 12 }

$gt, $gte

Greater than and greater than or equal to comparisons:

date: { $gt: "2016-02-10" }

$lt, $lte

Greater than and greater than or equal to comparisons:

date: { $lt: "2016-02-10" }

$in

Matches when the field value matches any one of the given values:

run: { $in: [ 10, 11, 12 ] }

$regex

Provides regular expression capabilities for pattern matching strings in queries:

benchmark: { $regex: "FooBarBench" }

benchmark: { $regex: "Foo.*Bench" }

Fields

The following fields are currently available for querying:

  • benchmark: The benchmark class name.
  • subject: The subject name (e.g. benchMd5)
  • revs: The number of revolutions.
  • date: The date.
  • run: The run ID (as inferred from the phpbench history command).
  • group: The group name.
  • param: Query a parameter value, parameter name in square brackets.

Parameters may be queried with the param field - the parameter name should be enclosed in square brackets as follows:

param[nb_elements]: 10

param[points]: { $gt: 50 }

Archiving

Archiving provides a way to export and reimport data from and to the configured storage. This allows you to:

  • Backup your results (for example to a GIT repository).
  • Migrate to other storage drivers.

By default PHPBench is configured to use an XML archiver, which will dump results to a directory in the current working directory, _archive.

To archive:

$ phpbench archive

To restore:

$ phpbench archive --restore

Both operations are idempotent - they will skip any existing records.

You may configure a different archiver in the configuration:

{
    "archiver": "xml"
}