Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
276 lines (186 loc) · 11.8 KB

CONTRIBUTING.md

File metadata and controls

276 lines (186 loc) · 11.8 KB
Raw

Contributing to opentelemetry-ebpf-instrumentation (OBI)

The eBPF Instrumentation special interest group (SIG) meets regularly. See the OpenTelemetry community repo for information on this and other language SIGs.

See the public meeting notes for a summary description of past meetings. To request edit access, join the meeting or get in touch on Slack.

⚠️ Generative/Agentic code users, please read carefully our OpenTelemetry eBPF Instrumentation Generative AI Policy ⚠️

Scope

It is important to note what this project is and is not intended to achieve. This helps focus development to these intended areas and defines clear functional boundaries for the project.

What this project is

This project aims to provide auto-instrumentation functionality for applications using eBPF and other process-external technologies. It conforms to OpenTelemetry standards and strives to be compatible with that ecosystem.

What this project is not

  • A replacement for manual instrumentation: Manual or SDK-based instrumentation can achieve a level of granularity that is beyond the scope of this project. For example, SDK instrumentation enables you to instrument the inner machinery of a service, capturing highly detailed span information. In contrast, this project focuses on instrumenting incoming (server) and outgoing (client) service requests, without necessarily reporting internal spans.

Development

Compiling the project

Requirements

  • OBI requires Linux with Kernel 5.8 or higher with BPF Type Format (BTF) enabled. BTF became enabled by default on most Linux distributions with kernel 5.14 or higher. You can check if your kernel has BTF enabled by verifying if /sys/kernel/btf/vmlinux exists on your system. If you need to recompile your kernel to enable BTF, the configuration option CONFIG_DEBUG_INFO_BTF=y must be set.
  • It also supports RedHat-based distributions: RHEL8, CentOS 8, Rocky8, AlmaLinux8, and others, which ship a Kernel 4.18 that backports eBPF-related patches.
  • eBPF enabled in the host.
  • For instrumenting Go programs, compile with at least Go 1.17. OBI support Go applications built with a major Go version no earlier than 3 versions behind the current stable major release.

In addition, use the latest versions of the following components:

  • go
  • clang
  • docker
  • make
  • clang-format
  • clang-tidy

Compilation steps

Compiling OBI is a two-tier process: first, we need to build the eBPF code (written in C) and generate the Go bindings. There are two Makefile targets for that, generate and docker-generate. The difference between them is that generate will attempt to use the local clang/LLVM toolchain, whereas docker-generate pulls a Docker image containing all of the tooling required - this is also the target used by OBI's GitHub CI. Once the eBPF files have been generated, we can use the compile Makefile target to build the main binary.

make docker-generate # or make generate
make compile

A convenience Makefile target called dev which invokes both the generation and compilation step is also provided:

make dev

Installing clang-format hooks

OBI relies on clang-format for linting the C code, and as such, ships a convenience pre-commit git hook that formats the code during the commit process. To enable/install this hook, simply do:

make install-hooks

Manually formatting the C code

make clang-format

Linting the C code

make clang-tidy

Formatting the Go code

make fmt

Linting the Go code

make lint

Running unit tests

make test

Running integration tests

make integration-test

Running k8s integration tests

make integration-test-k8s

Issues

Questions, bug reports, and feature requests can all be submitted as issues to this repository.

Finding Your First Contribution

For people that are trying to find a good first issue to work on, here is a good starting point:

  • Good first issues: Browse issues labeled good first issue on GitHub. These are specifically curated for newcomers.

  • Help wanted: Check issues labeled help wanted for tasks where maintainers are actively looking for contributors.

  • Fix TODOs and FIXMEs: Search the codebase for TODO and FIXME comments. These mark known improvements and issues that the authors left for later — and are often small, self-contained tasks.

    grep -rn 'TODO\|FIXME' --include='*.go' --include='*.c' --include='*.h' .

  • Improve documentation: Look for outdated, incomplete, or missing documentation. Clear docs are a valuable contribution and a great way to learn the codebase.

Contribution Guidelines

Contributors must review, test, and understand all changes before submitting a PR. This applies equally to manually written and tool-generated code. Use of AI or other tools does not transfer responsibility — the contributor is fully accountable for the final patch.

Changes must be small and focused. Avoid unrelated edits, cleanup, or formatting changes. Maintainers may ask for large or mixed changes to be split before review.

Refactors are allowed but must be directly relevant to the change. Do not include opportunistic or drive-by refactoring.

All relevant build, lint, and test steps must pass locally before opening a PR.

PRs must be ready for review when submitted, not ready for validation. The contributor is responsible for verifying correctness before asking for a reviewer's time.

For detailed code and eBPF/C guidelines, see AGENTS.md.

Code Ownership

AI tools are permitted, but they do not change what is expected of contributors. Every line in a PR is your responsibility, regardless of how it was produced. If you cannot explain a change, do not submit it.

Reviewers will ask you to walk through your changes. Inability to explain the rationale, the approach, or the details of any part of a PR is grounds for rejection. This includes changes generated or suggested by AI tools.

Avoid reimplementing existing code. AI tools frequently generate new implementations of functionality that already exists in the codebase. Before introducing any new utility, helper, abstraction, or pattern, search the codebase first. Reviewers will reject code that duplicates existing functionality.

Vet AI-generated plans and issue reports before filing. If you use an AI tool to draft an issue, design proposal, or implementation plan, read it critically before submitting. Check that it accurately reflects the codebase, does not contradict existing architecture, and does not propose work that is already done. Unvetted AI output creates noise and wastes reviewer time.

Pull Requests

How to Send Pull Requests

Everyone is welcome to contribute code to opentelemetry-ebpf-instrumentation via GitHub pull requests (PRs).

To create a new PR, fork the project in GitHub and clone the upstream repo:

git clone https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation

This would put the project in the opentelemetry-ebpf-instrumentation directory in current working directory.

Enter the newly created directory and add your fork as a new remote:

git remote add <YOUR_FORK> git@github.com:<YOUR_GITHUB_USERNAME>/opentelemetry-ebpf-instrumentation

Check out a new branch, make modifications, run linters and tests, and push the branch to your fork:

git checkout -b <YOUR_BRANCH_NAME>
# edit files
make fmt
make lint
git add -p
git commit
git push <YOUR_FORK> <YOUR_BRANCH_NAME>

Open a pull request against the main opentelemetry-ebpf-instrumentation repo.

How to Receive Comments

  • If the PR is not ready for review, please put [WIP] in the title or mark it as draft.
  • Make sure CLA is signed and CI is clear.

How to Get PRs Merged

Important

In order to facilitate PR reviews, PRs should be made of atomic commits that can be individually reviewed, even if they end up being squashed at the time of merge.

A PR is considered ready to merge when:

  • It has received at least one qualified approval1.

    For complex or sensitive PRs maintainers may require more than one qualified approval.

  • All feedback has been addressed.

    • All PR comments and suggestions are resolved.
    • All GitHub Pull Request reviews with a status of "Request changes" have been addressed. Another review by the objecting reviewer with a different status can be submitted to clear the original review, or the review can be dismissed by a Maintainer when the issues from the original review have been addressed.
    • Any comments or reviews that cannot be resolved between the PR author and reviewers can be submitted to the community Approvers and Maintainers during the weekly SIG meeting. If consensus is reached among the Approvers and Maintainers during the SIG meeting the objections to the PR may be dismissed or resolved or the PR closed by a Maintainer.
    • Any substantive changes to the PR require existing Approval reviews be cleared unless the approver explicitly states that their approval persists across changes. This includes changes resulting from other feedback. Approvers and Maintainers can help in clearing reviews and they should be consulted if there are any questions.

Note

It’s often helpful to let the reporter resolve a comment or issue themselves, rather than resolving it on their behalf. This reduces back-and-forth and makes it easier to track which feedback is still pending.

  • The PR branch is up to date with the base branch it is merging into.

    • To ensure this does not block the PR, it should be configured to allow maintainers to update it.

  • All required GitHub workflows have succeeded.

  • Urgent fix can take exception as long as it has been actively communicated among Maintainers.

Any Maintainer can merge the PR once the above criteria have been met.

Approvers and Maintainers

Maintainers

For more information about the maintainer role, see the community repository.

Approvers

For more information about the approver role, see the community repository.

Become an Approver or a Maintainer

See the community membership document in OpenTelemetry community repo.

Footnotes

  1. A qualified approval is a GitHub Pull Request review with "Approve" status from an OpenTelemetry eBPF Instrumentation Approver or Maintainer. ↩