From 88d6c7f186a1bf827c90d1b21125005558bc3d0b Mon Sep 17 00:00:00 2001 From: Sam Thursfield Date: Thu, 8 Feb 2018 17:12:33 +0000 Subject: HACKING.rst: Mention benchmarking and profiling tools This adds a reference to the benchmarking tool generated as part of https://gitlab.com/BuildStream/buildstream/issues/205. It also documents recommended strategies for profiling, which fixes https://gitlab.com/BuildStream/buildstream/issues/206. --- HACKING.rst | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/HACKING.rst b/HACKING.rst index fd8931305..841a79b49 100644 --- a/HACKING.rst +++ b/HACKING.rst @@ -247,6 +247,63 @@ tests for this), documentation on the datafiles extension can be found here: https://pypi.python.org/pypi/pytest-datafiles +Measuring BuildStream performance +--------------------------------- + +Benchmarking framework +~~~~~~~~~~~~~~~~~~~~~~~ + +BuildStream has a utility to measure performance which is available from a +separate repository at https://gitlab.com/BuildStream/benchmarks. This tool +allows you to run a fixed set of workloads with multiple versions of +BuildStream. From this you can see whether one version performs better or +worse than another which is useful when looking for regressions and when +testing potential optimizations. + +For full documentation on how to use the benchmarking tool see the README in +the 'benchmarks' repository. + +Profiling tools +~~~~~~~~~~~~~~~ + +When looking for ways to speed up the code you should make use of a profiling +tool. + +Python provides `cProfile `_ +which gives you a list of all functions called during execution and how much +time was spent in each function. Here is an example of running `bst --help` +under cProfile: + + python3 -m cProfile -o bst.cprofile -- $(which bst) --help + +You can then analyze the results interactively using the 'pstats' module: + + python3 -m pstats ./bst.cprofile + +For more detailed documentation of cProfile and 'pstats', see: +https://docs.python.org/3.7/library/profile.html. + +For a richer visualisation of the callstack you can try `Pyflame +`_. Once you have followed the instructions in +Pyflame's README to install the tool, you can profile `bst` commands as in the +following example: + + pyflame --output bst.flame --trace bst --help + +You may see an `Unexpected ptrace(2) exception:` error. Note that the `bst` +operation will continue running in the background in this case, you will need +to wait for it to complete or kill it. Once this is done, rerun the above +command which appears to fix the issue. + +Once you have output from pyflame, you can use the ``flamegraph.pl`` script +from the `Flamegraph project `_ +to generate an .svg image: + + ./flamegraph.pl bst.flame > bst-flamegraph.svg + +The generated SVG file can then be viewed in your preferred web browser. + + The MANIFEST.in and setup.py ---------------------------- When adding a dependency to BuildStream, it's important to update the setup.py accordingly. -- cgit v1.2.1