Skip to content
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.

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

[DOCS] Edit the Watcher summaries and descriptions #3345

Merged
merged 2 commits into from
Dec 18, 2024
Merged
Changes from 1 commit
Commits
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
Next Next commit
[DOCS] Edit Watcher summaries
  • Loading branch information
lcawl committed Dec 17, 2024
commit 9c915f4b33f69d6310e91d6fa008e0e49caefb0d
37 changes: 21 additions & 16 deletions docs/overlays/elasticsearch-shared-overlays.yaml
Original file line number Diff line number Diff line change
@@ -43,19 +43,19 @@ actions:
This API provides an alternative to relying solely on Kibana UI for connector and sync job management. The API comes with a set of validations and assertions to ensure that the state representation in the internal index remains valid.
externalDocs:
url: https://www.elastic.co/guide/en/elasticsearch/reference/master/es-connectors-tutorial-api.html
description: Connector API tutorial
description: Check out the connector API tutorial
- name: ccr
x-displayName: Cross-cluster replication
# D
- name: data stream
x-displayName: Data stream
externalDocs:
description: Data stream overview
description: Learn more about data streams.
url: https://www.elastic.co/guide/en/elasticsearch/reference/master/data-streams.html
- name: document
x-displayName: Document
externalDocs:
description: Reading and writing documents
description: Learn more about reading and writing documents.
url: https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-replication.html
# E
- name: enrich
@@ -66,14 +66,14 @@ actions:
Event Query Language (EQL) is a query language for event-based time series data, such as logs, metrics, and traces.
externalDocs:
url: https://www.elastic.co/guide/en/elasticsearch/reference/master/eql.html
description: EQL search
description: Learn more about EQL search.
- name: esql
x-displayName: ES|QL
description: >
The Elasticsearch Query Language (ES|QL) provides a powerful way to filter, transform, and analyze data stored in Elasticsearch, and in the future in other runtimes.
externalDocs:
url: https://www.elastic.co/guide/en/elasticsearch/reference/master/esql.html
description: ES|QL overview and tutorials
description: Learn more about ES|QL.
# F
- name: features
description: The feature APIs enable you to introspect and manage features provided by Elasticsearch and Elasticsearch plugins.
@@ -87,7 +87,7 @@ actions:
The graph explore API enables you to extract and summarize information about the documents and terms in an Elasticsearch data stream or index.
externalDocs:
url: https://www.elastic.co/guide/en/kibana/master/xpack-graph.html
description: Getting started with Graph
description: Get started with Graph.
# I
- name: indices
x-displayName: Index
@@ -97,7 +97,7 @@ actions:
x-displayName: Index lifecycle management
externalDocs:
url: https://www.elastic.co/guide/en/elasticsearch/reference/master/index-lifecycle-management.html
description: Manage the index lifecycle
description: Learn more about managing the index lifecycle.
- name: inference
x-displayName: Inference
description: >
@@ -115,14 +115,14 @@ actions:
description: Licensing APIs enable you to manage your licenses.
externalDocs:
url: https://www.elastic.co/subscriptions
description: For more information about the different types of licenses, refer to Elastic subscriptions
description: For more information about the different types of licenses, refer to Elastic subscriptions.
- name: logstash
x-displayName: Logstash
description: >
Logstash APIs enable you to manage pipelines that are used by Logstash Central Management.
externalDocs:
url: https://www.elastic.co/guide/en/logstash/master/logstash-centralized-pipeline-management.html
description: Centralized pipeline management
description: Learn more about centralized pipeline management.
# M
- name: ml
x-displayName: Machine learning
@@ -131,19 +131,19 @@ actions:
# description:
externalDocs:
url: https://www.elastic.co/guide/en/machine-learning/master/ml-ad-finding-anomalies.html
description: Finding anomalies
description: Learn more about finding anomalies.
- name: ml data frame
x-displayName: Machine learning data frame analytics
# description:
externalDocs:
url: https://www.elastic.co/guide/en/machine-learning/master/ml-dfa-overview.html
description: Data frame analytics overview
description: Learn more about data frame analytics.
- name: ml trained model
x-displayName: Machine learning trained model
# description:
externalDocs:
url: https://www.elastic.co/guide/en/machine-learning/master/ml-nlp-overview.html
description: Natural language processing overview
description: Learn more about natural language processing.
- name: migration
x-displayName: Migration
- name: monitoring
@@ -163,7 +163,7 @@ actions:
This allows pinning documents for only queries that match a specific term.
externalDocs:
url: https://www.elastic.co/guide/en/elasticsearch/reference/master/query-dsl-rule-query.html
description: Rule query
description: Learn more about the rule query.
# R
- name: rollup
x-displayName: Rollup
@@ -184,21 +184,21 @@ actions:
Snapshot and restore APIs enable you to set up snapshot repositories, manage snapshot backups, and restore snapshots to a running cluster.
externalDocs:
url: https://www.elastic.co/guide/en/elasticsearch/reference/master/snapshot-restore.html
description: Snapshot and restore
description: Learn more about snapshot and restore operations.
- name: slm
x-displayName: Snapshot lifecycle management
description: >
Snapshot lifecycle management (SLM) APIs enable you to set up policies to automatically take snapshots and control how long they are retained.
externalDocs:
url: https://www.elastic.co/guide/en/elasticsearch/reference/master/snapshots-take-snapshot.html
description: Create a snapshot
description: Learn more about creating a snapshot.
- name: sql
x-displayName: SQL
description: >
Elasticsearch's SQL APIs enable you to run SQL queries on Elasticsearch indices and data streams.
externalDocs:
url: https://www.elastic.co/guide/en/elasticsearch/reference/master/xpack-sql.html
description: An overview and tutorials for the Elasticsearch SQL features
description: Check out the overview and tutorials for the Elasticsearch SQL features.
- name: synonyms
x-displayName: Synonyms
description: >
@@ -218,6 +218,11 @@ actions:
# W
- name: watcher
x-displayName: Watcher
description: >
You can use Watcher to watch for changes or anomalies in your data and perform the necessary actions in response.
externalDocs:
url: https://www.elastic.co/guide/en/elasticsearch/reference/master/xpack-alerting.html
description: Learn more about Watcher.
# Add x-model and/or abbreviate schemas that should point to other references
- target: "$.components['schemas']['_types.query_dsl:QueryContainer']"
description: Add x-model for the QueryContainer object
1 change: 1 addition & 0 deletions specification/_doc_ids/table.csv
Original file line number Diff line number Diff line change
@@ -646,6 +646,7 @@ user-agent-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{br
user-profile,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/user-profile.html
verify-repository,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-register-repository.html#snapshots-repository-verification
voting-config-exclusions,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/voting-config-exclusions.html
watcher-works,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/how-watcher-works.html
watcher-api-ack-watch,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-ack-watch.html
watcher-api-activate-watch,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-activate-watch.html
watcher-api-deactivate-watch,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-deactivate-watch.html
8 changes: 8 additions & 0 deletions specification/watcher/ack_watch/WatcherAckWatchRequest.ts
Original file line number Diff line number Diff line change
@@ -21,8 +21,16 @@ import { RequestBase } from '@_types/Base'
import { Name, Names } from '@_types/common'

/**
* Acknowledge a watch.
* Acknowledging a watch enables you to manually throttle the execution of the watch's actions.
*
* The acknowledgement state of an action is stored in the `status.actions.<id>.ack.state` structure.
*
* IMPORTANT: If the specified watch is currently being executed, this API will return an error
* The reason for this behavior is to prevent overwriting the watch status from a watch execution.
* @rest_spec_name watcher.ack_watch
* @availability stack stability=stable
* @cluster_privileges manage_watcher
*/
export interface Request extends RequestBase {
path_parts: {
Original file line number Diff line number Diff line change
@@ -21,8 +21,12 @@ import { RequestBase } from '@_types/Base'
import { Name } from '@_types/common'

/**
* Activate a watch.
* A watch can be either active or inactive.
* @rest_spec_name watcher.activate_watch
* @availability stack stability=stable
* @cluster_privileges manage_watcher
* @ext_doc_id watcher-works
*/
export interface Request extends RequestBase {
path_parts: {
Original file line number Diff line number Diff line change
@@ -21,8 +21,12 @@ import { RequestBase } from '@_types/Base'
import { Name } from '@_types/common'

/**
* Deactivate a watch.
* A watch can be either active or inactive.
* @rest_spec_name watcher.deactivate_watch
* @availability stack stability=stable
* @cluster_privileges manage_watcher
* @ext_doc_id watcher-works
*/
export interface Request extends RequestBase {
path_parts: {
9 changes: 9 additions & 0 deletions specification/watcher/delete_watch/DeleteWatchRequest.ts
Original file line number Diff line number Diff line change
@@ -21,8 +21,17 @@ import { RequestBase } from '@_types/Base'
import { Name } from '@_types/common'

/**
* Delete a watch.
* When the watch is removed, the document representing the watch in the `.watches` index is gone and it will never be run again.
*
* Deleting a watch does not delete any watch execution records related to this watch from the watch history.
*
* IMPORTANT: Deleting a watch must be done by using only this API.
* Do not delete the watch directly from the `.watches` index using the Elasticsearch delete document API
* When Elasticsearch security features are enabled, make sure no write privileges are granted to anyone for the `.watches` index.
* @rest_spec_name watcher.delete_watch
* @availability stack stability=stable
* @cluster_privileges manage_watcher
*/
export interface Request extends RequestBase {
path_parts: {
Original file line number Diff line number Diff line change
@@ -26,8 +26,15 @@ import { RequestBase } from '@_types/Base'
import { Id } from '@_types/common'

/**
* Run a watch.
* This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.
* For testing and debugging purposes, you also have fine-grained control on how the watch runs. You can execute the watch without executing all of its actions or alternatively by simulating them. You can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after execution.
*
* For testing and debugging purposes, you also have fine-grained control on how the watch runs.
* You can run the watch without running all of its actions or alternatively by simulating them.
* You can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.
*
* You can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.
* This serves as great tool for testing and debugging your watches prior to adding them to Watcher.
* @rest_spec_name watcher.execute_watch
* @availability stack stability=stable
* @cluster_privileges manage_watcher
2 changes: 2 additions & 0 deletions specification/watcher/get_watch/GetWatchRequest.ts
Original file line number Diff line number Diff line change
@@ -21,8 +21,10 @@ import { RequestBase } from '@_types/Base'
import { Name } from '@_types/common'

/**
* Get a watch.
* @rest_spec_name watcher.get_watch
* @availability stack since=5.6.0 stability=stable
* @cluster_privileges monitor_watcher
*/
export interface Request extends RequestBase {
path_parts: {
13 changes: 13 additions & 0 deletions specification/watcher/put_watch/WatcherPutWatchRequest.ts
Original file line number Diff line number Diff line change
@@ -28,8 +28,21 @@ import { long } from '@_types/Numeric'
import { TransformContainer } from '@_types/Transform'

/**
* Create or update a watch.
* When a watch is registered, a new document that represents the watch is added to the `.watches` index and its trigger is immediately registered with the relevant trigger engine.
* Typically for the `schedule` trigger, the scheduler is the trigger engine.
*
* IMPORTANT: You must use Kibana or this API to create a watch.
* Do not add a watch directly to the `.watches` index by using the Elasticsearch index API.
* If Elasticsearch security features are enabled, do not give users write privileges on the `.watches` index.
*
* When you add a watch you can also define its initial active state by setting the *active* parameter.
*
* When Elasticsearch security features are enabled, your watch can index or search only on indices for which the user that stored the watch has privileges.
* If the user is able to read index `a`, but not index `b`, the same will apply when the watch runs.
* @rest_spec_name watcher.put_watch
* @availability stack stability=stable
* @cluster_privileges manage_watcher
*/
export interface Request extends RequestBase {
path_parts: {
Original file line number Diff line number Diff line change
@@ -23,8 +23,11 @@ import { QueryContainer } from '@_types/query_dsl/abstractions'
import { Sort, SortResults } from '@_types/sort'

/**
* Query watches.
* Get all registered watches in a paginated manner and optionally filter watches by a query.
* @rest_spec_name watcher.query_watches
* @availability stack since=7.11.0 stability=stable
* @cluster_privileges monitor_watcher
*/
export interface Request extends RequestBase {
body: {
3 changes: 3 additions & 0 deletions specification/watcher/start/WatcherStartRequest.ts
Original file line number Diff line number Diff line change
@@ -20,7 +20,10 @@
import { RequestBase } from '@_types/Base'

/**
* Start the watch service.
* Start the Watcher service if it is not already running.
* @rest_spec_name watcher.start
* @availability stack stability=stable
* @cluster_privileges manage_watcher
*/
export interface Request extends RequestBase {}
2 changes: 2 additions & 0 deletions specification/watcher/stats/WatcherStatsRequest.ts
Original file line number Diff line number Diff line change
@@ -21,8 +21,10 @@ import { RequestBase } from '@_types/Base'
import { WatcherMetric } from './types'

/**
* Get Watcher statistics.
* @rest_spec_name watcher.stats
* @availability stack since=5.5.0 stability=stable
* @cluster_privileges monitor_watcher
*/
export interface Request extends RequestBase {
path_parts: {
3 changes: 3 additions & 0 deletions specification/watcher/stop/WatcherStopRequest.ts
Original file line number Diff line number Diff line change
@@ -20,7 +20,10 @@
import { RequestBase } from '@_types/Base'

/**
* Stop the watch service.
* Stop the Watcher service if it is running.
* @rest_spec_name watcher.stop
* @availability stack stability=stable
* @cluster_privileges manage_watcher
*/
export interface Request extends RequestBase {}