Contributing to OTel-Arrow

September 4, 2026 · View on GitHub

Introduction

Welcome to the OpenTelemetry Protocol with Apache Arrow project! :tada: This repository defines and supports Golang and Rust libraries for producing and consuming telemetry data streams using the OpenTelemetry Protocol with Apache Arrow.

We value all contributions, whether big or small, and encourage you to join us in improving this project. If you have questions, don't hesitate to reach out to the OpenTelemetry community - we're here to help!

Pre-requisites

To work with this repository, you'll need:

Local Run/Build

Initialize Git submodules so that the OpenTelemetry protocol references used in building from .proto definitions can succeed:

git submodule update --init --recursive

When successful, you will find the directory proto/opentelemetry-proto/ populated with the OpenTelemetry protocol definition used in this repository.

How to set up and run a local OTel-Arrow collector

See collector/README.md for instructions on running the examples. See collector/BUILDING.md for instructions on building a collector from local sources.

Testing

-How to run the test suite for the repository. (TBD)

-Explanation of different types of tests (e.g., unit, integration, or functional). (TBD)

-Tools and frameworks used for testing (TBD)

-How to interpret test results and resolve common test failures. (TBD)

-Mention code coverage expectations or reporting tools if applicable. (TBD)

Micro Benchmarks

With certain code changes in the rust code base, running micro benchmarks to see if there are any issues with the performace could be a good idea. In order to do this cargobench label can be added to the pull request, which will trigger the Rust-Benchmarks workflow.

Contribution Guidelines

This guide outlines best practices and requirements to ensure a smooth and effective contribution process.

Adhering to Coding Standards

All contributions must align with the project's coding standards and guidelines. These standards ensure consistency, readability, and maintainability of the codebase. Please review the following:

  • Use clear and concise naming conventions for variables, functions, and files.
  • Run linters or formatters where applicable to maintain consistent code style.

Writing Meaningful Commit Messages

Commit messages are essential for understanding the history and context of changes. Follow these tips for writing effective commit messages:

  • Use the conventional commit format:

Examples of <type>: feat (new feature), fix (bug fix), docs (documentation updates), test (test-related updates), etc.

  • Include a brief description of what and why, avoiding overly technical jargon.
  • Use present-tense verbs, e.g., "Add" instead of "Added."

Changelog entries

This repository maintains two changelogs - go/CHANGELOG.md for the Go tree and rust/otap-dataflow/CHANGELOG.md for the Rust tree. Both are managed with chloggen. Entries live alongside the code they describe:

Every PR with a user-facing change must add at least one YAML entry in the appropriate directory. Copy the TEMPLATE.yaml in the appropriate .chloggen/ directory to a new .yaml file (e.g. arrow-encoder-fix-null-handling.yaml) and fill in the fields (change_type, component, note, issues).

Changelog eligibility currently tracks user-facing behavior, not API compatibility. The project does not publish crates or make an API stability promise, so an API change alone is not a breaking change. Choose the entry type that describes the user-facing impact instead.

You can validate or preview entries locally:

make chlog-install                       # one-time install
make chlog-validate
make chlog-preview                       # optional: render without writing

See go/.chloggen/README.md and rust/otap-dataflow/.chloggen/README.md for the full guide and the allowed component: values (defined in the config.yaml of each directory).

Skipping a changelog entry. Use any of the following when the change is not user-facing (build chores, internal refactors, doc-only edits, dev-only dependency bumps):

  • Include chore in the PR title.
  • Apply the chore label (for maintainers).
  • Apply the skipchangelog label (for maintainers).
  • Documentation-only PRs (all changed files are under a docs/ or rfcs/ directory).
  • PRs confined to rust/contrib/ -- those independently scoped projects ship no repository changelog, so there is no changelog to write an entry into. A PR that also touches a released module (for example rust/otap-dataflow/) is not exempt, even if the bulk of the change is under rust/contrib/.
  • For dependency-update PRs: Renovate auto-applies the dependencies label and bot-authored PRs are exempt.

Note: runtime dependency bumps that ship in a released binary or library should still get a changelog entry, since downstream consumers may care.

The changelog workflow enforces this on pull requests targeting main.

Including Tests for New Features or Bug Fixes

Testing is crucial to ensure code reliability. When contributing:

  • Write unit tests for new features and bug fixes.

  • Document every test immediately above the test declaration with:

    <comment> Scenario: <the behavior or condition under test>
<comment> Guarantees: <the observable invariant protected by the test>

    Use the language's customary comment syntax. Keep both statements specific enough that a reviewer can understand the test's intent and the behavior that must not regress without reading its implementation.

  • Run the test suite before submitting a pull request to verify changes.

  • Ensure test coverage remains high, and add tests for edge cases when applicable.

Community Standards and Style Guides

This project adheres to the OpenTelemetry community's standards. Please ensure you:

Follow the Code of Conduct.

Align with any specific style guides, such as Go Style Guide.

Contributor License Agreement (CLA)

Before contributing, you may need to sign a Contributor License Agreement (CLA). This ensures that the community can freely use your contributions.

Instructions for signing the CLA:

Visit OpenTelemetry CLA Portal and follow the steps to sign electronically.

Further Help

If you have any questions or run into issues:

Our Slack channel is #otel-arrow on CNCF Slack. If you are new to the CNCF Slack community, you can create an account.

Filing Issues

We track bugs, feature requests, and project tasks in GitHub Issues.

Please pick the right channel:

  • Bug, feature, or task: file an issue using the appropriate template.
  • Usage question or open-ended discussion: prefer the CNCF Slack channel #otel-arrow over filing an issue.
  • Security vulnerability: DO NOT file a public issue. Follow SECURITY.md to report privately.

Bug reports

Use the Bug Report template. A good bug report lets anyone reproduce the problem without further back-and-forth. The template prompts for the version, affected component(s), steps to reproduce, expected vs. actual behavior, environment, and logs - please fill in as many fields as apply. Minimal, self-contained reproductions are required for all bug reports. If a minimal repro is not viable, an explanation must be provided in the description.

Feature requests and proposals

Use the Feature Request template. Focus on the use case and the problem you are solving, not a specific implementation. For larger changes that will need design consensus (new components, protocol changes, breaking changes), call that out in the description so a maintainer can sponsor a proposal discussion before implementation begins.

Tasks and other issues

Use the Task template for internal work items (refactors, CI, tooling), or the Other template if none of the above fit.

What happens after you file

New issues are picked up by triagers, who apply labels, ask clarifying questions if needed, and decide whether the issue is ready to work on or needs SIG discussion. The full process - including how to volunteer to work on an open issue - is described in ISSUE_TRIAGE.md.

Our Development Process

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 all required CI checks are clear.
  • Submit small, focused PRs addressing a single concern/issue. See Keep Pull Requests Small and Incremental below for the expectations this project applies.
  • Make sure the PR title reflects the contribution.
  • Write a summary that helps understand the change.
  • Include usage examples in the summary, where applicable.
  • Include benchmarks (before/after) in the summary, for contributions that are performance enhancements.

Keep Pull Requests Small and Incremental

This repository has a limited pool of reviewers and approvers, and PR volume is high. The guiding rule is reviewability: a PR should be small enough and cohesive enough that a single reviewer can give every part close attention in one sitting. This expectation applies regardless of whether the change was authored manually or with AI assistance.

Hard-to-review PRs tend to be approved on the strength of the parts a reviewer was able to read closely, while the rest receives a pass, which slowly erodes long-term quality. Small, single-purpose PRs are the default because they are the easiest to review well; larger PRs are fine when the change is genuinely cohesive and clearly scoped.

Guidelines:

  • One concern per PR. A PR should do one thing: add a config type, wire a no-op, implement one behavior, fix one bug, perform one refactor. If the description needs the word "and", consider splitting.
  • Use diff size as a signal, not a limit. As a rough heuristic, PRs beyond ~400 lines of meaningful diff (excluding generated code, lockfiles, vendored data, and test fixtures) are worth a second look to see whether they can be split. Larger PRs are welcome when the change is cohesive (e.g. a single mechanical refactor, or a tightly-coupled set of edits that only make sense together); the description should briefly explain why the change is best reviewed as one unit.
  • Separate mechanical changes from logic changes. Renames, reformats, file moves, and dependency bumps belong in their own PRs, not bundled with behavioral changes.
  • Build new features incrementally. A typical sequence is:
    1. Introduce the crate / module skeleton in the right location.
    2. Add configuration types (serde, validation, tests) wired as a no-op.
    3. Integrate the no-op into the pipeline / runtime.
    4. Add behavior in small, independently reviewable slices, each with tests.
    5. Documentation and examples.
  • Use a tracking issue for multi-PR features so the overall design and progress remain visible to reviewers across the sequence of PRs.

Reviewers may ask authors to split a PR when it is hard to review thoroughly -- for example, when it bundles unrelated changes or is large enough that no single reviewer can give every component close attention. A large but cohesive PR with a clear scope and a description explaining why it is reviewed as one unit is fine.

How to Get PRs Merged

A PR is considered to be ready to merge when:

  • It has received approval from at least one Approver / Maintainer.
  • Major feedback is resolved.

Any Maintainer can merge the PR once it is ready to merge. Note, that some PRs may not be merged immediately if the repo is in the process of a release and the maintainers decided to defer the PR to the next release train. Also, maintainers may decide to wait for more than one approval for certain PRs, particularly ones that are affecting multiple areas, or topics that may warrant more discussion.

Repository background

The OpenTelemetry Protocol with Apache Arrow project was initially developed in the github.com/f5/otel-arrow-adapter repository. At the time of the OpenTelemetry donation, this repository was a construction of original code and code copied from the OpenTelemetry Protocol with Apache Arrow Collector, which is a fork of the OpenTelemetry Collector, as part of our development process.

Source locations

This repository contains the OpenTelemetry Protocol with Apache Arrow definition and our Rust and Golang reference implementations.

Exporter and receiver components for the OpenTelemetry Collector were developed in parallel, maintained in this repository through release v0.24.0, and now they are included in release of the OpenTelemetry Collector-Contrib repository.

  • Exporter: Send telemetry data using OpenTelemetry Protocol with Apache Arrow
  • Receiver: Receive telemetry data using OpenTelemetry Protocol with Apache Arrow.

Historically, the exporter and receiver components were forked from the Collector's core OTLP Exporter and OTLP Receiver, and the original branch history is now archived in the OpenTelemetry Protocol with Apache Arrow Collector repository.

How to change the protobuf specification

To (re)generate the ArrowStreamService gRPC service, you need to install the protoc compiler and the protoc-gen-grpc plugin.

go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.2
export PATH="$PATH:$(go env GOPATH)/bin"
./proto/generate.sh

Once the *.pb.go files are generated, you need to replace the content of the api/collector/arrow/v1 directory by the generated files present in the ./proto/api/collector/arrow/v1 directory.

Releasing this repository

See the instructions in RELEASING.md.

Local development issues: Rust

See the otap-dataflow-specific CONTRIBUTING.

Local development issues: Golang

This repository contains a top-level go.work file. This enables the Go modules defined here to avoid relative replace statements, which interfere with the ability to run them via simple go install and go run commands. The go.work file names all the module definitions inside this repository and allows them all to be used at once during local development.

Upgrading the collector used for testing

The OTAP components are tested using the upstream OpenTelemetry Collector Contrib distribution rather than a collector generated in this repository. The distribution version is pinned in the top-level Dockerfile (FROM otel/opentelemetry-collector-contrib:<tag>@sha256:<digest>) and is kept up to date automatically by Renovate (see .github/renovate.json5, which enables docker:pinDigests). To upgrade manually, edit the tag and digest on that FROM line. See collector/BUILDING.md for details.

Project Team

Maintainers

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

Approvers

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

Emeritus Approvers

Triagers

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