[pkg/stanza] Path to developing new receivers

[c-kruse]

Component(s)

pkg/stanza

Describe the issue you're reporting

I recently went through the process of starting to develop a new stanza-enabled receiver and found the learning curve quite steep. I've got a few suggestions on how to make this task a little more approachable, but feel free to steer this where you think there may be value.

For the existing stanza input operator based receivers the adapter package is quite clean, but at first approach it looks a bit like magic. When adding a receiver based on a new source that isn't based off a pre-existing input operator there are relatively few clues. There is a configuration Builder pattern that is apparent, but it's interface is relatively large, and the Operator interface it is meant to produce is more so. I think docs on building and configuring an operator, and the struct embedding that makes it reasonable would be pretty helpful. The CONTRIBUTING.md from the observIQ repo has just this - wish I'd have seen it earlier!.

Our use case is a little bespoke, and might not be terribly relevant to anyone in the future, but I ended up needing to arrange a bit of a shim layer. Stanza is, for lack of a better term, secondary, to what our receiver is trying to accomplish. The input operator configuration happens to be nested under an output configuration block and I wasn't particularly keen on embedding some of those structs in our configuration. I'm not sure if there's anything to learn from this, but maybe a curious onlooker might have takeaways form how I had to contort here re the builder package. PR with that changeset: SumoLogic/sumologic-otel-collector#1227

One other idea that folks seemed to want to reach for, was not developing the core functionality of the receiver as an input operator at all. Similar to what the logstransformprocessor does. Perhaps that pattern could be useful as an alternative?

Thank you all for reading!

[github-actions]

Pinging code owners:

• pkg/stanza: @djaglowski

See Adding Labels via Comments if you do not have permissions to add labels yourself.

[djaglowski]

Thanks for the feedback @c-kruse. I'm glad to see that the stanza codebase can be useful for new components. I'm not aware of many such cases so it's not received much attention in terms of developer-facing usability.

That said, I'm still a bit conflicted about whether to put effort into this aspect of the code. How many people will write additional stanza-based receivers? I'm sure there will be a few more, but it doesn't seem like a process that needs to be heavily optimized. I'm not saying we shouldn't make it easier but the cost of doing so could easily exceed the value. My guess is that a bit of documentation like you suggested would go a long way. We could always iterate later if the need becomes more apparent.

[c-kruse]

Thank you again @djaglowski! I can certainly appreciate not wanting to over invest in this aspect.

For what it is worth I would be pleased to see some basic docs added to the package - maybe speaking to the project's status in relation to observIQ and OTEL and then design choices/operator development as I had suggested above.

[github-actions]

This issue has been inactive for 60 days. It will be closed in 60 days if there is no activity. To ping code owners by adding a component label, see Adding Labels via Comments, or if you are unsure of which component this issue relates to, please ping @open-telemetry/collector-contrib-triagers. If this issue is still relevant, please ping the code owners or leave a comment explaining why it is still relevant. Otherwise, please close it.

Pinging code owners:

• pkg/stanza: @djaglowski

See Adding Labels via Comments if you do not have permissions to add labels yourself.

[github-actions]

This issue has been closed as inactive because it has been stale for 120 days with no activity.