Document TelemetrySource property of the ExecutionRejectedException

docs/strategies/circuit-breaker.md

@@ -9,8 +9,8 @@
   - `AddCircuitBreaker`
 - **Strategy Type**: Reactive
 - **Exception(s)**:
-  - `BrokenCircuitException`: Thrown when a circuit is broken and the action could not be executed.
-  - `IsolatedCircuitException`: Thrown when a circuit is isolated (held open) by manual override.
+  - [`BrokenCircuitException`](xref:Polly.CircuitBreaker.BrokenCircuitException): Thrown when a circuit is broken and the action could not be executed.
+  - [`IsolatedCircuitException`](xref:Polly.CircuitBreaker.IsolatedCircuitException): Thrown when a circuit is isolated (held open) by manual override.
 
 ---
 
@@ -92,6 +92,58 @@ new ResiliencePipelineBuilder<HttpResponseMessage>().AddCircuitBreaker(optionsSt
 ```
 <!-- endSnippet -->
 
+### Failure handling
+
+The circuit breaker returns the result / exception during the sampling period. Once the strategy opens the circuit every subsequent calls will be shortcut with a `BrokenCircuitException`.
+
+<!-- snippet: circuit-breaker-failure-handling -->
+```cs
+var pipeline = new ResiliencePipelineBuilder()
+    .AddCircuitBreaker(new CircuitBreakerStrategyOptions
+    {
+        FailureRatio = 0.1,
+        SamplingDuration = TimeSpan.FromSeconds(1),
+        MinimumThroughput = 3,
+        BreakDuration = TimeSpan.FromSeconds(30),
+        ShouldHandle = new PredicateBuilder().Handle<SomeExceptionType>()
+    })
+    .Build();
+
+for(int i = 0; i < 10; i++)
+{
+    try
+    {
+        pipeline.Execute(() => throw new SomeExceptionType());
+    }
+    catch(SomeExceptionType)
+    {
+        Console.WriteLine("Operation failed please try again.");
+    }
+    catch(BrokenCircuitException)
+    {
+        Console.WriteLine("Operation failed too many times please try again later.");
+    }
+}
+```
+<!-- endSnippet -->
+
+The output would look like this:
+
+```none
+Operation failed please try again.
+Operation failed please try again.
+Operation failed please try again.
+Operation failed too many times please try again later.
+Operation failed too many times please try again later.
+Operation failed too many times please try again later.
+Operation failed too many times please try again later.
+Operation failed too many times please try again later.
+Operation failed too many times please try again later.
+Operation failed too many times please try again later.
+```
+
+The `BrokenCircuitException` and the `IsolatedCircuitException` provides access to the following properties: `RetryAfter`, and `TelemetrySource`. If the `RetryAfter` optional `TimeSpan` is provided then this indicates that circuit is open at least this time period and you should retry your operation no sooner than the value given. The `TelemetrySource` property is a [`ResilienceTelemetrySource`](xref:Polly.Telemetry.ResilienceTelemetrySource) which allows you retrieve information like the executed pipeline and the executed strategy. These can be really handy whenever you have multiple circuit breaker strategies in your pipeline and you want to know which strategy threw the `BrokenCircuitException`.
+
 ## Defaults
 
 | Property                 | Default Value                                           | Description                                                                                                                                               |

docs/strategies/rate-limiter.md

@@ -8,7 +8,7 @@
   - `AddRateLimiter`,
   - `AddConcurrencyLimiter`
 - **Exception(s)**:
-  - `RateLimiterRejectedException`: Thrown when a rate limiter rejects an execution.
+  - [`RateLimiterRejectedException`](xref:Polly.RateLimiting.RateLimiterRejectedException): Thrown when a rate limiter rejects an execution.
 
 > [!NOTE]
 > The rate limiter strategy resides inside the [Polly.RateLimiting](https://www.nuget.org/packages/Polly.RateLimiting) package, not in ([Polly.Core](https://www.nuget.org/packages/Polly.Core)) like other strategies.
@@ -73,9 +73,9 @@ catch (RateLimiterRejectedException ex)
 
 ### Failure handling
 
-It might not be obvious at the first glance what is the difference between these two techniques:
+At the first glance it might not be obvious what is the difference between these two techniques:
 
-<!-- snippet: rate-limiter-handling-failure -->
+<!-- snippet: rate-limiter-with-onrejected -->
 ```cs
 var withOnRejected = new ResiliencePipelineBuilder()
     .AddRateLimiter(new RateLimiterStrategyOptions
@@ -90,7 +90,11 @@ var withOnRejected = new ResiliencePipelineBuilder()
             return default;
         }
     }).Build();
+```
+<!-- endSnippet -->
 
+<!-- snippet: rate-limiter-without-onrejected -->
+```cs
 var withoutOnRejected = new ResiliencePipelineBuilder()
     .AddRateLimiter(new RateLimiterStrategyOptions
     {
@@ -111,28 +115,29 @@ catch (RateLimiterRejectedException)
 ```
 <!-- endSnippet -->
 
-## Defaults
-
-| Property                    | Default Value                                        | Description                                                                                                 |
-|-----------------------------|------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
-| `RateLimiter`               | `null`                                               | **Dynamically** creates a `RateLimitLease` for executions.                                                  |
-| `DefaultRateLimiterOptions` | `PermitLimit` set to 1000 and `QueueLimit` set to 0. | If `RateLimiter` is not provided then this options object will be used for the default concurrency limiter. |
-| `OnRejected`                | `null`                                               | If provided then it will be invoked after the limiter rejected an execution.                                |
-
-### `OnRejected` versus catching `RateLimiterRejectedException`
-
 The `OnRejected` user-provided delegate is called just before the strategy throws the `RateLimiterRejectedException`. This delegate receives a parameter which allows you to access the `Context` object as well as the `Lease`:
 
-- Accessing the `Context` is also possible via a different `Execute{Async}` overload.
-- Accessing the rejected `Lease` can be useful in certain scenarios.
+- `Context` can be accessed via some `Execute{Async}` overloads.
+- `Lease` can be useful in advanced scenarios.
 
 So, what is the purpose of the `OnRejected`?
 
 The `OnRejected` delegate can be useful when you define a resilience pipeline which consists of multiple strategies. For example, you have a rate limiter as the inner strategy and a retry as the outer strategy. If the retry is defined to handle `RateLimiterRejectedException`, that means the `Execute{Async}` may or may not throw that exception depending on future attempts. So, if you want to get notification about the fact that the rate limit has been exceeded, you have to provide a delegate to the `OnRejected` property.
 
-> [!IMPORTANT]
-> The [`RateLimiterRejectedException`](xref:Polly.RateLimiting.RateLimiterRejectedException) has a `RetryAfter` property. If this optional `TimeSpan` is provided then this indicates that your requests are throttled and you should retry them no sooner than the value given.
-> Please note that this information is not available inside the `OnRejected` callback.
+The `RateLimiterRejectedException` has a `RetryAfter` and a `TelemetrySource` property. If the `RetryAfter` optional `TimeSpan` is provided then this indicates that your requests are throttled and you should retry them no sooner than the value given.
+
+> [!NOTE]
+> Please note that the `RetryAfter` information is not available inside the `OnRejected` callback.
+
+ The `TelemetrySource` property is a [`ResilienceTelemetrySource`](xref:Polly.Telemetry.ResilienceTelemetrySource) which allows you retrieve information like the executed pipeline and the executed strategy. These can be really handy whenever you have multiple limiter strategies in your pipeline (for example a rate and a concurrency limiter) and you want to know which strategy threw the `RateLimiterRejectedException`.
+
+## Defaults
+
+| Property                    | Default Value                                        | Description                                                                                                 |
+|-----------------------------|------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
+| `RateLimiter`               | `null`                                               | **Dynamically** creates a `RateLimitLease` for executions.                                                  |
+| `DefaultRateLimiterOptions` | `PermitLimit` set to 1000 and `QueueLimit` set to 0. | If `RateLimiter` is not provided then this options object will be used for the default concurrency limiter. |
+| `OnRejected`                | `null`                                               | If provided then it will be invoked after the limiter rejected an execution.                                |
 
 ## Telemetry
 

docs/strategies/timeout.md

@@ -7,7 +7,7 @@
 - **Extension(s)**:
   - `AddTimeout`
 - **Exception(s)**:
-  - `TimeoutRejectedException`: Thrown when a delegate executed through a timeout strategy does not complete before the timeout.
+  - [`TimeoutRejectedException`](xref:Polly.Timeout.TimeoutRejectedException): Thrown when a delegate executed through a timeout strategy does not complete before the timeout.
 
 ---
 
@@ -77,9 +77,9 @@ HttpResponseMessage httpResponse = await pipeline.ExecuteAsync(
 
 ### Failure handling
 
-It might not be obvious at the first glance what is the difference between these two techniques:
+At the first glance it might not be obvious what is the difference between these two techniques:
 
-<!-- snippet: timeout-handling-failure -->
+<!-- snippet: timeout-with-ontimeout -->
 ```cs
 var withOnTimeout = new ResiliencePipelineBuilder()
     .AddTimeout(new TimeoutStrategyOptions
@@ -91,7 +91,11 @@ var withOnTimeout = new ResiliencePipelineBuilder()
             return default;
         }
     }).Build();
+```
+<!-- endSnippet -->
 
+<!-- snippet: timeout-without-ontimeout -->
+```cs
 var withoutOnTimeout = new ResiliencePipelineBuilder()
     .AddTimeout(new TimeoutStrategyOptions
     {
@@ -109,6 +113,17 @@ catch (TimeoutRejectedException)
 ```
 <!-- endSnippet -->
 
+The `OnTimeout` user-provided delegate is called just before the strategy throws the `TimeoutRejectedException`. This delegate receives a parameter which allows you to access the `Context` object as well as the `Timeout`:
+
+- `Context` can be also accessed via some `Execute{Async}` overloads.
+- `Timeout` can be useful if you are using the `TimeoutGenerator` property of the `TimeoutStrategyOptions` rather than its `Timeout` property.
+
+So, what is the purpose of the `OnTimeout` in case of static timeout settings?
+
+The `OnTimeout` delegate can be useful when you define a resilience pipeline which consists of multiple strategies. For example you have a timeout as the inner strategy and a retry as the outer strategy. If the retry is defined to handle `TimeoutRejectedException`, that means the `Execute{Async}` may or may not throw that exception depending on future attempts. So, if you want to get notification about the fact that a timeout has occurred, you have to provide a delegate to the `OnTimeout` property.
+
+The `TimeoutRejectedException` provides access to a property called `TelemetrySource`. This property is a [`ResilienceTelemetrySource`](xref:Polly.Telemetry.ResilienceTelemetrySource) which allows you retrieve information like the executed pipeline and the executed strategy. These can be really handy whenever you have multiple Timeout strategies in your pipeline and you want to know which strategy threw the `TimeoutRejectedException`.
+
 ## Defaults
 
 | Property           | Default Value | Description                                                                                                                          |
@@ -123,17 +138,6 @@ catch (TimeoutRejectedException)
 - If both `Timeout` and `TimeoutGenerator` are specified then `Timeout` will be ignored.
 - If `TimeoutGenerator` returns a `TimeSpan` that is less than or equal to `TimeSpan.Zero` then the strategy will have no effect.
 
-### `OnTimeout` versus catching `TimeoutRejectedException`
-
-The `OnTimeout` user-provided delegate is called just before the strategy throws the `TimeoutRejectedException`. This delegate receives a parameter which allows you to access the `Context` object as well as the `Timeout`:
-
-- Accessing the `Context` is also possible via a different `Execute{Async}` overload.
-- Accessing the `Timeout` can be useful if you are using the `TimeoutGenerator` property rather than the `Timeout` property.
-
-So, what is the purpose of the `OnTimeout` in case of static timeout settings?
-
-The `OnTimeout` delegate can be useful when you define a resilience pipeline which consists of multiple strategies. For example you have a timeout as the inner strategy and a retry as the outer strategy. If the retry is defined to handle `TimeoutRejectedException`, that means the `Execute{Async}` may or may not throw that exception depending on future attempts. So, if you want to get notification about the fact that a timeout has occurred, you have to provide a delegate to the `OnTimeout` property.
-
 ## Telemetry
 
 The timeout strategy reports the following telemetry events:

src/Snippets/Docs/CircuitBreaker.cs

@@ -82,6 +82,35 @@
         new ResiliencePipelineBuilder<HttpResponseMessage>().AddCircuitBreaker(optionsStateProvider);
 
         #endregion
+
+        #region circuit-breaker-failure-handling
+        var pipeline = new ResiliencePipelineBuilder()
+            .AddCircuitBreaker(new CircuitBreakerStrategyOptions
+            {
+                FailureRatio = 0.1,
+                SamplingDuration = TimeSpan.FromSeconds(1),
+                MinimumThroughput = 3,
+                BreakDuration = TimeSpan.FromSeconds(30),
+                ShouldHandle = new PredicateBuilder().Handle<SomeExceptionType>()
+            })
+            .Build();
+
+        for(int i = 0; i < 10; i++)
+        {
+            try
+            {
+                pipeline.Execute(() => throw new SomeExceptionType());
+            }
+			catch(SomeExceptionType)
+            {
+                Console.WriteLine("Operation failed please try again.");
+            }
+            catch(BrokenCircuitException)
+            {
+                Console.WriteLine("Operation failed too many times please try again later.");
+            }
+        }
+        #endregion
     }
 
     public static void AntiPattern_CircuitAwareRetry()

src/Snippets/Docs/RateLimiter.cs

@@ -97,7 +97,7 @@ public static void Usage()
     public static async Task HandleRejection()
     {
         var query = "dummy";
-        #region rate-limiter-handling-failure
+        #region rate-limiter-with-onrejected
         var withOnRejected = new ResiliencePipelineBuilder()
             .AddRateLimiter(new RateLimiterStrategyOptions
             {
@@ -111,7 +111,9 @@ public static async Task HandleRejection()
                     return default;
                 }
             }).Build();
+        #endregion
 
+        #region rate-limiter-without-onrejected
         var withoutOnRejected = new ResiliencePipelineBuilder()
             .AddRateLimiter(new RateLimiterStrategyOptions
             {

src/Snippets/Docs/Timeout.cs

@@ -70,7 +70,7 @@ public static async Task Usage()
     public static async Task HandleTimeout()
     {
         static ValueTask UserDelegate(CancellationToken ct) => ValueTask.CompletedTask;
-        #region timeout-handling-failure
+        #region timeout-with-ontimeout
         var withOnTimeout = new ResiliencePipelineBuilder()
             .AddTimeout(new TimeoutStrategyOptions
             {
@@ -81,7 +81,9 @@ public static async Task HandleTimeout()
                     return default;
                 }
             }).Build();
+        #endregion
 
+        #region timeout-without-ontimeout
         var withoutOnTimeout = new ResiliencePipelineBuilder()
             .AddTimeout(new TimeoutStrategyOptions
             {