Skip to content

Add documentation for the jobs failure policy #4676

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: v1.15
Choose a base branch
from
+42 −9
Open

Add documentation for the jobs failure policy #4676

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 10 additions & 9 deletions ...ntent/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ weight: 2000
description: "Learn more about the Dapr Jobs features and concepts"
---

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

## Job identity

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

Only one job can be associated with a name at any given time. Any attempt to create a new job using the same name
Expand All @@ -27,8 +27,8 @@ A job can be scheduled using any of the following mechanisms:
- Intervals using Cron expressions, duration values, or period expressions
- Specific dates and times

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

Expand All @@ -48,7 +48,7 @@ fields spanning the values specified in the table below:

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

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

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

#### Example 1
Expand Down Expand Up @@ -107,15 +107,16 @@ In this setup, you have full control over how triggered jobs are received and pr
through this gRPC method.

### HTTP
If a gRPC server isn't registered with Dapr when the application starts up, Dapr instead triggers jobs by making a
If a gRPC server isn't registered with Dapr when the application starts up, Dapr instead triggers jobs by making a
POST request to the endpoint `/job/<job-name>`. The body includes the following information about the job:
- `Schedule`: When the job triggers occur
- `RepeatCount`: An optional value indicating how often the job should repeat
- `DueTime`: An optional point in time representing either the one time when the job should execute (if not recurring)
or the not-before time from which the schedule should take effect
- `Ttl`: An optional value indicating when the job should expire
- `Payload`: A collection of bytes containing data originally stored when the job was scheduled
- `FailurePolicy`: An optional failure policy for the job.

The `DueTime` and `Ttl` fields will reflect an RC3339 timestamp value reflective of the time zone provided when the job was
originally scheduled. If no time zone was provided, these values indicate the time zone used by the server running
Dapr.
Dapr.
32 changes: 32 additions & 0 deletions daprdocs/content/en/reference/api/jobs_api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ Parameter | Description
`dueTime` | An optional time at which the job should be active, or the "one shot" time, if other scheduling type fields are not provided. Accepts a "point in time" string in the format of RFC3339, Go duration string (calculated from creation time), or non-repeating ISO8601.
`repeats` | An optional number of times in which the job should be triggered. If not set, the job runs indefinitely or until expiration.
`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.
`failure_policy` | An optional failure policy for the job. Details of the format are below.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add to this line what the default value is when unset.

Please can we add a new table with the full failure_policy API definitions- add what the defaults are when fields are unset.


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

#### failure_policy

`failure_policy` specifies how the job should handle failures.

It can be set to `constant` or `drop`.
- The `constant` policy will retry the job up to `max_retries` times, with a delay of `interval` between retries.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add that if max_retries is not set, it will retry forever.

- The `drop` policy will drop the job after the first failure, without retrying.

##### Example 1

```json
{
//...
"failure_policy": {
"constant": {
"max_retries": 3,
"interval": "10s"
}
}
}
```
##### Example 2

```json
{
//...
"failure_policy": {
"drop": {}
}
}
```

### Request body

Expand Down