Skip to content

Commit

Permalink
Improve "Adding New Components" section
Browse files Browse the repository at this point in the history
There was some feedback from initial PR that was not incorporated, see open-telemetry#88
  • Loading branch information
Paulo Janotti committed Jan 16, 2020
1 parent fc49e9a commit 992e5c3
Showing 1 changed file with 15 additions and 9 deletions.
24 changes: 15 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
This is a repository for OpenTelemetry Collector contributions that are not part of the
[core repository](https://github.com/open-telemetry/opentelemetry-collector) and
core distribution of the Collector. Typically, these contributions are vendor
specific receivers/exporters and/or components that are either legacy or are only
useful to relatively small number of users.
specific receivers/exporters and/or components that are only
useful to a relatively small number of users.

## Contributing
If you would like to contribute please read [contributing guidelines](https://github.com/open-telemetry/opentelemetry-collector/blob/master/CONTRIBUTING.md)
Expand All @@ -17,6 +17,11 @@ the interfaces defined on the [core repository](https://github.com/open-telemetr
Familiarize yourself with the interface of the component that you want to write,
and use existing implementations as reference.

*NOTICE:* The Collector is in Alpha 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.

- 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,
Expand All @@ -28,9 +33,9 @@ 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 soruce files and tests.

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% of code coverage.
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
Expand All @@ -43,12 +48,13 @@ Below are some recommendations that apply to typical components. These are not r
rules and there are exceptions to them, but, take care considering when you are
not following them.

- Avoid introducing asynchronicity 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).
- 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](https://github.com/open-telemetry/opentelemetry-collector/tree/master/exporter/exporterhelper)
on core repo.
repo, see [exporterhelper package](https://github.com/open-telemetry/opentelemetry-collector/tree/master/exporter/exporterhelper).
This will ensure that the exporter provides [zPages](https://opencensus.io/zpages/)
and a standard set of metrics.

### Questions?
Reach the Collector community on [gitter](https://gitter.im/open-telemetry/opentelemetry-service)
Expand Down

0 comments on commit 992e5c3

Please sign in to comment.