[diagnostics] Add InstrumentAdvice details to instrumentation doc #43640

CodeBlanch · 2024-11-19T19:21:22Z

Summary

Add content + example showing the System.Diagnostics.DiagnosticSource v9.0.0 InstrumentAdvice API.

The goal is to link to this from the OTel .NET docs: https://github.com/open-telemetry/opentelemetry-dotnet/blob/e3665c95c21082f5675cb4d5863051201f640397/docs/metrics/customizing-the-sdk/README.md?plain=1#L244-L252

Internal previews

📄 File	🔗 Preview link
docs/core/diagnostics/metrics-instrumentation.md	docs/core/diagnostics/metrics-instrumentation

tarekgh · 2024-11-19T19:34:56Z

docs/core/diagnostics/metrics-instrumentation.md

+class Program
+{
+    static Meter s_meter = new Meter("HatCo.Store");
+    static readonly IReadOnlyList<double> s_shortSecondsBucketBoundaries = [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];


static readonly IReadOnlyList s_shortSecondsBucketBoundaries = [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];

nit: does this need to be static at all. can you add the list inline when creating InstrumentAdvice?

The inline list does seem like it would be a little easier to read. Perhaps something like:

static Histogram<double> s_orderProcessingTime = s_meter.CreateHistogram( name: "hatco.store.order_processing_time", unit: "s", description: "Duration order processing.", advice: new InstrumentAdvice<double> { HistogramBucketBoundaries = [0.01, 0.05, 0.1, 0.5, 1, 5] });

tarekgh · 2024-11-19T19:36:49Z

docs/core/diagnostics/metrics-instrumentation.md

@@ -224,6 +224,11 @@ Types of instruments currently available:
  <xref:System.Diagnostics.Metrics.Histogram%601.Record%2A> to record these measurements during the collection tool's update interval: 1,5,2,3,10,9,7,4,6,8. A collection tool
  might report that the 50th, 90th, and 95th percentiles of these measurements are 5, 9, and 9 respectively.

+  > [!NOTE]
+  > For details about how to set the recommended bucket boundaries when creating


Do we need to tell somewhere InstrumentAdvice<T> can be used in the future with more instruments as the scenario permit?

Up to you. I feel like we don't need to mention it now. When we have more advice features we can make doc updates to show them?

cijothomas · 2024-11-19T19:40:12Z

docs/core/diagnostics/metrics-instrumentation.md

+Aggregation](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#explicit-bucket-histogram-aggregation).
+
+When using explicit bucket aggregation the measurements recorded through a
+Histogram will be grouped into buckets which track the sum and count of values


sum is overall, only count is tracked per bucket..

cijothomas · 2024-11-19T19:41:49Z

docs/core/diagnostics/metrics-instrumentation.md

+Specification: `[ 0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000,
+7500, 10000 ]`.
+
+The default values may not lead to the best granularity for every Histogram. For


https://opentelemetry.io/blog/2023/why-histograms/
https://opentelemetry.io/blog/2023/histograms-vs-summaries/

are 2 useful links that maybe shared here for users to read more on this area...

Added links as a sub-section after the main content

cijothomas · 2024-11-19T19:42:44Z

docs/core/diagnostics/metrics-instrumentation.md

+
+The `InstrumentAdvice` API may be used by instrumentation authors to specify the
+set of recommended default bucket boundaries for a given Histogram. Consumers
+can then choose to use those values when configuring aggregation.


could you add a note about -> more buckets gives more precise data, but at the cost of more memory/cpu, so users wont go and add millions of buckets.

Added an "IMPORTANT" section to cover that

noahfalk · 2024-11-19T23:37:58Z

docs/core/diagnostics/metrics-instrumentation.md

@@ -542,6 +547,66 @@ Name                                                  Current Value
 > [!NOTE]
 > OpenTelemetry refers to tags as 'attributes'. These are two different names for the same functionality.

+## Using Advice to customize Histogram instruments
+
+Consumers of Histogram instruments can choose different aggregation strategies.


It might be worth spending a few sentences just to describe what histogram bucketing is. Some readers may not be familiar with them. For example:

When using histograms, it is the responsibility of the tool or library collecting the data to decide how best to represent the distribution of values that were recorded. A common strategy is to divide up the range of possible values into sub-ranges called buckets and report how many recorded values were in each bucket. For example a tool might divide numbers into three buckets, those less than 1, those between 1-10, and those greater than 10. If your app recorded the values 0.5, 6, 0.1, 12 then there would be two data points the first bucket, one in the second, and one in the 3rd. Using more buckets with narrower ranges allows representing a distribution with more accuracy, but the tradeoff is that it takes more space to store the results.

Added at the top. Removed the last sentence because I added an "IMPORTANT" section to cover that based on @cijothomas's feedback.

noahfalk

This looked good to me overall. A few suggestions inline.

cijothomas · 2024-11-20T21:58:00Z

docs/core/diagnostics/metrics-instrumentation.md

+
+> [!IMPORTANT]
+> In general more buckets will lead to more precise data for a given Histogram
+> but each bucket requires memory to store the aggregated details. It is


nit: i think the cost is not just memory, but more CPU to iterate through to find the right slot.

Good point. I tweaked it to mention CPU as well

cijothomas · 2024-11-20T23:00:52Z

docs/core/diagnostics/metrics-instrumentation.md

+The default values may not lead to the best granularity for every Histogram. For
+example, sub-second request durations would all fall into the `0` bucket.
+
+To solve this problem the `9.0.0` version of the


Suggested rephrase (to account for the fact that this problem is already solved elsewhere; this is just making it easier or making it work for non-otel scenario too)

The solution used by OpenTelemetry was to customize the buckets, by using OpenTelemetry specific mechanism (link to view doc), but this only worked when OpenTelemetry was used.
Starting 9.0.0, histogram creation API is enhanced to allowed accepting buckets..

I added some content to mention View API

Add InstrumentAdvice details to instrumentation doc.

d7bf628

CodeBlanch requested review from tommcdon and a team as code owners November 19, 2024 19:21

dotnetrepoman bot added this to the November 2024 milestone Nov 19, 2024

dotnetrepoman bot added the dotnet-fundamentals/svc label Nov 19, 2024

dotnet-policy-service bot added the community-contribution Indicates PR is created by someone from the .NET community. label Nov 19, 2024

tarekgh reviewed Nov 19, 2024

View reviewed changes

cijothomas reviewed Nov 19, 2024

View reviewed changes

tarekgh approved these changes Nov 19, 2024

View reviewed changes

noahfalk reviewed Nov 19, 2024

View reviewed changes

noahfalk approved these changes Nov 19, 2024

View reviewed changes

Code review.

ebf9bef

cijothomas reviewed Nov 20, 2024

View reviewed changes

Code review.

385df5b

cijothomas reviewed Nov 20, 2024

View reviewed changes

CodeBlanch added 3 commits November 21, 2024 11:23

Code review.

7319405

Lint.

b77c9d3

Tweak.

9161132

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[diagnostics] Add InstrumentAdvice details to instrumentation doc #43640

[diagnostics] Add InstrumentAdvice details to instrumentation doc #43640

CodeBlanch commented Nov 19, 2024 •

edited by github-actions bot

Loading

tarekgh Nov 19, 2024

noahfalk Nov 19, 2024

CodeBlanch Nov 20, 2024

tarekgh Nov 19, 2024

CodeBlanch Nov 20, 2024

cijothomas Nov 19, 2024

CodeBlanch Nov 20, 2024

cijothomas Nov 19, 2024

CodeBlanch Nov 20, 2024

cijothomas Nov 19, 2024

CodeBlanch Nov 20, 2024

noahfalk Nov 19, 2024 •

edited

Loading

CodeBlanch Nov 20, 2024

noahfalk left a comment

cijothomas Nov 20, 2024

CodeBlanch Nov 20, 2024

cijothomas Nov 20, 2024

CodeBlanch Nov 21, 2024

[diagnostics] Add InstrumentAdvice details to instrumentation doc #43640

Are you sure you want to change the base?

[diagnostics] Add InstrumentAdvice details to instrumentation doc #43640

Conversation

CodeBlanch commented Nov 19, 2024 • edited by github-actions bot Loading

Summary

Internal previews

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

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

noahfalk Nov 19, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

noahfalk left a 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

CodeBlanch commented Nov 19, 2024 •

edited by github-actions bot

Loading

noahfalk Nov 19, 2024 •

edited

Loading