Skip to content

Commit 0b197f8

Browse files
committed
chore: Add documentation for the jobs failure policy
Signed-off-by: Albert Callarisa <[email protected]>
1 parent 68f1be7 commit 0b197f8

File tree

2 files changed

+43
-10
lines changed

2 files changed

+43
-10
lines changed

daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ weight: 2000
66
description: "Learn more about the Dapr Jobs features and concepts"
77
---
88

9-
Now that you've learned about the [jobs building block]({{< ref jobs-overview.md >}}) at a high level, let's deep dive
9+
Now that you've learned about the [jobs building block]({{< ref jobs-overview.md >}}) at a high level, let's deep dive
1010
into the features and concepts included with Dapr Jobs and the various SDKs. Dapr Jobs:
1111
- Provides a robust and scalable API for scheduling operations to be triggered in the future.
1212
- Exposes several capabilities which are common across all supported languages.
@@ -15,19 +15,19 @@ into the features and concepts included with Dapr Jobs and the various SDKs. Dap
1515

1616
## Job identity
1717

18-
All jobs are registered with a case-sensitive job name. These names are intended to be unique across all services
19-
interfacing with the Dapr runtime. The name is used as an identifier when creating and modifying the job as well as
18+
All jobs are registered with a case-sensitive job name. These names are intended to be unique across all services
19+
interfacing with the Dapr runtime. The name is used as an identifier when creating and modifying the job as well as
2020
to indicate which job a triggered invocation is associated with.
2121

22-
Only one job can be associated with a name at any given time. By default, any attempt to create a new job using the same name as an existing job results in an error. However, if the `overwrite` flag is set to `true`, the new job overwrites the existing job with the same name.
22+
Only one job can be associated with a name at any given time. By default, any attempt to create a new job using the same name as an existing job results in an error. However, if the `overwrite` flag is set to `true`, the new job overwrites the existing job with the same name.
2323

2424
## Scheduling Jobs
2525
A job can be scheduled using any of the following mechanisms:
2626
- Intervals using Cron expressions, duration values, or period expressions
2727
- Specific dates and times
2828

29-
For all time-based schedules, if a timestamp is provided with a time zone via the RFC3339 specification, that
30-
time zone is used. When not provided, the time zone used by the server running Dapr is used.
29+
For all time-based schedules, if a timestamp is provided with a time zone via the RFC3339 specification, that
30+
time zone is used. When not provided, the time zone used by the server running Dapr is used.
3131
In other words, do **not** assume that times run in UTC time zone, unless otherwise specified when scheduling
3232
the job.
3333

@@ -47,7 +47,7 @@ fields spanning the values specified in the table below:
4747

4848
### Schedule using a duration value
4949
You can schedule jobs using [a Go duration string](https://pkg.go.dev/time#ParseDuration), in which
50-
a string consists of a (possibly) signed sequence of decimal numbers, each with an optional fraction and a unit suffix.
50+
a string consists of a (possibly) signed sequence of decimal numbers, each with an optional fraction and a unit suffix.
5151
Valid time units are `"ns"`, `"us"`, `"ms"`, `"s"`, `"m"`, or `"h"`.
5252

5353
#### Example 1
@@ -69,7 +69,7 @@ The following period expressions are supported. The "@every" expression also acc
6969
| @hourly | Run once an hour at the beginning of the hour | 0 0 * * * * |
7070

7171
### Schedule using a specific date/time
72-
A job can also be scheduled to run at a particular point in time by providing a date using the
72+
A job can also be scheduled to run at a particular point in time by providing a date using the
7373
[RFC3339 specification](https://www.rfc-editor.org/rfc/rfc3339).
7474

7575
#### Example 1
@@ -106,7 +106,7 @@ In this setup, you have full control over how triggered jobs are received and pr
106106
through this gRPC method.
107107

108108
### HTTP
109-
If a gRPC server isn't registered with Dapr when the application starts up, Dapr instead triggers jobs by making a
109+
If a gRPC server isn't registered with Dapr when the application starts up, Dapr instead triggers jobs by making a
110110
POST request to the endpoint `/job/<job-name>`. The body includes the following information about the job:
111111
- `Schedule`: When the job triggers occur
112112
- `RepeatCount`: An optional value indicating how often the job should repeat
@@ -115,7 +115,8 @@ or the not-before time from which the schedule should take effect
115115
- `Ttl`: An optional value indicating when the job should expire
116116
- `Payload`: A collection of bytes containing data originally stored when the job was scheduled
117117
- `Overwrite`: A flag to allow the requested job to overwrite an existing job with the same name, if it already exists.
118+
- `FailurePolicy`: An optional failure policy for the job.
118119

119120
The `DueTime` and `Ttl` fields will reflect an RC3339 timestamp value reflective of the time zone provided when the job was
120121
originally scheduled. If no time zone was provided, these values indicate the time zone used by the server running
121-
Dapr.
122+
Dapr.

daprdocs/content/en/reference/api/jobs_api.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ Parameter | Description
3838
`repeats` | An optional number of times in which the job should be triggered. If not set, the job runs indefinitely or until expiration.
3939
`ttl` | An optional time to live or expiration of the job. Accepts a "point in time" string in the format of RFC3339, Go duration string (calculated from job creation time), or non-repeating ISO8601.
4040
`overwrite` | A boolean value to specify if the job can overwrite an existing one with the same name. Default value is `false`
41+
`failure_policy` | An optional failure policy for the job. Details of the format are below.
4142

4243
#### schedule
4344
`schedule` accepts both systemd timer-style cron expressions, as well as human readable '@' prefixed period strings, as defined below.
@@ -63,6 +64,37 @@ Entry | Description | Equivalent
6364
@daily (or @midnight) | Run once a day, midnight | 0 0 0 * * *
6465
@hourly | Run once an hour, beginning of hour | 0 0 * * * *
6566

67+
#### failure_policy
68+
69+
`failure_policy` specifies how the job should handle failures.
70+
71+
It can be set to `constant` or `drop`.
72+
- The `constant` policy will retry the job up to `max_retries` times, with a delay of `interval` between retries.
73+
- The `drop` policy will drop the job after the first failure, without retrying.
74+
75+
##### Example 1
76+
77+
```json
78+
{
79+
//...
80+
"failure_policy": {
81+
"constant": {
82+
"max_retries": 3,
83+
"interval": "10s"
84+
}
85+
}
86+
}
87+
```
88+
##### Example 2
89+
90+
```json
91+
{
92+
//...
93+
"failure_policy": {
94+
"drop": {}
95+
}
96+
}
97+
```
6698

6799
### Request body
68100

0 commit comments

Comments
 (0)