Skip to content

Latest commit

 

History

History
173 lines (114 loc) · 7.45 KB

CONTRIBUTING.md

File metadata and controls

173 lines (114 loc) · 7.45 KB

Contributing to the OpenTelemetry Protocol with Apache Arrow project

Introduction

Welcome to the OpenTelemetry Protocol with Apache Arrow project! 🎉
This repository defines and supports Golang 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

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)

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."

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.
  • 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:

Join the OpenTelemetry Slack Community.

Our Development Process

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 Golang libraries for producing and consuming streams of data in this format.

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/[email protected]
go install google.golang.org/grpc/cmd/[email protected]
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

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 OpenTelemetry Collector dependencies

When a new version of the OpenTelemetry collector, is available, the easiest way to upgrade this repository is:

  1. Update the distribution::otelcol_version field in otelarrowcol-build.yaml
  2. Modify any components from the core or contrib repositories to use the corresponding versions (e.g., pprofextension's module version should match the new collector release).
  3. Regenerate otelarrowcol via make genotelarrowcol
  4. Run go work sync to update the other modules with fresh dependencies.