Skip to content

Commit 5441dc9

Browse files
peter-csalapeter-csala
authored
[Docs] Add telemetry section to chaos strategies documentation pages (#2071)
1 parent 07f09a6 commit 5441dc9

File tree

12 files changed

+188
-65
lines changed

12 files changed

+188
-65
lines changed

‎docs/advanced/telemetry.md‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Telemetry
22

3-
Starting with version 8, Polly provides telemetry for all built-in resilience strategies.
3+
Starting with version 8, Polly provides telemetry for all built-in standard and chaos resilience strategies.
44

55
## Usage
66

@@ -140,14 +140,18 @@ Tags:
140140

141141
The `event.name` tag is reported by individual resilience strategies. The built-in strategies report the following events:
142142

143-
- `OnRetry`
144-
- `OnFallback`
145-
- `OnHedging`
146-
- `OnTimeout`
147-
- `OnCircuitClosed`
148-
- `OnCircuitOpened`
149-
- `OnCircuitHalfOpened`
150-
- `OnRateLimiterRejected`
143+
- [`OnRetry`](../strategies/retry.md#telemetry)
144+
- [`OnFallback`](../strategies/fallback.md#telemetry)
145+
- [`OnHedging`](../strategies/hedging.md#telemetry)
146+
- [`OnTimeout`](../strategies/timeout.md#telemetry)
147+
- [`OnCircuitClosed`](../strategies/circuit-breaker.md#telemetry)
148+
- [`OnCircuitOpened`](../strategies/circuit-breaker.md#telemetry)
149+
- [`OnCircuitHalfOpened`](../strategies/circuit-breaker.md#telemetry)
150+
- [`OnRateLimiterRejected`](../strategies/rate-limiter.md#telemetry)
151+
- [`Chaos.OnFault`](../chaos/fault.md#telemetry)
152+
- [`Chaos.OnOutcome`](../chaos/outcome.md#telemetry)
153+
- [`Chaos.OnLatency`](../chaos/latency.md#telemetry)
154+
- [`Chaos.OnBehavior`](../chaos/behavior.md#telemetry)
151155

152156
### Instrument: `resilience.polly.strategy.attempt.duration`
153157

‎docs/chaos/behavior.md‎

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,15 @@
22

33
## About
44

5-
- **Options**: [`ChaosBehaviorStrategyOptions`](xref:Polly.Simmy.Behavior.ChaosBehaviorStrategyOptions)
6-
- **Extensions**: `AddChaosBehavior`
7-
- **Strategy Type**: Proactive
5+
- **Option(s)**:
6+
- [`ChaosBehaviorStrategyOptions`](xref:Polly.Simmy.Behavior.ChaosBehaviorStrategyOptions)
7+
- **Extension(s)**:
8+
- `AddChaosBehavior`
9+
- **Exception(s)**: -
810

911
---
1012

11-
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.
13+
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.
1214

1315
## Usage
1416

@@ -66,10 +68,35 @@ var pipeline = new ResiliencePipelineBuilder()
6668

6769
## Defaults
6870

69-
| Property | Default Value | Description |
70-
|----------------------|---------------|------------------------------------------------|
71-
| `OnBehaviorInjected` | `null` | Action executed when the behavior is injected. |
72-
| `BehaviorGenerator` | `null` | Custom behavior to be injected. |
71+
| Property | Default Value | Description |
72+
|----------------------|---------------|------------------------------------------------------------------------------------------------------------------------------|
73+
| `BehaviorGenerator` | `null` | This required delegate allows you to inject custom behavior by utilizing information that is only available at runtime. |
74+
| `OnBehaviorInjected` | `null` | If provided then it will be invoked after the behavior injection occurred. |
75+
76+
## Telemetry
77+
78+
The behavior chaos strategy reports the following telemetry events:
79+
80+
| Event Name | Event Severity | When? |
81+
|--------------------|----------------|------------------------------------------------------------------|
82+
| `Chaos.OnBehavior` | `Information` | Just before the strategy calls the `OnBehaviorInjected` delegate |
83+
84+
Here are some sample events:
85+
86+
```none
87+
Resilience event occurred. EventName: 'Chaos.OnBehavior', Source: '(null)/(null)/Chaos.Behavior', Operation Key: '', Result: ''
88+
89+
Resilience event occurred. EventName: 'Chaos.OnBehavior', Source: 'MyPipeline/MyPipelineInstance/MyChaosBehaviorStrategy', Operation Key: 'MyBehaviorInjectedOperation', Result: ''
90+
```
91+
92+
> [!NOTE]
93+
> 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.
94+
>
95+
> So, if the behavior is either not injected or injected and throws an exception then there will be no telemetry emitted.
96+
>
97+
> Also remember that the `Result` will be **always empty** for the `Chaos.OnBehavior` telemetry event.
98+
99+
For further information please check out the [telemetry page](../advanced/telemetry.md).
73100

74101
## Diagrams
75102

‎docs/chaos/fault.md‎

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,15 @@
22

33
## About
44

5-
- **Options**: [`ChaosFaultStrategyOptions`](xref:Polly.Simmy.Fault.ChaosFaultStrategyOptions)
6-
- **Extensions**: `AddChaosFault`
7-
- **Strategy Type**: Proactive
5+
- **Option(s)**:
6+
- [`ChaosFaultStrategyOptions`](xref:Polly.Simmy.Fault.ChaosFaultStrategyOptions)
7+
- **Extensions**:
8+
- `AddChaosFault`
9+
- **Exception(s)**: -
810

911
---
1012

11-
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.
13+
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.
1214

1315
## Usage
1416

@@ -87,10 +89,35 @@ var pipeline = new ResiliencePipelineBuilder()
8789

8890
## Defaults
8991

90-
| Property | Default Value | Description |
91-
|-------------------|---------------|------------------------------------------------------|
92-
| `OnFaultInjected` | `null` | Action executed when the fault is injected. |
93-
| `FaultGenerator` | `null` | Generates the fault to inject for a given execution. |
92+
| Property | Default Value | Description |
93+
|-------------------|---------------|------------------------------------------------------------------------------------------------------------------------|
94+
| `FaultGenerator` | `null` | This required delegate allows you to inject exception by utilizing information that is only available at runtime. |
95+
| `OnFaultInjected` | `null` | If provided then it will be invoked after the fault injection occurred. |
96+
97+
## Telemetry
98+
99+
The fault chaos strategy reports the following telemetry events:
100+
101+
| Event Name | Event Severity | When? |
102+
|-----------------|----------------|---------------------------------------------------------------|
103+
| `Chaos.OnFault` | `Information` | Just before the strategy calls the `OnFaultInjected` delegate |
104+
105+
Here are some sample events:
106+
107+
```none
108+
Resilience event occurred. EventName: 'Chaos.OnFault', Source: '(null)/(null)/Chaos.Fault', Operation Key: '', Result: ''
109+
110+
Resilience event occurred. EventName: 'Chaos.OnFault', Source: 'MyPipeline/MyPipelineInstance/MyChaosFaultStrategy', Operation Key: 'MyFaultInjectedOperation', Result: ''
111+
```
112+
113+
> [!NOTE]
114+
> 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`.
115+
>
116+
> So, if the fault is either not injected or injected and throws an exception then there will be no telemetry emitted.
117+
>
118+
> Also remember that the `Result` will be **always empty** for the `Chaos.OnFault` telemetry event.
119+
120+
For further information please check out the [telemetry page](../advanced/telemetry.md).
94121

95122
## Diagrams
96123

‎docs/chaos/index.md‎

Lines changed: 19 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -52,10 +52,14 @@ This section highlights the major differences compared to the [`Polly.Contrib.Si
5252
- **Unified configuration options**: The `InjectOptionsBase` and `InjectOptionsAsyncBase` are now consolidated into `ChaosStrategyOptions`. This change brings Simmy in line with the Polly v8 API, offering built-in support for options-based configuration and seamless integration of synchronous and asynchronous executions.
5353
- **Chaos strategies enabled by default**: Adding a chaos strategy (previously known as monkey policy) now means it's active right away. This is a departure from earlier versions, where the monkey policy had to be explicitly enabled.
5454
- **API changes**: The new version of Simmy introduces several API updates. While this list isn't complete, it includes key changes like renaming `Inject` to `AddChaos` and switching from `Result` to `Outcome`. Here are some specific renames:
55-
- `InjectException` is now `AddChaosFault`
56-
- `InjectResult` is now `AddChaosOutcome`
57-
- `InjectBehavior` is now `AddChaosBehavior`
58-
- `InjectLatency` is now `AddChaosLatency`
55+
56+
| From | To |
57+
|-------------------|--------------------|
58+
| `InjectException` | `AddChaosFault` |
59+
| `InjectResult` | `AddChaosOutcome` |
60+
| `InjectBehavior` | `AddChaosBehavior` |
61+
| `InjectLatency` | `AddChaosLatency` |
62+
5963
- **Sync and async unification**: Before, Simmy had various methods to set policies like `InjectLatency`, `InjectLatencyAsync`, `InjectLatency<T>`, and `InjectLatencyAsync<T>`. With the new version based on Polly v8, these methods have been combined into a single `AddChaosLatency` extension that works for both `ResiliencePipelineBuilder` and `ResiliencePipelineBuilder<T>`. These rules are covering all types of chaos strategies (Outcome, Fault, Latency, and Behavior).
6064

6165
## Motivation
@@ -82,12 +86,12 @@ Chaos strategies (formerly known as Monkey strategies) are in essence a [Resilie
8286

8387
### Built-in strategies
8488

85-
| Strategy | Reactive | What does the strategy do? |
86-
|-------------------------|----------|----------------------------------------------------------------------|
87-
| [Fault](fault.md) | No | Injects exceptions in your system. |
88-
| [Outcome](outcome.md) | Yes | Injects fake outcomes (results or exceptions) in your system. |
89-
| [Latency](latency.md) | No | Injects latency into executions before the calls are made. |
90-
| [Behavior](behavior.md) | No | Allows you to inject *any* extra behavior, before a call is placed. |
89+
| Strategy | Type | What does the strategy do? |
90+
|-------------------------|-----------|---------------------------------------------------------------------|
91+
| [Fault](fault.md) | Proactive | Injects exceptions in your system. |
92+
| [Outcome](outcome.md) | Reactive | Injects fake outcomes (results or exceptions) in your system. |
93+
| [Latency](latency.md) | Proactive | Injects latency into executions before the calls are made. |
94+
| [Behavior](behavior.md) | Proactive | Allows you to inject *any* extra behavior, before a call is placed. |
9195

9296
## Common options across strategies
9397

@@ -114,12 +118,12 @@ All the strategies' options implement the [`ChaosStrategyOptions`](xref:Polly.Si
114118

115119
## Telemetry
116120

117-
The telemetry of chaos strategies is seamlessly integrated with Polly [telemetry infrastructure](../advanced/telemetry.md). The chaos strategies produce the following events:
121+
The telemetry of chaos strategies is seamlessly integrated with Polly [telemetry infrastructure](../advanced/telemetry.md). The chaos strategies produce the following information events:
118122

119-
- `Chaos.OnFault`
120-
- `Chaos.OnOutcome`
121-
- `Chaos.OnLatency`
122-
- `Chaos.OnBehavior`
123+
- [`Chaos.OnFault`](fault.md#telemetry)
124+
- [`Chaos.OnOutcome`](outcome.md#telemetry)
125+
- [`Chaos.OnLatency`](latency.md#telemetry)
126+
- [`Chaos.OnBehavior`](behavior.md#telemetry)
123127

124128
## Patterns
125129

‎docs/chaos/latency.md‎

Lines changed: 41 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,15 @@
22

33
## About
44

5-
- **Options**: [`ChaosLatencyStrategyOptions`](xref:Polly.Simmy.Latency.ChaosLatencyStrategyOptions)
6-
- **Extensions**: `AddChaosLatency`
7-
- **Strategy Type**: Proactive
5+
- **Option(s)**:
6+
- [`ChaosLatencyStrategyOptions`](xref:Polly.Simmy.Latency.ChaosLatencyStrategyOptions)
7+
- **Extension(s)**:
8+
- `AddChaosLatency`
9+
- **Exception(s)**: -
810

911
---
1012

11-
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.
13+
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.
1214

1315
## Usage
1416

@@ -90,15 +92,45 @@ var pipeline = new ResiliencePipelineBuilder()
9092

9193
## Defaults
9294

93-
| Property | Default Value | Description |
94-
|---------------------|---------------|--------------------------------------------------------|
95-
| `Latency` | `30 seconds` | A `TimeSpan` indicating the delay to be injected. |
96-
| `LatencyGenerator` | `null` | Generates the latency to inject for a given execution. |
97-
| `OnLatencyInjected` | `null` | Action executed when latency is injected. |
95+
| Property | Default Value | Description |
96+
|---------------------|---------------|----------------------------------------------------------------------------------------------------------------------|
97+
| `Latency` | 30 seconds | Defines a **fixed** delay to be injected. |
98+
| `LatencyGenerator` | `null` | This delegate allows you to **dynamically** inject delay by utilizing information that is only available at runtime. |
99+
| `OnLatencyInjected` | `null` | If provided then it will be invoked after the latency injection occurred. |
98100

99101
> [!NOTE]
100102
> If both `Latency` and `LatencyGenerator` are specified then `Latency` will be ignored.
101103
104+
---
105+
106+
> [!IMPORTANT]
107+
> Please note that if the calculated latency is negative (regardless if it's fixed or dynamic) then it will not be injected.
108+
109+
## Telemetry
110+
111+
The latency chaos strategy reports the following telemetry events:
112+
113+
| Event Name | Event Severity | When? |
114+
|-------------------|----------------|-----------------------------------------------------------------|
115+
| `Chaos.OnLatency` | `Information` | Just before the strategy calls the `OnLatencyInjected` delegate |
116+
117+
Here are some sample events:
118+
119+
```none
120+
Resilience event occurred. EventName: 'Chaos.OnLatency', Source: '(null)/(null)/Chaos.Latency', Operation Key: '', Result: ''
121+
122+
Resilience event occurred. EventName: 'Chaos.OnLatency', Source: 'MyPipeline/MyPipelineInstance/MyLatencyStrategy', Operation Key: 'MyLatencyInjectedOperation', Result: ''
123+
```
124+
125+
> [!NOTE]
126+
> Please note that the `Chaos.OnLatency` telemetry event will be reported **only if** the latency chaos strategy injects a positive delay.
127+
>
128+
> 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.
129+
>
130+
> Also remember that the `Result` will be **always empty** for the `Chaos.OnLatency` telemetry event.
131+
132+
For further information please check out the [telemetry page](../advanced/telemetry.md).
133+
102134
## Diagrams
103135

104136
### Normal 🐵 sequence diagram

‎docs/chaos/outcome.md‎

Lines changed: 37 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,15 @@
22

33
## About
44

5-
- **Options**:
5+
- **Option(s)**:
66
- [`ChaosOutcomeStrategyOptions<T>`](xref:Polly.Simmy.Outcomes.ChaosOutcomeStrategyOptions`1)
7-
- **Extensions**: `AddChaosOutcome`
8-
- **Strategy Type**: Reactive
7+
- **Extension(s)**:
8+
- `AddChaosOutcome`
9+
- **Exception(s)**: -
910

1011
---
1112

12-
The outcome chaos strategy is designed to inject or substitute fake results into system operations. This allows testing how an application behaves when it receives different types of responses, like successful results, errors, or exceptions.
13+
The outcome **reactive** chaos strategy is designed to inject or substitute fake results into system operations. This allows testing how an application behaves when it receives different types of responses, like successful results, errors, or exceptions.
1314

1415
## Usage
1516

@@ -79,10 +80,38 @@ var pipeline = new ResiliencePipelineBuilder<HttpResponseMessage>()
7980

8081
## Defaults
8182

82-
| Property | Default Value | Description |
83-
|---------------------|---------------|---------------------------------------------------------|
84-
| `OutcomeGenerator` | `null` | Function to generate the outcome for a given execution. |
85-
| `OnOutcomeInjected` | `null` | Action executed when the outcome is injected. |
83+
| Property | Default Value | Description |
84+
|---------------------|---------------|-----------------------------------------------------------------------------------------------------------------------------|
85+
| `OutcomeGenerator` | `null` | This required delegate allows you to inject custom outcome by utilizing information that is only available at runtime. |
86+
| `OnOutcomeInjected` | `null` | If provided then it will be invoked after the outcome injection occurred. |
87+
88+
> [!NOTE]
89+
> Please note this strategy is a reactive chaos strategy, but it does not have a `ShouldHandle` delegate.
90+
91+
## Telemetry
92+
93+
The outcome chaos strategy reports the following telemetry events:
94+
95+
| Event Name | Event Severity | When? |
96+
|-------------------|----------------|-----------------------------------------------------------------|
97+
| `Chaos.OnOutcome` | `Information` | Just before the strategy calls the `OnOutcomeInjected` delegate |
98+
99+
Here are some sample events:
100+
101+
```none
102+
Resilience event occurred. EventName: 'Chaos.OnOutcome', Source: '(null)/(null)/Chaos.Outcome', Operation Key: '', Result: ''
103+
104+
Resilience event occurred. EventName: 'Chaos.OnOutcome', Source: 'MyPipeline/MyPipelineInstance/MyOutcomeStrategy', Operation Key: 'MyOutcomeInjectedOperation', Result: ''
105+
```
106+
107+
> [!NOTE]
108+
> Please note that the `Chaos.OnOutcome` telemetry event will be reported **only if** the outcome chaos strategy injects an outcome object.
109+
>
110+
> So, if the outcome is not injected or injected but the generator delegate throws an exception then there will be no telemetry emitted.
111+
>
112+
> Also remember that the `Result` will be **always empty** for the `Chaos.OnOutcome` telemetry event.
113+
114+
For further information please check out the [telemetry page](../advanced/telemetry.md).
86115

87116
## Diagrams
88117

0 commit comments

Comments
 (0)