mirror of https://github.com/dapr/docs.git
Merge pull request #2 from hhunter-ms/resiliency_docs
Grammar pass on resiliency docs
This commit is contained in:
greenie-msft
GitHub
commit
5dae464f86
|
|
@ -6,16 +6,21 @@ weight: 4500
|
|||
description: "Configure resiliency policies for timeouts, retries/backoffs and circuit breakers"
|
||||
---
|
||||
|
||||
Resiliency is currently a preview feature. Before you can utilize resiliency policies, you must first enable the resiliency preview feature.
|
||||
> Resiliency is currently a preview feature. Before you can utilize resiliency policies, you must first enable the resiliency preview feature.
|
||||
|
||||
### Policies
|
||||
Policies is where timeouts, retries and circuit breaker policies are defined. Each is given a name so they can be referred to from the `targets` section in the resiliency spec.
|
||||
|
||||
You define timeouts, retries and circuit breaker policies under `policies`. Each policy is given a name so you can refer to them from the `targets` section in the resiliency spec.
|
||||
|
||||
#### Timeouts
|
||||
|
||||
Timeouts can be used to early-terminate long-running operations. If a timeout is exceeded the operation in progress will be terminated if possible and an error is returned. Valid values are of the form `15s`, `2m`, `1h30m`, etc
|
||||
Timeouts can be used to early-terminate long-running operations. If you've exceeded timeout:
|
||||
|
||||
- The operation in progress will be terminated (if possible).
|
||||
- An error is returned.
|
||||
|
||||
Valid values are of the form `15s`, `2m`, `1h30m`, etc. For example:
|
||||
|
||||
Example definitions:
|
||||
```yaml
|
||||
spec:
|
||||
policies:
|
||||
|
|
@ -28,14 +33,17 @@ spec:
|
|||
|
||||
#### Retries
|
||||
|
||||
Retries allow defining of a retry stragegy for failed operations. Requests failed due to triggering a defined timeout or circuit breaker policy will also be retried per the retry strategy. The following retry options are configurable:
|
||||
With `retries`, you can define a retry strategy for failed operations, including requests failed due to triggering a defined timeout or circuit breaker policy. The following retry options are configurable:
|
||||
|
||||
- `policy`: determines the backoff and retry interval strategy. Valid values are `constant` and `exponential`. Defaults to `constant`.
|
||||
- `duration`: determines the time interval between retries. Default: `5s`. Only applies to the `constant` `policy`. Valid values are of the form `200ms`, `15s`, `2m`, etc
|
||||
- `maxInterval`: determines the largest interval between retries to which the `exponential` backoff `policy` can grow. Additional retries will always occur after a duration of `maxInterval`. Defaults to `60s`. Valid values are of the form `5s`, `1m`, `1m30s`, etc
|
||||
- `maxRetries`: The number of retries to attempt. `-1` denotes an indefinite number of retries. Defaults to `-1`.
|
||||
| Retry option | Description |
|
||||
| ------------ | ----------- |
|
||||
| `policy` | Determines the back-off and retry interval strategy. Valid values are `constant` and `exponential`. Defaults to `constant`. |
|
||||
| `duration` | Determines the time interval between retries. Default: `5s`. Only applies to the `constant` `policy`. Valid values are of the form `200ms`, `15s`, `2m`, etc. |
|
||||
| `maxInterval` | Determines the maximum interval between retries to which the `exponential` back-off `policy` can grow. Additional retries will always occur after a duration of `maxInterval`. Defaults to `60s`. Valid values are of the form `5s`, `1m`, `1m30s`, etc |
|
||||
| `maxRetries` | The maximum number of retries to attempt. `-1` denotes an indefinite number of retries. Defaults to `-1`. |
|
||||
|
||||
The exponential back-off window uses the following formula:
|
||||
|
||||
The exponential backoff window uses the following formula:
|
||||
```
|
||||
BackOffDuration = PreviousBackOffDuration * (Random value from 0.5 to 1.5) * 1.5
|
||||
if BackOffDuration > maxInterval {
|
||||
|
|
@ -44,6 +52,7 @@ if BackOffDuration > maxInterval {
|
|||
```
|
||||
|
||||
Example definitions:
|
||||
|
||||
```yaml
|
||||
spec:
|
||||
policies:
|
||||
|
|
@ -62,12 +71,14 @@ spec:
|
|||
|
||||
##### Circuit Breakers
|
||||
|
||||
Circuit Breakers (CBs) are policies that are used when other applications/services/components are experiencing elevated failure rates. Their purpose is to monitor the requests and, when a certain criteria is met, shut off all traffic to the impacted service. This is to give the service time to recover from their outage instead of flooding them with events. The circuit breaker can also allow partial traffic through to see if the system has healed (half open state). Once successful requests start to occur, the CB can close and allow traffic to resume.
|
||||
Circuit breakers (CBs) policies are used when other applications/services/components are experiencing elevated failure rates. CBs monitor the requests and shut off all traffic to the impacted service when a certain criteria is met. By doing this, CBs give the service time to recover from their outage instead of flooding them with events. The CB can also allow partial traffic through to see if the system has healed (half-open state). Once successful requests start to occur, the CB can close and allow traffic to resume.
|
||||
|
||||
- `maxRequests`: The maximum number of requests allowed to pass through when the CB is half-open (recovering from failure). Defaults to `1`.
|
||||
- `interval`: The cyclical period of time used by the CB to clear its internal counts. If set to 0 seconds, this will never clear. Defaults to `0s`.
|
||||
- `timeout`: The period of the open state (directly after failure) until the CB switches to half-open. Defaults to `60s`.
|
||||
- `trip`: A Common Expression Language (CEL) statement that is evaluated by the CB. When the statement evaluates to true, the CB trips and becomes open. Default is `consecutiveFailures > 5`.
|
||||
| Retry option | Description |
|
||||
| ------------ | ----------- |
|
||||
| `maxRequests` | The maximum number of requests allowed to pass through when the CB is half-open (recovering from failure). Defaults to `1`. |
|
||||
| `interval` | The cyclical period of time used by the CB to clear its internal counts. If set to 0 seconds, this will never clear. Defaults to `0s`. |
|
||||
| `timeout` | The period of the open state (directly after failure) until the CB switches to half-open. Defaults to `60s`. |
|
||||
| `trip` | A Common Expression Language (CEL) statement that is evaluated by the CB. When the statement evaluates to true, the CB trips and becomes open. Default is `consecutiveFailures > 5`. |
|
||||
|
||||
Example:
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ weight: 4500
|
|||
description: "Configure Dapr error retries, timeouts, and circuit breakers"
|
||||
---
|
||||
|
||||
Resiliency is currently a preview feature. Before you can utilize resiliency policies, you must first [enable the resiliency preview feature]({{< ref preview-features >}}).
|
||||
> Resiliency is currently a preview feature. Before you can utilize resiliency policies, you must first [enable the resiliency preview feature]({{< ref preview-features >}}).
|
||||
|
||||
## Introduction
|
||||
|
||||
|
|
|
|||
|
|
@ -6,16 +6,21 @@ weight: 4500
|
|||
description: "Apply resiliency policies for apps, components and actors"
|
||||
---
|
||||
|
||||
Resiliency is currently a preview feature. Before you can utilize resiliency policies, you must first enable the resiliency preview feature.
|
||||
> Resiliency is currently a preview feature. Before you can utilize resiliency policies, you must first enable the resiliency preview feature.
|
||||
|
||||
### Targets
|
||||
Targets are what named policies are applied to. Dapr supports 3 target types - `apps`, `components` and `actors`, which covers all Dapr builing blocks with the exception of observability. It's worth noting that resilient behaviors might differ between target types, as some targets may already include resilient capabilities, for example service invocation with built-in retries.
|
||||
Named policies are applied to targets. Dapr supports 3 target types that cover all Dapr building blocks, except observability:
|
||||
- `apps`
|
||||
- `components`
|
||||
- `actors`
|
||||
|
||||
Resilient behaviors might differ between target types, as some targets may already include resilient capabilities; for example, service invocation with built-in retries.
|
||||
|
||||
#### Apps
|
||||
|
||||
<img src="/images/resiliency_svc_invocation.png" width=1000 alt="Diagram showing service invocation resiliency" />
|
||||
|
||||
The `apps` target allows for applying `retry`, `timeout` and `circuitbreaker` policies to service invocation calls to other Dapr apps. Under `apps`, each key is the target service's `app-id` that the policies are applied to. Policies are applied when the network failure occurs between sidecar communication (as pictured in the diagram above). Additionally, Dapr provides [built-in service invocation retries]({{<ref "service-invocation-overview.md#retries">}}), so any applied `retry` policies are additional.
|
||||
With the `apps` target, you can apply `retry`, `timeout`, and `circuitBreaker` policies to service invocation calls between Dapr apps. Under `targets/apps`, policies are applied to each key or target service's `app-id` listed when network failure occurs between sidecar communication (as pictured in the diagram above).
|
||||
|
||||
Example of policies to a target app with the `app-id` "appB":
|
||||
|
||||
|
|
@ -29,17 +34,26 @@ specs:
|
|||
circuitBreaker: general
|
||||
```
|
||||
|
||||
> Dapr provides [built-in service invocation retries]({{< ref "service-invocation-overview.md#retries" >}}), so any applied `retry` policies are additional.
|
||||
|
||||
#### Components
|
||||
|
||||
The `components` target allows for applying of `retry`, `timeout` and `circuitbreaker` policies to components operations. Policy assignments are optional.
|
||||
With the `components` target, you can apply `retry`, `timeout` and `circuitBreaker` policies to components operations. Policy assignments are optional.
|
||||
|
||||
Policies can be applied for `outbound` operations (calls to the Dapr sidecar) and/or `inbound` (the sidecar calling your app). At this time, inbound only applies to PubSub and InputBinding components.
|
||||
Policies can be applied for `outbound` operations (calls to the Dapr sidecar) and/or `inbound` (the sidecar calling your app). At this time, *inbound* only applies to PubSub and InputBinding components.
|
||||
|
||||
##### Outbound
|
||||
Calls from the sidecar to a component are `outbound` operations. Persisting or retrieveting state, publishing a message, invoking an output binding are all examples of `outbound` operations. Some components have `retry` capabilities built-in and are configured on a per component basis.
|
||||
|
||||
`outbound` operations are calls from the sidecar to a component, such as:
|
||||
|
||||
- Persisting or retrieving state.
|
||||
- Publishing a message.
|
||||
- Invoking an output binding.
|
||||
|
||||
<img src="/images/resiliency_outbound.png" width=1000 alt="Diagram showing service invocation resiliency">
|
||||
|
||||
Some components have built-in `retry` capabilities and are configured on a per-component basis.
|
||||
|
||||
```yaml
|
||||
spec:
|
||||
targets:
|
||||
|
|
@ -50,12 +64,17 @@ spec:
|
|||
circuitBreaker: pubsubCB
|
||||
```
|
||||
|
||||
##### Inbound
|
||||
Call from the sidecar to your application are `inbound` operations. Subscribing to a topic and inbound bindings are examples of `inbound` operations.
|
||||
##### Inbound
|
||||
|
||||
`inbound` operations are calls from the sidecar to your application, such as:
|
||||
|
||||
- Subscribing to a topic.
|
||||
- Inbound bindings.
|
||||
|
||||
<img src="/images/resiliency_inbound.png" width=1000 alt="Diagram showing service invocation resiliency" />
|
||||
|
||||
Example
|
||||
Some components have built-in `retry` capabilities and are configured on a per-component basis.
|
||||
|
||||
```yaml
|
||||
spec:
|
||||
targets:
|
||||
|
|
@ -68,9 +87,11 @@ spec:
|
|||
```
|
||||
|
||||
##### PubSub
|
||||
|
||||
In a PubSub `target/component`, you can specify both `inbound` and `outbound` operations.
|
||||
|
||||
<img src="/images/resiliency_pubsub.png" width=1000 alt="Diagram showing service invocation resiliency">
|
||||
|
||||
Example
|
||||
```yaml
|
||||
spec:
|
||||
targets:
|
||||
|
|
@ -87,13 +108,20 @@ spec:
|
|||
|
||||
#### Actors
|
||||
|
||||
Allows applying of `retry`, `timeout` and `circuitbreaker` policies to actor operations. Policy assignments are optional.
|
||||
With the `actors` target, you can apply `retry`, `timeout`, and `circuitBreaker` policies to actor operations. Policy assignments are optional.
|
||||
|
||||
When using a `circuitbreaker` policy, you can additionally specify whether circuit breaking state should be scoped to an invididual actor ID, to all actors across the actor type, or both. Specify `circuitBreakerScope` with values `id`, `type`, or `both`.
|
||||
When using a `circuitBreaker` policy, you can specify whether circuit breaking state should be scoped to:
|
||||
|
||||
Additionally, you can specify a cache size for the number of circuit breakers to keep in memory. This can be done by specifying `circuitBreakerCacheSize` and providing an integer value, e.g. `5000`.
|
||||
- An individual actor ID.
|
||||
- All actors across the actor type.
|
||||
- Both.
|
||||
|
||||
Specify `circuitBreakerScope` with values `id`, `type`, or `both`.
|
||||
|
||||
You can specify a cache size for the number of circuit breakers to keep in memory. Do this by specifying `circuitBreakerCacheSize` and providing an integer value, e.g. `5000`.
|
||||
|
||||
Example
|
||||
|
||||
```yaml
|
||||
spec:
|
||||
targets:
|
||||
|
|
|
|||
Loading…
Reference in New Issue