Subweight

Compares Weight files that where generated by Substrate.

License: GPL v3

This project parses and compares Substrate Weight files. It helps tremendously with the review process of large Weight diffs. The results can be displayed conveniently in the CLI or browser. # Abstract Manually comparing Substrate Weight files is a task where humans falter and computers excel. When you want to know what I am talking about; take a look at [this diff](https://github.com/paritytech/polkadot/pull/5098/files). Now tell me which lines are problematic and which are fine 😈? Does not look appealing, does it? This is where *Subweight* comes to the rescue: It takes the old and the new version and compares all extrinsics. The human-friendly output looks like this: ![](.assets/compare%20mr%20output.png) This automatically sorts the worst offenders to the top and allows humans to see at a glance what is going on – without loosing details! Links to the diff are all there, and sharing results is as easy as copying a link to the line. Compatible with most Substrate chains. Enjoy! You can play around with the following public endpoints that are exposed by `subweight-web`: - [Compare Merge Requests](https://weights.tasty.limo/compare-mr) - [Compare Commits](https://weights.tasty.limo/compare-commit) The *dev* branch is deployed at . # Install Install both binaries: ```sh cargo install subweight subweight-web subweight --version subweight-web --version ``` # Compilation The [rust-toolchain.toml](./rust-toolchain.toml) defines the exact Rust version that the code was tested with. The formatting rules are defined in [rustfmt.toml](./rustfmt.toml). ```sh git clone https://github.com/ggwpez/substrate-weight-compare cd substrate-weight-compare/ cargo build --profile production ``` # Example: Web Interface Assuming you have a Substrate compatible repository checked out in the parent directory: ```sh subweight-web --root ../ --repos polkadot substrate cumulus ``` then open your browser and try the following: - [http://localhost:8080/](http://localhost:8080/) # Example: Compare weight files Suppose you have some weight files in: - `OLD=repos/polkadot/` and - `NEW=my_other_repos/polkadot` The base command looks like this: ```sh subweight compare files --old $OLD/* --new $NEW/* --method asymptotic ``` If you want to compare the weights of the Kusama to the Polkadot runtime, the command becomes a bit more longer: ```sh subweight compare files --old ../polkadot/runtime/kusama/**/weights/*.rs --new ../polkadot/runtime/polkadot/*/weights/*.rs --method asymptotic --ignore-errors --change changed unchanged --unit time --threshold 10 ``` ```sh +-----------------------------------------+-----------------------------+----------+----------+---------------+ | File | Extrinsic | Old | New | Change [%] | +=============================================================================================================+ | pallet_election_provider_multi_phase.rs | feasibility_check | 1.23ms | 812.80us | -33.90 | |-----------------------------------------+-----------------------------+----------+----------+---------------| | frame_benchmarking_baseline.rs | addition | 162.00ns | 112.00ns | -30.86 | |-----------------------------------------+-----------------------------+----------+----------+---------------| | runtime_parachains_hrmp.rs | hrmp_cancel_open_request | 27.90us | 39.02us | +39.86 | |-----------------------------------------+-----------------------------+----------+----------+---------------| | pallet_tips.rs | slash_tip | 15.86us | 22.61us | +42.56 | |-----------------------------------------+-----------------------------+----------+----------+---------------| | runtime_parachains_initializer.rs | force_approve | 3.12us | 4.53us | +45.02 | |-----------------------------------------+-----------------------------+----------+----------+---------------| | runtime_parachains_hrmp.rs | clean_open_channel_requests | 366.82us | 590.73us | +61.04 | |-----------------------------------------+-----------------------------+----------+----------+---------------| | runtime_parachains_hrmp.rs | hrmp_accept_open_channel | 29.81us | 48.54us | +62.81 | |-----------------------------------------+-----------------------------+----------+----------+---------------| | runtime_parachains_hrmp.rs | hrmp_close_channel | 27.58us | 44.92us | +62.89 | |-----------------------------------------+-----------------------------+----------+----------+---------------| | runtime_parachains_hrmp.rs | force_process_hrmp_open | 2.17ms | 3.64ms | +67.28 | |-----------------------------------------+-----------------------------+----------+----------+---------------| | runtime_parachains_hrmp.rs | hrmp_init_open_channel | 32.67us | 55.70us | +70.49 | |-----------------------------------------+-----------------------------+----------+----------+---------------| | runtime_parachains_hrmp.rs | force_process_hrmp_close | 1.21ms | 2.11ms | +74.25 | |-----------------------------------------+-----------------------------+----------+----------+---------------| | runtime_parachains_hrmp.rs | force_clean_hrmp | 1.82ms | 3.27ms | +80.04 | +-----------------------------------------+-----------------------------+----------+----------+---------------+ ``` Cou can use the `--print-terms` flag to print the terms. This example omits them since the rows get really long. # Example: Compare Polkadot Commits Compare arbitrary Polkadot commits assuming you run this in the Polkadot directory: ```sh subweight --verbose compare commits HEAD HEAD~100 --threshold 10 --method asymptotic --path-pattern "runtime/*/src/weights/**/*.rs,bridges/modules/*/src/weights.rs" +------------------------------------------------------------------+-------------------------+--------+---------+----------------+ | File | Extrinsic | Old | New | Change [%] | +================================================================================================================================+ | runtime/rococo/src/weights/runtime_parachains_paras_inherent.rs | enter_variable_disputes | - | - | ERROR | |------------------------------------------------------------------+-------------------------+--------+---------+----------------| | runtime/westend/src/weights/xcm/pallet_xcm_benchmarks_generic.rs | set_topic | 2.59us | 10.01us | +286.67 | |------------------------------------------------------------------+-------------------------+--------+---------+----------------| | runtime/westend/src/weights/xcm/pallet_xcm_benchmarks_generic.rs | clear_transact_status | 2.65us | 9.96us | +276.24 | |------------------------------------------------------------------+-------------------------+--------+---------+----------------| | runtime/westend/src/weights/xcm/pallet_xcm_benchmarks_generic.rs | clear_topic | 2.59us | 8.29us | +220.04 | +------------------------------------------------------------------+-------------------------+--------+---------+----------------+ ``` It prints first the ones that decreased (good) and then the ones that increased (bad) sorted by ascending absolute value. # Config options ## Repository Selects the project to use. *Subweight* has the goal of being compatible with: - [Substrate] - [Polkadot] - [Cumulus] Other projects which are currently compatible, but not a hard requirement: - [Acala] - [Astar] - [Moonbeam] - [Composable Finance] - [Noodle] Note: Not all repositories are deployed to the *Subweight* web service. ## Path Pattern Uses the [glob](https://docs.rs/glob/latest/glob/) crate to match files in the repository path with the given pattern. Here are some examples that the web interface uses. These do not catch *all* files, which is a bug: - Substrate: `frame/*/src/weights.rs` - Polkadot: `runtime/*/src/weights/**/*.rs,bridges/modules/*/src/weights.rs` - Cumulus: `**/weights/*.rs,**/weights/xcm/*.rs,**/src/weights.rs` `weights/**/*.rs` is preferred to `weights/*.rs` to include possible sub-folders like XCM. The `mod.rs` file is automatically excluded. ## Pallet Filter by the pallets to include by using a [Regex]. Examples: - `.*` would be *any* pallet. - `system|assets` would be the `system` and the `assets` pallet. ## Extrinsic Analogous to the [Pallet](#pallet) filter this filters by the extrinsics using a [Regex]. Examples: - `.*` would be *any* extrinsic. - `mint|burn` would be the `mint` and the `burn` extrinsics. ## Evaluation Method The evaluation method defines how the weight equation is evaluate (=calculated). This is a deciding factor when making a decision whether or not a weight got worse. - *Base*: Only consider the constant factor of the weight plus storage operations. - *Exact Worst*: Assumes both equations to be hyper-planes and finds their greatest relative increase by evaluating all corners. The runtime for `n` components is `2^n` which is hard-limited to 16 components. This requires your weight files to support [component range annotations](https://github.com/paritytech/substrate/issues/11397). One way to check that is to search for the string `"The range of component"` in your weight.rs files. - *Guess Worst*: Tries to apply *Exact Worst* but assumes all components to have a maximum of 100, if no maximum was found. This is a best-effort approach in case your weight files do not have component range annotations. - *Asymptotic*: Set all components to their maximum value. Can be used to get a feeling for the asymptotic change of the formula. NOTE: The storage weights are currently set to RocksDB Substrate default. ## Rel Threshold Filters the changes results by an absolute percentual threshold. The percentages values are calculated as increase or decrease. Eg: from 100 to 150 would be +50% and would be included by any threshold >=50. ## Abs Threshold Filters the changes results by an absolute threshold. ## Dimension The weight in Substrate is chromatic (two dimensional). Its dimensions are *Reference Time* and *PoV size*. The dimension can therefore be set to either *Time* or *Proof*. A good unit will then automatically be selected, for example `µs` for *Time* or `KiB` for *Proof*; depending on the size of the concrete scalars. - *Time*: The execution time that the call consumed on reference hardware. - *Proof*: The size of the Proof-of-validity (PoV) that the call produced. The relevant MR is [substrate#11637](https://github.com/paritytech/substrate/pull/11637) which requires integration the weight template for your project to emit chromatic weights. ## Ignore Errors Silently ignore parse errors. This is useful when using inclusive path patterns. You can see all the errors when clicking on the red error box. ## Git Pull Pull the branch before comparing anything. This ensures that you are on the last commit. This does not override the *Cache*. It can therefore take up to 10 minutes for a new change to show up. ## Cache The web UI caches success responses for 10 minutes. Currently there is no flag to disable it. Use commit hashes instead of branches if you want to ensure that you are not being served cached results. # Possible Errors and Warnings ## Web Interface ### `No range for component …` This means that the weights of that call were not updated to expose the exact range of that component. Re-run them with a newer version of Substrate if you want this. ### `… has different ranges in the old and new version` This means that the range of a component changed between the old and the new version. This is not a mistake of a problem, but it makes it impossible to accurately compare the terms - therefore the error. When using one of the `Guess-*` comparison methods, it does not try to do an accurate comparison, therefore the error disappears. # Running the Tests There exist *unit* and *integration* tests. Most of them are guarded behind feature flags. The explanation below covers both in one. You can run the sanity checks just with `cargo test`. ## Integration tests Integration tests are written in a macro fashion to allow for easy extension (see [integration.rs]). They have hard-coded expected results and a specific commit hash on which they are run. The CI does this and additionally for Polkadot also on the master commit. ```sh git clone https://github.com/ggwpez/substrate-weight-compare cd substrate-weight-compare # Clone all the test-able repos mkdir -p repos git clone https://github.com/paritytech/polkadot/ repos/polkadot git clone https://github.com/paritytech/substrate/ repos/substrate git clone https://github.com/paritytech/cumulus/ repos/cumulus git clone https://github.com/AcalaNetwork/acala/ repos/acala git clone https://github.com/AstarNetwork/astar/ repos/astar git clone https://github.com/PureStake/moonbeam/ repos/moonbeam git clone https://github.com/ComposableFi/composable/ repos/composable git clone https://github.com/NodleCode/chain/ repos/chain # Run ALL the tests cargo test --release --all-targets --all-features ``` [Substrate]: https://github.com/paritytech/substrate [Polkadot]: https://github.com/paritytech/polkadot [Cumulus]: https://github.com/paritytech/cumulus [Acala]: https://github.com/AcalaNetwork/acala [Astar]: https://github.com/AstarNetwork/astar [Moonbeam]: https://github.com/PureStake/moonbeam [Composable Finance]: https://github.com/ComposableFi/composable [Noodle]: https://github.com/NodleCode/chain [Regex]: https://github.com/fancy-regex/fancy-regex [integration.rs]: https://github.com/ggwpez/substrate-weight-compare/blob/master/core/src/test/parse/integration.rs # License GPLv3 only, see [LICENSE](LICENSE).