From 62d7b5e476740dd1e2340dedd7b1959b13c6a39f Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Tue, 17 Dec 2024 16:16:50 -0800 Subject: [PATCH] [DOCS] Edit task manager summaries (#3343) (cherry picked from commit 2426d4ef41869354cb5ab9d3817f6ac604ea0393) --- output/openapi/elasticsearch-openapi.json | 16 +++++++----- .../elasticsearch-serverless-openapi.json | 5 ++-- 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, 51 insertions(+), 25 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 86d89e524d..d966a9fd38 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -33185,7 +33185,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": [ { @@ -33214,7 +33215,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": [ { @@ -33247,7 +33249,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": [ { @@ -33320,7 +33322,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": [ { @@ -33346,7 +33349,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" @@ -64994,6 +64997,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": { @@ -65018,7 +65022,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": { diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json index 8c20e86693..8c530e344a 100644 --- a/output/openapi/elasticsearch-serverless-openapi.json +++ b/output/openapi/elasticsearch-serverless-openapi.json @@ -18349,7 +18349,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": [ { @@ -44325,6 +44325,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": { @@ -44349,7 +44350,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": { diff --git a/output/schema/schema.json b/output/schema/schema.json index 361f055ed1..7a837fcec3 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -19136,7 +19136,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", @@ -19178,7 +19178,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", @@ -19214,14 +19214,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": { @@ -207152,6 +207151,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": { @@ -207258,7 +207258,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": { @@ -207288,7 +207288,7 @@ } } ], - "specLocation": "tasks/_types/TaskInfo.ts#L32-L47" + "specLocation": "tasks/_types/TaskInfo.ts#L32-L58" }, { "kind": "type_alias", @@ -207416,7 +207416,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", @@ -207509,7 +207509,7 @@ } } ], - "specLocation": "tasks/cancel/CancelTasksRequest.ts#L23-L51" + "specLocation": "tasks/cancel/CancelTasksRequest.ts#L23-L59" }, { "kind": "response", @@ -207537,7 +207537,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", @@ -207653,7 +207653,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", @@ -207694,7 +207694,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, @@ -207782,7 +207782,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