[Docs] Improve telemetry docs (#1681)

Author: martintmk

docs/advanced/resilience-context.md

@@ -102,3 +102,6 @@ finally
 }
 ```
 <!-- endSnippet -->
+
+> [!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/dotnet/core/diagnostics/metrics-instrumentation#best-practices-3) for more details.

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:
 
-<!-- snippet: telemetry-coordinates -->
+<!-- snippet: telemetry-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);
 ```
 <!-- endSnippet -->
 
+> [!NOTE]
+> 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:
 
 ### Instrument: `resilience.polly.strategy.events`

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
     }