Package: chainbench
Chainstack is the leading suite of services connecting developers with Web3 infrastructure•Homepage•Supported protocols•Chainstack blog•Chainstack docs•Blockchain API reference••Start for free•ChainbenchThis project allows you to benchmark your blockchain infrastructure. It usesLocustunder the hood.Project DetailsChainbench lets you to easily define profiles for any EVM-compatible chain.
You can use not only hard-coded values but also real chain data to generate dynamic call parameters.Main features:Built-in profiles for Ethereum, Binance Smart Chain, Polygon, Oasis, Avalanche and SolanaSupport for custom profilesDynamic call params generation using real chain dataHeadless and web UI modesCheck out thedocsfor more information about the profile creation.PrerequisitesPython 3.10+Poetry 1.7+ (installation instructionshere)InstallationUsing pippipinstallchainbenchAfter installation, you can run the tool using the following command:chainbenchstart--helpUsing PoetryClone the repository:gitclonegit@github.com:chainstacklabs/chainbench.gitInstall dependencies:cdchainbench&&poetryinstall--withoutdevWhen installing using Poetry, you can run the tool using the following command:poetryrunchainbenchExample UsageAll the examples below assume that you have installed the tool usingpip. If you installed it usingpoetry, replacechainbenchwithpoetry run chainbench.To list all available commands and options, run:chainbench--helpstartcommand is used to start a load test. To learn about the parameters and flags, run the following command:chainbenchstart--helpYou may specify a method to test, for example:chainbenchstarteth_blockNumber--users50--workers2--test-time12h--targethttps://node-url--headless--autoquitThis will run a load test witheth_blockNumbermethod calls with 2 workers, 50 users and 12 hours test time in headless mode with default test data size S.
After the test is finished, the tool will automatically quit.
If you run the command above without '--headless' flag, it will start a web UI where you may select other methods to run tests with.To see which methods are supported, run:chainbenchlistmethodsYou may also specify a profile with multiple methods and weights to use for the test instead of testing a single method. For example:chainbenchstart--profilebsc.general--users50--workers2--test-time12h--targethttps://node-url--headless--autoquitThis will run a load test with a general BSC profile.Parameters and Flags-p, --profile: Specifies the profile to use for the benchmark. Available profiles can be found in the profile directory. Sample usage-p bsc.general-u, --users: Sets the number of simulated users to use for the benchmark.-w, --workers: Sets the number of worker threads to use for the benchmark.-t, --test-time: Sets the duration of the test to run.--target: Specifies the target blockchain node URL that the benchmark will connect to.--headless: Runs the benchmark in headless mode, meaning that no graphical user interface (GUI) will be displayed during the test. This is useful for running the test on a remote server or when the GUI is not needed.--autoquit: Tells the Chainbench tool to automatically quit after the test has finished. This is useful for running the benchmark in an automated environment where manual intervention is not desired.--help: Displays the help message.--debug-trace-methods: Enables tasks tagged with debug or trace to be executed-E, --exclude-tags: Exclude tasks tagged with custom tags from the test. You may specify this option multiple times.--use-latest-blocks: Use latest blocks for test data generation and runs a background process to update the test data with latest blocks.--size: Specifies the test data size. Available values are XS, S, M, L, XL. Default is S.You may also runchainbench start --helpfor the full list of parameters and flags.ProfilesDefault profiles are located in theprofiledirectory. For a tutorial on how to create custom profiles, please refer tothis document.You may use the following command to list all profiles available out of the box:chainbenchlistprofilesThe-dor--profile-dirflag can be used to specify a custom directory with profiles. For example:chainbenchstart--profile-dir/path/to/profiles--profilemy-profile--users50--workers2--test-time12h--targethttps://node-url--headless--autoquitThis will run a load test using/path/to/profiles/my-profile.pyprofile.It's possible to group profiles into directories. For example, you can create a directory calledbscand put all the BSC profiles there. Then you can run a load test using the following command:chainbenchstart--profile-dir/path/to/profiles--profilebsc.my-profile--users50--workers2--test-time12h--targethttps://node-url--headless--autoquitChainbench will look for the profile in/path/to/profiles/bsc/my-profile.py. Currently, only one level of nesting is supported.There are built-inevm.lightandevm.heavyprofiles for EVM-compatible chains.Here's an example of how to run a load test for Ethereum using theevm.lightprofile:chainbenchstart--profileevm.light--users50--workers2--test-time12h--targethttps://node-url--headless--autoquitTest Data SizeYou may specify the test data size using the--sizeflag. This will determine how much data is used in the test.
Take note that larger data size will result in longer test data generation time before the test starts.
We plan to add an option to reuse previously generated test data in the future to avoid regenerating the same
test data for multiple test runs.SizeBlocksXS10S100M1,000L10,000XL100,000Test Data - Using Latest BlocksWhen running tests on nodes that are running in sync modes that do not have access to the full blockchain history, it is recommended to use the--use-latest-blocksflag.Example:
If the node runs in a sync mode that only keeps the last 128 blocks in history, you may run a test with the following command:chainbenchstart--profileevm.light--users50--workers2--test-time1h--targethttps://node-url--headless--autoquit--use-latest-blocks--sizeSWith test data size S and--use-latest-blocksflag, the tool will generate test data using the latest 100 blocks.
Chainbench will keep the test data up to date by running a background process that will update the test data with latest blocks.MonitorsMonitors are separate processes that run during the test to collect or process some additional data and metrics relevant to the test.
For example, head-lag-monitor will collect the latest block information from the node under test, check the timestamp and compare it to current time to calculate how much the node lags behind.
You may include monitors in your test by using the-mor--monitoroption and specifying the name of the monitor. At the moment, monitors only work in headless mode.Here's an example:chainbenchstart--profileevm.light--users50--workers2--test-time12h--targethttps://node-url--headless--autoquit-mhead-lag-monitorWeb UI ModeRun the following command to run a load test for BSC in UI mode. It will start a web server on port 8089.
Target is required to initialize the test data, however you may change the target endpoint later in the UI, along with the number of users, spawn rate and test time.
Do take note when changing the target option that test data initialized with an Ethereum node endpoint, for example, can only be used to test other Ethereum node endpoints.chainbenchstart--profilebsc.general--workers1--targethttps://any-working-node-endpoint.comIf you'd like to select which profiles or more specifically which user classes to use for the test, you may start a test in Web UI Mode without specifying a profile or passing in the method argument.chainbenchstart--workers1--targethttps://any-working-node-endpoint.com--profile-dirchainbench/profile/evmThis will start a test with all the EVM profiles and user classes available in the UI for you to select.Headless ModeIf you want to run a load test for BSC in headless mode, run the following command:chainbenchstart--profilebsc.general--workers4--users100--test-time1h--targethttps://node-url--headless--autoquitIt will run a load test for BSC with 4 workers, 100 users and 1 hour test time.In practice, you will probably want to run the benchmark on a remote server. Here's the example utilizingnohup:nohupchainbenchstart--profilebsc.general--workers4--users100--test-time1h--targethttps://node-url--headless--autoquit&Other CommandsDiscover Available Methods on EndpointsThis command will discover all available rpc methods on the specified endpoint and print them to the console. List of methods that are tested are based on the--clientsoption.chainbenchdiscoverhttps://node-url--clientsgeth,erigonTo list valid arguments for--clientsoption and the reference client version, run:chainbenchlistclientsIf you don't specify the--clientsoption, the tool will default to Ethereum JSON-RPC Specification (eth).LicenseThis project is licensed under theApache 2.0 License.