Skip to content

Latest commit

 

History

History
91 lines (74 loc) · 6.24 KB

CONTRIBUTING.md

File metadata and controls

91 lines (74 loc) · 6.24 KB
Raw

Contributing

If you would like to contribute please read OpenTelemetry Collector contributing guidelines before you begin your work.

Pull-request title

The title for your pull-request should contain the component type and name in brackets, plus a short statement for your change. For instance:

[processor/tailsampling] fix AND policy

Adding New Components

Before any code is written, open an issue providing the following information:

  • Who's the sponsor for your component. A sponsor is an approver who will be in charge of being the official reviewer of the code and become a code owner for the component. For vendor-specific components, it's good to have a volunteer sponsor. If you can't find one, we'll assign one in a round-robin fashion. A vendor-specific component directly interfaces with a vendor-specific API and is expected to be maintained by a representative of the same vendor. For non-vendor specific components, having a sponsor means that your use case has been validated.
  • Some information about your component, such as the reasoning behind it, use-cases, telemetry data types supported, and anything else you think is relevant for us to make a decision about accepting the component.
  • The configuration options your component will accept. This will help us understand what it does and have an idea of how the implementation might look like.

Any component (receiver, processor, exporter, or extension) needs to implement the interfaces defined on the core repository. Familiarize yourself with the interface of the component that you want to write, and use existing implementations as reference.

NOTICE: The Collector is in Beta stage and as such the interfaces may undergo breaking changes. Component creators must be available to update or review their components when such changes happen, otherwise the component will be excluded from the default builds.

Generally, maintenance of components is the responsibility of contributors who authored them. If the original author or some other contributor does not maintain the component it may be excluded from the default build. The component will be excluded if it causes build problems, has failing tests or otherwise causes problems to the rest of the repository and the rest of contributors.

  • Create your component under the proper folder and use Go standard package naming recommendations.
  • Use a boiler-plate Makefile that just references the one at top level, ie.: include ../../Makefile.Common - this allows you to build your component with required build configurations for the contrib repo while avoiding building the full repo during development.
  • Each component has its own go.mod file. This allows custom builds of the collector to take a limited sets of dependencies - so run go mod commands as appropriate for your component.
  • Implement the needed interface on your component by importing the appropriate component from the core repo. Follow the pattern of existing components regarding config and factory source files and tests.
  • Implement your component as appropriate. Provide end-to-end tests (or mock backend/client as appropriate). Target is to get 80% or more of code coverage.
  • Add a README.md on the root of your component describing its configuration and usage, likely referencing some of the yaml files used in the component tests. We also suggest that the yaml files used in tests have comments for all available configuration settings so users can copy and modify them as needed.
  • Add a replace directive at the root go.mod file so your component is included in the build of the contrib executable.
  • Add your component to versions.yaml.
  • All components must be included in internal/components/ and in the respective testing harnesses. To align with the test goal of the project, components must be testable within the framework defined within the folder. If a component can not be properly tested within the existing framework, it must increase the non testable components number with a comment within the PR explaining as to why it can not be tested.

Rotating sponsors

The following GitHub users are the currently available sponsors, either by being an approver or a maintainer of the contrib repository. The list is ordered based on a random sort of the list of sponsors done live at the Collector SIG meeting on 27-Apr-2022 and serves as the seed for the round-robin selection of sponsors, as described in the section above.

Whenever a sponsor is picked from the top of this list, please move them to the bottom.

General Recommendations

Below are some recommendations that apply to typical components. These are not rigid rules and there are exceptions but in general try to follow them.

  • Avoid introducing batching, retries or worker pools directly on receivers and exporters. Typically, these are general cases that can be better handled via processors (that also can be reused by other receivers and exporters).
  • When implementing exporters try to leverage the exporter helpers from the core repo, see exporterhelper package. This will ensure that the exporter provides zPages and a standard set of metrics.
  • replace statements in go.mod files can be automatically inserted by running make crosslink. For more information on the crosslink tool see the README here.