App-vNext · martincostello · Apr 27, 2024 · Apr 23, 2024 · Apr 23, 2024 · Apr 23, 2024
diff --git a/docs/chaos/behavior.md b/docs/chaos/behavior.md
@@ -2,13 +2,15 @@
 
 ## About
 
-- **Options**: [`ChaosBehaviorStrategyOptions`](xref:Polly.Simmy.Behavior.ChaosBehaviorStrategyOptions)
-- **Extensions**: `AddChaosBehavior`
-- **Strategy Type**: Proactive
+- **Option(s)**:
+  - [`ChaosBehaviorStrategyOptions`](xref:Polly.Simmy.Behavior.ChaosBehaviorStrategyOptions)
+- **Extension(s)**:
+  - `AddChaosBehavior`
+- **Exception(s)**: -
 
 ---
 
-The behavior chaos strategy is designed to inject custom behaviors into system operations right before such an operation is invoked. This strategy is flexible, allowing users to define specific behaviors such as altering the input, simulating resource exhaustion, putting the system in a given state before the actual operation is called, or other operational variations to simulate real-world scenarios.
+The behavior **proactive** chaos strategy is designed to inject custom behaviors into system operations right before such an operation is invoked. This strategy is flexible, allowing users to define specific behaviors such as altering the input, simulating resource exhaustion, putting the system in a given state before the actual operation is called, or other operational variations to simulate real-world scenarios.
 
 ## Usage
 
@@ -66,10 +68,35 @@ var pipeline = new ResiliencePipelineBuilder()
 
 ## Defaults
 
-| Property             | Default Value | Description                                    |
-|----------------------|---------------|------------------------------------------------|
-| `OnBehaviorInjected` | `null`        | Action executed when the behavior is injected. |
-| `BehaviorGenerator`  | `null`        | Custom behavior to be injected.                |
+| Property             | Default Value | Description                                                                                                                  |
+|----------------------|---------------|------------------------------------------------------------------------------------------------------------------------------|
+| `BehaviorGenerator`  | `null`        | This **mandatory** delegate allows you to inject custom behavior by utilizing information that is only available at runtime. |
+| `OnBehaviorInjected` | `null`        | If provided then it will be invoked after the behavior injection occurred.                                                   |
+
+## Telemetry
+
+The behavior chaos strategy reports the following telemetry events:
+
+| Event Name         | Event Severity | When?                                                            |
+|--------------------|----------------|------------------------------------------------------------------|
+| `Chaos.OnBehavior` | `Information`  | Just before the strategy calls the `OnBehaviorInjected` delegate |
+
+Here are some sample events:
+
+```none
+Resilience event occurred. EventName: 'Chaos.OnBehavior', Source: '(null)/(null)/Chaos.Behavior', Operation Key: '', Result: ''
+
+Resilience event occurred. EventName: 'Chaos.OnBehavior', Source: 'MyPipeline/MyPipelineInstance/MyChaosBehaviorStrategy', Operation Key: 'MyBehaviorInjectedOperation', Result: ''
+```
+
+> [!NOTE]
+> Please note that the `Chaos.OnBehavior` telemetry event will be reported **only if** the behavior chaos strategy injects a custom behavior which does not throw exception.
+>
+> So, if the behavior is either not injected or injected and throws an exception then there will be no telemetry emitted.
+>
+> Also remember that the `Result` will be **always empty** for the `Chaos.OnBehavior` telemetry event.
+
+For further information please check out the [telemetry page](../advanced/telemetry.md).
 
 ## Diagrams
 

diff --git a/docs/chaos/fault.md b/docs/chaos/fault.md
@@ -2,13 +2,15 @@
 
 ## About
 
-- **Options**: [`ChaosFaultStrategyOptions`](xref:Polly.Simmy.Fault.ChaosFaultStrategyOptions)
-- **Extensions**: `AddChaosFault`
-- **Strategy Type**: Proactive
+- **Option(s)**:
+  - [`ChaosFaultStrategyOptions`](xref:Polly.Simmy.Fault.ChaosFaultStrategyOptions)
+- **Extensions**:
+  - `AddChaosFault`
+- **Exception(s)**: -
 
 ---
 
-The fault chaos strategy is designed to introduce faults (exceptions) into the system, simulating real-world scenarios where operations might fail unexpectedly. It is configurable to inject specific types of exceptions or use custom logic to generate faults dynamically.
+The fault **proactive** chaos strategy is designed to introduce faults (exceptions) into the system, simulating real-world scenarios where operations might fail unexpectedly. It is configurable to inject specific types of exceptions or use custom logic to generate faults dynamically.
 
 ## Usage
 
@@ -87,10 +89,35 @@ var pipeline = new ResiliencePipelineBuilder()
 
 ## Defaults
 
-| Property          | Default Value | Description                                          |
-|-------------------|---------------|------------------------------------------------------|
-| `OnFaultInjected` | `null`        | Action executed when the fault is injected.          |
-| `FaultGenerator`  | `null`        | Generates the fault to inject for a given execution. |
+| Property          | Default Value | Description                                                                                                            |
+|-------------------|---------------|------------------------------------------------------------------------------------------------------------------------|
+| `FaultGenerator`  | `null`        | This **mandatory** delegate allows you to inject exception by utilizing information that is only available at runtime. |
+| `OnFaultInjected` | `null`        | If provided then it will be invoked after the fault injection occurred.                                                |
+
+## Telemetry
+
+The fault chaos strategy reports the following telemetry events:
+
+| Event Name      | Event Severity | When?                                                         |
+|-----------------|----------------|---------------------------------------------------------------|
+| `Chaos.OnFault` | `Information`  | Just before the strategy calls the `OnFaultInjected` delegate |
+
+Here are some sample events:
+
+```none
+Resilience event occurred. EventName: 'Chaos.OnFault', Source: '(null)/(null)/Chaos.Fault', Operation Key: '', Result: ''
+
+Resilience event occurred. EventName: 'Chaos.OnFault', Source: 'MyPipeline/MyPipelineInstance/MyChaosFaultStrategy', Operation Key: 'MyFaultInjectedOperation', Result: ''
+```
+
+> [!NOTE]
+> Please note that the `Chaos.OnFault` telemetry event will be reported **only if** the fault chaos strategy injects an exception which is wrapped into a `ValueTask`.
+>
+> So, if the fault is either not injected or injected and throws an exception then there will be no telemetry emitted.
+>
+> Also remember that the `Result` will be **always empty** for the `Chaos.OnFault` telemetry event.
+
+For further information please check out the [telemetry page](../advanced/telemetry.md).
 
 ## Diagrams
 

diff --git a/docs/chaos/latency.md b/docs/chaos/latency.md
@@ -2,13 +2,15 @@
 
 ## About
 
-- **Options**: [`ChaosLatencyStrategyOptions`](xref:Polly.Simmy.Latency.ChaosLatencyStrategyOptions)
-- **Extensions**: `AddChaosLatency`
-- **Strategy Type**: Proactive
+- **Option(s)**:
+  - [`ChaosLatencyStrategyOptions`](xref:Polly.Simmy.Latency.ChaosLatencyStrategyOptions)
+- **Extension(s)**:
+  - `AddChaosLatency`
+- **Exception(s)**: -
 
 ---
 
-The latency chaos strategy is designed to introduce controlled delays into system operations, simulating network latency or slow processing times. This strategy helps in assessing and improving the resilience of applications against increased response times.
+The latency **proactive** chaos strategy is designed to introduce controlled delays into system operations, simulating network latency or slow processing times. This strategy helps in assessing and improving the resilience of applications against increased response times.
 
 ## Usage
 
@@ -90,15 +92,45 @@ var pipeline = new ResiliencePipelineBuilder()
 
 ## Defaults
 
-| Property            | Default Value | Description                                            |
-|---------------------|---------------|--------------------------------------------------------|
-| `Latency`           | `30 seconds`  | A `TimeSpan` indicating the delay to be injected.      |
-| `LatencyGenerator`  | `null`        | Generates the latency to inject for a given execution. |
-| `OnLatencyInjected` | `null`        | Action executed when latency is injected.              |
+| Property            | Default Value | Description                                                                                                          |
+|---------------------|---------------|----------------------------------------------------------------------------------------------------------------------|
+| `Latency`           | 30 seconds    | Defines a **static** delay to be injected.                                                                           |
+| `LatencyGenerator`  | `null`        | This delegate allows you to **dynamically** inject delay by utilizing information that is only available at runtime. |
+| `OnLatencyInjected` | `null`        | If provided then it will be invoked after the latency injection occurred.                                            |
 
 > [!NOTE]
 > If both `Latency` and `LatencyGenerator` are specified then `Latency` will be ignored.
 
+---
+
+> [!IMPORTANT]
+> Please note that if the calculated latency is negative (regardless if it's static or dynamic) then it will not be injected.
+
+## Telemetry
+
+The latency chaos strategy reports the following telemetry events:
+
+| Event Name        | Event Severity | When?                                                           |
+|-------------------|----------------|-----------------------------------------------------------------|
+| `Chaos.OnLatency` | `Information`  | Just before the strategy calls the `OnLatencyInjected` delegate |
+
+Here are some sample events:
+
+```none
+Resilience event occurred. EventName: 'Chaos.OnLatency', Source: '(null)/(null)/Chaos.Latency', Operation Key: '', Result: ''
+
+Resilience event occurred. EventName: 'Chaos.OnLatency', Source: 'MyPipeline/MyPipelineInstance/MyLatencyStrategy', Operation Key: 'MyLatencyInjectedOperation', Result: ''
+```
+
+> [!NOTE]
+> Please note that the `Chaos.OnLatency` telemetry event will be reported **only if** the latency chaos strategy injects a positive delay.
+>
+> So, if the latency is not injected then there will be no telemetry emitted. Also if injected but the latency is negative or the `LatencyGenerator` throws an exception then there will be no telemetry emitted.
+>
+> Also remember that the `Result` will be **always empty** for the `Chaos.OnLatency` telemetry event.
+
+For further information please check out the [telemetry page](../advanced/telemetry.md).
+
 ## Diagrams
 
 ### Normal 🐵 sequence diagram

diff --git a/docs/strategies/circuit-breaker.md b/docs/strategies/circuit-breaker.md
@@ -148,7 +148,7 @@ Resilience event occurred. EventName: 'OnCircuitClosed', Source: 'MyPipeline/MyP
 >
 > Also the `Result` will be **always empty** for the `OnCircuitHalfOpened` telemetry event.
 
-For further information please check out the [telemetry page](https://www.pollydocs.org/advanced/telemetry).
+For further information please check out the [telemetry page](../advanced/telemetry.md).
 
 ## Diagrams
 

diff --git a/docs/strategies/fallback.md b/docs/strategies/fallback.md
@@ -99,7 +99,7 @@ Resilience event occurred. EventName: 'OnFallback', Source: '(null)/(null)/Fallb
 >
 > Also remember that the `Result` will be **always populated** for the `OnFallback` telemetry event.
 
-For further information please check out the [telemetry page](https://www.pollydocs.org/advanced/telemetry).
+For further information please check out the [telemetry page](../advanced/telemetry.md).
 
 ## Diagrams
 

diff --git a/docs/strategies/hedging.md b/docs/strategies/hedging.md
@@ -113,7 +113,7 @@ Execution attempt. Source: 'MyPipeline/MyPipelineInstance/Hedging', Operation Ke
 >
 > Also remember that `Attempt: '0'` relates to the original execution attempt.
 
-For further information please check out the [telemetry page](https://www.pollydocs.org/advanced/telemetry).
+For further information please check out the [telemetry page](../advanced/telemetry.md).
 
 ## Concurrency modes
 

diff --git a/docs/strategies/rate-limiter.md b/docs/strategies/rate-limiter.md
@@ -154,7 +154,7 @@ Resilience event occurred. EventName: 'OnRateLimiterRejected', Source: 'MyPipeli
 >
 > Also remember that the `Result` will be **always empty** for the `OnRateLimiterRejected` telemetry event.
 
-For further information please check out the [telemetry page](https://www.pollydocs.org/advanced/telemetry).
+For further information please check out the [telemetry page](../advanced/telemetry.md).
 
 ## Diagrams
 

diff --git a/docs/strategies/retry.md b/docs/strategies/retry.md
@@ -168,7 +168,7 @@ Execution attempt. Source: 'MyPipeline/MyPipelineInstance/MyRetryStrategy', Oper
 >
 > Also remember that `Attempt: '0'` relates to the original execution attempt.
 
-For further information please check out the [telemetry page](https://www.pollydocs.org/advanced/telemetry).
+For further information please check out the [telemetry page](../advanced/telemetry.md).
 
 ## Calculation of the next delay
 

diff --git a/docs/strategies/timeout.md b/docs/strategies/timeout.md
@@ -153,7 +153,7 @@ Resilience event occurred. EventName: 'OnTimeout', Source: 'MyPipeline/MyPipelin
 >
 > Also remember that the `Result` will be **always empty** for the `OnTimeout` telemetry event.
 
-For further information please check out the [telemetry page](https://www.pollydocs.org/advanced/telemetry).
+For further information please check out the [telemetry page](../advanced/telemetry.md).
 
 ## Diagrams