{"id":28498157,"url":"https://github.com/facebookexperimental/resctl-demo","last_synced_at":"2025-07-03T13:32:27.477Z","repository":{"id":38074417,"uuid":"248521239","full_name":"facebookexperimental/resctl-demo","owner":"facebookexperimental","description":"Demonstrate and benchmark various features of Linux resource control in a self-contained package.","archived":false,"fork":false,"pushed_at":"2024-12-05T17:24:04.000Z","size":3246,"stargazers_count":163,"open_issues_count":6,"forks_count":35,"subscribers_count":37,"default_branch":"main","last_synced_at":"2025-06-07T05:16:49.517Z","etag":null,"topics":["containerization","linux","resource-controller"],"latest_commit_sha":null,"homepage":"https://facebookmicrosites.github.io/resctl-demo-website/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/facebookexperimental.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-19T14:16:12.000Z","updated_at":"2025-06-04T19:15:27.000Z","dependencies_parsed_at":"2024-01-11T05:38:13.983Z","dependency_job_id":"664bc0a3-13db-49bd-9b55-34876f55df36","html_url":"https://github.com/facebookexperimental/resctl-demo","commit_stats":{"total_commits":630,"total_committers":11,"mean_commits":57.27272727272727,"dds":0.08730158730158732,"last_synced_commit":"9d086bfc7a1e08d54e5c041319bd39b5675ad46d"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/facebookexperimental/resctl-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookexperimental%2Fresctl-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookexperimental%2Fresctl-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookexperimental%2Fresctl-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookexperimental%2Fresctl-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/facebookexperimental","download_url":"https://codeload.github.com/facebookexperimental/resctl-demo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookexperimental%2Fresctl-demo/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263335479,"owners_count":23450858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["containerization","linux","resource-controller"],"created_at":"2025-06-08T13:36:56.273Z","updated_at":"2025-07-03T13:32:27.469Z","avatar_url":"https://github.com/facebookexperimental.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"img/logo.svg\" alt=\"resctl-demo logo\" width=\"50%\"/\u003e\n\nResource control aims to control compute resource distribution to improve\nreliability and utilization of a system. The facebook kernel and container\nteams have been intensively researching and implementing mechanisms and\nmethods to advance resource control. This repository contains two projects -\nresctl-demo and resctl-bench.\n\nresctl-demo\n-----------\n\nresctl-demo demonstrates and documents various aspects of resource control\nusing self-contained workloads in guided scenarios.\n\n\u003ca href=\"https://engineering.fb.com/wp-content/uploads/2020/10/resctl-demoV2.mp4\"\u003e\n  \u003cimg src=\"img/screenshot.png\" alt=\"resctl-demo in action\" width=\"50%\"\u003e\n\u003c/a\u003e\n\nresctl-bench\n------------\n\nresctl-bench is a collection of whole-system benchmarks to evaluate resource\ncontrol and hardware behaviors using realistic simulated workloads.\n\nComprehensive resource control involves the whole system. Furthermore,\ntesting resource control end-to-end requires scenarios involving realistic\nworkloads and monitoring their interactions. The combination makes\nbenchmarking resource control challenging and error-prone. It's easy to slip\nup on a configuration and testing with real workloads can be tedious and\nunreliable.\n\nresctl-bench encapsulates the whole process so that resource control\nbenchmarks can be performed easily and reliably. It verifies and updates\nsystem configurations, reproduces resource contention scenarios with a\nrealistic latency-sensitive workload simulator and other secondary\nworkloads, analyzes the resulting system and workload behaviors, and\ngenerates easily understandable reports.\n\nRead the [documentation](resctl-bench/README.md) for more information.\n\n\nPremade System Images\n=====================\n\nComprehensive resource control has many requirements, some of which can be\ndifficult to configure on an existing system. resctl-demo provides premade\nimages to help getting started. Visit the following page for details:\n\n  https://facebookmicrosites.github.io/resctl-demo-website\n\nInstallation\n============\n\n`resctl-demo` and `resctl-bench` are packaged in Fedora as of Fedora 34 and\nin EPEL as of EPEL 8. They can be installed with:\n\n```\nsudo dnf install resctl-demo resctl-bench\n```\n\nwhich will pull in any other dependencies that might be required. On Fedora,\nyou will also want to disable zram based swap:\n\n```\ntouch /etc/systemd/zram-generator.conf\nsystemctl stop dev-zram0.swap\n```\n\nFor other distributions, please follow the next sections to install from\ncargo or from source.\n\nInstallation with cargo\n=======================\n\nresctl-demo and resctl-bench can be installed using cargo which is the\npackage manager for rust. cargo can be installed with rustup:\n\n  https://rustup.rs/\n\nFor distro-specific way to install cargo, see the distro sub-sections. Note\nthat the distro packaged version might not be recent enough.\n\nOnce cargo is available, run the following command to install resctl-bench\nand resctl-demo. Don't forget to install rd-hashd and rd-agent.\n\n```\ncargo install rd-hashd rd-agent resctl-demo resctl-bench\n```\n\ncargo installs under `$HOME/.cargo/bin` by default. Feel free to copy them\nelsewhere as convenient. For example:\n\n```\ncd ~/.cargo/bin\ncp rd-hashd rd-agent resctl-demo resctl-bench /usr/local/bin\n```\n\nInformation on installing cargo and other dependencies on different distros\nfollows.\n\n\nArch\n----\n\nInstalling cargo:\n\n```\npacman -S --needed rust\n```\n\nThe common dependencies:\n\n```\npacman -S --needed coreutils util-linux python python-bcc fio stress\n```\n\noomd is available through AUR:\n\n```\ngit clone https://aur.archlinux.org/oomd-git.git oomd-git\ncd oomd-git\nmakepkg -si\n```\n\nresctl-demo needs the followings to plot graphs and run linux build job as\none of the workloads:\n\n```\npacman -S --needed gnuplot gcc binutils make bison flex pkgconf openssl libelf\n```\n\n\nFedora\n------\n\nInstalling cargo:\n\n```\ndnf install cargo\n```\n\nThe common dependencies:\n\n```\ndnf install coreutils util-linux python3 python3-bcc fio stress oomd\n```\n\nresctl-demo needs the followings to plot graphs and run linux build job as\none of the workloads:\n\n```\ndnf install gnuplot gcc binutils make bison flex pkgconf openssl-devel elfutils-devel\n```\n\nDisable zram based swap:\n\n```\ntouch /etc/systemd/zram-generator.conf\nsystemctl stop dev-zram0.swap\n```\n\nIf `journalctl -u rd-agent` shows EXEC failures, put SELinux in permissive mode\nby setting `SELINUX=permissive` in `/etc/selinux/config` and rebooting.\n\n\nUbuntu\n------\n\nInstalling cargo:\n\n```\napt install cargo\n```\n\nThe common dependencies:\n\n```\napt install coreutils util-linux python3 python3-bpfcc fio stress oomd\n```\n\nresctl-demo needs the followings to plot graphs and run linux build job as\none of the workloads:\n\n```\napt install gnuplot gcc binutils make bison flex pkgconf libssl-dev libelf-dev\n```\n\n\nBuilding and Installing Manually\n================================\n\nBuilding is straight-forward. Check out the source code and run:\n\n```\ncargo build --release\n```\n\nInstalling from local source directory:\n\n```\ncargo install --path rd-hashd\ncargo install --path rd-agent\ncargo install --path resctl-demo\ncargo install --path resctl-bench\n```\n\nAlternatively, run `build-and-tar.sh` script to create a tarball containing\nthe binaries:\n\n```\n./build-and-tar.sh\n```\n\nYou can install resctl-demo and resctl-bench by simply untarring the\nresulting tarball:\n\n```\ncd /usr/local/bin\ntar xvzf $SRC_DIR/target/resctl-demo.tar.gz\n```\n\nFollow the instructions in the Installation section to install other\ndependencies.\n\n\nRunning resctl-demo\n===================\n\nresctl-demo should be run as root in hostcritical.slice. Use the following\ncommand:\n\n```\nsudo systemd-run --scope --slice hostcritical.slice --unit resctl-demo /usr/local/bin/resctl-demo\n```\n\n\nRequirements\n============\n\nThe basic building blocks are provided by the Linux kernel's cgroup2 and other\nresource related features. On top, usage and configuration methods combined with\nuser-space helpers such as oomd and sideloader implement resource isolation to\nachieve workload protection and stacking.\n\n* Linux kernel in the git branch\n  `https://git.kernel.org/pub/scm/linux/kernel/git/tj/misc.git\n  resctl-demo-v5.13-rc7` which contains the following extra commits on top\n  of v5.13-rc7:\n    * Four mm commits to [fix inode shadow entry\n      protection](resctl-bench/doc/shadow-inode.md)\n    * Backport of [`blkcg: drop CLONE_IO check in\n      blkcg_can_attach()`](https://git.kernel.org/pub/scm/linux/kernel/git/axboe/linux-block.git/commit/?h=for-5.14/block\u0026id=b5f3352e0868611b555e1dcb2e1ffb8e346c519c)\n* cgroup2\n* btrfs on non-composite storage device (sda or nvme0n1, not md or dm)\n* Swap file on btrfs at least as large as 1/3 of physical memory\n* systemd\n* oomd\n* dd, stdbuf, findmnt, python3, fio, stress, gnuplot, gcc, ld, make, bison,\n  flex, pkg-config, libssl, libelf\n\n\nLicense\n=======\n\nresctl-demo is apache-2.0 licensed, as found in the [LICENSE](LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacebookexperimental%2Fresctl-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffacebookexperimental%2Fresctl-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacebookexperimental%2Fresctl-demo/lists"}