From 81446e90fe8c3cbb886867fbf6c21e509cd4e472 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Tue, 17 Dec 2024 16:23:30 -0800 Subject: [PATCH] [DOCS] Edit task manager summaries (#3343) (#3351) (cherry picked from commit 2426d4ef41869354cb5ab9d3817f6ac604ea0393) --- output/openapi/elasticsearch-openapi.json | 64 ++++++++++++++++--- .../elasticsearch-serverless-openapi.json | 49 +++++++++++++- output/schema/schema.json | 26 ++++---- specification/tasks/_types/TaskInfo.ts | 13 +++- .../tasks/cancel/CancelTasksRequest.ts | 8 +++ specification/tasks/get/GetTaskRequest.ts | 2 +- specification/tasks/list/ListTasksRequest.ts | 6 +- 7 files changed, 141 insertions(+), 27 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 55a50a9353..80065340a3 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -689,6 +689,9 @@ "description": "Performs multiple indexing or delete operations in a single API call.\nThis reduces overhead and can greatly increase indexing speed.", "operationId": "bulk-1", "parameters": [ + { + "$ref": "#/components/parameters/bulk#list_executed_pipelines" + }, { "$ref": "#/components/parameters/bulk#pipeline" }, @@ -715,6 +718,9 @@ }, { "$ref": "#/components/parameters/bulk#require_alias" + }, + { + "$ref": "#/components/parameters/bulk#require_data_stream" } ], "requestBody": { @@ -734,6 +740,9 @@ "description": "Performs multiple indexing or delete operations in a single API call.\nThis reduces overhead and can greatly increase indexing speed.", "operationId": "bulk", "parameters": [ + { + "$ref": "#/components/parameters/bulk#list_executed_pipelines" + }, { "$ref": "#/components/parameters/bulk#pipeline" }, @@ -760,6 +769,9 @@ }, { "$ref": "#/components/parameters/bulk#require_alias" + }, + { + "$ref": "#/components/parameters/bulk#require_data_stream" } ], "requestBody": { @@ -784,6 +796,9 @@ { "$ref": "#/components/parameters/bulk#index" }, + { + "$ref": "#/components/parameters/bulk#list_executed_pipelines" + }, { "$ref": "#/components/parameters/bulk#pipeline" }, @@ -810,6 +825,9 @@ }, { "$ref": "#/components/parameters/bulk#require_alias" + }, + { + "$ref": "#/components/parameters/bulk#require_data_stream" } ], "requestBody": { @@ -832,6 +850,9 @@ { "$ref": "#/components/parameters/bulk#index" }, + { + "$ref": "#/components/parameters/bulk#list_executed_pipelines" + }, { "$ref": "#/components/parameters/bulk#pipeline" }, @@ -858,6 +879,9 @@ }, { "$ref": "#/components/parameters/bulk#require_alias" + }, + { + "$ref": "#/components/parameters/bulk#require_data_stream" } ], "requestBody": { @@ -25155,7 +25179,7 @@ "rollup" ], "summary": "Create a rollup job", - "description": "WARNING: From 8.15.0, calling this API in a cluster with no rollup usage will fail with a message about the deprecation and planned removal of rollup features. A cluster either needs to contain a rollup job or a rollup index in order for this API to be allowed to run.\n\nThe rollup job configuration contains all the details about how the job should run, when it indexes documents, and what future queries will be able to run against the rollup index.\n\nThere are three main sections to the job configuration: the logistical details about the job (for example, the cron schedule), the fields that are used for grouping, and what metrics to collect for each group.\n\nJobs are created in a `STOPPED` state. You can start them with the start rollup jobs API.", + "description": "WARNING: From 8.15.0, calling this API in a cluster with no rollup usage will fail with a message about the deprecation and planned removal of rollup features. A cluster needs to contain either a rollup job or a rollup index in order for this API to be allowed to run.\n\nThe rollup job configuration contains all the details about how the job should run, when it indexes documents, and what future queries will be able to run against the rollup index.\n\nThere are three main sections to the job configuration: the logistical details about the job (for example, the cron schedule), the fields that are used for grouping, and what metrics to collect for each group.\n\nJobs are created in a `STOPPED` state. You can start them with the start rollup jobs API.", "operationId": "rollup-put-job", "parameters": [ { @@ -25239,7 +25263,7 @@ "rollup" ], "summary": "Delete a rollup job", - "description": "A job must be stopped first before it can be deleted.\nIf you attempt to delete a started job, an error occurs.\nSimilarly, if you attempt to delete a nonexistent job, an exception occurs.\n\nIMPORTANT: When you delete a job, you remove only the process that is actively monitoring and rolling up data.\nThe API does not delete any previously rolled up data.\nThis is by design; a user may wish to roll up a static data set.\nBecause the data set is static, after it has been fully rolled up there is no need to keep the indexing rollup job around (as there will be no new data).\nThus the job can be deleted, leaving behind the rolled up data for analysis.\nIf you wish to also remove the rollup data and the rollup index contains the data for only a single job, you can delete the whole rollup index.\nIf the rollup index stores data from several jobs, you must issue a delete-by-query that targets the rollup job's identifier in the rollup index. For example:\n\n```\nPOST my_rollup_index/_delete_by_query\n{\n \"query\": {\n \"term\": {\n \"_rollup.id\": \"the_rollup_job_id\"\n }\n }\n}\n```", + "description": "A job must be stopped before it can be deleted.\nIf you attempt to delete a started job, an error occurs.\nSimilarly, if you attempt to delete a nonexistent job, an exception occurs.\n\nIMPORTANT: When you delete a job, you remove only the process that is actively monitoring and rolling up data.\nThe API does not delete any previously rolled up data.\nThis is by design; a user may wish to roll up a static data set.\nBecause the data set is static, after it has been fully rolled up there is no need to keep the indexing rollup job around (as there will be no new data).\nThus the job can be deleted, leaving behind the rolled up data for analysis.\nIf you wish to also remove the rollup data and the rollup index contains the data for only a single job, you can delete the whole rollup index.\nIf the rollup index stores data from several jobs, you must issue a delete-by-query that targets the rollup job's identifier in the rollup index. For example:\n\n```\nPOST my_rollup_index/_delete_by_query\n{\n \"query\": {\n \"term\": {\n \"_rollup.id\": \"the_rollup_job_id\"\n }\n }\n}\n```", "operationId": "rollup-delete-job", "parameters": [ { @@ -33246,7 +33270,8 @@ "tags": [ "tasks" ], - "summary": "Cancels a task, if it can be cancelled through an API", + "summary": "Cancel a task", + "description": "A task may continue to run for some time after it has been cancelled because it may not be able to safely stop its current activity straight away.\nIt is also possible that Elasticsearch must complete its work on other tasks before it can process the cancellation.\nThe get task information API will continue to list these cancelled tasks until they complete.\nThe cancelled flag in the response indicates that the cancellation command has been processed and the task will stop as soon as possible.\n\nTo troubleshoot why a cancelled task does not complete promptly, use the get task information API with the `?detailed` parameter to identify the other tasks the system is running.\nYou can also use the node hot threads API to obtain detailed information about the work the system is doing instead of completing the cancelled task.", "operationId": "tasks-cancel", "parameters": [ { @@ -33275,7 +33300,8 @@ "tags": [ "tasks" ], - "summary": "Cancels a task, if it can be cancelled through an API", + "summary": "Cancel a task", + "description": "A task may continue to run for some time after it has been cancelled because it may not be able to safely stop its current activity straight away.\nIt is also possible that Elasticsearch must complete its work on other tasks before it can process the cancellation.\nThe get task information API will continue to list these cancelled tasks until they complete.\nThe cancelled flag in the response indicates that the cancellation command has been processed and the task will stop as soon as possible.\n\nTo troubleshoot why a cancelled task does not complete promptly, use the get task information API with the `?detailed` parameter to identify the other tasks the system is running.\nYou can also use the node hot threads API to obtain detailed information about the work the system is doing instead of completing the cancelled task.", "operationId": "tasks-cancel-1", "parameters": [ { @@ -33308,7 +33334,7 @@ "tasks" ], "summary": "Get task information", - "description": "Returns information about the tasks currently executing in the cluster.", + "description": "Get information about a task currently running in the cluster.", "operationId": "tasks-get", "parameters": [ { @@ -33381,7 +33407,8 @@ "tags": [ "tasks" ], - "summary": "The task management API returns information about tasks currently executing on one or more nodes in the cluster", + "summary": "Get all tasks", + "description": "Get information about the tasks currently running on one or more nodes in the cluster.", "operationId": "tasks-list", "parameters": [ { @@ -33407,7 +33434,7 @@ { "in": "query", "name": "detailed", - "description": "If `true`, the response includes detailed information about shard recoveries.", + "description": "If `true`, the response includes detailed information about shard recoveries.\nThis information is useful to distinguish tasks from each other but is more costly to run.", "deprecated": false, "schema": { "type": "boolean" @@ -65065,6 +65092,7 @@ "type": "boolean" }, "description": { + "description": "Human readable text that identifies the particular request that the task is performing.\nFor example, it might identify the search request being performed by a search task.\nOther kinds of tasks have different descriptions, like `_reindex` which has the source and the destination, or `_bulk` which just has the number of requests and the destination indices.\nMany requests will have only an empty description because more detailed information about the request is not easily available or particularly helpful in identifying the request.", "type": "string" }, "headers": { @@ -65089,7 +65117,7 @@ "$ref": "#/components/schemas/_types:EpochTimeUnitMillis" }, "status": { - "description": "Task status information can vary wildly from task to task.", + "description": "The internal status of the task, which varies from task to task.\nThe format also varies.\nWhile the goal is to keep the status for a particular task consistent from version to version, this is not always possible because sometimes the implementation changes.\nFields might be removed from the status for a particular request so any parsing you do of the status might break in minor releases.", "type": "object" }, "type": { @@ -93641,6 +93669,16 @@ }, "style": "simple" }, + "bulk#list_executed_pipelines": { + "in": "query", + "name": "list_executed_pipelines", + "description": "If `true`, the response will include the ingest pipelines that were executed for each index or create.", + "deprecated": false, + "schema": { + "type": "boolean" + }, + "style": "form" + }, "bulk#pipeline": { "in": "query", "name": "pipeline", @@ -93731,6 +93769,16 @@ }, "style": "form" }, + "bulk#require_data_stream": { + "in": "query", + "name": "require_data_stream", + "description": "If `true`, the request's actions must target a data stream (existing or to-be-created).", + "deprecated": false, + "schema": { + "type": "boolean" + }, + "style": "form" + }, "cat.aliases#name": { "in": "path", "name": "name", diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json index ce9b4f2d51..82aa7f60e4 100644 --- a/output/openapi/elasticsearch-serverless-openapi.json +++ b/output/openapi/elasticsearch-serverless-openapi.json @@ -467,6 +467,9 @@ "description": "Performs multiple indexing or delete operations in a single API call.\nThis reduces overhead and can greatly increase indexing speed.", "operationId": "bulk-1", "parameters": [ + { + "$ref": "#/components/parameters/bulk#list_executed_pipelines" + }, { "$ref": "#/components/parameters/bulk#pipeline" }, @@ -493,6 +496,9 @@ }, { "$ref": "#/components/parameters/bulk#require_alias" + }, + { + "$ref": "#/components/parameters/bulk#require_data_stream" } ], "requestBody": { @@ -512,6 +518,9 @@ "description": "Performs multiple indexing or delete operations in a single API call.\nThis reduces overhead and can greatly increase indexing speed.", "operationId": "bulk", "parameters": [ + { + "$ref": "#/components/parameters/bulk#list_executed_pipelines" + }, { "$ref": "#/components/parameters/bulk#pipeline" }, @@ -538,6 +547,9 @@ }, { "$ref": "#/components/parameters/bulk#require_alias" + }, + { + "$ref": "#/components/parameters/bulk#require_data_stream" } ], "requestBody": { @@ -562,6 +574,9 @@ { "$ref": "#/components/parameters/bulk#index" }, + { + "$ref": "#/components/parameters/bulk#list_executed_pipelines" + }, { "$ref": "#/components/parameters/bulk#pipeline" }, @@ -588,6 +603,9 @@ }, { "$ref": "#/components/parameters/bulk#require_alias" + }, + { + "$ref": "#/components/parameters/bulk#require_data_stream" } ], "requestBody": { @@ -610,6 +628,9 @@ { "$ref": "#/components/parameters/bulk#index" }, + { + "$ref": "#/components/parameters/bulk#list_executed_pipelines" + }, { "$ref": "#/components/parameters/bulk#pipeline" }, @@ -636,6 +657,9 @@ }, { "$ref": "#/components/parameters/bulk#require_alias" + }, + { + "$ref": "#/components/parameters/bulk#require_data_stream" } ], "requestBody": { @@ -18343,7 +18367,7 @@ "tasks" ], "summary": "Get task information", - "description": "Returns information about the tasks currently executing in the cluster.", + "description": "Get information about a task currently running in the cluster.", "operationId": "tasks-get", "parameters": [ { @@ -44319,6 +44343,7 @@ "type": "boolean" }, "description": { + "description": "Human readable text that identifies the particular request that the task is performing.\nFor example, it might identify the search request being performed by a search task.\nOther kinds of tasks have different descriptions, like `_reindex` which has the source and the destination, or `_bulk` which just has the number of requests and the destination indices.\nMany requests will have only an empty description because more detailed information about the request is not easily available or particularly helpful in identifying the request.", "type": "string" }, "headers": { @@ -44343,7 +44368,7 @@ "$ref": "#/components/schemas/_types:EpochTimeUnitMillis" }, "status": { - "description": "Task status information can vary wildly from task to task.", + "description": "The internal status of the task, which varies from task to task.\nThe format also varies.\nWhile the goal is to keep the status for a particular task consistent from version to version, this is not always possible because sometimes the implementation changes.\nFields might be removed from the status for a particular request so any parsing you do of the status might break in minor releases.", "type": "object" }, "type": { @@ -57676,6 +57701,16 @@ }, "style": "simple" }, + "bulk#list_executed_pipelines": { + "in": "query", + "name": "list_executed_pipelines", + "description": "If `true`, the response will include the ingest pipelines that were executed for each index or create.", + "deprecated": false, + "schema": { + "type": "boolean" + }, + "style": "form" + }, "bulk#pipeline": { "in": "query", "name": "pipeline", @@ -57766,6 +57801,16 @@ }, "style": "form" }, + "bulk#require_data_stream": { + "in": "query", + "name": "require_data_stream", + "description": "If `true`, the request's actions must target a data stream (existing or to-be-created).", + "deprecated": false, + "schema": { + "type": "boolean" + }, + "style": "form" + }, "cat.aliases#name": { "in": "path", "name": "name", diff --git a/output/schema/schema.json b/output/schema/schema.json index 04ce00cee7..1dbfb5b1c0 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -19347,7 +19347,7 @@ "stability": "experimental" } }, - "description": "Cancels a task, if it can be cancelled through an API.", + "description": "Cancel a task.\nA task may continue to run for some time after it has been cancelled because it may not be able to safely stop its current activity straight away.\nIt is also possible that Elasticsearch must complete its work on other tasks before it can process the cancellation.\nThe get task information API will continue to list these cancelled tasks until they complete.\nThe cancelled flag in the response indicates that the cancellation command has been processed and the task will stop as soon as possible.\n\nTo troubleshoot why a cancelled task does not complete promptly, use the get task information API with the `?detailed` parameter to identify the other tasks the system is running.\nYou can also use the node hot threads API to obtain detailed information about the work the system is doing instead of completing the cancelled task.", "docId": "tasks", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/tasks.html", "name": "tasks.cancel", @@ -19389,7 +19389,7 @@ "stability": "experimental" } }, - "description": "Get task information.\nReturns information about the tasks currently executing in the cluster.", + "description": "Get task information.\nGet information about a task currently running in the cluster.", "docId": "tasks", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/tasks.html", "name": "tasks.get", @@ -19425,14 +19425,13 @@ "stability": "experimental" } }, - "description": "The task management API returns information about tasks currently executing on one or more nodes in the cluster.", + "description": "Get all tasks.\nGet information about the tasks currently running on one or more nodes in the cluster.", "docId": "tasks", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/tasks.html", "name": "tasks.list", "privileges": { "cluster": [ - "monitor", - "manage" + "monitor" ] }, "request": { @@ -207368,6 +207367,7 @@ } }, { + "description": "Human readable text that identifies the particular request that the task is performing.\nFor example, it might identify the search request being performed by a search task.\nOther kinds of tasks have different descriptions, like `_reindex` which has the source and the destination, or `_bulk` which just has the number of requests and the destination indices.\nMany requests will have only an empty description because more detailed information about the request is not easily available or particularly helpful in identifying the request.", "name": "description", "required": false, "type": { @@ -207474,7 +207474,7 @@ } }, { - "description": "Task status information can vary wildly from task to task.", + "description": "The internal status of the task, which varies from task to task.\nThe format also varies.\nWhile the goal is to keep the status for a particular task consistent from version to version, this is not always possible because sometimes the implementation changes.\nFields might be removed from the status for a particular request so any parsing you do of the status might break in minor releases.", "name": "status", "required": false, "type": { @@ -207504,7 +207504,7 @@ } } ], - "specLocation": "tasks/_types/TaskInfo.ts#L32-L47" + "specLocation": "tasks/_types/TaskInfo.ts#L32-L58" }, { "kind": "type_alias", @@ -207632,7 +207632,7 @@ "body": { "kind": "no_body" }, - "description": "Cancels a task, if it can be cancelled through an API.", + "description": "Cancel a task.\nA task may continue to run for some time after it has been cancelled because it may not be able to safely stop its current activity straight away.\nIt is also possible that Elasticsearch must complete its work on other tasks before it can process the cancellation.\nThe get task information API will continue to list these cancelled tasks until they complete.\nThe cancelled flag in the response indicates that the cancellation command has been processed and the task will stop as soon as possible.\n\nTo troubleshoot why a cancelled task does not complete promptly, use the get task information API with the `?detailed` parameter to identify the other tasks the system is running.\nYou can also use the node hot threads API to obtain detailed information about the work the system is doing instead of completing the cancelled task.", "inherits": { "type": { "name": "RequestBase", @@ -207725,7 +207725,7 @@ } } ], - "specLocation": "tasks/cancel/CancelTasksRequest.ts#L23-L51" + "specLocation": "tasks/cancel/CancelTasksRequest.ts#L23-L59" }, { "kind": "response", @@ -207753,7 +207753,7 @@ "body": { "kind": "no_body" }, - "description": "Get task information.\nReturns information about the tasks currently executing in the cluster.", + "description": "Get task information.\nGet information about a task currently running in the cluster.", "inherits": { "type": { "name": "RequestBase", @@ -207869,7 +207869,7 @@ "body": { "kind": "no_body" }, - "description": "The task management API returns information about tasks currently executing on one or more nodes in the cluster.", + "description": "Get all tasks.\nGet information about the tasks currently running on one or more nodes in the cluster.", "inherits": { "type": { "name": "RequestBase", @@ -207910,7 +207910,7 @@ } }, { - "description": "If `true`, the response includes detailed information about shard recoveries.", + "description": "If `true`, the response includes detailed information about shard recoveries.\nThis information is useful to distinguish tasks from each other but is more costly to run.", "name": "detailed", "required": false, "serverDefault": false, @@ -207998,7 +207998,7 @@ } } ], - "specLocation": "tasks/list/ListTasksRequest.ts#L25-L72" + "specLocation": "tasks/list/ListTasksRequest.ts#L25-L74" }, { "kind": "response", diff --git a/specification/tasks/_types/TaskInfo.ts b/specification/tasks/_types/TaskInfo.ts index 5752ad6c06..d404bfcdb2 100644 --- a/specification/tasks/_types/TaskInfo.ts +++ b/specification/tasks/_types/TaskInfo.ts @@ -33,6 +33,12 @@ export class TaskInfo { action: string cancelled?: boolean cancellable: boolean + /** + * Human readable text that identifies the particular request that the task is performing. + * For example, it might identify the search request being performed by a search task. + * Other kinds of tasks have different descriptions, like `_reindex` which has the source and the destination, or `_bulk` which just has the number of requests and the destination indices. + * Many requests will have only an empty description because more detailed information about the request is not easily available or particularly helpful in identifying the request. + */ description?: string headers: Dictionary id: long @@ -40,7 +46,12 @@ export class TaskInfo { running_time?: Duration running_time_in_nanos: DurationValue start_time_in_millis: EpochTime - /** Task status information can vary wildly from task to task. */ + /** + * The internal status of the task, which varies from task to task. + * The format also varies. + * While the goal is to keep the status for a particular task consistent from version to version, this is not always possible because sometimes the implementation changes. + * Fields might be removed from the status for a particular request so any parsing you do of the status might break in minor releases. + */ status?: UserDefinedValue type: string parent_task_id?: TaskId diff --git a/specification/tasks/cancel/CancelTasksRequest.ts b/specification/tasks/cancel/CancelTasksRequest.ts index 4fe3a7ad18..79fce38634 100644 --- a/specification/tasks/cancel/CancelTasksRequest.ts +++ b/specification/tasks/cancel/CancelTasksRequest.ts @@ -21,6 +21,14 @@ import { RequestBase } from '@_types/Base' import { TaskId } from '@_types/common' /** + * Cancel a task. + * A task may continue to run for some time after it has been cancelled because it may not be able to safely stop its current activity straight away. + * It is also possible that Elasticsearch must complete its work on other tasks before it can process the cancellation. + * The get task information API will continue to list these cancelled tasks until they complete. + * The cancelled flag in the response indicates that the cancellation command has been processed and the task will stop as soon as possible. + * + * To troubleshoot why a cancelled task does not complete promptly, use the get task information API with the `?detailed` parameter to identify the other tasks the system is running. + * You can also use the node hot threads API to obtain detailed information about the work the system is doing instead of completing the cancelled task. * @rest_spec_name tasks.cancel * @availability stack since=2.3.0 stability=experimental * @availability serverless stability=experimental visibility=private diff --git a/specification/tasks/get/GetTaskRequest.ts b/specification/tasks/get/GetTaskRequest.ts index 6126a7746b..f6b1f9f6da 100644 --- a/specification/tasks/get/GetTaskRequest.ts +++ b/specification/tasks/get/GetTaskRequest.ts @@ -23,7 +23,7 @@ import { Duration } from '@_types/Time' /** * Get task information. - * Returns information about the tasks currently executing in the cluster. + * Get information about a task currently running in the cluster. * @rest_spec_name tasks.get * @availability stack since=5.0.0 stability=experimental * @availability serverless stability=experimental visibility=public diff --git a/specification/tasks/list/ListTasksRequest.ts b/specification/tasks/list/ListTasksRequest.ts index 00ba85ef35..63fb774595 100644 --- a/specification/tasks/list/ListTasksRequest.ts +++ b/specification/tasks/list/ListTasksRequest.ts @@ -23,11 +23,12 @@ import { Id, NodeIds } from '@_types/common' import { Duration } from '@_types/Time' /** - * The task management API returns information about tasks currently executing on one or more nodes in the cluster. + * Get all tasks. + * Get information about the tasks currently running on one or more nodes in the cluster. * @rest_spec_name tasks.list * @availability stack since=2.3.0 stability=experimental * @availability serverless stability=experimental visibility=private - * @cluster_privileges monitor, manage + * @cluster_privileges monitor * @doc_id tasks */ export interface Request extends RequestBase { @@ -38,6 +39,7 @@ export interface Request extends RequestBase { actions?: string | string[] /** * If `true`, the response includes detailed information about shard recoveries. + * This information is useful to distinguish tasks from each other but is more costly to run. * @server_default false */ detailed?: boolean