[pkg/ottl] Improve OTTL Docs

open-telemetry / opentelemetry-collector-contrib

Contrib repository for the OpenTelemetry Collector

https://opentelemetry.io

Apache License 2.0

3.08k stars 2.38k forks source link

[pkg/ottl] Improve OTTL Docs #31387

Open TylerHelmuth opened 8 months ago

TylerHelmuth commented 8 months ago

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[bot] commented 8 months ago

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[bot] commented 8 months ago

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[bot] commented 8 months ago

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[bot] commented 6 months ago

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 commented 3 months ago

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 commented 3 months ago

I think https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/29017 helps with the context problem.

bixu commented 3 months ago

@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 commented 3 months ago

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