HttpSemanticConventions - new metric in AspNetCore Instrumentation.

[TimothyMothra]

Towards #4484
Supersedes #4766

This PR focus on introducing the new http.server.request.duration metrics in the AspNetCore Instrumentation library.

Changes

• all the following changes are made behind the environment variable OTEL_SEMCONV_STABILITY_OPT_IN
• update Instrumentation.AspNetCore class HttpInMetricsListener to emit new metric.
  • http.server.duration (milliseconds) replaced with http.server.request.duration (seconds milliseconds seconds)
    This is defined in the as-of-yet unreleased v1.22.0 https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-metrics.md
• remove opt-in attributes
  • server.port
  • server.address

Future work

• The unit of this metric needs to be changed to seconds. This requires a different default histogram. DONE!

Merge requirement checklist

• CONTRIBUTING guidelines followed (nullable enabled, static analysis, etc.)
• Unit tests added/updated
• Appropriate CHANGELOG.md files updated for non-trivial changes
• Changes in public API reviewed (if applicable)

[codecov]

Codecov Report

Merging #4802 (0015a20) into main (680115f) will increase coverage by 0.00%.
The diff coverage is 68.18%.

@@           Coverage Diff           @@
##             main    #4802   +/-   ##
=======================================
  Coverage   83.90%   83.90%           
=======================================
  Files         293      293           
  Lines       12001    12028   +27     
=======================================
+ Hits        10069    10092   +23     
- Misses       1932     1936    +4     

Files Changed	Coverage
...AspNetCore/Implementation/HttpInMetricsListener.cs	68.18%

[utpilla]

Suggested change

	Have you opt-ed into the new Http Semantic Conventions using `OTEL_SEMCONV_STABILITY_OPT_IN`?
	Have you opted in to the new Http Semantic Conventions using `OTEL_SEMCONV_STABILITY_OPT_IN`?

[utpilla]

Use the commit tag?

[TimothyMothra]

I'm conflicted here.
I would rather link to an explicit tag. There changes we're implementing now are post v1.21.0, but this repo hasn't made a new release yet.

I can change links in both the Readme and Changelog to a commit as you've suggested.
When the next release happens (presumably v1.22.0) I think we should update these links.

[utpilla]

Same as https://github.com/open-telemetry/opentelemetry-dotnet/pull/4802/files#r1323869142

[utpilla]

Left a few suggestions for CHANGELOG and README.

[cijothomas]

This metric measures time in seconds and offers unique
histogram buckets

Not sure how to interpret "offers unique histogram buckets"? What does it mean?

[TimothyMothra]

"offers" is the wrong word here, "uses" would be more appropriate.
I'm trying to call attention to the fact that the buckets are different than the default.
4 lines below this I list the exact buckets.

I'm trying to find a succinct way to describe that this metric is different than what came before.
@cijothomas, do you think this would be better as a bulleted list?

ie:

- new metric: `http.server.request.duration`
- unit: seconds
- buckets: 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1,
  2.5, 5, 7.5, 10

[cijothomas]

the list is good. Hint that the buckets are so, because SDK specially handles this metric.

[cijothomas]

this is not clear. The env variable can take none,http,http/dup as values, This doc should also be structured in that way. i.e what if the env variable is set to "none", (also the default)
what is the env varaible is set to "http"
what is the env varaible is set to "http/dup" - both metric are emitted

[TimothyMothra]

@utpilla, @cijothomas, @vishweshbankwar
I've rewritten both the Readme and Changelog. Please re-review.

[cijothomas]

Introduced a new metric, http.server.request.duration, for users who opt-in
to the new semantic convention by configuring the OTEL_SEMCONV_STABILITY_OPT_IN
environment variable to value "fillthis". This metric measures time in seconds, but histogram buckets are adjusted
automatically for this metric by OTel SDK which specially treat this metric. This metric follows the OTel Semantic Conventions from (add link).

• Metric Name: http.server.request.duration
• Unit: seconds
• Histogram Buckets: 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 (due to OpenTelemetry SDK's special treatment)
• Replaces old metric: http.server.duration
  • Unit: miliseconds
  • Histogram Buckets: 0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000 (the general default of Histogram buckets)

OTEL_SEMCONV_STABILITY_OPT_IN may be set to "fillthis", to help an easier transition, at the cost of emitting both old and new metrics.

^did some refactoring. Feel free to take it with modifications.
A user who do not have any experience with OTel sem. conventions and the new vs old, should find it easy to follow the changelog. Key things I'd prefer to convey here are:

1. No breaking changes if you just update to this new version.
2. Opt-in feature to emit a new metric that follows a new convention, which despite using "s", still allows good histogram precision due to SDK treating it specially.
3. Hint at emitting both to smooth transition.
4. Hint that the new metric is the long term bet, as it'll be the one getting stabilizied by Otel sem convention.

[TimothyMothra]

Thanks for the refactor. I'll take another pass at this today.

Do we typically put instructions in the changelog? I was trying to keep the changelog succinct, and use the readme for the full information. The challenge is that this change has a LOT of details :)

[TimothyMothra]

just pushed my rewrite. I think I've addressed all your points. please re-review.

[utpilla]

@TimothyMothra Thanks for your patience on working on this PR!

[TimothyMothra]

@TimothyMothra Thanks for your patience on working on this PR!

This one was tricky and touched a lot of parts! Glad we could get this merged.