Docs for Metrics - add basic and advanced examples

[cijothomas]

Opening an issue to track adding docs for Metrics.

Proposing to add 2 examples to begin with:

1. Basic instrumentation - This will use stdout exporter, and show example usage of all instrument kinds. More geared towards "learning the various OTel instruments".
2. Advanced configuration - This will use OTLP Exporter, and shows advanced configuration - Views (and its various use cases), changing Temporality.

The docs alone might not be sufficient, hence the proposal to have 2 examples. Happy to iterate based on feedback.

Note: It was discussed in today's SIG meeting as well, in the context of filling the spec compliant matrix. The examples will demonstrate most common use cases, and not every line item from the spec-compliance matrix.

Related issue : #914

[cijothomas]

I'll start with a simple PR to kick-start 1 from the above, and iterate based on the feedbacks.

[jtescher]

@cijothomas this considered resolved now?

[cijothomas]

@cijothomas this considered resolved now?

Not yet. Will need another follow up to #1170 (it has desc. about the nest PRs.)

[cijothomas]

One key thing missing today is:
Changing Temporality to Delta (as a lot of observability vendors accept delta only, but default is cumulative.)

Tagging as good-first-issue, to see if anyone wants to enhance the example to show the above.

[cijothomas]

Need to address the issue about using Views with OTLP Exporter as well. Its probably involves code change, but a temporary docs change could help as well : #1174 (comment)

[mattbodd]

I'm interested in taking this on @cijothomas

[Annosha]

@mattbodd are you working on updating the docs? If not I'd like to work on this issue. TIA @cijothomas

[cijothomas]

@Annosha feel free to send short PRs with doc improvements. There are WIP PRs like #2221 and #2220 that affect some docs, so short, focused PRs are recommended.

Few things I suggest to make it super clear in docs (just an initial list from top of mind)

1. MeterProvider should be created once only.
2. Meters should be created once only
3. Instruments should be created once and re-used. It is okay to create instruments from multiple places (internally it'll be same instrument), but users should store the instrument and reuse.
4. For observable callbacks, make sure the callback code has no async runtime specifics like tokio::sleep etc.

[cijothomas]

@Annosha feel free to send short PRs with doc improvements. There are WIP PRs like #2221 and #2220 that affect some docs, so short, focused PRs are recommended.

Few things I suggest to make it super clear in docs (just an initial list from top of mind)

1. MeterProvider should be created once only.
2. Meters should be created once only
3. Instruments should be created once and re-used. It is okay to create instruments from multiple places (internally it'll be same instrument), but users should store the instrument and reuse.
4. For observable callbacks, make sure the callback code has no async runtime specifics like tokio::sleep etc.

@Annosha Are you planning to work on this?

[cijothomas]

#2946 can close this.