Merge pull request #155 from tensorwerk/benchmark-gh-actions

Benchmark Suite and Automated PR Regression Testing.

Author: rlizzo

.github/workflows/asvbench.yml

@@ -0,0 +1,45 @@
+name: ASV Benchmarking
+
+on:
+  pull_request:
+    branches:
+    - master
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      max-parallel: 4
+      fail-fast: false
+      matrix:
+        os: [ubuntu-18.04, macOS-10.14]
+        python-version: [3.6, 3.7]
+    steps:
+    - uses: actions/checkout@v1
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v1
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install --upgrade setuptools virtualenv
+        pip install --upgrade asv
+    - name: Run Benchmarks
+      run: |
+        cd asv_bench/
+        asv machine --yes
+        asv continuous origin/master HEAD | tee asv.log
+        ASV_COMPARE="$(asv compare origin/master HEAD)"
+        if [[ $(cat asv.log | grep "failed") ]]; then
+          echo "Benchmarks Run With Errors"
+          exit 1
+        elif [[ $(cat asv.log | grep "PERFORMANCE DECREASED") ]]; then
+          echo "$ASV_COMPARE"
+          echo "Benchmarks Decreased Performance"
+          exit 1
+        else
+          echo "$ASV_COMPARE"
+          echo "Benchmarks Run Without Errors"
+        fi
+      shell: bash

.gitignore

@@ -35,6 +35,11 @@ coverage.xml
 htmlcov
 .hypothesis
 
+# Performance Testing
+asv_bench/html
+asv_bench/env
+asv_bench/results
+
 # Translations
 *.mo
 

CHANGELOG.rst

@@ -14,6 +14,9 @@ New Features
   (`#131 <https://github.com/tensorwerk/hangar-py/pull/131>`__) `@rlizzo <https://github.com/rlizzo>`__
 * Ability to change the backend storage format and options applied to an ``arrayset`` after initialization.
   (`#133 <https://github.com/tensorwerk/hangar-py/pull/133>`__) `@rlizzo <https://github.com/rlizzo>`__
+* Added Benchmarking Suite to Test for Performance Regressions in PRs.
+  (`#155 <https://github.com/tensorwerk/hangar-py/pull/155>`__) `@rlizzo <https://github.com/rlizzo>`__
+
 
 Improvements
 ------------

asv_bench/README.rst

@@ -0,0 +1,142 @@
+Hangar Performance Benchmarking Suite
+=====================================
+
+A set of benchmarking tools are included in order to track the performance of
+common hangar operations over the course of time. The benchmark suite is run
+via the phenomenal `Airspeed Velocity (ASV) <https://asv.readthedocs.io/>`_
+project.
+
+Benchmarks can be viewed at the following web link, or by examining the raw
+data files in the separate benchmark results repo.
+
+-  `Benchmark Web View <https://tensorwerk.com/hangar-benchmarks>`_
+-  `Benchmark Results Repo <https://github.com/tensorwerk/hangar-benchmarks>`_
+
+.. figure:: ../docs/img/asv-detailed.png
+   :align: center
+
+Purpose
+*******
+
+In addition to providing historical metrics and insight into application
+performance over many releases of Hangar, *the benchmark suite is used as a
+canary to identify potentially problematic pull requests.* All PRs to the
+Hangar repository are automatically benchmarked by our CI system to compare the
+performance of proposed changes to that of the current ``master`` branch.
+
+*The results of this canary are explicitly NOT to be used as the
+"be-all-end-all" decider of whether a PR is suitable to be merged or not.*
+
+Instead, it is meant to serve the following purposes:
+
+1. **Help contributors understand the consequences of some set of changes on the
+   greater system early in the PR process.** Simple code is best; if there's no
+   obvious performance degradation or significant improvement to be had, then
+   there's no need (or really rationale) for using more complex algorithms or
+   data structures. It's more work for the author, project maintainers, and
+   long term health of the codebase.
+
+2. **Not everything can be caught by the capabilities of a traditional test
+   suite.** Hangar is fairly flat/modular in structure, but there are certain
+   hotspots in the codebase where a simple change could drastically degrade
+   performance. It's not always obvious where these hotspots are, and even a
+   change which is functionally identical (introducing no issues/bugs to the
+   end user) can unknowingly cross a line and introduce some large regression
+   completely unnoticed to the authors/reviewers.
+
+3. Sometimes tradeoffs need to be made when introducing something new to a
+   system. Whether this be due to fundamental CS problems (space vs. time) or
+   simple matters of practicality vs. purity, it's always easier to act in
+   environments where relevant information is available before a decision is
+   made. **Identifying and quantifying tradeoffs/regressions/benefits during
+   development is the only way we can make informed decisions.** The only times
+   to be OK with some regression is when knowing about it in advance, it might
+   be the right choice at the time, but if we don't measure we will never know.
+
+
+Important Notes on Using/Modifying the Benchmark Suite
+******************************************************
+
+1. **Do not commit any of the benchmark results, environment files, or generated
+   visualizations to the repository**. We store benchmark results in a `separate
+   repository <https://github.com/tensorwerk/hangar-benchmarks>`_ so to not
+   clutter the main repo with un-necessary data. The default directories these are
+   generated in are excluded in our ``.gitignore`` config, so baring some unusual
+   git usage patterns, this should not be a day-to-day concern.
+
+2. Proposed changes to the benchmark suite should be made to the code in this
+   repository first. The benchmark results repository mirror will be
+   synchronized upon approval/merge of changes to the main Hangar repo.
+
+
+Introduction to Running Benchmarks
+**********************************
+
+As ASV sets up and manages it's own virtual environments and source
+installations, benchmark execution is not run via ``tox``. While a brief
+tutorial is included below, please refer to the `ASV Docs
+<https://asv.readthedocs.io/>`_ for detailed information on how to both run,
+understand, and write ASV benchmarks.
+
+First Time Setup
+----------------
+
+1. Ensure that ``virtualenv``, ``setuptools``, ``pip`` are updated to the
+   latest version.
+
+2. Install ASV ``$ pip install asv``.
+
+3. Open a terminal and navigate to the ``hangar-py/asv-bench`` directory.
+
+4. Run ``$ asv machine`` to record details of your machine, it is OK to
+   just use the defaults.
+
+
+Running Benchmarks
+------------------
+
+Refer to the `using ASV
+<https://asv.readthedocs.io/en/stable/using.html#running-benchmarks>`_ page for
+a full tutorial, paying close attention to the `asv run
+<https://asv.readthedocs.io/en/stable/commands.html#asv-run>`_ command.
+Generally ``asv run`` requires a range of commits to benchmark across
+(specified via either branch name, tags, or commit digests).
+
+To benchmark every commit between the current master ``HEAD`` and ``v0.3.0``,
+you would execute::
+
+    $ asv run v0.2.0..master
+
+However, this may result in a larger workload then you are willing to wait
+around for. To limit the number of commits, you can specify the ``--steps=N``
+option to only benchmark ``N`` commits at most between ``HEAD`` and ``v0.3.0``.
+
+The most useful tool during development is the `asv continuous
+<https://asv.readthedocs.io/en/stable/commands.html#asv-continuous>`_ command.
+using the following syntax will benchmark any changes in a local development
+branch against the base ``master`` commit::
+
+    $ asv continuous origin/master HEAD
+
+Running `asv compare
+<https://asv.readthedocs.io/en/stable/commands.html#asv-compare>`_ will
+generate a quick summary of any performance differences::
+
+    $ asv compare origin/master HEAD
+
+Visualizing Results
+-------------------
+
+After generating benchmark data for a number of commits through history, the
+results can be reviewed in (an automatically generated) local web interface by
+running the following commands::
+
+    $ asv publish
+    $ asv preview
+
+Navigating to ``http://127.0.0.1:8080/`` will pull up an interactive webpage
+where the full set of benchmark graphs/explorations utilities can be viewed.
+This will look something like the image below.
+
+.. figure:: ../docs/img/asv-main.png
+   :align: center

asv_bench/asv.conf.json

@@ -0,0 +1,160 @@
+{
+    // The version of the config file format.  Do not change, unless
+    // you know what you are doing.
+    "version": 1,
+
+    // The name of the project being benchmarked
+    "project": "hangar",
+
+    // The project's homepage
+    "project_url": "https://hangar-py.readthedocs.io",
+
+    // The URL or local path of the source code repository for the
+    // project being benchmarked
+    "repo": "..",
+
+    // The Python project's subdirectory in your repo.  If missing or
+    // the empty string, the project is assumed to be located at the root
+    // of the repository.
+    // "repo_subdir": "",
+
+    // Customizable commands for building, installing, and
+    // uninstalling the project. See asv.conf.json documentation.
+    //
+    // "install_command": ["in-dir={env_dir} python -mpip install {wheel_file}"],
+    // "uninstall_command": ["return-code=any python -mpip uninstall -y {project}"],
+    // "build_command": [
+    //     "python setup.py build",
+    //     "PIP_NO_BUILD_ISOLATION=false python -mpip wheel --no-deps --no-index -w {build_cache_dir} {build_dir}"
+    // ],
+
+    // List of branches to benchmark. If not provided, defaults to "master"
+    // (for git) or "default" (for mercurial).
+    "branches": ["master"], // for git
+    // "branches": ["default"],    // for mercurial
+
+    // The DVCS being used.  If not set, it will be automatically
+    // determined from "repo" by looking at the protocol in the URL
+    // (if remote), or by looking for special directories, such as
+    // ".git" (if local).
+    "dvcs": "git",
+
+    // The tool to use to create environments.  May be "conda",
+    // "virtualenv" or other value depending on the plugins in use.
+    // If missing or the empty string, the tool will be automatically
+    // determined by looking for tools on the PATH environment
+    // variable.
+    "environment_type": "virtualenv",
+
+    // timeout in seconds for installing any dependencies in environment
+    // defaults to 10 min
+    //"install_timeout": 600,
+
+    // the base URL to show a commit for the project.
+    "show_commit_url": "http://github.com/tensorwerk/hangar-py/commit/",
+
+    // The Pythons you'd like to test against.  If not provided, defaults
+    // to the current version of Python used to run `asv`.
+    // "pythons": ["3.7"],
+
+    // The list of conda channel names to be searched for benchmark
+    // dependency packages in the specified order
+    // "conda_channels": ["conda-forge", "defaults"],
+
+    // The matrix of dependencies to test.  Each key is the name of a
+    // package (in PyPI) and the values are version numbers.  An empty
+    // list or empty string indicates to just test against the default
+    // (latest) version. null indicates that the package is to not be
+    // installed. If the package to be tested is only available from
+    // PyPi, and the 'environment_type' is conda, then you can preface
+    // the package name by 'pip+', and the package will be installed via
+    // pip (with all the conda available packages installed first,
+    // followed by the pip installed packages).
+    //
+    // "matrix": {
+    //     "numpy": ["1.6", "1.7"],
+    //     "six": ["", null],        // test with and without six installed
+    //     "pip+emcee": [""],   // emcee is only available for install with pip.
+    // },
+
+    // Combinations of libraries/python versions can be excluded/included
+    // from the set to test. Each entry is a dictionary containing additional
+    // key-value pairs to include/exclude.
+    //
+    // An exclude entry excludes entries where all values match. The
+    // values are regexps that should match the whole string.
+    //
+    // An include entry adds an environment. Only the packages listed
+    // are installed. The 'python' key is required. The exclude rules
+    // do not apply to includes.
+    //
+    // In addition to package names, the following keys are available:
+    //
+    // - python
+    //     Python version, as in the *pythons* variable above.
+    // - environment_type
+    //     Environment type, as above.
+    // - sys_platform
+    //     Platform, as in sys.platform. Possible values for the common
+    //     cases: 'linux2', 'win32', 'cygwin', 'darwin'.
+    //
+    // "exclude": [
+    //     {"python": "3.2", "sys_platform": "win32"}, // skip py3.2 on windows
+    //     {"environment_type": "conda", "six": null}, // don't run without six on conda
+    // ],
+    //
+    // "include": [
+    //     // additional env for python2.7
+    //     {"python": "2.7", "numpy": "1.8"},
+    //     // additional env if run on windows+conda
+    //     {"platform": "win32", "environment_type": "conda", "python": "2.7", "libpython": ""},
+    // ],
+
+    // The directory (relative to the current directory) that benchmarks are
+    // stored in.  If not provided, defaults to "benchmarks"
+    "benchmark_dir": "benchmarks",
+
+    // The directory (relative to the current directory) to cache the Python
+    // environments in.  If not provided, defaults to "env"
+    "env_dir": "env",
+
+    // The directory (relative to the current directory) that raw benchmark
+    // results are stored in.  If not provided, defaults to "results".
+    "results_dir": "results",
+
+    // The directory (relative to the current directory) that the html tree
+    // should be written to.  If not provided, defaults to "html".
+    "html_dir": "html",
+
+    // The number of characters to retain in the commit hashes.
+    "hash_length": 8,
+
+    // `asv` will cache results of the recent builds in each
+    // environment, making them faster to install next time.  This is
+    // the number of builds to keep, per environment.
+    "build_cache_size": 1
+
+    // The commits after which the regression search in `asv publish`
+    // should start looking for regressions. Dictionary whose keys are
+    // regexps matching to benchmark names, and values corresponding to
+    // the commit (exclusive) after which to start looking for
+    // regressions.  The default is to start from the first commit
+    // with results. If the commit is `null`, regression detection is
+    // skipped for the matching benchmark.
+    //
+    // "regressions_first_commits": {
+    //    "some_benchmark": "352cdf",  // Consider regressions only after this commit
+    //    "another_benchmark": null,   // Skip regression detection altogether
+    // },
+
+    // The thresholds for relative change in results, after which `asv
+    // publish` starts reporting regressions. Dictionary of the same
+    // form as in ``regressions_first_commits``, with values
+    // indicating the thresholds.  If multiple entries match, the
+    // maximum is taken. If no entry matches, the default is 5%.
+    //
+    // "regressions_thresholds": {
+    //    "some_benchmark": 0.01,     // Threshold of 1%
+    //    "another_benchmark": 0.5,   // Threshold of 50%
+    // },
+}

asv_bench/benchmarks/__init__.py

@@ -0,0 +1 @@
+