[pkg/ottl] Improve OTTL Docs

[TylerHelmuth]

Component(s)

pkg/ottl

Is your feature request related to a problem? Please describe.

OTTL docs exist, but I get the sense that they are sufficient. We get lots and lots of questions in the CNCF slack and in Github about how to use OTTL, especially in the filterprocessor.

Describe the solution you'd like

We should do a wholistic review of our docs, making sure that they are as user-focused as possible. While the API/Grammar of OTTL is important, it isn't as important as directing users to how to write statements in their configs.

Things to review:

• Func documentation
• Examples
• Documentation of important language features, such as passing Converters as params, arithmetic, where clauses, etc.
• Precence on opentelemetry.io
• Transformprocessor readme
• Filterprocessor readme.

[github-actions]

Pinging code owners for processor/filter: @TylerHelmuth @boostchicken. See Adding Labels via Comments if you do not have permissions to add labels yourself.

[github-actions]

Pinging code owners for pkg/ottl: @TylerHelmuth @kentquirk @bogdandrutu @evan-bradley. See Adding Labels via Comments if you do not have permissions to add labels yourself.

[github-actions]

Pinging code owners for processor/transform: @TylerHelmuth @kentquirk @bogdandrutu @evan-bradley. See Adding Labels via Comments if you do not have permissions to add labels yourself.

[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:

• processor/filter: @TylerHelmuth @boostchicken
• processor/transform: @TylerHelmuth @kentquirk @bogdandrutu @evan-bradley
• pkg/ottl: @TylerHelmuth @kentquirk @bogdandrutu @evan-bradley

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

[bixu]

Things to review:

• Func documentation
• Examples
• Documentation of important language features, such as passing Converters as params, arithmetic, where clauses, etc.
• Precence on opentelemetry.io
• Transformprocessor readme
• Filterprocessor readme.

To these I would add:

• High-level explanation of Contexts and and their relationships (ie accessing values across context boundaries)

While OTTL feature set feels pretty rich atm, it remains hard to learn for new practitioners due to the sparseness of docs. Still, I envision a future where we use OTTL for all of our telemetry processing at $job. Great docs would speed up our adoption.

[TylerHelmuth]

I think #29017 helps with the context problem.

[bixu]

@TylerHelmuth, I'm interested in taking a crack at this. Do we have an example of docs elsewhere in the project that would be a good example to follow? If not, can I submit a draft PR to get early feedback?

[TylerHelmuth]

The stanza docs are pretty good.

I'm pretty happy with our function docs, but unhappy with how we explain what a transform context means. I would also like to see a ton of this stuff be on the opentelemetry.io site