Provide examples on how to create components

[hickeyma]

EDIT: I have kept all original text (with strikethrough) but have made modifications based on feedback

It would be very helpful and improve usability if an example~~s~~ ~~were~~ was provided for ~~the different~~ a component~~s like receivers, processor, exporters and extensions~~. This would simplify the process of creating a component for new users.

~~Examples could be added to the Go documentation for the component package. Refer to Testable Examples in Go for more details.~~

This request follows a discussion with @mx-psi.

Tasks

• [ ] Add Building a Trace Receiver reference to collector contrib Adding New Components section (https://github.com/open-telemetry/opentelemetry-collector-contrib/pull/12490)
• [x] Add Building a Trace Receiver reference to collector When adding a new component section (#5690)
• [ ] Add "Building Component" sub menu to Collector Docs which would contain Building a custom authenticator and Building a Trace Receiver

[mx-psi]

Should we create an checklist for each kind of component (receiver, processor, exporter, extension...)? So that this can potentially be taken on by several people

[fatsheep9146]

I agree, I think we can also learn from go-contrib new instrumentation library request template to define following steps/tasks to build a usable component.

Tasks

• Code complete:
  • [ ] Comprehensive unit tests.
  • [ ] End-to-end integration tests.
  • [ ] Tests all passing.
  • [ ] Instrumentation functionality verified.
• Documented
  • [ ] Added to the OpenTelemetry Registry
  • [ ] README included for the module describing high-level purpose.
  • [ ] Complete documentation of all public API including package documentation.
  • [ ] Instrumentation documentation updated.
• Examples
  • [ ] Dockerfile file to build example application.
  • [ ] docker-compose.yml to run example in a docker environment to demonstrate instrumentation.

[hickeyma]

Good ideas @mx-psi @fatsheep9146. I'll add to the description when I get a chance.

[jpkrohling]

Is this about adding documentation for people creating new components (ie, writing Go code that ends up in a distribution), or is it for end-users, configuring components available in a collector distribution?

[mx-psi]

Is this about adding documentation for people creating new components (ie, writing Go code that ends up in a distribution), or is it for end-users, configuring components available in a collector distribution?

The former: writing Go code

[fatsheep9146]

Good ideas @mx-psi @fatsheep9146. I'll add to the description when I get a chance.

@hickeyma Excellent :-), I’d love to help with review or contribute for this issue if you need.

[jpkrohling]

There are a couple of pages/articles that can serve as the foundation for this:

https://medium.com/opentelemetry/extending-the-opentelemetry-collector-with-your-own-components-64c10cf675db https://opentelemetry.io/docs/collector/custom-auth/ https://opentelemetry.io/docs/collector/trace-receiver/

[hickeyma]

Thanks for the links @jpkrohling

[hickeyma]

Following the feedback from @jpkrohling in https://github.com/open-telemetry/opentelemetry-collector/issues/5675#issuecomment-1181985956, I investigated this further. Here is the feedback from my investigation:

• The Building a Trace Receiver doc is an excellent reference for building a component and I think it trancends a trace receiver component. I therefore think that having examples per component type would be overhead.
• Examples added to the Go documentation is very nice capability but I'm not sure the component models fits nicely with it because the Building a Trace Receiver doc shows how involved building a component is and not just short snappy end to end code. It also requires a lot of background explanation to make decisions.
• By adding links in key existing documentation would direct a user to useful documentation like the Building a Trace Receiver doc.

I have updated the description to breakdown what I propose the tasks could be for this work.

@mx-psi @fatsheep9146 @jpkrohling Please let me know what you think.

[mx-psi]

@hickeyma I think having a link to that doc is definitely better than not having anything! The benefit of having a testable example is that we ensure that the examples will always be kept up to date (since CI will fail otherwise), but it's true that they won't be end to end examples

[hickeyma]

@mx-psi Ok, thanks for the feedback.

I think having a link to that doc is definitely better than not having anything!

I have pushed #5690 and https://github.com/open-telemetry/opentelemetry-collector-contrib/pull/12490 to see provide context and references.

The benefit of having a testable example is that we ensure that the examples will always be kept up to date (since CI will fail otherwise), but it's true that they won't be end to end examples

I agree that this would be beneficial. Does this work when its not an end to end example for a user?

[mx-psi]

I took a look at your PRs @hickeyma, they make sense to me :)

Does this work when its not an end to end example for a user?

I don't understand what you mean in this question, sorry

[hickeyma]

I don't understand what you mean in this question, sorry

I am wondering if providing a testable example which is not end to end would make sense for the components?

[hickeyma]

I’d love to help with review or contribute for this issue if you need.

@fatsheep9146 Let me know if you would like to tackle the open issue of sub menu to collector docs (refer to item in description).

[mx-psi]

I am wondering if providing a testable example which is not end to end would make sense for the components?

Ah, okay, thanks for clarifying! I think there is some value (maybe not only for component developers but also for other users of the Go API) and we can have some dummy implementation (so e.g. a receiver that generates a gauge point every minute? or some sort of simple logging exporter?) that still showcases how to use the interface.

Do you agree?

[Chinwendu20]

The third in the checklist should be modified in the opentelemetry.io repo right?

[hickeyma]

@Chinwendu20 It should be. Are you interested in pushing a PR?

[Enzujp]

Hello @hickeyma , if it is still valid, I'd like to work on the third item in the checklist!

[hickeyma]

@Enzujp Haven't looked at it in over a year. Maybe check the docs and see?

[Enzujp]

Will do just that.