From f049875c35d76217d8979c96d9b60c307f711a59 Mon Sep 17 00:00:00 2001 From: Martin Tomka Date: Fri, 6 Oct 2023 10:47:23 +0200 Subject: [PATCH 1/3] [Docs] Improve telemetry docs --- docs/advanced/resilience-context.md | 3 +++ docs/advanced/telemetry.md | 19 ++++++++++++++++++- src/Snippets/Docs/Telemetry.cs | 15 ++++++++++++++- 3 files changed, 35 insertions(+), 2 deletions(-) diff --git a/docs/advanced/resilience-context.md b/docs/advanced/resilience-context.md index e3f185543a6..0f8c1e6550d 100644 --- a/docs/advanced/resilience-context.md +++ b/docs/advanced/resilience-context.md @@ -102,3 +102,6 @@ finally } ``` + +> [!NOTE] +> The `OperationKey` values are reported in [telemetry](telemetry.md#metrics). Beware of using very large or unbounded combinations for the operation key. See [best practices](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/metrics-instrumentation#best-practices-3) for more details. diff --git a/docs/advanced/telemetry.md b/docs/advanced/telemetry.md index 51951d92f90..4e2f716731e 100644 --- a/docs/advanced/telemetry.md +++ b/docs/advanced/telemetry.md @@ -82,10 +82,11 @@ Every telemetry event has the following tags: - `pipeline.name`: Optional, comes from `ResiliencePipelineBuilder.Name`. - `pipeline.instance`: Optional, comes from `ResiliencePipelineBuilder.InstanceName`. - `strategy.name`: Optional, comes from `RetryStrategyOptions.Name`. +- `operation.key`: Optional, comes from `ResilienceContext.OperationKey`. The sample below demonstrates how to assign these tags: - + ```cs var builder = new ResiliencePipelineBuilder(); builder.Name = "my-name"; @@ -96,9 +97,25 @@ builder.AddRetry(new RetryStrategyOptions // The default value is "Retry" Name = "my-retry-name" }); + +ResiliencePipeline pipeline = builder.Build(); + +// Create resilience context with operation key +ResilienceContext resilienceContext = ResilienceContextPool.Shared.Get("my-operation-key"); + +// Execute the pipeline with the context +pipeline.Execute( + context => + { + // Your code comes here + }, + resilienceContext); ``` +> [!NOTE] +> Beware of using very large or unbounded combinations of tag values being recorded for the tags above. See [best practices](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/metrics-instrumentation#best-practices-3) for more details. + These values are subsequently reflected in the following metering instruments exposed by Polly: ### Instrument: `resilience.polly.strategy.events` diff --git a/src/Snippets/Docs/Telemetry.cs b/src/Snippets/Docs/Telemetry.cs index 09de96d8865..ffe5c7a72fb 100644 --- a/src/Snippets/Docs/Telemetry.cs +++ b/src/Snippets/Docs/Telemetry.cs @@ -9,7 +9,7 @@ internal static class Telemetry { public static void TelemetryCoordinates() { - #region telemetry-coordinates + #region telemetry-tags var builder = new ResiliencePipelineBuilder(); builder.Name = "my-name"; @@ -21,6 +21,19 @@ public static void TelemetryCoordinates() Name = "my-retry-name" }); + ResiliencePipeline pipeline = builder.Build(); + + // Create resilience context with operation key + ResilienceContext resilienceContext = ResilienceContextPool.Shared.Get("my-operation-key"); + + // Execute the pipeline with the context + pipeline.Execute( + context => + { + // Your code comes here + }, + resilienceContext); + #endregion } From f3945d8b3ca662e70a7c88ee70a58491765b5575 Mon Sep 17 00:00:00 2001 From: Martin Tomka Date: Fri, 6 Oct 2023 10:54:34 +0200 Subject: [PATCH 2/3] Cleanup --- docs/advanced/resilience-context.md | 2 +- docs/advanced/telemetry.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/advanced/resilience-context.md b/docs/advanced/resilience-context.md index 0f8c1e6550d..0433a80397e 100644 --- a/docs/advanced/resilience-context.md +++ b/docs/advanced/resilience-context.md @@ -104,4 +104,4 @@ finally > [!NOTE] -> The `OperationKey` values are reported in [telemetry](telemetry.md#metrics). Beware of using very large or unbounded combinations for the operation key. See [best practices](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/metrics-instrumentation#best-practices-3) for more details. +> The `OperationKey` values are reported in [telemetry](telemetry.md#metrics). Beware of using very large or unbounded combinations for the operation key. See [best practices](https://learn.microsoft.com/dotnet/core/diagnostics/metrics-instrumentation#best-practices-3) for more details. diff --git a/docs/advanced/telemetry.md b/docs/advanced/telemetry.md index 4e2f716731e..27a54049925 100644 --- a/docs/advanced/telemetry.md +++ b/docs/advanced/telemetry.md @@ -114,7 +114,7 @@ pipeline.Execute( > [!NOTE] -> Beware of using very large or unbounded combinations of tag values being recorded for the tags above. See [best practices](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/metrics-instrumentation#best-practices-3) for more details. +> Beware of using very large or unbounded combinations of tag values being recorded for the tags above. See [best practices](https://learn.microsoft.com/dotnet/core/diagnostics/metrics-instrumentation#best-practices-3) for more details. These values are subsequently reflected in the following metering instruments exposed by Polly: From 58773230b330df00cb30c4bf0b25af0937ee2e9f Mon Sep 17 00:00:00 2001 From: Martin Tomka Date: Fri, 6 Oct 2023 12:27:20 +0200 Subject: [PATCH 3/3] grammar --- docs/advanced/telemetry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced/telemetry.md b/docs/advanced/telemetry.md index 27a54049925..809d35e4dd1 100644 --- a/docs/advanced/telemetry.md +++ b/docs/advanced/telemetry.md @@ -114,7 +114,7 @@ pipeline.Execute( > [!NOTE] -> Beware of using very large or unbounded combinations of tag values being recorded for the tags above. See [best practices](https://learn.microsoft.com/dotnet/core/diagnostics/metrics-instrumentation#best-practices-3) for more details. +> Beware of using very large or unbounded combinations of tag values for the tags above. See [best practices](https://learn.microsoft.com/dotnet/core/diagnostics/metrics-instrumentation#best-practices-3) for more details. These values are subsequently reflected in the following metering instruments exposed by Polly: