diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 0d9811e7..5ecedfc5 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -88,3 +88,53 @@ To run a subset of tests:: To run all the test environments in *parallel* (you need to ``pip install detox``):: detox + + +Benchmarking +============ + +Codspeed +-------- + +A few benchmarks are run automatically on pull requests, using `Codspeed `_. +Once the benchmarks have completed, a report will be included as a comment on the pull request. + +Codspeed also shows flame graphs which can help track down why a change might have impacted performance. + +Local benchmarking +------------------ + +It's also possible to run local benchmarks, which can be helpful if you want to quickly compare performance +across different versions of the code. + +To benchmark a particular version of the code, run ``tox -ebenchmark``. This command creates a report that will be +stored in a local file (ignored by Git). + +You can then see how your latest benchmark compares with earlier ones, by running: + +``pytest-benchmark compare --group-by=func --sort=name --columns=mean`` + +This will display a list of all the benchmarks you've run locally, ordered from earlier to later. + +Profiling +========= + +Codspeed +-------- + +The easiest way to profile code is to look at the Codspeed flamegraph, automatically generated during benchmarking +(see above). + +Profiling Rust code locally +--------------------------- + +Rust integration tests can be profiled using `Cargo Flamegraph `_ +(which will need to be installed first, e.g. using ``cargo install flamegraph``). + +Navigate to the ``rust`` directory in this package. + +Run cargo flamegraph on the relevant test. E.g. to profile ``rust/tests/large.rs``, run: + +``sudo cargo flamegraph --root --test large`` + +This will create a file called ``flamegraph.svg``, which you can open to view the flamegraph. \ No newline at end of file