diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e8d5ba1..e6d35b2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,11 +2,11 @@ We welcome your contributions! There are multiple ways to contribute. -# Opening issues +## Opening issues For bugs or enhancement requests, please file a GitHub issue unless it is security related. When filing a bug remember that the better written the bug is, the more likely it is to be fixed. If you think you have found a security vulnerability, do not raise a GitHub issue and follow the instructions in our security policy documented in SECURITY.md. -# Contributing code +## Contributing code We welcome your code contributions. Before submitting code via a pull request, you will need to have signed the Oracle Contributor Agreement (OCA) at @@ -22,7 +22,7 @@ git commit --signoff Only pull requests from committers that can be verified as having signed the OCA can be accepted. -# Pull request process +## Pull request process - Ensure there is an issue created to track and discuss the fix or enhancement you intend to submit. - Fork this repository. @@ -34,13 +34,13 @@ Only pull requests from committers that can be verified as having signed the OCA - Submit the pull request. Do not leave the pull request blank. Explain exactly what your changes are meant to do and provide simple steps on how to validate your changes. Ensure that you reference the issue you created as well. - We will assign the pull request for review before it is submitted internally and the PR is closed. -# Code of conduct +## Code of conduct Follow the Golden Rule. If you would like more specific guidelines, see the Contributor Covenant Code of Conduct at https://www.contributor-covenant.org/version/1/4/code-of-conduct/ -# Technical guide to contribution +## Technical guide to contribution The architecture used is @@ -50,7 +50,7 @@ The architecture used is - a set of plug-in shared object tuners which are loaded when bpftune starts; sysctl_tuner.[bpf.]c, neigh_table_tuner.[bpf.]c -# Adding a tuner +## Adding a tuner Tuners are added as plug-in .so objects built as tuner_name.c, and each tuner has a BPF program named tuner_name.bpf.c. To add a new tuner, add these @@ -59,7 +59,7 @@ files and simply add tuner_name to TUNERS in src/Makefile. Tuners can also be built outside of bpftune; see the sample_tuner/ subdirectory for a simple example and sample Makefile. -# BPF component (tuner_name.bpf.c) +## BPF component (tuner_name.bpf.c) The BPF code must @@ -137,7 +137,7 @@ possible as that will work for both kprobe and fentry for example. For maps, use the BPF_MAP_DEF() definitions which will invoke the older libbpf map definition if using an older libbpf. -# Userspace component - tuner_name.c +## Userspace component - tuner_name.c It should #include , and must consist of the following functions @@ -191,7 +191,7 @@ should be added to a tuner_name.h file which both include. Remember to include both the skel.h and skel.legacy.h files. -# Events +## Events When an event the user-space component needs to know about occurs, a ringbuf event should be sent. The event structure is: @@ -211,7 +211,7 @@ struct bpftune_event { The scenario refers to the event type (seen packet loss to remote system), and the payload can be a string, a raw data structure etc. -# Overhead +## Overhead When choosing BPF events to instrument, please try to avoid very high-frequency events. Try to use fentry instead of kprobe, @@ -231,7 +231,7 @@ $ TUNER=tcp_buffer_tuner.so sh qperf_test.sh Replace TUNER value with the name of the tuner you want to assess. -# Tests +## Tests Tests are mandatory for tuners; in the test directory you can see lots of examples. The test framework uses network namespaces to diff --git a/README.md b/README.md index c64f417..f990aa9 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ behaviour. The key benefit it provides are than using coarse system-wide stats), we can tune at a finer grain too (individual socket policies, individual device policies etc) -# The problem +## The problem The Linux kernel contains a large number of tunables; these often take the form of sysctl(8) parameters, and are usually @@ -55,7 +55,7 @@ not only can we observe the system and tune appropriately, we can also observe the effect of that tuning and re-tune if necessary. -# Key design principles +## Key design principles - Minimize overhead. Use observability features sparingly; do not trace very high frequency events. @@ -85,7 +85,7 @@ if necessary. round-trip time; if the correlation between these exceeds a threshould (0.7) we stop increasing buffer size. -# Concepts +## Concepts The key components are @@ -104,7 +104,7 @@ The key components are in the log is key; this allows an admin to understand what changed and why. -# Architecture +## Architecture - bpftune is a daemon which manages a set of .so plugin tuners; each of these is a shared object that is loaded on start-up. @@ -126,7 +126,7 @@ The key components are the common map definitions (ringbuf, etc) and shared variables such as learning rate and tuner ids that each tuner needs. -# Supported tuners +## Supported tuners - congestion tuner: auto-tune choice of congestion control algorithm. See bpftune-tcp-cong (8). @@ -146,7 +146,7 @@ The key components are Namespace awareness is important as we want to be able to auto-tune containers also. See bpftune-netns (8). -# Code organization +## Code organization Both core bpftune.c and individual tuners use the libbpftune library. It handles logging, tuner init/fini, and BPF init/fini. @@ -155,7 +155,7 @@ Each tuner shared object defines an init(), fini() and event_handler() function. These respectively set up and clean up BPF and handle events that originate from the BPF code. -# Tests +## Tests Tests are supplied for each tuner in the tests/ subdirectory. "make test" runs all the tests. Tests use network namespaces @@ -184,7 +184,7 @@ SPDX-URL: https://spdx.org/licenses/GPL-2.0.html See [the license file](./LICENSE.txt) for more details. -# Does my system support bpftune? +## Does my system support bpftune? Simply run "bpftune -S" to see: @@ -201,7 +201,7 @@ Two aspects are important here - does the system support network namespace cookies? If so per-network-namespace policy is supported. -# Demo +## Demo Simply starting bpftune and observing changes made via /var/log/messages can be instructive. For example, on a standard VM with sysctl defaults, @@ -265,7 +265,7 @@ bpftune: Summary: scenario 'need to increase TCP buffer size(s)' occurred 9 time bpftune: sysctl 'net.ipv4.tcp_rmem' changed from (4096 131072 1310720 ) -> (4096 131072 9765625 ) ``` -# For more info +## For more info See the docs/ subdirectory for manual pages covering bpftune and assoiated tuners.