Skip to content

Commit 9d987cd

Browse files
JeremyduprasJeremy Dupraskolchfa-awsnatebower
authored
Addition of Job scheduler APIs documentation - Jobs API - Locks API (#10663)
* adding job scheduler api documentation Signed-off-by: Jeremy Dupras <jdupras@amazon.com> * adding locks API and spelling Signed-off-by: Jeremy Dupras <jdupras@amazon.com> * updating for comments Signed-off-by: Jeremy Dupras <jdupras@amazon.com> * Doc review Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Apply suggestions from code review Signed-off-by: Nathan Bower <nbower@amazon.com> --------- Signed-off-by: Jeremy Dupras <jdupras@amazon.com> Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> Signed-off-by: Nathan Bower <nbower@amazon.com> Co-authored-by: Jeremy Dupras <jdupras@amazon.com> Co-authored-by: Fanit Kolchina <kolchfa@amazon.com> Co-authored-by: Nathan Bower <nbower@amazon.com>
1 parent c25c63d commit 9d987cd

File tree

4 files changed

+209
-1
lines changed

4 files changed

+209
-1
lines changed

‎_api-reference/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ OpenSearch supports the following REST APIs:
3737
- [Index state management API]({{site.url}}{{site.baseurl}}/im-plugin/ism/api/)
3838
- [ISM error prevention API]({{site.url}}{{site.baseurl}}/im-plugin/ism/error-prevention/api/)
3939
- [Ingest APIs]({{site.url}}{{site.baseurl}}/api-reference/ingest-apis/index/)
40+
- [Job Scheduler APIs]({{site.url}}{{site.baseurl}}/monitoring-your-cluster/job-scheduler/index/#job-scheduler-apis)
4041
- [Vector search API]({{site.url}}{{site.baseurl}}/vector-search/api/)
4142
- [ML Commons API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/)
4243
- [Multi-search]({{site.url}}{{site.baseurl}}/api-reference/multi-search/)

‎_monitoring-your-cluster/job-scheduler/index.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
layout: default
33
title: Job Scheduler
44
nav_order: 1
5-
has_children: false
5+
has_children: true
66
has_toc: false
77
redirect_from:
88
- /job-scheduler-plugin/index/
@@ -131,6 +131,13 @@ The logic used by your job should be defined by a class extended from `Scheduled
131131

132132
For more information, see the Job Scheduler [sample extension](https://github.com/opensearch-project/job-scheduler/blob/main/sample-extension-plugin/src/main/java/org/opensearch/jobscheduler/sampleextension/SampleJobParameter.java) directory in the [Job Scheduler GitHub repo](https://github.com/opensearch-project/job-scheduler).
133133

134+
## Job Scheduler APIs
135+
136+
The Job Scheduler plugin supports the following APIs used to monitor the jobs running on the cluster:
137+
138+
- [Jobs API]({{site.url}}{{site.baseurl}}/monitoring-your-cluster/job-scheduler/jobs/)
139+
- [Locks API]({{site.url}}{{site.baseurl}}/monitoring-your-cluster/job-scheduler/locks/)
140+
134141
## Job Scheduler cluster settings
135142

136143
The Job Scheduler plugin supports the following cluster settings. All settings are dynamic. To learn more about static and dynamic settings, see [Configuring OpenSearch]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/index/).

‎_monitoring-your-cluster/job-scheduler/jobs.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
layout: default
3+
title: Jobs API
4+
parent: Job Scheduler
5+
nav_order: 10
6+
redirect_from:
7+
- /monitoring-plugins/job-scheduler/api/
8+
---
9+
10+
# Job Scheduler Jobs API
11+
Introduced 3.2
12+
{: .label .label-purple }
13+
14+
The Jobs API allows you to view all Job Scheduler jobs.
15+
16+
## Endpoints
17+
18+
```json
19+
GET /_plugins/_job_scheduler/api/jobs
20+
```
21+
22+
## Query parameters
23+
24+
The following table lists the available query parameters. All query parameters are optional.
25+
26+
| Parameter | Data type | Description |
27+
| :--- | :--- | :--- |
28+
| `by_node` | Boolean | Returns the jobs grouped by the node on which they are running. Default is `false`. |
29+
30+
## Example request
31+
32+
```json
33+
GET /_plugins/_job_scheduler/api/jobs
34+
```
35+
{% include copy-curl.html %}
36+
37+
## Example response
38+
39+
```json
40+
{
41+
"jobs": [
42+
{
43+
"job_type": "reports-scheduler",
44+
"job_id": "Cuu8Z5gBTcOdmakPQ51t",
45+
"index_name": ".opendistro-reports-definitions",
46+
"name": "index_report",
47+
"descheduled": false,
48+
"enabled": true,
49+
"enabled_time": "2025-08-01T22:24:08.044Z",
50+
"last_update_time": "2025-08-01T22:24:08.044Z",
51+
"last_execution_time": "none",
52+
"last_expected_execution_time": "none",
53+
"next_expected_execution_time": "2025-08-04T02:15:00.000Z",
54+
"schedule": {
55+
"type": "cron",
56+
"expression": "15 2 1,15 * 1",
57+
"timezone": "Africa/Abidjan",
58+
"delay": "none"
59+
},
60+
"lock_duration": "no_lock",
61+
"jitter": "none"
62+
},
63+
{
64+
"job_type": "scheduler_sample_extension",
65+
"job_id": "jobid1",
66+
"index_name": ".scheduler_sample_extension",
67+
"name": "sample-job-it",
68+
"descheduled": false,
69+
"enabled": true,
70+
"enabled_time": "1970-07-23T00:27:45.353Z",
71+
"last_update_time": "1970-07-23T00:27:45.353Z",
72+
"last_execution_time": "2025-08-01T22:28:45.357484385Z",
73+
"last_expected_execution_time": "2025-08-01T22:28:45.353111804Z",
74+
"next_expected_execution_time": "2025-08-01T22:29:45.353111804Z",
75+
"schedule": {
76+
"type": "interval",
77+
"start_time": "1970-07-23T00:27:45.353Z",
78+
"interval": 1,
79+
"unit": "Minutes",
80+
"delay": "none"
81+
},
82+
"lock_duration": 10,
83+
"jitter": "none"
84+
}
85+
],
86+
"failures": [],
87+
"total_jobs": 2
88+
}
89+
```
90+
91+
## Response body fields
92+
93+
The following table lists all response body fields.
94+
95+
| Field | Data type | Description |
96+
| :--- | :--- | :--- |
97+
| `jobs` | Array | Contains all jobs reported by the Job Scheduler. |
98+
| `job_type` | String | The plugin that scheduled the job. |
99+
| `job_id` | String | The unique identifier of the job. |
100+
| `index_name` | String | The index in which the job information is stored. |
101+
| `name` | String | The job name. The name is not necessarily unique. |
102+
| `descheduled` | Boolean | Indicates whether the job is scheduled to be executed (`false`) or is not scheduled (`true`) by the Job Scheduler. |
103+
| `enabled` | Boolean | Indicates whether the job is active (`true`) or inactive (`false`), as defined by the plugin using the Job Scheduler. |
104+
| `enabled_time` | String | The time at which the job was originally scheduled. |
105+
| `last_update_time` | String | The time at which the job was last updated. |
106+
| `last_expected_exection_time` | String | The time at which the job was most recently executed. |
107+
| `next_expected_execution_time` | String | The time at which the job is expected to be executed next. |
108+
| `schedule` | Map | The job's execution schedule. Can define a [Cron](#cron-schedule) or [interval](#interval-schedule) schedule. |
109+
| `schedule.type` | String | The schedule type. Valid values are `cron` and `interval`. |
110+
| `lock_duration` | Integer | The maximum amount of time (in seconds) that a job can remain locked during execution.|
111+
| `jitter` | Double | A random delay applied to job execution times to prevent simultaneous runs across the system.|
112+
| `failures` | Array | A list of nodes that failed to report jobs. |
113+
| `total_jobs` | Integer | The total number of jobs reported across all nodes. |
114+
115+
### Interval schedule
116+
117+
The `interval` schedule supports the following fields.
118+
119+
| Field | Data type | Description |
120+
| :--- | :--- | :--- |
121+
| `start_time` | String | The schedule start time. |
122+
| `interval` | Integer | The numeric interval duration between job executions (for example, `10`). |
123+
| `unit` | String | The interval units (for example, `Minutes`, `Hours`, or `Days`). |
124+
| `delay` | String | A fixed amount of time applied to the job before execution. |
125+
126+
### Cron schedule
127+
128+
The `cron` schedule supports the following fields.
129+
130+
| Field | Data type | Description |
131+
| :--- | :--- | :--- |
132+
| `expression` | String | A Cron expression defining the schedule. |
133+
| `timezone` | String | The time zone associated with the Cron schedule. |

‎_monitoring-your-cluster/job-scheduler/locks.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
layout: default
3+
title: Locks API
4+
parent: Job Scheduler
5+
nav_order: 20
6+
redirect_from:
7+
- /monitoring-plugins/job-scheduler/api/
8+
---
9+
10+
# Job Scheduler Locks API
11+
Introduced 3.2
12+
{: .label .label-purple }
13+
14+
The Job Scheduler uses a distributed locking mechanism to ensure that only one instance of a job runs at a time across the cluster. The Locks API returns information about all active job locks managed by the Job Scheduler.
15+
16+
## Endpoints
17+
18+
```json
19+
GET /_plugins/_job_scheduler/api/locks
20+
GET /_plugins/_job_scheduler/api/locks/<lock_id>
21+
```
22+
23+
## Path parameters
24+
25+
The following table lists the available path parameters. All path parameters are optional.
26+
27+
| Parameter | Data type | Description |
28+
| :--- | :--- | :--- |
29+
| `<lock_id>` | String | A unique identifier for the lock, formatted as `"index"-"job_id"` (for example, `.scheduler_sample_extension-jobid1`). The index name and job ID must be separated by a hyphen (`-`).|
30+
31+
## Example request
32+
33+
```json
34+
GET /_plugins/_job_scheduler/api/locks
35+
```
36+
{% include copy-curl.html %}
37+
38+
## Example response
39+
40+
```json
41+
{
42+
"total_locks": 1,
43+
"locks": {
44+
".scheduler_sample_extension-jobid1": {
45+
"job_index_name": ".scheduler_sample_extension",
46+
"job_id": "jobid1",
47+
"lock_time": 1754410412,
48+
"lock_duration_seconds": 10,
49+
"released": false
50+
}
51+
}
52+
}
53+
```
54+
55+
## Response body fields
56+
57+
The following table lists all response body fields.
58+
59+
| Field | Data type | Description |
60+
| :--- | :--- | :--- |
61+
| `total_locks` | Integer | The total number of active and released locks. |
62+
| `locks` | Map | A map of lock IDs and their associated lock information. |
63+
| `job_index_name` | String | The name of the index in which the job is stored. |
64+
| `job_id` | String | The job ID. |
65+
| `lock_time` | Seconds since the epoch | The time at which the lock was acquired. |
66+
| `lock_duration_seconds` | Integer | The maximum amount of time for which the lock is valid. |
67+
| `released` | Boolean | Indicates whether the lock has been released (`true`) or is currently active (`false`). |

0 commit comments

Comments
 (0)