Metrics customization guide with .NET 9 Advice API details #5911

Annosha · 2024-10-21T07:38:41Z

Closes #5855 Update documentation for .NET 9 Advice API

Changes

Added documentation for explicit bucket histogram aggregation using the .NET 9 Advice API.
Provided example code to demonstrate the usage of explicit bucket boundaries in histograms.
Included best practices for selecting meaningful bucket boundaries and tips for using the new API.

Merge requirement checklist

CONTRIBUTING guidelines followed (license requirements, 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)

Annosha · 2024-10-21T07:57:10Z

@CodeBlanch Please review the changes and provide necessary feedback.

cijothomas · 2024-10-21T12:32:50Z

docs/metrics/customizing-the-sdk/README.md

+With the introduction of the .NET 9 Advice API, developers can
+customize histogram metrics more effectively. The Advice API
+allows for explicit bucket boundaries when defining histograms,
+leading to more precise and informative metrics.


Customizing buckets via views offer same precision so this statement is not fully true.

cijothomas · 2024-10-21T12:33:34Z

docs/metrics/customizing-the-sdk/README.md

@@ -335,6 +335,61 @@ by using Views.

 See [Program.cs](./Program.cs) for a complete example.

+### Explicit Bucket Histogram Aggregation with .NET 9 Advice API


It’s misleading to call it .net 9 advice api as this api can be used in older .net runtimes

This is unresolved.

cijothomas · 2024-10-21T12:34:41Z

docs/metrics/customizing-the-sdk/README.md

+ boundaries, consider the typical range of values that your application
+ processes. This helps to ensure that the histogram provides relevant
+ insights.
+- **Monitor and Adjust**: After implementing explicit bucket


Without some concrete steps to monitor, I think it’s best to omit this.

@Annosha A lot of comments are marked resolved, but I don't see how. Please leave a comment about how the comment is addressed before resolving them.

docs/metrics/customizing-the-sdk/README.md

cijothomas · 2024-10-21T12:37:53Z

docs/metrics/customizing-the-sdk/README.md

@@ -335,6 +335,61 @@ by using Views.

 See [Program.cs](./Program.cs) for a complete example.

+### Explicit Bucket Histogram Aggregation with .NET 9 Advice API


thus document is about sdk customization, so histogram advice is somewhat misfit here. we can mention it in the views section about custom buckets, but anything more should be elsewhere.

this is unresolved.

docs/metrics/customizing-the-sdk/README.md

Annosha · 2024-10-23T08:52:20Z

@cijothomas @reyang @CodeBlanch please provide feedback on latest changes.

docs/metrics/customizing-the-sdk/README.md

Annosha · 2024-10-24T12:14:31Z

@reyang please take a look at the improvements.

docs/metrics/customizing-the-sdk/README.md

reyang · 2024-10-28T18:00:42Z

docs/metrics/customizing-the-sdk/README.md

+Additionally, if an exponential histogram is defined using the View API,
+the explicit bucket boundaries provided by the Advice API will be ignored,
+as exponential histograms take precedence.


Want to make sure I understand this - if the user leveraged the View API to choose a subset of the attributes, and there are no explicit buckets provided - would the buckets provided by the Hint API take effect or not?

Yes, the buckets provided by the Advice (Hint) API would take effect in this case. Here's what I understand:

Exponential Histogram with View API: If the user defines an exponential histogram via the View API, it takes full precedence, and any explicit bucket boundaries provided by the Advice API are ignored.

No Explicit Buckets Provided by View API: If the View API is used but does not define explicit bucket boundaries (e.g., it only filters attributes or configures other aspects), then:

The SDK will fall back to the explicit buckets from the Advice (Hint) API if they are available.

If no buckets are defined in the Advice API either, then the SDK defaults apply.

@cijothomas Could you please verify if these are correct?

Co-authored-by: Reiley Yang <reyang@microsoft.com>

cijothomas

Few comments left in the PR. My main concern is below:
Customizing the SDK section is not the right place to talk about Advice API in detail. We should mention it, and list the priority order when Advice and View are both used, but nothing more.

cijothomas · 2024-10-29T07:24:56Z

docs/metrics/customizing-the-sdk/README.md

@@ -473,11 +572,11 @@ recording of `Exemplar`s.
 OpenTelemetry SDK comes with the following `ExemplarFilter`s (defined on
 `ExemplarFilterType`):

-* (Default behavior) `AlwaysOff`: Makes no measurements eligible for becoming an
+- (Default behavior) `AlwaysOff`: Makes no measurements eligible for becoming an


please remove all unrelated changes from this PR. We are glad to accept them as a separate PR, so as to keep each PR focused on only one aspect only.

docs/metrics/customizing-the-sdk/README.md

reyang

Looks like a good step forward. I feel we might need to change the structure of the doc, the current way how explicit buckets vs. base-2 exponential buckets are organized seems to be misleading to me. Not a blocker for this PR though.

github-actions · 2024-11-06T03:18:03Z

This PR was marked stale due to lack of activity and will be closed in 7 days. Commenting or pushing will instruct the bot to automatically remove the label. This bot runs once per day.

Co-authored-by: Reiley Yang <reyang@microsoft.com>

github-actions · 2024-11-16T03:19:39Z

This PR was marked stale due to lack of activity and will be closed in 7 days. Commenting or pushing will instruct the bot to automatically remove the label. This bot runs once per day.

github-actions · 2024-11-24T03:23:24Z

Closed as inactive. Feel free to reopen if this PR is still being worked on.

Update metrics customization guide with .NET 9 Advice API details

5da3fb8

Annosha requested a review from a team as a code owner October 21, 2024 07:38

github-actions bot added the documentation Documentation related label Oct 21, 2024

cijothomas reviewed Oct 21, 2024

View reviewed changes

docs/metrics/customizing-the-sdk/README.md Show resolved Hide resolved

cijothomas reviewed Oct 21, 2024

View reviewed changes

reyang reviewed Oct 21, 2024

View reviewed changes

docs/metrics/customizing-the-sdk/README.md Show resolved Hide resolved

Improvements based on feedback

6f0f11b

reyang reviewed Oct 23, 2024

View reviewed changes

docs/metrics/customizing-the-sdk/README.md Outdated Show resolved Hide resolved

reyang reviewed Oct 23, 2024

View reviewed changes

docs/metrics/customizing-the-sdk/README.md Outdated Show resolved Hide resolved

Feedback-improvements

fe28161

Annosha and others added 4 commits October 24, 2024 17:14

Merge branch 'main' into docs-advice-api

904666c

linting fixes

1e97051

lint fixes

76ad2b7

Merge branch 'main' into docs-advice-api

24d7beb

reyang reviewed Oct 28, 2024

View reviewed changes

docs/metrics/customizing-the-sdk/README.md Outdated Show resolved Hide resolved

reyang reviewed Oct 28, 2024

View reviewed changes

Annosha and others added 2 commits October 29, 2024 10:11

Update docs/metrics/customizing-the-sdk/README.md

f547210

Co-authored-by: Reiley Yang <reyang@microsoft.com>

Merge branch 'main' into docs-advice-api

03d3c8a

cijothomas requested changes Oct 29, 2024

View reviewed changes

cijothomas reviewed Oct 29, 2024

View reviewed changes

reyang reviewed Oct 29, 2024

View reviewed changes

docs/metrics/customizing-the-sdk/README.md Outdated Show resolved Hide resolved

reyang reviewed Oct 29, 2024

View reviewed changes

docs/metrics/customizing-the-sdk/README.md Outdated Show resolved Hide resolved

reyang approved these changes Oct 29, 2024

View reviewed changes

github-actions bot added the Stale Issues and pull requests which have been flagged for closing due to inactivity label Nov 6, 2024

Annosha and others added 2 commits November 8, 2024 21:37

Update docs/metrics/customizing-the-sdk/README.md

1d82d76

Co-authored-by: Reiley Yang <reyang@microsoft.com>

Update docs/metrics/customizing-the-sdk/README.md

aec0a7d

Co-authored-by: Reiley Yang <reyang@microsoft.com>

github-actions bot removed the Stale Issues and pull requests which have been flagged for closing due to inactivity label Nov 9, 2024

CodeBlanch mentioned this pull request Nov 11, 2024

[docs-metrics] Add content for histogram bucket configuration via advice api #5965

Merged

1 task

github-actions bot added the Stale Issues and pull requests which have been flagged for closing due to inactivity label Nov 16, 2024

github-actions bot closed this Nov 24, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Metrics customization guide with .NET 9 Advice API details #5911

Metrics customization guide with .NET 9 Advice API details #5911

Annosha commented Oct 21, 2024

Annosha commented Oct 21, 2024

cijothomas Oct 21, 2024

cijothomas Oct 21, 2024

cijothomas Oct 29, 2024

cijothomas Oct 21, 2024

cijothomas Oct 29, 2024

cijothomas Oct 21, 2024

cijothomas Oct 29, 2024

Annosha commented Oct 23, 2024

Annosha commented Oct 24, 2024

reyang Oct 28, 2024

Annosha Oct 29, 2024

cijothomas left a comment

cijothomas Oct 29, 2024

reyang left a comment

github-actions bot commented Nov 6, 2024

github-actions bot commented Nov 16, 2024

github-actions bot commented Nov 24, 2024

		@@ -335,6 +335,61 @@ by using Views.

		See [Program.cs](./Program.cs) for a complete example.

		### Explicit Bucket Histogram Aggregation with .NET 9 Advice API

Metrics customization guide with .NET 9 Advice API details #5911

Metrics customization guide with .NET 9 Advice API details #5911

Conversation

Annosha commented Oct 21, 2024

Changes

Merge requirement checklist

Annosha commented Oct 21, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Annosha commented Oct 23, 2024

Annosha commented Oct 24, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cijothomas left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

reyang left a comment

Choose a reason for hiding this comment

github-actions bot commented Nov 6, 2024

github-actions bot commented Nov 16, 2024

github-actions bot commented Nov 24, 2024