From 0812a484427fde0dc86f83dfc1f41ff2066707cd Mon Sep 17 00:00:00 2001
From: Martin Tomka <martintomka@microsoft.com>
Date: Tue, 24 Oct 2023 11:43:02 +0200
Subject: [PATCH 1/3] [Docs] Add docs for metering enrichment

---
 docs/advanced/telemetry.md     | 40 ++++++++++++++++++++++++++++++++++
 src/Snippets/Docs/Telemetry.cs | 35 +++++++++++++++++++++++++++++
 2 files changed, 75 insertions(+)

diff --git a/docs/advanced/telemetry.md b/docs/advanced/telemetry.md
index 99859843eee..37f65374481 100644
--- a/docs/advanced/telemetry.md
+++ b/docs/advanced/telemetry.md
@@ -186,6 +186,46 @@ Tags:
 |`operation.key`| The operation key associated with the call site. |
 |`exception.type`| The full name of the exception assigned to the execution result (`System.InvalidOperationException`). |
 
+### Metering enrichment
+
+Polly API lets you add extra tags to any resilience event created by resilience strategies. To do this, derive from the <xref:Polly.Telemetry.MeteringEnricher> class and add your custom enricher to the <xref:Polly.Telemetry.TelemetryOptions.MeteringEnrichers> list.
+
+The custom enricher:
+
+<!-- snippet: metering-enricher -->
+```cs
+internal class CustomMeteringEnricher : MeteringEnricher
+{
+    public override void Enrich<TResult, TArgs>(in EnrichmentContext<TResult, TArgs> context)
+    {
+        // You can read additional details from any resilience event and use it to enrich the telemetry
+        if (context.TelemetryEvent.Arguments is OnRetryArguments<TResult> retryArgs)
+        {
+            // See https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/metrics.md for more details
+            // on how to name the tags.
+            context.Tags.Add(new("retry.attempt", retryArgs.AttemptNumber));
+        }
+    }
+}
+```
+<!-- endSnippet -->
+
+Registering the custom enricher:
+
+<!-- snippet: metering-enricher-registration -->
+```cs
+var telemetryOptions = new TelemetryOptions();
+
+// Register custom enricher
+telemetryOptions.MeteringEnrichers.Add(new CustomMeteringEnricher());
+
+var builder = new ResiliencePipelineBuilder()
+    .AddRetry(new RetryStrategyOptions())
+    .ConfigureTelemetry(telemetryOptions) // This method enables telemetry in the builder
+    .Build();
+```
+<!-- endSnippet -->
+
 ## Logs
 
 Logs are registered under the `Polly` logger name. Here are some examples of the logs:
diff --git a/src/Snippets/Docs/Telemetry.cs b/src/Snippets/Docs/Telemetry.cs
index 1dc6433b39d..056be05a24c 100644
--- a/src/Snippets/Docs/Telemetry.cs
+++ b/src/Snippets/Docs/Telemetry.cs
@@ -99,4 +99,39 @@ public override void Enrich<TResult, TArgs>(in EnrichmentContext<TResult, TArgs>
     }
 
     #endregion
+
+    public static void MeteringEnricherRegistration()
+    {
+        #region metering-enricher-registration
+
+        var telemetryOptions = new TelemetryOptions();
+
+        // Register custom enricher
+        telemetryOptions.MeteringEnrichers.Add(new CustomMeteringEnricher());
+
+        var builder = new ResiliencePipelineBuilder()
+            .AddRetry(new RetryStrategyOptions())
+            .ConfigureTelemetry(telemetryOptions) // This method enables telemetry in the builder
+            .Build();
+
+        #endregion
+    }
+
+    #region metering-enricher
+
+    internal class CustomMeteringEnricher : MeteringEnricher
+    {
+        public override void Enrich<TResult, TArgs>(in EnrichmentContext<TResult, TArgs> context)
+        {
+            // You can read additional details from any resilience event and use it to enrich the telemetry
+            if (context.TelemetryEvent.Arguments is OnRetryArguments<TResult> retryArgs)
+            {
+                // See https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/metrics.md for more details
+                // on how to name the tags.
+                context.Tags.Add(new("retry.attempt", retryArgs.AttemptNumber));
+            }
+        }
+    }
+
+    #endregion
 }

From 0237d3b2ec71e5505663146d78558adccebfd257 Mon Sep 17 00:00:00 2001
From: Martin Tomka <martintomka@microsoft.com>
Date: Tue, 24 Oct 2023 11:59:04 +0200
Subject: [PATCH 2/3] cleanup

---
 docs/advanced/telemetry.md     | 2 +-
 src/Snippets/Docs/Telemetry.cs | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/advanced/telemetry.md b/docs/advanced/telemetry.md
index 37f65374481..ef6d2af8b51 100644
--- a/docs/advanced/telemetry.md
+++ b/docs/advanced/telemetry.md
@@ -194,7 +194,7 @@ The custom enricher:
 
 <!-- snippet: metering-enricher -->
 ```cs
-internal class CustomMeteringEnricher : MeteringEnricher
+internal sealed class CustomMeteringEnricher : MeteringEnricher
 {
     public override void Enrich<TResult, TArgs>(in EnrichmentContext<TResult, TArgs> context)
     {
diff --git a/src/Snippets/Docs/Telemetry.cs b/src/Snippets/Docs/Telemetry.cs
index 056be05a24c..7825e20db60 100644
--- a/src/Snippets/Docs/Telemetry.cs
+++ b/src/Snippets/Docs/Telemetry.cs
@@ -119,7 +119,7 @@ public static void MeteringEnricherRegistration()
 
     #region metering-enricher
 
-    internal class CustomMeteringEnricher : MeteringEnricher
+    internal sealed class CustomMeteringEnricher : MeteringEnricher
     {
         public override void Enrich<TResult, TArgs>(in EnrichmentContext<TResult, TArgs> context)
         {

From 8b77bac099ebbcc1b9fed9950e90109f28d1afe7 Mon Sep 17 00:00:00 2001
From: Martin Tomka <martintomka@microsoft.com>
Date: Tue, 24 Oct 2023 12:07:37 +0200
Subject: [PATCH 3/3] update wordlist

---
 .github/wordlist.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/wordlist.txt b/.github/wordlist.txt
index 3e816cc7e57..3c447baa572 100644
--- a/.github/wordlist.txt
+++ b/.github/wordlist.txt
@@ -64,3 +64,4 @@ uwp
 waitandretry
 wpf
 xunit
+enricher