mirror of
https://github.com/elastic/kibana.git
synced 2025-04-24 01:38:56 -04:00
[docs] Migrate docs from AsciiDoc to Markdown (#212558)
Migrate docs from AsciiDoc to Markdown. The preview can be built after #212557 is merged. @florent-leborgne please tag reviewers, add the appropriate label(s), and take this out of draft when you're ready. Note: More files are deleted than added here because the content from some files was moved to [elastic/docs-content](https://github.com/elastic/docs-content). **What has moved to [elastic/docs-content](https://github.com/elastic/docs-content)?** Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: - explore-analyze: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools... - deploy-manage: Stack management (Spaces, user management, remote clusters...) - troubleshooting: .... troubleshooting pages **What is staying in the Kibana repo?** - Reference content (= anything that is or could be auto-generated): Settings, syntax references - Release notes - Developer guide --------- Co-authored-by: Florent Le Borgne <florent.leborgne@elastic.co>
This commit is contained in:
Colleen McGinnis
GitHub
parent
b43558db48
commit
1814c60017
1449 changed files with 24161 additions and 65559 deletions
|
|
@ -1,65 +0,0 @@
|
|||
[chapter]
|
||||
[[accessibility]]
|
||||
= Accessibility Statement for Kibana
|
||||
++++
|
||||
<titleabbrev>Accessibility</titleabbrev>
|
||||
++++
|
||||
|
||||
Elastic is committed to ensuring digital accessibility for people with disabilities. We are continually improving the user experience, and strive toward ensuring our tools are usable by everyone.
|
||||
|
||||
[float]
|
||||
[[accessibility-measures]]
|
||||
== Measures to support accessibility
|
||||
Elastic takes the following measures to ensure accessibility of Kibana:
|
||||
|
||||
* Maintains and incorporates an https://elastic.github.io/eui/[accessible component library].
|
||||
* Provides continual accessibility training for our staff.
|
||||
* Employs a third-party audit.
|
||||
|
||||
[float]
|
||||
[[accessibility-conformance-status]]
|
||||
== Conformance status
|
||||
Kibana aims to meet https://www.w3.org/WAI/WCAG21/quickref/?currentsidebar=%23col_customize&levels=aaa&technologies=server%2Csmil%2Cflash%2Csl[WCAG 2.1 level AA] compliance. Currently, we can only claim to partially conform, meaning we do not fully meet all of the success criteria. However, we do try to take a broader view of accessibility, and go above and beyond the legal and regulatory standards to provide a good experience for all of our users.
|
||||
|
||||
[float]
|
||||
[[accessibility-feedback]]
|
||||
== Feedback
|
||||
We welcome your feedback on the accessibility of Kibana. Please let us know if you encounter accessibility barriers on Kibana by either emailing us at accessibility@elastic.co or opening https://github.com/elastic/kibana/issues/new?labels=Project%3AAccessibility&template=Accessibility.md&title=%28Accessibility%29[an issue on GitHub].
|
||||
|
||||
[float]
|
||||
[[accessibility-specs]]
|
||||
== Technical specifications
|
||||
Accessibility of Kibana relies on the following technologies to work with your web browser and any assistive technologies or plugins installed on your computer:
|
||||
|
||||
* HTML
|
||||
* CSS
|
||||
* JavaScript
|
||||
* WAI-ARIA
|
||||
|
||||
[float]
|
||||
[[accessibility-limitations-and-alternatives]]
|
||||
== Limitations and alternatives
|
||||
Despite our best efforts to ensure accessibility of Kibana, there are some limitations. Please https://github.com/elastic/kibana/issues/new?labels=Project%3AAccessibility&template=Accessibility.md&title=%28Accessibility%29[open an issue on GitHub] if you observe an issue not in this list.
|
||||
|
||||
Known limitations are in the following areas:
|
||||
|
||||
* *Charts*: We have a clear plan for the first steps of making charts accessible. We’ve opened this https://github.com/elastic/elastic-charts/issues/300[Charts accessibility ticket on GitHub] for tracking our progress.
|
||||
* *Maps*: Maps might pose difficulties to users with vision disabilities. We welcome your input on making our maps accessible. Go to the https://github.com/elastic/kibana/issues/57271[Maps accessibility ticket on GitHub] to join the discussion and view our plans.
|
||||
* *Tables*: Although generally accessible and marked-up as standard HTML tables with column headers, tables rarely make use of row headers and have poor captions. You will see incremental improvements as various applications adopt a new accessible component.
|
||||
* *Color contrast*: Modern Kibana interfaces generally do not have color contrast issues. However, older code might fall below the recommended contrast levels. As we continue to update our code, this issue will phase out naturally.
|
||||
|
||||
To see individual tickets, view our https://github.com/elastic/kibana/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3AProject%3AAccessibility[GitHub issues with label "`Project:Accessibility`"].
|
||||
|
||||
[float]
|
||||
[[accessibility-approach]]
|
||||
== Assessment approach
|
||||
Elastic assesses the accessibility of Kibana with the following approaches:
|
||||
|
||||
* *Self-evaluation*: Our employees are familiar with accessibility standards and review new designs and implemented features to confirm that they are accessible.
|
||||
* *External evaluation*: We engage external contractors to help us conduct an independent assessment and generate a formal VPAT. Please email accessibility@elastic.co if you’d like a copy.
|
||||
* *Automated evaluation*: We are starting to run https://www.deque.com/axe/[axe] on every page. See our current progress in the https://github.com/elastic/kibana/issues/51456[automated testing GitHub issue].
|
||||
|
||||
Manual testing largely focuses on screen reader support and is done on:
|
||||
|
||||
* VoiceOver on MacOS with Safari, Chrome and Edge
|
||||
* NVDA on Windows with Chrome and Firefox
|
||||
|
|
@ -1,58 +0,0 @@
|
|||
[[<ACTION-TYPE>-action-type]]
|
||||
== <ACTION-TYPE> connector and action
|
||||
++++
|
||||
<titleabbrev><ACTION-TYPE></titleabbrev>
|
||||
++++
|
||||
|
||||
Include a short description of the connector type.
|
||||
|
||||
[float]
|
||||
[[define-<ACTION-TYPE>-ui]]
|
||||
=== Create connectors in {kib}
|
||||
|
||||
You can create connectors in *{stack-manage-app} > {connectors-ui}*
|
||||
or as needed when you're creating a rule.
|
||||
|
||||
// Optionally add a screenshot
|
||||
|
||||
[float]
|
||||
[[<ACTION-TYPE>-connector-configuration]]
|
||||
==== Connector configuration
|
||||
|
||||
<ACTION-TYPE> connectors have the following configuration properties:
|
||||
|
||||
////
|
||||
List of user-facing connector configurations.
|
||||
This should align with the fields available in the Create connector flyout form for this connector type.
|
||||
To include these configuration details in the API documentation, add appropriate files in x-pack/platform/plugins/shared/actions/docs/openapi/components/schemas/ and reference them from oas_docs/overlays/connectors.overlays.yaml
|
||||
////
|
||||
|
||||
Property1:: A short description of this property.
|
||||
Property2:: A short description of this property with format hints. This can be specified in `this specific format`.
|
||||
|
||||
////
|
||||
Add preconfigured settings for this connector type in alert-action-settings.asciidoc and an example in pre-configured-connectors.asciidoc.
|
||||
////
|
||||
|
||||
[float]
|
||||
[[<ACTION-TYPE>-action-configuration]]
|
||||
=== Test connectors
|
||||
|
||||
You can test connectors as you're creating or editing the connector in {kib}.
|
||||
|
||||
<ACTION-TYPE> actions have the following properties.
|
||||
|
||||
////
|
||||
List of user-facing action configurations.
|
||||
This should align with the fields available in the Action section of the Create/Update alert flyout.
|
||||
To include these configuration details in the API documentation, add appropriate files in x-pack/platform/plugins/shared/actions/docs/openapi/components/schemas/ and reference them from oas_docs/overlays/connectors.overlays.yaml
|
||||
////
|
||||
|
||||
Property1:: A short description of this property.
|
||||
Property2:: A short description of this property with format hints. This can be specified in `this specific format`.
|
||||
|
||||
////
|
||||
Optional - additional configuration details here
|
||||
[[configuring-<ACTION-TYPE>]]
|
||||
==== Configure <ACTION-TYPE>
|
||||
////
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
[[actions-and-connectors-api]]
|
||||
== Action and connector APIs
|
||||
|
||||
For information about the actions and connectors that {kib} supports, refer to
|
||||
<<action-types>>.
|
||||
|
||||
For the latest API details, refer to {api-kibana}/group/endpoint-connectors[connector APIs].
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
[[alerting-apis]]
|
||||
== Alerting APIs
|
||||
|
||||
For the latest details, refer to {api-kibana}/group/endpoint-alerting[alerting APIs].
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
[[cases-api]]
|
||||
== Cases APIs
|
||||
|
||||
For the latest details, refer to {api-kibana}/group/endpoint-cases[case APIs].
|
||||
|
|
@ -1,19 +0,0 @@
|
|||
[[dashboard-api]]
|
||||
== Import and export dashboard APIs
|
||||
|
||||
deprecated::[7.15.0,Both of these APIs have been deprecated and will be removed in 9.0.0]
|
||||
|
||||
Import and export dashboards with the corresponding saved objects, such as visualizations, saved
|
||||
searches, and data views.
|
||||
|
||||
WARNING: Do not write documents directly to the `.kibana` index. When you write directly
|
||||
to the `.kibana` index, the data becomes corrupted and permanently breaks future {kib} versions.
|
||||
|
||||
The following import and export dashboard APIs are available:
|
||||
|
||||
* <<dashboard-import-api, Import dashboard API>> to import dashboards and corresponding saved objects
|
||||
|
||||
* <<dashboard-api-export, Export dashboard API>> to export dashboards and corresponding saved objects
|
||||
|
||||
include::dashboard/import-dashboard.asciidoc[]
|
||||
include::dashboard/export-dashboard.asciidoc[]
|
||||
|
|
@ -1,47 +0,0 @@
|
|||
[[dashboard-api-export]]
|
||||
=== Export dashboard API
|
||||
++++
|
||||
<titleabbrev>Export dashboard</titleabbrev>
|
||||
++++
|
||||
|
||||
deprecated::[7.15.0,Use the {api-kibana}/group/endpoint-saved-objects[saved objects API] instead.]
|
||||
|
||||
Export dashboards and corresponding saved objects.
|
||||
|
||||
[[dashboard-api-export-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/kibana/dashboards/export`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space-id>/api/kibana/dashboards/export`
|
||||
|
||||
[[dashboard-api-export-params]]
|
||||
==== Query parameters
|
||||
|
||||
`dashboard`::
|
||||
(Required, array|string) The IDs of the dashboards that you want to export.
|
||||
To export multiple dashboards, repeat the query parameter.
|
||||
|
||||
[[dashboard-api-export-response-body]]
|
||||
==== Response body
|
||||
|
||||
`objects`::
|
||||
(array) A top level property that includes the saved objects. The order of the objects is not guaranteed. Use the exact response body as the request body for the corresponding <<dashboard-import-api, Import dashboard API>>.
|
||||
|
||||
[[dashboard-api-export-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
[float]
|
||||
[[dashboard-api-export-example]]
|
||||
==== Example
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X GET api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c <1>
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
<1> The dashboard ID is `942dcef0-b2cd-11e8-ad8e-85441f0c2e5c`.
|
||||
|
|
@ -1,101 +0,0 @@
|
|||
[[dashboard-import-api]]
|
||||
=== Import dashboard API
|
||||
++++
|
||||
<titleabbrev>Import dashboard</titleabbrev>
|
||||
++++
|
||||
|
||||
deprecated::[7.15.0,Use the {api-kibana}/group/endpoint-saved-objects[saved objects API] instead.]
|
||||
|
||||
Import dashboards and corresponding saved objects.
|
||||
|
||||
[[dashboard-api-import-request]]
|
||||
==== Request
|
||||
|
||||
`POST <kibana host>:<port>/api/kibana/dashboards/import`
|
||||
|
||||
`POST <kibana host>:<port>/s/<space-id>/api/kibana/dashboards/import`
|
||||
|
||||
[[dashboard-api-import-params]]
|
||||
==== Query parameters
|
||||
|
||||
`force`::
|
||||
(Optional, boolean) Overwrite any existing objects on ID conflict.
|
||||
|
||||
`exclude`::
|
||||
(Optional, array) Saved object types that you want to exclude from the import.
|
||||
|
||||
[[dashboard-api-import-request-body]]
|
||||
==== Request body
|
||||
|
||||
Use the complete response body from the <<dashboard-api-export, Export dashboard API>> as the request body. Do not manually construct a payload to the endpoint. The max payload size is determined by the `savedObjects.maxImportPayloadBytes` configuration key.
|
||||
|
||||
[[dashboard-api-import-response-body]]
|
||||
==== Response body
|
||||
|
||||
`objects`::
|
||||
(array) A top level property that includes the saved objects.
|
||||
|
||||
[[dashboard-api-import-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call, even if there are errors importing individual saved objects. If there are errors, the error information is returned in the response body on an object-by-object basis.
|
||||
|
||||
[[dashboard-api-import-example]]
|
||||
==== Example
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/kibana/dashboards/import?exclude=index-pattern
|
||||
{
|
||||
"objects": [
|
||||
{
|
||||
"id": "80b956f0-b2cd-11e8-ad8e-85441f0c2e5c",
|
||||
"type": "visualization",
|
||||
"updated_at": "2018-09-07T18:40:33.247Z",
|
||||
"version": 1,
|
||||
"attributes": {
|
||||
"title": "Count Example",
|
||||
"visState": "{\"title\":\"Count Example\",\"type\":\"metric\",\"params\":{\"addTooltip\":true,\"addLegend\":false,\"type\":\"metric\",\"metric\":{\"percentageMode\":false,\"useRanges\":false,\"colorSchema\":\"Green to Red\",\"metricColorMode\":\"None\",\"colorsRange\":[{\"from\":0,\"to\":10000}],\"labels\":{\"show\":true},\"invertColors\":false,\"style\":{\"bgFill\":\"#000\",\"bgColor\":false,\"labelColor\":false,\"subText\":\"\",\"fontSize\":60}}},\"aggs\":[{\"id\":\"1\",\"enabled\":true,\"type\":\"count\",\"schema\":\"metric\",\"params\":{}}]}",
|
||||
"uiStateJSON": "{}",
|
||||
"description": "",
|
||||
"version": 1,
|
||||
"kibanaSavedObjectMeta": {
|
||||
"searchSourceJSON": "{\"index\":\"90943e30-9a47-11e8-b64d-95841ca0b247\",\"query\":{\"query\":\"\",\"language\":\"lucene\"},\"filter\":[]}"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "90943e30-9a47-11e8-b64d-95841ca0b247",
|
||||
"type": "index-pattern",
|
||||
"updated_at": "2018-09-07T18:39:47.683Z",
|
||||
"version": 1,
|
||||
"attributes": {
|
||||
"title": "kibana_sample_data_logs",
|
||||
"timeFieldName": "timestamp",
|
||||
"fields": "<truncated for example>",
|
||||
"fieldFormatMap": "{\"hour_of_day\":{}}"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "942dcef0-b2cd-11e8-ad8e-85441f0c2e5c",
|
||||
"type": "dashboard",
|
||||
"updated_at": "2018-09-07T18:41:05.887Z",
|
||||
"version": 1,
|
||||
"attributes": {
|
||||
"title": "Example Dashboard",
|
||||
"hits": 0,
|
||||
"description": "",
|
||||
"panelsJSON": "[{\"gridData\":{\"w\":24,\"h\":15,\"x\":0,\"y\":0,\"i\":\"1\"},\"version\":\"7.0.0-alpha1\",\"panelIndex\":\"1\",\"type\":\"visualization\",\"id\":\"80b956f0-b2cd-11e8-ad8e-85441f0c2e5c\",\"embeddableConfig\":{}}]",
|
||||
"optionsJSON": "{\"useMargins\":true,\"hidePanelTitles\":false}",
|
||||
"version": 1,
|
||||
"timeRestore": false,
|
||||
"kibanaSavedObjectMeta": {
|
||||
"searchSourceJSON": "{\"query\":{\"query\":\"\",\"language\":\"lucene\"},\"filter\":[]}"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
[[data-views-api]]
|
||||
== Data views API
|
||||
|
||||
Manage data views, formerly known as {kib} index patterns.
|
||||
|
||||
For the latest details, refer to {api-kibana}/group/endpoint-data-views[data view APIs].
|
||||
|
||||
WARNING: Do not write documents directly to the `.kibana` index. When you write directly
|
||||
to the `.kibana` index, the data becomes corrupted and permanently breaks future {kib} versions.
|
||||
|
||||
|
|
@ -1,207 +0,0 @@
|
|||
[role="xpack"]
|
||||
[[features-api-get]]
|
||||
== Get features API
|
||||
|
||||
experimental[] Retrieves all {kib} features. Features are used by spaces and security to refine and secure access to {kib}.
|
||||
|
||||
[float]
|
||||
[[features-api-get-request]]
|
||||
=== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/features`
|
||||
|
||||
[float]
|
||||
[[features-api-get-codes]]
|
||||
=== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
[float]
|
||||
[[features-api-get-example]]
|
||||
=== Example
|
||||
|
||||
The API returns the following:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"id": "discover",
|
||||
"name": "Discover",
|
||||
"app": [
|
||||
"kibana"
|
||||
],
|
||||
"catalogue": [
|
||||
"discover"
|
||||
],
|
||||
"privileges": {
|
||||
"all": {
|
||||
"savedObject": {
|
||||
"all": [
|
||||
"search",
|
||||
"url"
|
||||
],
|
||||
"read": [
|
||||
"config",
|
||||
"index-pattern"
|
||||
]
|
||||
},
|
||||
"ui": [
|
||||
"show",
|
||||
"createShortUrl",
|
||||
"save"
|
||||
]
|
||||
},
|
||||
"read": {
|
||||
"savedObject": {
|
||||
"all": [],
|
||||
"read": [
|
||||
"config",
|
||||
"index-pattern",
|
||||
"search",
|
||||
"url"
|
||||
]
|
||||
},
|
||||
"ui": [
|
||||
"show"
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "visualize",
|
||||
"name": "Visualize",
|
||||
"app": [
|
||||
"kibana"
|
||||
],
|
||||
"catalogue": [
|
||||
"visualize"
|
||||
],
|
||||
"privileges": {
|
||||
"all": {
|
||||
"savedObject": {
|
||||
"all": [
|
||||
"visualization",
|
||||
"url"
|
||||
],
|
||||
"read": [
|
||||
"config",
|
||||
"index-pattern",
|
||||
"search"
|
||||
]
|
||||
},
|
||||
"ui": [
|
||||
"show",
|
||||
"createShortUrl",
|
||||
"delete",
|
||||
"save"
|
||||
]
|
||||
},
|
||||
"read": {
|
||||
"savedObject": {
|
||||
"all": [],
|
||||
"read": [
|
||||
"config",
|
||||
"index-pattern",
|
||||
"search",
|
||||
"visualization"
|
||||
]
|
||||
},
|
||||
"ui": [
|
||||
"show"
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "dashboard",
|
||||
"name": "Dashboard",
|
||||
"app": [
|
||||
"kibana"
|
||||
],
|
||||
"catalogue": [
|
||||
"dashboard"
|
||||
],
|
||||
"privileges": {
|
||||
"all": {
|
||||
"savedObject": {
|
||||
"all": [
|
||||
"dashboard",
|
||||
"url"
|
||||
],
|
||||
"read": [
|
||||
"config",
|
||||
"index-pattern",
|
||||
"search",
|
||||
"visualization",
|
||||
"canvas-workpad"
|
||||
]
|
||||
},
|
||||
"ui": [
|
||||
"createNew",
|
||||
"show",
|
||||
"showWriteControls"
|
||||
]
|
||||
},
|
||||
"read": {
|
||||
"savedObject": {
|
||||
"all": [],
|
||||
"read": [
|
||||
"config",
|
||||
"index-pattern",
|
||||
"search",
|
||||
"visualization",
|
||||
"canvas-workpad",
|
||||
"dashboard"
|
||||
]
|
||||
},
|
||||
"ui": [
|
||||
"show"
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "dev_tools",
|
||||
"name": "Dev Tools",
|
||||
"app": [
|
||||
"kibana"
|
||||
],
|
||||
"catalogue": [
|
||||
"console",
|
||||
"searchprofiler",
|
||||
"grokdebugger"
|
||||
],
|
||||
"privileges": {
|
||||
"all": {
|
||||
"api": [
|
||||
"console"
|
||||
],
|
||||
"savedObject": {
|
||||
"all": [],
|
||||
"read": [
|
||||
"config"
|
||||
]
|
||||
},
|
||||
"ui": [
|
||||
"show"
|
||||
]
|
||||
},
|
||||
"read": {
|
||||
"api": [
|
||||
"console"
|
||||
],
|
||||
"savedObject": {
|
||||
"all": [],
|
||||
"read": [
|
||||
"config"
|
||||
]
|
||||
},
|
||||
"ui": [
|
||||
"show"
|
||||
]
|
||||
}
|
||||
},
|
||||
"privilegesTooltip": "User should also be granted the appropriate Elasticsearch cluster and index privileges"
|
||||
},
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
[[index-patterns-api]]
|
||||
== Index patterns APIs
|
||||
|
||||
deprecated::[8.0.0,Use <<data-views-api>> instead.]
|
||||
|
||||
experimental[] Manage {kib} index patterns.
|
||||
|
||||
WARNING: Do not write documents directly to the `.kibana` index. When you write directly
|
||||
to the `.kibana` index, the data becomes corrupted and permanently breaks future {kib} versions.
|
||||
|
||||
WARNING: Use the index patterns API for managing {kib} index patterns instead of lower-level <<saved-objects-api, saved objects API>>.
|
||||
|
||||
The following index patterns APIs are available:
|
||||
|
||||
* Index patterns
|
||||
** <<index-patterns-api-get, Get index pattern API>> to retrieve a single {kib} index pattern
|
||||
** <<index-patterns-api-create, Create index pattern API>> to create {kib} index pattern
|
||||
** <<index-patterns-api-update, Update index pattern API>> to partially updated {kib} index pattern
|
||||
** <<index-patterns-api-delete, Delete index pattern API>> to delete {kib} index pattern
|
||||
* Default index pattern
|
||||
** <<index-patterns-api-default-get, Get default index pattern API>> to retrieve a default index pattern
|
||||
** <<index-patterns-api-default-set, Set default index pattern API>> to set a default index pattern
|
||||
* Fields
|
||||
** <<index-patterns-fields-api-update, Update index pattern field>> to change field metadata, such as `count`, `customLabel` and `format`
|
||||
* Runtime fields
|
||||
** <<index-patterns-runtime-field-api-get, Get runtime field API>> to retrieve a runtime field
|
||||
** <<index-patterns-runtime-field-api-create, Create runtime field API>> to create a runtime field
|
||||
** <<index-patterns-runtime-field-api-upsert, Upsert runtime field API>> to create or update a runtime field
|
||||
** <<index-patterns-runtime-field-api-update, Update runtime field API>> to partially update an existing runtime field
|
||||
** <<index-patterns-runtime-field-api-delete, Delete runtime field API>> to delete a runtime field
|
||||
|
||||
include::index-patterns/get.asciidoc[]
|
||||
include::index-patterns/create.asciidoc[]
|
||||
include::index-patterns/update.asciidoc[]
|
||||
include::index-patterns/delete.asciidoc[]
|
||||
include::index-patterns/default-get.asciidoc[]
|
||||
include::index-patterns/default-set.asciidoc[]
|
||||
include::index-patterns/update-fields.asciidoc[]
|
||||
include::index-patterns/runtime-fields/get.asciidoc[]
|
||||
include::index-patterns/runtime-fields/create.asciidoc[]
|
||||
include::index-patterns/runtime-fields/upsert.asciidoc[]
|
||||
include::index-patterns/runtime-fields/update.asciidoc[]
|
||||
include::index-patterns/runtime-fields/delete.asciidoc[]
|
||||
|
||||
|
|
@ -1,105 +0,0 @@
|
|||
[[index-patterns-api-create]]
|
||||
=== Create index pattern API
|
||||
++++
|
||||
<titleabbrev>Create index pattern</titleabbrev>
|
||||
++++
|
||||
|
||||
deprecated::[8.0.0,Use the {api-kibana}/group/endpoint-data-views[data views API] instead.]
|
||||
|
||||
experimental[] Create {kib} index patterns.
|
||||
|
||||
[[index-patterns-api-create-request]]
|
||||
==== Request
|
||||
|
||||
`POST <kibana host>:<port>/api/index_patterns/index_pattern`
|
||||
|
||||
`POST <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern`
|
||||
|
||||
[[index-patterns-api-create-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
[[index-patterns-api-create-body-params]]
|
||||
==== Request body
|
||||
|
||||
`override`:: (Optional, boolean) Overrides an existing index pattern if an
|
||||
index pattern with the provided title already exists. The default is `false`.
|
||||
|
||||
`refresh_fields`:: (Optional, boolean) Reloads index pattern fields after
|
||||
the index pattern is stored. The default is `false`.
|
||||
|
||||
`index_pattern`:: (Required, object) The index pattern object. All fields are optional.
|
||||
|
||||
[[index-patterns-api-create-request-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
[[index-patterns-api-create-example]]
|
||||
==== Examples
|
||||
|
||||
Create an index pattern with a custom title:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/index_patterns/index_pattern
|
||||
{
|
||||
"index_pattern": {
|
||||
"title": "hello"
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
Customize the creation behavior:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/index_patterns/index_pattern
|
||||
{
|
||||
"override": false,
|
||||
"refresh_fields": true,
|
||||
"index_pattern": {
|
||||
"title": "hello"
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
At creation, all index pattern fields are optional:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/index_patterns/index_pattern
|
||||
{
|
||||
"index_pattern": {
|
||||
"id": "...",
|
||||
"version": "...",
|
||||
"title": "...",
|
||||
"type": "...",
|
||||
"timeFieldName": "...",
|
||||
"sourceFilters": [],
|
||||
"fields": {},
|
||||
"typeMeta": {},
|
||||
"fieldFormats": {},
|
||||
"fieldAttrs": {},
|
||||
"runtimeFieldMap": {}
|
||||
"allowNoIndex": "..."
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
|
||||
The API returns the index pattern object:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"index_pattern": {...}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
|
|
@ -1,57 +0,0 @@
|
|||
[[index-patterns-api-default-get]]
|
||||
=== Get default index pattern API
|
||||
++++
|
||||
<titleabbrev>Get default index pattern</titleabbrev>
|
||||
++++
|
||||
|
||||
deprecated::[8.0.0,Use the {api-kibana}/group/endpoint-data-views[data views API] instead.]
|
||||
|
||||
experimental[] Retrieve a default index pattern ID. Kibana UI uses default index pattern unless user picks a different one.
|
||||
|
||||
[[index-patterns-api-default-get-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/index_patterns/default`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space_id>/api/index_patterns/default`
|
||||
|
||||
[[index-patterns-api-default-get-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
[[index-patterns-api-default-get-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
[[index-patterns-api-default-get-example]]
|
||||
==== Example
|
||||
|
||||
Retrieve the default index pattern id:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X GET api/index_patterns/default
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns an ID of a default index pattern:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"index_pattern_id": "..."
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
In case there is no default index pattern, the API returns:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"index_pattern_id": null
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,86 +0,0 @@
|
|||
[[index-patterns-api-default-set]]
|
||||
=== Set default index pattern API
|
||||
++++
|
||||
<titleabbrev>Set default index pattern</titleabbrev>
|
||||
++++
|
||||
|
||||
deprecated::[8.0.0,Use the {api-kibana}/group/endpoint-data-views[data views API] instead.]
|
||||
|
||||
experimental[] Set a default index pattern ID. Kibana UI will use default index pattern unless user picks a different one.
|
||||
The API doesn't validate if given `index_pattern_id` is a valid id.
|
||||
|
||||
[[index-patterns-api-default-set-request]]
|
||||
==== Request
|
||||
|
||||
`POST <kibana host>:<port>/api/index_patterns/default`
|
||||
|
||||
`POST <kibana host>:<port>/s/<space_id>/api/index_patterns/default`
|
||||
|
||||
[[index-patterns-api-default-set-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
[[index-patterns-api-default-set-body]]
|
||||
==== Request body
|
||||
|
||||
`index_pattern_id`:: (Required, `string` or `null`) Sets a default index pattern id. Use `null` to unset a default index pattern.
|
||||
|
||||
`force`:: (Optional, boolean) Updates existing default index pattern id. The default is `false`.
|
||||
|
||||
|
||||
[[index-patterns-api-default-set-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
[[index-patterns-api-default-set-example]]
|
||||
==== Example
|
||||
|
||||
Set the default index pattern id if none is set:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/index_patterns/default
|
||||
{
|
||||
"index_pattern_id": "..."
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
|
||||
Upsert the default index pattern:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/index_patterns/default
|
||||
{
|
||||
"index_pattern_id": "...",
|
||||
"force": true
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
Unset the default index pattern:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/index_patterns/default
|
||||
{
|
||||
"index_pattern_id": null,
|
||||
"force": true
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
|
|
@ -1,43 +0,0 @@
|
|||
[[index-patterns-api-delete]]
|
||||
=== Delete index pattern API
|
||||
++++
|
||||
<titleabbrev>Delete index pattern</titleabbrev>
|
||||
++++
|
||||
|
||||
deprecated::[8.0.0,Use <<data-views-api-delete>> instead.]
|
||||
|
||||
experimental[] Delete {kib} index patterns.
|
||||
|
||||
WARNING: Once you delete an index pattern, _it cannot be recovered_.
|
||||
|
||||
[[index-patterns-api-delete-request]]
|
||||
==== Request
|
||||
|
||||
`DELETE <kibana host>:<port>/api/index_patterns/index_pattern/<id>`
|
||||
|
||||
`DELETE <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern/<id>`
|
||||
|
||||
[[index-patterns-api-delete-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
`id`::
|
||||
(Required, string) The ID of the index pattern you want to delete.
|
||||
|
||||
[[index-patterns-api-delete-response-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates that index pattern is deleted. Returns an empty response body.
|
||||
|
||||
==== Example
|
||||
|
||||
Delete an index pattern object with the `my-pattern` ID:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X DELETE api/index_patterns/index_pattern/my-pattern
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
|
@ -1,67 +0,0 @@
|
|||
[[index-patterns-api-get]]
|
||||
=== Get index pattern API
|
||||
++++
|
||||
<titleabbrev>Get index pattern</titleabbrev>
|
||||
++++
|
||||
|
||||
deprecated::[8.0.0,Use the {api-kibana}/group/endpoint-data-views[data views API] instead.]
|
||||
|
||||
experimental[] Retrieve a single {kib} index pattern by ID.
|
||||
|
||||
[[index-patterns-api-get-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/index_patterns/index_pattern/<id>`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern/<id>`
|
||||
|
||||
[[index-patterns-api-get-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
`id`::
|
||||
(Required, string) The ID of the index pattern you want to retrieve.
|
||||
|
||||
[[index-patterns-api-get-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
`404`::
|
||||
The specified index pattern and ID doesn't exist.
|
||||
|
||||
[[index-patterns-api-get-example]]
|
||||
==== Example
|
||||
|
||||
Retrieve the index pattern object with the `my-pattern` ID:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X GET api/index_patterns/index_pattern/my-pattern
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns an index pattern object:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"index_pattern": {
|
||||
"id": "my-pattern",
|
||||
"version": "...",
|
||||
"title": "...",
|
||||
"type": "...",
|
||||
"timeFieldName": "...",
|
||||
"sourceFilters": [],
|
||||
"fields": {},
|
||||
"typeMeta": {},
|
||||
"fieldFormats": {},
|
||||
"fieldAttrs": {},
|
||||
"runtimeFieldMap" {},
|
||||
"allowNoIndex: "..."
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,63 +0,0 @@
|
|||
[[index-patterns-runtime-field-api-create]]
|
||||
=== Create runtime field API
|
||||
++++
|
||||
<titleabbrev>Create runtime field</titleabbrev>
|
||||
++++
|
||||
|
||||
deprecated::[8.0.0,Use the {api-kibana}/group/endpoint-data-views[data views API] instead.]
|
||||
|
||||
experimental[] Create a runtime field
|
||||
|
||||
[[index-patterns-runtime-field-create-request]]
|
||||
==== Request
|
||||
|
||||
`POST <kibana host>:<port>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field`
|
||||
|
||||
`POST <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field`
|
||||
|
||||
[[index-patterns-runtime-field-create-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
`index_pattern_id`::
|
||||
(Required, string) The ID of the index pattern.
|
||||
|
||||
[[index-patterns-runtime-field-create-body]]
|
||||
==== Request body
|
||||
|
||||
`name`:: (Required, string) The name for a runtime field.
|
||||
|
||||
`runtimeField`:: (Required, object) The runtime field definition object.
|
||||
|
||||
|
||||
[[index-patterns-runtime-field-create-example]]
|
||||
==== Examples
|
||||
|
||||
Create a runtime field on an index pattern:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/index_patterns/index_pattern/<index_pattern_id>/runtime_field
|
||||
{
|
||||
"name": "runtimeFoo",
|
||||
"runtimeField": {
|
||||
"type": "long",
|
||||
"script": {
|
||||
"source": "emit(doc["foo"].value)"
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns created runtime field object and update index pattern object:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"index_pattern": {...},
|
||||
"field": {...}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,39 +0,0 @@
|
|||
[[index-patterns-runtime-field-api-delete]]
|
||||
=== Delete runtime field API
|
||||
++++
|
||||
<titleabbrev>Delete runtime field</titleabbrev>
|
||||
++++
|
||||
|
||||
deprecated::[8.0.0,Use the {api-kibana}/group/endpoint-data-views[data views API]instead.]
|
||||
|
||||
experimental[] Delete a runtime field from an index pattern.
|
||||
|
||||
[[index-patterns-runtime-field-api-delete-request]]
|
||||
==== Request
|
||||
|
||||
`DELETE <kibana host>:<port>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field/<name>`
|
||||
|
||||
`DELETE <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field/<name>`
|
||||
|
||||
[[index-patterns-runtime-field-api-delete-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
`index_pattern_id`::
|
||||
(Required, string) The ID of the index pattern your want to delete a runtime field from.
|
||||
|
||||
`name`::
|
||||
(Required, string) The name of the runtime field you want to delete.
|
||||
|
||||
|
||||
==== Example
|
||||
|
||||
Delete a runtime field from an index pattern:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X DELETE api/index_patterns/index_pattern/<my-pattern>/runtime_field/<runtime-field-name>
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
|
@ -1,54 +0,0 @@
|
|||
[[index-patterns-runtime-field-api-get]]
|
||||
=== Get runtime field API
|
||||
++++
|
||||
<titleabbrev>Get runtime field</titleabbrev>
|
||||
++++
|
||||
|
||||
deprecated::[8.0.0,Use the {api-kibana}/group/endpoint-data-views[data views API] instead.]
|
||||
|
||||
experimental[] Get a runtime field
|
||||
|
||||
[[index-patterns-runtime-field-get-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field/<name>`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field/<name>`
|
||||
|
||||
[[index-patterns-runtime-field-get-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
`index_pattern_id`::
|
||||
(Required, string) The ID of the index pattern.
|
||||
|
||||
`name`::
|
||||
(Required, string) The name of the runtime field you want to retrieve.
|
||||
|
||||
|
||||
[[index-patterns-runtime-field-get-example]]
|
||||
==== Example
|
||||
|
||||
Retrieve a runtime field named `foo` of index pattern with the `my-pattern` ID:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X GET api/index_patterns/index_pattern/my-pattern/runtime_field/foo
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns a runtime `field` object, and a `runtimeField` definition object:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"field": {
|
||||
...
|
||||
},
|
||||
"runtimeField": {
|
||||
...
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,68 +0,0 @@
|
|||
[[index-patterns-runtime-field-api-update]]
|
||||
=== Update runtime field API
|
||||
++++
|
||||
<titleabbrev>Update runtime field</titleabbrev>
|
||||
++++
|
||||
|
||||
deprecated::[8.0.0,Use the {api-kibana}/group/endpoint-data-views[data views API] instead.]
|
||||
|
||||
experimental[] Update an existing runtime field
|
||||
|
||||
[[index-patterns-runtime-field-update-request]]
|
||||
==== Request
|
||||
|
||||
`POST <kibana host>:<port>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field/<name>`
|
||||
|
||||
`POST <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field/<name>`
|
||||
|
||||
[[index-patterns-runtime-field-update-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
`index_pattern_id`::
|
||||
(Required, string) The ID of the index pattern.
|
||||
|
||||
`name`::
|
||||
(Required, string) The name of the runtime field you want to update.
|
||||
|
||||
[[index-patterns-runtime-field-update-body]]
|
||||
==== Request body
|
||||
|
||||
`runtimeField`:: (Required, object) The runtime field definition object.
|
||||
|
||||
You can update following fields:
|
||||
|
||||
* `type`
|
||||
* `script`
|
||||
|
||||
|
||||
|
||||
[[index-patterns-runtime-field-update-example]]
|
||||
==== Examples
|
||||
|
||||
Update an existing runtime field on an index pattern:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/index_patterns/index_pattern/<index_pattern_id>/runtime_field/<runtime_field_name>
|
||||
{
|
||||
"runtimeField": {
|
||||
"script": {
|
||||
"source": "emit(doc["bar"].value)"
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns updated runtime field object and updated index pattern object:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"index_pattern": {...},
|
||||
"field": {...}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,63 +0,0 @@
|
|||
[[index-patterns-runtime-field-api-upsert]]
|
||||
=== Upsert runtime field API
|
||||
++++
|
||||
<titleabbrev>Upsert runtime field</titleabbrev>
|
||||
++++
|
||||
|
||||
deprecated::[8.0.0,Use the {api-kibana}/group/endpoint-data-views[data views API] instead.]
|
||||
|
||||
experimental[] Create or update an existing runtime field
|
||||
|
||||
[[index-patterns-runtime-field-upsert-request]]
|
||||
==== Request
|
||||
|
||||
`PUT <kibana host>:<port>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field`
|
||||
|
||||
`PUT <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field`
|
||||
|
||||
[[index-patterns-runtime-field-upsert-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
`index_pattern_id`::
|
||||
(Required, string) The ID of the index pattern.
|
||||
|
||||
[[index-patterns-runtime-field-upsert-body]]
|
||||
==== Request body
|
||||
|
||||
`name`:: (Required, string) The name for a new runtime field or a name of an existing runtime field.
|
||||
|
||||
`runtimeField`:: (Required, object) The runtime field definition object.
|
||||
|
||||
|
||||
[[index-patterns-runtime-field-upsert-example]]
|
||||
==== Examples
|
||||
|
||||
Create or update an existing runtime field on an index pattern:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X PUT api/index_patterns/index_pattern/<index_pattern_id>/runtime_field
|
||||
{
|
||||
"name": "runtimeFoo",
|
||||
"runtimeField": {
|
||||
"type": "long",
|
||||
"script": {
|
||||
"source": "emit(doc["foo"].value)"
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns created or updated runtime field object and updated index pattern object:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"index_pattern": {...},
|
||||
"field": {...}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,102 +0,0 @@
|
|||
[[index-patterns-fields-api-update]]
|
||||
=== Update index pattern fields API
|
||||
++++
|
||||
<titleabbrev>Update index pattern fields metadata</titleabbrev>
|
||||
++++
|
||||
|
||||
deprecated::[8.0.0,Use the {api-kibana}/group/endpoint-data-views[data views API] instead.]
|
||||
|
||||
experimental[] Update fields presentation metadata, such as `count`,
|
||||
`customLabel`, and `format`. You can update multiple fields in one request. Updates
|
||||
are merged with persisted metadata. To remove existing metadata, specify `null` as the value.
|
||||
|
||||
[[index-patterns-fields-api-update-request]]
|
||||
==== Request
|
||||
|
||||
`POST <kibana host>:<port>/api/index_patterns/index_pattern/<id>/fields`
|
||||
|
||||
`POST <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern/<id>/fields`
|
||||
|
||||
[[index-patterns-fields-api-update-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
`id`::
|
||||
(Required, string) The ID of the index pattern fields you want to update.
|
||||
|
||||
[[index-patterns-fields-api-update-request-body]]
|
||||
==== Request body
|
||||
|
||||
`fields`::
|
||||
(Required, object) the field object
|
||||
|
||||
|
||||
[[index-patterns-fields-api-update-errors-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
[[index-patterns-fields-api-update-example]]
|
||||
==== Examples
|
||||
|
||||
Set popularity `count` for field `foo`:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/index_patterns/index-pattern/my-pattern/fields
|
||||
{
|
||||
"fields": {
|
||||
"foo": {
|
||||
"count": 123
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
Update multiple metadata fields in one request:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/index_patterns/index-pattern/my-pattern/fields
|
||||
{
|
||||
"fields": {
|
||||
"foo": {
|
||||
"count": 123,
|
||||
"customLabel": "Foo"
|
||||
},
|
||||
"bar": {
|
||||
"customLabel": "Bar"
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
Use `null` value to delete metadata:
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/index_patterns/index-pattern/my-pattern/fields
|
||||
{
|
||||
"fields": {
|
||||
"foo": {
|
||||
"customLabel": null
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
|
||||
The endpoint returns the updated index pattern object:
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"index_pattern": {
|
||||
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,116 +0,0 @@
|
|||
[[index-patterns-api-update]]
|
||||
=== Update index pattern API
|
||||
++++
|
||||
<titleabbrev>Update index pattern</titleabbrev>
|
||||
++++
|
||||
|
||||
deprecated::[8.0.0,Use the {api-kibana}/group/endpoint-data-views[data views API] instead.]
|
||||
|
||||
experimental[] Update part of an index pattern. Only the specified fields are updated in the
|
||||
index pattern. Unspecified fields stay as they are persisted.
|
||||
|
||||
[[index-patterns-api-update-request]]
|
||||
==== Request
|
||||
|
||||
`POST <kibana host>:<port>/api/index_patterns/index_pattern/<id>`
|
||||
|
||||
`POST <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern/<id>`
|
||||
|
||||
[[index-patterns-api-update-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
`id`::
|
||||
(Required, string) The ID of the index pattern you want to update.
|
||||
|
||||
[[index-patterns-api-update-request-body]]
|
||||
==== Request body
|
||||
|
||||
`refresh_fields`:: (Optional, boolean) Reloads the index pattern fields after
|
||||
the index pattern is updated. The default is `false`.
|
||||
|
||||
`index_pattern`::
|
||||
(Required, object) The index patterns fields you want to update.
|
||||
+
|
||||
|
||||
You can partially update the following fields:
|
||||
|
||||
* `title`
|
||||
* `name`
|
||||
* `timeFieldName`
|
||||
* `fields`
|
||||
* `sourceFilters`
|
||||
* `fieldFormatMap`
|
||||
* `type`
|
||||
* `typeMeta`
|
||||
|
||||
[[index-patterns-api-update-errors-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
[[index-patterns-api-update-example]]
|
||||
==== Examples
|
||||
|
||||
Update a title of the `<my-pattern>` index pattern:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/index_patterns/index-pattern/my-pattern
|
||||
{
|
||||
"index_pattern": {
|
||||
"title": "some-other-pattern-*"
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
Customize the update behavior:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/index_patterns/index-pattern/my-pattern
|
||||
{
|
||||
"refresh_fields": true,
|
||||
"index_pattern": {
|
||||
"fields": {}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
|
||||
All update fields are optional, but you can specify the following fields:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/index_patterns/index-pattern/my-pattern
|
||||
{
|
||||
"index_pattern": {
|
||||
"title": "...",
|
||||
"name": "...",
|
||||
"timeFieldName": "...",
|
||||
"sourceFilters": [],
|
||||
"fieldFormats": {},
|
||||
"type": "...",
|
||||
"typeMeta": {},
|
||||
"fields": {},
|
||||
"runtimeFieldMap": {}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns the updated index pattern object:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"index_pattern": {
|
||||
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,22 +0,0 @@
|
|||
[role="xpack"]
|
||||
[[logstash-configuration-management-api]]
|
||||
== Logstash configuration management APIs
|
||||
|
||||
Programmatically integrate with Logstash configuration management.
|
||||
|
||||
WARNING: Do not directly access the `.logstash` index. The structure of the `.logstash` index is subject to change, which could cause your integration to break. Instead, use the Logstash configuration management APIs.
|
||||
|
||||
The following Logstash configuration management APIs are available:
|
||||
|
||||
* <<logstash-configuration-management-api-delete, Delete Logstash pipeline API>> to delete a centrally-managed Logstash pipeline
|
||||
|
||||
* <<logstash-configuration-management-api-list, List Logstash pipeline API>> to list all centrally-managed Logstash pipelines
|
||||
|
||||
* <<logstash-configuration-management-api-create, Create Logstash pipeline API>> to create a centrally-managed Logstash pipeline, or update an existing pipeline
|
||||
|
||||
* <<logstash-configuration-management-api-retrieve, Retrieve pipeline API>> to retrieve a centrally-managed Logstash pipeline
|
||||
|
||||
include::logstash-configuration-management/delete-pipeline.asciidoc[]
|
||||
include::logstash-configuration-management/list-pipeline.asciidoc[]
|
||||
include::logstash-configuration-management/create-logstash.asciidoc[]
|
||||
include::logstash-configuration-management/retrieve-pipeline.asciidoc[]
|
||||
|
|
@ -1,61 +0,0 @@
|
|||
[[logstash-configuration-management-api-create]]
|
||||
=== Create Logstash pipeline API
|
||||
++++
|
||||
<titleabbrev>Create Logstash pipeline</titleabbrev>
|
||||
++++
|
||||
|
||||
experimental[] Create a centrally-managed Logstash pipeline, or update an existing pipeline.
|
||||
|
||||
[[logstash-configuration-management-api-create-request]]
|
||||
==== Request
|
||||
|
||||
`PUT <kibana host>:<port>/api/logstash/pipeline/<id>`
|
||||
|
||||
[[logstash-configuration-management-api-create-params]]
|
||||
==== Path parameters
|
||||
|
||||
`id`::
|
||||
(Required, string) The pipeline ID. Only alphanumeric characters, hyphens, and underscores are supported.
|
||||
|
||||
[[logstash-configuration-management-api-create-request-body]]
|
||||
==== Request body
|
||||
|
||||
`description`::
|
||||
(Optional, string) The pipeline description.
|
||||
|
||||
`pipeline`::
|
||||
(Required, string) The pipeline definition.
|
||||
|
||||
`settings`::
|
||||
(Optional, object) The pipeline settings. Supported settings, represented as object keys, include the following:
|
||||
|
||||
* `pipeline.workers`
|
||||
* `pipeline.batch.size`
|
||||
* `pipeline.batch.delay`
|
||||
* `pipeline.ecs_compatibility`
|
||||
* `pipeline.ordered`
|
||||
* `queue.type`
|
||||
* `queue.max_bytes`
|
||||
* `queue.checkpoint.writes`
|
||||
|
||||
[[logstash-configuration-management-api-create-codes]]
|
||||
==== Response code
|
||||
|
||||
`204 No Content`::
|
||||
Indicates a successful call.
|
||||
|
||||
[float]
|
||||
[[logstash-configuration-management-api-create-example]]
|
||||
==== Example
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X PUT api/logstash/pipeline/hello-world
|
||||
{
|
||||
"pipeline": "input { stdin {} } output { stdout {} }",
|
||||
"settings": {
|
||||
"queue.type": "persisted"
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
|
@ -1,33 +0,0 @@
|
|||
[[logstash-configuration-management-api-delete]]
|
||||
=== Delete Logstash pipeline API
|
||||
++++
|
||||
<titleabbrev>Delete pipeline</titleabbrev>
|
||||
++++
|
||||
|
||||
experimental[] Delete a centrally-managed Logstash pipeline.
|
||||
|
||||
[[logstash-configuration-management-api-delete-request]]
|
||||
==== Request
|
||||
|
||||
`DELETE <kibana host>:<port>/api/logstash/pipeline/<id>`
|
||||
|
||||
[[logstash-configuration-management-api-delete-params]]
|
||||
==== Path parameters
|
||||
|
||||
`id`::
|
||||
(Required, string) The pipeline ID.
|
||||
|
||||
[[logstash-configuration-management-api-delete-codes]]
|
||||
==== Response code
|
||||
|
||||
`204 No Content`::
|
||||
Indicates a successful call.
|
||||
|
||||
[[logstash-configuration-management-api-delete-example]]
|
||||
==== Example
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X DELETE api/logstash/pipeline/hello-world
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
|
@ -1,40 +0,0 @@
|
|||
[[logstash-configuration-management-api-list]]
|
||||
=== List Logstash pipeline API
|
||||
++++
|
||||
<titleabbrev>List pipeline</titleabbrev>
|
||||
++++
|
||||
|
||||
experimental[] List all centrally-managed Logstash pipelines.
|
||||
|
||||
IMPORTANT: Limit the number of pipelines to 10k or fewer. As the number of pipelines nears and surpasses 10k, you may see performance issues on {kib}.
|
||||
|
||||
[[logstash-configuration-management-api-list-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/logstash/pipelines`
|
||||
|
||||
[[logstash-configuration-management-api-list-example]]
|
||||
==== Example
|
||||
|
||||
The API returns the following:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"pipelines": [
|
||||
{
|
||||
"id": "hello-world",
|
||||
"description": "Just a simple pipeline",
|
||||
"last_modified": "2018-04-14T12:23:29.772Z",
|
||||
"username": "elastic" <1>
|
||||
},
|
||||
{
|
||||
"id": "sleepy-pipeline",
|
||||
"description": "",
|
||||
"last_modified": "2018-03-24T03:41:30.554Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
<1> The `username` property appears when security is enabled, and depends on when the pipeline was created or last updated.
|
||||
|
|
@ -1,36 +0,0 @@
|
|||
[[logstash-configuration-management-api-retrieve]]
|
||||
=== Retrieve pipeline API
|
||||
++++
|
||||
<titleabbrev>Retrieve pipeline</titleabbrev>
|
||||
++++
|
||||
|
||||
experimental[] Retrieve a centrally-managed Logstash pipeline.
|
||||
|
||||
[[logstash-configuration-management-api-retrieve-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/logstash/pipeline/<id>`
|
||||
|
||||
[[logstash-configuration-management-api-retrieve-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`id`::
|
||||
(Required, string) The pipeline ID.
|
||||
|
||||
[[logstash-configuration-management-api-retrieve-example]]
|
||||
==== Example
|
||||
|
||||
The API returns the following:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"id": "hello-world",
|
||||
"description": "Just a simple pipeline",
|
||||
"username": "elastic",
|
||||
"pipeline": "input { stdin {} } output { stdout {} }",
|
||||
"settings": {
|
||||
"queue.type": "persistent"
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
[[machine-learning-api]]
|
||||
== {ml-cap} APIs
|
||||
|
||||
For the latest details, refer to {api-kibana}/group/endpoint-ml[machine learning APIs].
|
||||
|
|
@ -1,47 +0,0 @@
|
|||
[[osquery-manager-api]]
|
||||
== Osquery manager API
|
||||
|
||||
.New API Reference
|
||||
[sidebar]
|
||||
--
|
||||
For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-osquery-api[Osquery APIs].
|
||||
--
|
||||
|
||||
experimental[] Run live queries, manage packs and saved queries
|
||||
|
||||
Use the osquery manager APIs for managing packs and saved queries.
|
||||
|
||||
The following osquery manager APIs are available:
|
||||
|
||||
* Live queries
|
||||
** <<osquery-manager-live-queries-api-get-all, Get all live queries API>> to retrieve a list of live queries
|
||||
** <<osquery-manager-live-queries-api-get, Get live query API>> to retrieve a single live query
|
||||
** <<osquery-manager-live-queries-api-create, Create live query API>> to create a live query
|
||||
** <<osquery-manager-live-queries-api-get-results, Get live query results API>> to retrieve the results of a single live query
|
||||
* Packs
|
||||
** <<osquery-manager-packs-api-get-all, Get all packs API>> to retrieve a list of packs
|
||||
** <<osquery-manager-packs-api-get, Get pack API>> to retrieve a pack
|
||||
** <<osquery-manager-packs-api-create, Create pack API>> to create a pack
|
||||
** <<osquery-manager-packs-api-update, Update pack API>> to partially update an existing pack
|
||||
** <<osquery-manager-packs-api-delete, Delete pack API>> to delete a pack
|
||||
* Saved queries
|
||||
** <<osquery-manager-saved-queries-api-get-all, Get all saved queries API>> to retrieve a list of saved queries
|
||||
** <<osquery-manager-saved-queries-api-get, Get saved query API>> to retrieve a saved query
|
||||
** <<osquery-manager-saved-queries-api-create, Create saved query API>> to create a saved query
|
||||
** <<osquery-manager-saved-queries-api-update, Update saved query API>> to partially update an existing saved query
|
||||
** <<osquery-manager-saved-queries-api-delete, Delete saved query API>> to delete a saved query
|
||||
|
||||
include::osquery-manager/live-queries/get.asciidoc[]
|
||||
include::osquery-manager/live-queries/get-all.asciidoc[]
|
||||
include::osquery-manager/live-queries/get-results.asciidoc[]
|
||||
include::osquery-manager/live-queries/create.asciidoc[]
|
||||
include::osquery-manager/packs/get.asciidoc[]
|
||||
include::osquery-manager/packs/get-all.asciidoc[]
|
||||
include::osquery-manager/packs/create.asciidoc[]
|
||||
include::osquery-manager/packs/update.asciidoc[]
|
||||
include::osquery-manager/packs/delete.asciidoc[]
|
||||
include::osquery-manager/saved-queries/get.asciidoc[]
|
||||
include::osquery-manager/saved-queries/get-all.asciidoc[]
|
||||
include::osquery-manager/saved-queries/create.asciidoc[]
|
||||
include::osquery-manager/saved-queries/update.asciidoc[]
|
||||
include::osquery-manager/saved-queries/delete.asciidoc[]
|
||||
|
|
@ -1,193 +0,0 @@
|
|||
[[osquery-manager-live-queries-api-create]]
|
||||
=== Create live query API
|
||||
++++
|
||||
<titleabbrev>Create live query</titleabbrev>
|
||||
++++
|
||||
|
||||
.New API Reference
|
||||
[sidebar]
|
||||
--
|
||||
For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-osquery-api[Osquery APIs].
|
||||
--
|
||||
|
||||
experimental[] Create live queries.
|
||||
|
||||
|
||||
[[osquery-manager-live-queries-api-create-request]]
|
||||
==== Request
|
||||
|
||||
`POST <kibana host>:<port>/api/osquery/live_queries`
|
||||
|
||||
`POST <kibana host>:<port>/s/<space_id>/api/osquery/live_queries`
|
||||
|
||||
|
||||
[[osquery-manager-live-queries-api-create-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. When `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
|
||||
[[osquery-manager-live-queries-api-create-body-params]]
|
||||
==== Request body
|
||||
|
||||
`agent_ids`:: (Optional, array) A list of agent IDs to run the query on.
|
||||
|
||||
`agent_all`:: (Optional, boolean) When `true`, the query runs on all agents.
|
||||
|
||||
`agent_platforms`:: (Optional, array) A list of agent platforms to run the query on.
|
||||
|
||||
`agent_policy_ids`:: (Optional, array) A list of agent policy IDs to run the query on.
|
||||
|
||||
`query`:: (Optional, string) The SQL query you want to run.
|
||||
|
||||
`saved_query_id`:: (Optional, string) The ID of a saved query.
|
||||
|
||||
`ecs_mapping`:: (Optional, object) Map osquery results columns or static values to Elastic Common Schema (ECS) fields.
|
||||
|
||||
`pack_id`:: (Optional, string) The ID of the pack you want to run.
|
||||
|
||||
`alert_ids`:: (Optional, array) A list of alert IDs associated to the live query.
|
||||
|
||||
`case_ids`:: (Optional, array) A list of case IDs associated to the live query.
|
||||
|
||||
`event_ids`:: (Optional, array) A list of event IDs associated to the live query.
|
||||
|
||||
`metadata`:: (Optional, object) Custom metadata object associated to the live query.
|
||||
|
||||
`timeout`:: (Optional, number) A timeout period, in seconds, after which the query will stop running. Overwriting the default timeout allows you to support queries that require more time to complete. The default and minimum supported value is `60`. The maximum supported value is `900`.
|
||||
|
||||
|
||||
[[osquery-manager-live-queries-api-create-request-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
|
||||
[[osquery-manager-live-queries-api-create-example]]
|
||||
==== Examples
|
||||
|
||||
Run a live query on all supported agents:
|
||||
|
||||
TIP: `osquery_manager` integration has to be added to the agent policy.
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/osquery/live_queries \
|
||||
{
|
||||
"query": "select * from uptime;",
|
||||
"ecs_mapping": {
|
||||
"host.uptime": {
|
||||
"field": "total_seconds"
|
||||
}
|
||||
},
|
||||
"agent_all": true,
|
||||
"timeout": 120
|
||||
}
|
||||
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
|
||||
The API returns the live query object:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"data": {
|
||||
"action_id": "3c42c847-eb30-4452-80e0-728584042334",
|
||||
"@timestamp": "2022-07-26T09:59:32.220Z",
|
||||
"expiration": "2022-07-26T10:04:32.220Z", # after this time no more agents will run the query
|
||||
"type": "INPUT_ACTION",
|
||||
"input_type": "osquery",
|
||||
"agent_ids": [],
|
||||
"agent_all": true,
|
||||
"agent_platforms": [],
|
||||
"agent_policy_ids": [],
|
||||
"agents": ["16d7caf5-efd2-4212-9b62-73dafc91fa13"], # stores the actual queried agent IDs
|
||||
"user_id": "elastic",
|
||||
"metadata": {
|
||||
"execution_context": {
|
||||
"name": "osquery",
|
||||
"url": "/app/osquery/live_queries/new"
|
||||
}
|
||||
},
|
||||
"queries": [
|
||||
{
|
||||
"action_id": "609c4c66-ba3d-43fa-afdd-53e244577aa0", # unique ID of the query, use it when querying the live query API to get the single query results
|
||||
"id": "6724a474-cbba-41ef-a1aa-66aebf0879e2", # ID of the query, doesn't have to be unique
|
||||
"query": "select * from uptime;",
|
||||
"timeout": 120,
|
||||
"ecs_mapping": {
|
||||
"host.uptime": {
|
||||
"field": "total_seconds"
|
||||
}
|
||||
},
|
||||
"agents": [
|
||||
"16d7caf5-efd2-4212-9b62-73dafc91fa13" # stores the actual queried agent IDs
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
|
||||
Run a pack on Darwin-supported agents:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/osquery/live_queries \
|
||||
{
|
||||
"pack_id": "bbe5b070-0c51-11ed-b0f8-ad31b008e832"
|
||||
"agent_platforms": ["darwin"]
|
||||
}
|
||||
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns the live query object:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"data": {
|
||||
"action_id": "3c42c847-eb30-4452-80e0-728584042334",
|
||||
"@timestamp": "2022-07-26T09:59:32.220Z",
|
||||
"expiration": "2022-07-26T10:04:32.220Z", # after this time no more agents will run the query
|
||||
"type": "INPUT_ACTION",
|
||||
"input_type": "osquery",
|
||||
"agent_ids": [],
|
||||
"agent_all": false,
|
||||
"agent_platforms": ["darwin"],
|
||||
"agent_policy_ids": [],
|
||||
"agents": ["16d7caf5-efd2-4212-9b62-73dafc91fa13"], # stores the actual queried agent IDs
|
||||
"user_id": "elastic",
|
||||
"pack_id": "bbe5b070-0c51-11ed-b0f8-ad31b008e832",
|
||||
"pack_name": "test_pack",
|
||||
"pack_prebuilt": false,
|
||||
"metadata": {
|
||||
"execution_context": {
|
||||
"name": "osquery",
|
||||
"url": "/app/osquery/live_queries/new"
|
||||
}
|
||||
},
|
||||
"queries": [
|
||||
{
|
||||
"action_id": "609c4c66-ba3d-43fa-afdd-53e244577aa0", # unique ID of the query, use it when querying the live query API to get the single query results
|
||||
"id": "uptime", # ID of the query, doesn't have to be unique
|
||||
"query": "select * from uptime;",
|
||||
"ecs_mapping": {
|
||||
"host.uptime": {
|
||||
"field": "total_seconds"
|
||||
}
|
||||
},
|
||||
"agents": [
|
||||
"16d7caf5-efd2-4212-9b62-73dafc91fa13" # stores the actual queried agent IDs
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,104 +0,0 @@
|
|||
[[osquery-manager-live-queries-api-get-all]]
|
||||
=== Get live queries API
|
||||
++++
|
||||
<titleabbrev>Get live queries</titleabbrev>
|
||||
++++
|
||||
|
||||
.New API Reference
|
||||
[sidebar]
|
||||
--
|
||||
For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-osquery-api[Osquery APIs].
|
||||
--
|
||||
|
||||
experimental[] Get live queries.
|
||||
|
||||
|
||||
[[osquery-manager-live-queries-api-get-all-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/osquery/live_queries`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space_id>/api/osquery/live_queries`
|
||||
|
||||
|
||||
[[osquery-manager-live-queries-api-get-all-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. When `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
|
||||
[[osquery-manager-live-queries-api-get-all-query-params]]
|
||||
==== Query parameters
|
||||
|
||||
`page`::
|
||||
(Optional, integer) The page number to return. The default is `1`.
|
||||
|
||||
`pageSize`::
|
||||
(Optional, integer) The number of rules to return per page. The default is `20`.
|
||||
|
||||
`sort`::
|
||||
(Optional, string) The field that is used to sort the results. Options include `createdAt` or `updatedAt`.
|
||||
The default is `createdAt`.
|
||||
+
|
||||
NOTE: Even though the JSON case object uses `created_at` and `updated_at`
|
||||
fields, you must use `createdAt` and `updatedAt` fields in the URL
|
||||
query.
|
||||
|
||||
`sortOrder`::
|
||||
(Optional, string) Specified the sort order. Options include `desc` or `asc`.
|
||||
The default is `desc`.
|
||||
|
||||
|
||||
[[osquery-manager-live-queries-api-get-all-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
|
||||
[[osquery-manager-live-queries-api-get-all-example]]
|
||||
==== Example
|
||||
|
||||
Retrieve the last 10 live queries :
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X GET api/osquery/live_queries?page=1&perPage=10
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns a JSON object of the retrieved live queries:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"page": 1,
|
||||
"per_page": 10,
|
||||
"total": 11,
|
||||
"data": [
|
||||
{
|
||||
"action_id": "3c42c847-eb30-4452-80e0-728584042334",
|
||||
"expiration": "2022-07-26T10:04:32.220Z",
|
||||
"@timestamp": "2022-07-26T09:59:32.220Z",
|
||||
"agents": ["16d7caf5-efd2-4212-9b62-73dafc91fa13"],
|
||||
"user_id": "elastic",
|
||||
"queries": [
|
||||
{
|
||||
"action_id": "609c4c66-ba3d-43fa-afdd-53e244577aa0",
|
||||
"id": "6724a474-cbba-41ef-a1aa-66aebf0879e2",
|
||||
"query": "select * from uptime;",
|
||||
"saved_query_id": "42ba9c50-0cc5-11ed-aa1d-2b27890bc90d",
|
||||
"ecs_mapping": {
|
||||
"host.uptime": {
|
||||
"field": "total_seconds"
|
||||
}
|
||||
},
|
||||
"agents": ["16d7caf5-efd2-4212-9b62-73dafc91fa13"],
|
||||
}
|
||||
],
|
||||
},
|
||||
{...}
|
||||
]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,70 +0,0 @@
|
|||
[[osquery-manager-live-queries-api-get-results]]
|
||||
=== Get live query results API
|
||||
++++
|
||||
<titleabbrev>Get live query results</titleabbrev>
|
||||
++++
|
||||
|
||||
.New API Reference
|
||||
[sidebar]
|
||||
--
|
||||
For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-osquery-api[Osquery APIs].
|
||||
--
|
||||
|
||||
experimental[] Retrieve a single live query result by ID.
|
||||
|
||||
|
||||
[[osquery-manager-live-queries-api-get-results-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/osquery/live_queries/<id>/results/<query_action_id>`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space_id>/api/osquery/live_queries/<query_action_id>`
|
||||
|
||||
|
||||
[[osquery-manager-live-queries-api-get-results-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) The space identifier. When `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
`id`::
|
||||
(Required, string) The ID of the live query result you want to retrieve.
|
||||
|
||||
`query_action_id`::
|
||||
(Required, string) The ID of the query action that generated the live query results.
|
||||
|
||||
|
||||
|
||||
[[osquery-manager-live-queries-api-get-results-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
`404`::
|
||||
The specified live query or <query_action_id> doesn't exist.
|
||||
|
||||
|
||||
[[osquery-manager-live-queries-api-get-results-example]]
|
||||
==== Example
|
||||
|
||||
Retrieve the live query results for `3c42c847-eb30-4452-80e0-728584042334` ID and `609c4c66-ba3d-43fa-afdd-53e244577aa0` query action ID:
|
||||
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X GET api/osquery/live_queries/3c42c847-eb30-4452-80e0-728584042334/results/609c4c66-ba3d-43fa-afdd-53e244577aa0
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns a live query action single query result:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"data": {
|
||||
"total": 2,
|
||||
"edges": [{...}, {...}],
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,89 +0,0 @@
|
|||
[[osquery-manager-live-queries-api-get]]
|
||||
=== Get live query API
|
||||
++++
|
||||
<titleabbrev>Get live query</titleabbrev>
|
||||
++++
|
||||
|
||||
.New API Reference
|
||||
[sidebar]
|
||||
--
|
||||
For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-osquery-api[Osquery APIs].
|
||||
--
|
||||
|
||||
experimental[] Retrieves a single live query by ID.
|
||||
|
||||
|
||||
[[osquery-manager-live-queries-api-get-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/osquery/live_queries/<id>`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space_id>/api/osquery/live_queries/<id>`
|
||||
|
||||
|
||||
[[osquery-manager-live-queries-api-get-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) The space identifier. When `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
`id`::
|
||||
(Required, string) The ID of the live query you want to retrieve.
|
||||
|
||||
|
||||
[[osquery-manager-live-queries-api-get-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
`404`::
|
||||
The specified live query and ID doesn't exist.
|
||||
|
||||
|
||||
[[osquery-manager-live-queries-api-get-example]]
|
||||
==== Example
|
||||
|
||||
Retrieve the live query object with the `bbe5b070-0c51-11ed-b0f8-ad31b008e832` ID:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X GET api/osquery/live_queries/bbe5b070-0c51-11ed-b0f8-ad31b008e832
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns a live query object:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"data": {
|
||||
"action_id": "3c42c847-eb30-4452-80e0-728584042334",
|
||||
"expiration": "2022-07-26T10:04:32.220Z",
|
||||
"@timestamp": "2022-07-26T09:59:32.220Z",
|
||||
"agents": ["16d7caf5-efd2-4212-9b62-73dafc91fa13"],
|
||||
"user_id": "elastic",
|
||||
"queries": [
|
||||
{
|
||||
"action_id": "609c4c66-ba3d-43fa-afdd-53e244577aa0",
|
||||
"id": "6724a474-cbba-41ef-a1aa-66aebf0879e2",
|
||||
"query": "select * from uptime;",
|
||||
"saved_query_id": "42ba9c50-0cc5-11ed-aa1d-2b27890bc90d",
|
||||
"ecs_mapping": {
|
||||
"host.uptime": {
|
||||
"field": "total_seconds"
|
||||
}
|
||||
},
|
||||
"agents": ["16d7caf5-efd2-4212-9b62-73dafc91fa13"],
|
||||
"docs": 0, # results count
|
||||
"failed": 1, # failed queries
|
||||
"pending": 0, # pending agents
|
||||
"responded": 1, # total responded agents
|
||||
"successful": 0, # successful agents
|
||||
"status": "completed" # single query status
|
||||
}
|
||||
],
|
||||
"status": "completed" # global status of the live query (completed, pending)
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,105 +0,0 @@
|
|||
[[osquery-manager-packs-api-create]]
|
||||
=== Create pack API
|
||||
++++
|
||||
<titleabbrev>Create pack</titleabbrev>
|
||||
++++
|
||||
|
||||
.New API Reference
|
||||
[sidebar]
|
||||
--
|
||||
For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-osquery-api[Osquery APIs].
|
||||
--
|
||||
|
||||
experimental[] Create packs.
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-create-request]]
|
||||
==== Request
|
||||
|
||||
`POST <kibana host>:<port>/api/osquery/packs`
|
||||
|
||||
`POST <kibana host>:<port>/s/<space_id>/api/osquery/packs`
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-create-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) The space identifier. When `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-create-body-params]]
|
||||
==== Request body
|
||||
|
||||
`name`:: (Required, string) The pack name.
|
||||
|
||||
`description`:: (Optional, string) The pack description.
|
||||
|
||||
`enabled`:: (Optional, boolean) Enables the pack.
|
||||
|
||||
`policy_ids`:: (Optional, array) A list of agents policy IDs.
|
||||
|
||||
`shards`:: (Optional, object) An object with shard configuration for policies included in the pack. For each policy, set the shard configuration to a percentage (1–100) of target hosts.
|
||||
|
||||
`queries`:: (Required, object) An object of queries.
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-create-request-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-create-example]]
|
||||
==== Examples
|
||||
|
||||
Create a pack:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/osquery/packs \
|
||||
{
|
||||
"name": "my_pack",
|
||||
"description": "My pack",
|
||||
"enabled": true,
|
||||
"policy_ids": [
|
||||
"my_policy_id",
|
||||
"fleet-server-policy"
|
||||
],
|
||||
"shards": {
|
||||
"my_policy_id": 35,
|
||||
"fleet-server-policy": 58
|
||||
},
|
||||
"queries": {
|
||||
"my_query": {
|
||||
"query": "SELECT * FROM listening_ports;",
|
||||
"interval": 60,
|
||||
"timeout": 120,
|
||||
"ecs_mapping": {
|
||||
"client.port": {
|
||||
"field": "port"
|
||||
},
|
||||
"tags": {
|
||||
"value": [
|
||||
"tag1",
|
||||
"tag2"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
|
||||
The API returns the pack object:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"data": {...}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,51 +0,0 @@
|
|||
[[osquery-manager-packs-api-delete]]
|
||||
=== Delete pack API
|
||||
++++
|
||||
<titleabbrev>Delete pack</titleabbrev>
|
||||
++++
|
||||
|
||||
.New API Reference
|
||||
[sidebar]
|
||||
--
|
||||
For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-osquery-api[Osquery APIs].
|
||||
--
|
||||
|
||||
experimental[] Delete packs.
|
||||
|
||||
WARNING: Once you delete a pack, _it cannot be recovered_.
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-delete-request]]
|
||||
==== Request
|
||||
|
||||
`DELETE <kibana host>:<port>/api/osquery/packs/<id>`
|
||||
|
||||
`DELETE <kibana host>:<port>/s/<space_id>/api/osquery/packs/<id>`
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-delete-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) The space identifier. When `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
`id`::
|
||||
(Required, string) The ID of the pack you want to delete.
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-delete-response-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates that the pack is deleted. Returns an empty response body.
|
||||
|
||||
[[osquery-manager-packs-api-delete-example]]
|
||||
==== Example
|
||||
|
||||
Delete a pack object with the `bbe5b070-0c51-11ed-b0f8-ad31b008e832` ID:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X DELETE api/osquery/packs/bbe5b070-0c51-11ed-b0f8-ad31b008e832
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
|
@ -1,113 +0,0 @@
|
|||
[[osquery-manager-packs-api-get-all]]
|
||||
=== Get packs API
|
||||
++++
|
||||
<titleabbrev>Get packs</titleabbrev>
|
||||
++++
|
||||
|
||||
.New API Reference
|
||||
[sidebar]
|
||||
--
|
||||
For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-osquery-api[Osquery APIs].
|
||||
--
|
||||
|
||||
experimental[] Get packs.
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-get-all-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/osquery/packs`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space_id>/api/osquery/packs`
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-get-all-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) The space identifier. When `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
[[osquery-manager-packs-api-get-all-query-params]]
|
||||
==== Query parameters
|
||||
|
||||
`page`::
|
||||
(Optional, integer) The page number to return. The default is `1`.
|
||||
|
||||
`pageSize`::
|
||||
(Optional, integer) The number of rules to return per page. The default is `20`.
|
||||
|
||||
`sort`::
|
||||
(Optional, string) Specifies the field that sorts the results. Options include `createdAt` or `updatedAt`.
|
||||
The default is `createdAt`.
|
||||
+
|
||||
NOTE: Even though the JSON case object uses the `created_at` and `updated_at`
|
||||
fields, you must use `createdAt` and `updatedAt` fields in the URL
|
||||
query.
|
||||
|
||||
`sortOrder`::
|
||||
(Optional, string) Specifies the sort order. Options include `desc` or `asc`.
|
||||
The default is `desc`.
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-get-all-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-get-all-example]]
|
||||
==== Example
|
||||
|
||||
Retrieve the first 10 packs:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X GET api/osquery/packs?page=1&perPage=10&sortField=updatedAt&sortOrder=asc
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns a JSON object with the retrieved packs:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"page": 1,
|
||||
"per_page": 10,
|
||||
"total": 11,
|
||||
"data": [
|
||||
{
|
||||
"type": "osquery-pack",
|
||||
"id": "bbe5b070-0c51-11ed-b0f8-ad31b008e832",
|
||||
"namespaces": ["default"],
|
||||
"attributes": {
|
||||
"name": "test_pack",
|
||||
"queries": [
|
||||
{
|
||||
"query": "select * from uptime",
|
||||
"interval": 3600,
|
||||
"id": "uptime",
|
||||
"ecs_mapping": [
|
||||
{
|
||||
"value": {
|
||||
"field": "days"
|
||||
},
|
||||
"key": "message"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"enabled": true,
|
||||
"created_at": "2022-07-25T19:41:10.263Z",
|
||||
"created_by": "elastic",
|
||||
"updated_at": "2022-07-25T20:12:01.455Z",
|
||||
"updated_by": "elastic",
|
||||
"description": ""
|
||||
},
|
||||
"policy_ids": []
|
||||
},
|
||||
{...}
|
||||
]
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,88 +0,0 @@
|
|||
[[osquery-manager-packs-api-get]]
|
||||
=== Get pack API
|
||||
++++
|
||||
<titleabbrev>Get pack</titleabbrev>
|
||||
++++
|
||||
|
||||
.New API Reference
|
||||
[sidebar]
|
||||
--
|
||||
For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-osquery-api[Osquery APIs].
|
||||
--
|
||||
|
||||
experimental[] Retrieve a single pack by ID.
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-get-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/osquery/packs/<id>`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space_id>/api/osquery/packs/<id>`
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-get-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) The space identifier. When `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
`id`::
|
||||
(Required, string) The ID of the pack you want to retrieve.
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-get-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
`404`::
|
||||
The specified pack and ID doesn't exist.
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-get-example]]
|
||||
==== Example
|
||||
|
||||
Retrieve the pack object with the `bbe5b070-0c51-11ed-b0f8-ad31b008e832` ID:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X GET api/osquery/packs/bbe5b070-0c51-11ed-b0f8-ad31b008e832
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns the pack object:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"data": {
|
||||
"id": "bbe5b070-0c51-11ed-b0f8-ad31b008e832",
|
||||
"type": "osquery-pack",
|
||||
"namespaces": [
|
||||
"default"
|
||||
],
|
||||
"updated_at": "2022-07-25T20:12:01.455Z",
|
||||
"name": "test_pack",
|
||||
"queries": {
|
||||
"uptime": {
|
||||
"interval": 3600,
|
||||
"query": "select * from uptime",
|
||||
"ecs_mapping": {
|
||||
"message": {
|
||||
"field": "days"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"enabled": true,
|
||||
"created_at": "2022-07-25T19:41:10.263Z",
|
||||
"created_by": "elastic",
|
||||
"updated_by": "elastic",
|
||||
"description": "",
|
||||
"policy_ids": [],
|
||||
"read_only": false # true for prebuilt packs
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,82 +0,0 @@
|
|||
[[osquery-manager-packs-api-update]]
|
||||
=== Update pack API
|
||||
++++
|
||||
<titleabbrev>Update pack</titleabbrev>
|
||||
++++
|
||||
|
||||
.New API Reference
|
||||
[sidebar]
|
||||
--
|
||||
For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-osquery-api[Osquery APIs].
|
||||
--
|
||||
|
||||
experimental[] Update packs.
|
||||
|
||||
WARNING: You are unable to update a prebuilt pack (`read_only = true`).
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-update-request]]
|
||||
==== Request
|
||||
|
||||
`PUT <kibana host>:<port>/api/osquery/packs/<id>`
|
||||
|
||||
`PUT <kibana host>:<port>/s/<space_id>/api/osquery/packs/<id>`
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-update-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) The space identifier. When `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
`id`::
|
||||
(Required, string) The ID of the pack you want to update.
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-update-body-params]]
|
||||
==== Request body
|
||||
|
||||
`name`:: (Optional, string) The pack name.
|
||||
|
||||
`description`:: (Optional, string) The pack description.
|
||||
|
||||
`enabled`:: (Optional, boolean) Enables the pack.
|
||||
|
||||
`policy_ids`:: (Optional, array) A list of agent policy IDs.
|
||||
|
||||
`shards`:: (Optional, object) An object with shard configuration for policies included in the pack. For each policy, set the shard configuration to a percentage (1–100) of target hosts.
|
||||
|
||||
`queries`:: (Required, object) An object of queries.
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-update-request-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
|
||||
[[osquery-manager-packs-api-update-example]]
|
||||
==== Examples
|
||||
|
||||
Update a name of the <my_pack> pack:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X PUT api/osquery/packs/<id> \
|
||||
{
|
||||
"name": "updated_my_pack_name",
|
||||
}
|
||||
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
|
||||
The API returns the pack saved object:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"data": {...}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,92 +0,0 @@
|
|||
[[osquery-manager-saved-queries-api-create]]
|
||||
=== Create saved query API
|
||||
++++
|
||||
<titleabbrev>Create saved query</titleabbrev>
|
||||
++++
|
||||
|
||||
.New API Reference
|
||||
[sidebar]
|
||||
--
|
||||
For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-osquery-api[Osquery APIs].
|
||||
--
|
||||
|
||||
experimental[] Create saved queries.
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-create-request]]
|
||||
==== Request
|
||||
|
||||
`POST <kibana host>:<port>/api/osquery/saved_queries`
|
||||
|
||||
`POST <kibana host>:<port>/s/<space_id>/api/osquery/saved_queries`
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-create-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) The space identifier. When `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-create-body-params]]
|
||||
==== Request body
|
||||
|
||||
`id`:: (Required, string) The saved query name.
|
||||
|
||||
`description`:: (Optional, string) The saved query description.
|
||||
|
||||
`platform`:: (Optional, string) Restricts the query to a specified platform. The default is 'all' platforms. To specify multiple platforms, use commas. For example, 'linux,darwin'.
|
||||
|
||||
`query`:: (Required, string) The SQL query you want to run.
|
||||
|
||||
`version`:: (Optional, string) Uses the Osquery versions greater than or equal to the specified version string.
|
||||
|
||||
`interval`:: (Optional, string) An interval, in seconds, on which to run the query.
|
||||
|
||||
`ecs_mapping`:: (Optional, object) Maps Osquery results columns or static values to ECS fields.
|
||||
|
||||
`timeout`:: (Optional, number) A timeout period, in seconds, after which the query will stop running. Overwriting the default timeout allows you to support queries that require more time to complete. The default and minimum supported value is `60`. The maximum supported value is `900`.
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-create-request-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-create-example]]
|
||||
==== Examples
|
||||
|
||||
Create a saved query:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/osquery/saved_queries \
|
||||
{
|
||||
"id": "saved_query_id",
|
||||
"description": "Saved query description",
|
||||
"query": "select * from uptime;",
|
||||
"interval": "60",
|
||||
"timeout": 120,
|
||||
"version": "2.8.0",
|
||||
"platform": "linux,darwin",
|
||||
"ecs_mapping": {
|
||||
"host.uptime": {
|
||||
"field": "total_seconds"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
|
||||
The API returns the saved query object:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"data": {...}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,51 +0,0 @@
|
|||
[[osquery-manager-saved-queries-api-delete]]
|
||||
=== Delete saved query API
|
||||
++++
|
||||
<titleabbrev>Delete saved query</titleabbrev>
|
||||
++++
|
||||
|
||||
.New API Reference
|
||||
[sidebar]
|
||||
--
|
||||
For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-osquery-api[Osquery APIs].
|
||||
--
|
||||
|
||||
experimental[] Delete saved queries.
|
||||
|
||||
WARNING: Once you delete a saved query, _it cannot be recovered_.
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-delete-request]]
|
||||
==== Request
|
||||
|
||||
`DELETE <kibana host>:<port>/api/osquery/saved_queries/<id>`
|
||||
|
||||
`DELETE <kibana host>:<port>/s/<space_id>/api/osquery/saved_queries/<id>`
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-delete-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) The space identifier. When `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
`id`::
|
||||
(Required, string) The ID of the saved query you want to delete.
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-delete-response-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates the saved query is deleted. Returns an empty response body.
|
||||
|
||||
[[osquery-manager-saved-queries-api-delete-example]]
|
||||
==== Example
|
||||
|
||||
Delete a saved query object with the `42ba9c50-0cc5-11ed-aa1d-2b27890bc90d` ID:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X DELETE api/osquery/saved_queries/42ba9c50-0cc5-11ed-aa1d-2b27890bc90d
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
|
@ -1,105 +0,0 @@
|
|||
[[osquery-manager-saved-queries-api-get-all]]
|
||||
=== Get saved-queries API
|
||||
++++
|
||||
<titleabbrev>Get saved-queries</titleabbrev>
|
||||
++++
|
||||
|
||||
.New API Reference
|
||||
[sidebar]
|
||||
--
|
||||
For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-osquery-api[Osquery APIs].
|
||||
--
|
||||
|
||||
experimental[] Get saved queries.
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-get-all-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/osquery/saved_queries`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space_id>/api/osquery/saved_queries`
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-get-all-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) The space identifier. When `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
[[osquery-manager-saved-queries-api-get-all-query-params]]
|
||||
==== Query parameters
|
||||
|
||||
`page`::
|
||||
(Optional, integer) The page number to return. The default is `1`.
|
||||
|
||||
`pageSize`::
|
||||
(Optional, integer) The number of rules to return per page. The default is `20`.
|
||||
|
||||
`sort`::
|
||||
(Optional, string) Specifies the field that sorts the results.
|
||||
Options include `createdAt` or `updatedAt`. The default is `createdAt`.
|
||||
+
|
||||
NOTE: Even though the JSON case object uses the `created_at` and `updated_at`
|
||||
fields, you must use `createdAt` and `updatedAt` fields in the URL
|
||||
query.
|
||||
|
||||
`sortOrder`::
|
||||
(Optional, string) Determines the sort order. Options include `desc` or `asc`.
|
||||
The default is `desc`.
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-get-all-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-get-all-example]]
|
||||
==== Example
|
||||
|
||||
Retrieve the first 10 saved queries:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X GET api/osquery/saved-queries?page=1&perPage=10&sortField=updatedAt&sortOrder=asc
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns a JSON object of the retrieved saved queries:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"page": 1,
|
||||
"per_page": 100,
|
||||
"total": 11,
|
||||
"data": [
|
||||
{
|
||||
"type": "osquery-saved-query",
|
||||
"id": "42ba9c50-0cc5-11ed-aa1d-2b27890bc90d",
|
||||
"namespaces": ["default"],
|
||||
"attributes": {
|
||||
"id": "saved_query_id",
|
||||
"description": "Saved query description",
|
||||
"query": "select * from uptime;",
|
||||
"platform": "linux,darwin",
|
||||
"version": "2.8.0",
|
||||
"interval": "60",
|
||||
"ecs_mapping": {
|
||||
"host.uptime": {
|
||||
"field": "total_seconds"
|
||||
}
|
||||
},
|
||||
"created_by": "elastic",
|
||||
"created_at": "2022-07-26T09:28:08.597Z",
|
||||
"updated_by": "elastic",
|
||||
"updated_at": "2022-07-26T09:28:08.597Z",
|
||||
"prebuilt": false
|
||||
},
|
||||
},
|
||||
{...}
|
||||
]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,90 +0,0 @@
|
|||
[[osquery-manager-saved-queries-api-get]]
|
||||
=== Get saved query API
|
||||
++++
|
||||
<titleabbrev>Get saved query</titleabbrev>
|
||||
++++
|
||||
|
||||
.New API Reference
|
||||
[sidebar]
|
||||
--
|
||||
For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-osquery-api[Osquery APIs].
|
||||
--
|
||||
|
||||
experimental[] Retrieve a single saved query by ID.
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-get-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/osquery/saved_queries/<id>`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space_id>/api/osquery/saved_queries/<id>`
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-get-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) The space identifier. When `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
`id`::
|
||||
(Required, string) The ID of the saved query you want to retrieve.
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-get-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
`404`::
|
||||
The specified saved query and ID doesn't exist.
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-get-example]]
|
||||
==== Example
|
||||
|
||||
Retrieve the saved query object with the `42ba9c50-0cc5-11ed-aa1d-2b27890bc90d` ID:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X GET api/osquery/saved_queries/42ba9c50-0cc5-11ed-aa1d-2b27890bc90d
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns the saved query object:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"data": {
|
||||
"id": "42ba9c50-0cc5-11ed-aa1d-2b27890bc90d",
|
||||
"type": "osquery-saved-query",
|
||||
"namespaces": [
|
||||
"default"
|
||||
],
|
||||
"updated_at": "2022-07-26T09:28:08.600Z",
|
||||
"version": "WzQzMTcsMV0=",
|
||||
"attributes": {
|
||||
"id": "saved_query_id",
|
||||
"description": "Saved query description",
|
||||
"query": "select * from uptime;",
|
||||
"platform": "linux,darwin",
|
||||
"version": "2.8.0",
|
||||
"interval": "60",
|
||||
"ecs_mapping": {
|
||||
"host.uptime": {
|
||||
"field": "total_seconds"
|
||||
}
|
||||
},
|
||||
"created_by": "elastic",
|
||||
"created_at": "2022-07-26T09:28:08.597Z",
|
||||
"updated_by": "elastic",
|
||||
"updated_at": "2022-07-26T09:28:08.597Z",
|
||||
"prebuilt": false
|
||||
},
|
||||
"references": [],
|
||||
"coreMigrationVersion": "8.4.0"
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,84 +0,0 @@
|
|||
[[osquery-manager-saved-queries-api-update]]
|
||||
=== Update saved query API
|
||||
++++
|
||||
<titleabbrev>Update saved query</titleabbrev>
|
||||
++++
|
||||
|
||||
.New API Reference
|
||||
[sidebar]
|
||||
--
|
||||
For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-osquery-api[Osquery APIs].
|
||||
--
|
||||
|
||||
experimental[] Update saved queries.
|
||||
|
||||
WARNING: You are unable to update a prebuilt saved query (`prebuilt = true`).
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-update-request]]
|
||||
==== Request
|
||||
|
||||
`PUT <kibana host>:<port>/api/osquery/saved_queries/<id>`
|
||||
|
||||
`PUT <kibana host>:<port>/s/<space_id>/api/osquery/saved_queries/<id>`
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-update-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) The space identifier. When `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
`id`::
|
||||
(Required, string) The ID of the saved query you want to update.
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-update-body-params]]
|
||||
==== Request body
|
||||
|
||||
`id`:: (Required, string) The saved query name.
|
||||
|
||||
`description`:: (Optional, string) The saved query description.
|
||||
|
||||
`platform`:: (Optional, string) Restricts the query to a specified platform. The default is 'all' platforms. To specify multiple platforms, use commas. For example, 'linux,darwin'.
|
||||
|
||||
`query`:: (Required, string) The SQL query you want to run.
|
||||
|
||||
`version`:: (Optional, string) Runs on Osquery versions greater than or equal to the specified version string.
|
||||
|
||||
`interval`:: (Optional, integer) The interval, in seconds, to run the query.
|
||||
|
||||
`ecs_mapping`:: (Optional, object) Maps Osquery result columns or static values to ECS fields.
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-update-request-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
|
||||
[[osquery-manager-saved-queries-api-update-example]]
|
||||
==== Examples
|
||||
|
||||
Update a name of the <my_saved query> saved query:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X PUT api/osquery/saved_queries/<id> \
|
||||
{
|
||||
"id": "updated_my_saved_query_name",
|
||||
}
|
||||
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
|
||||
The API returns the saved query saved object:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"data": {...}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
[[role-management-api]]
|
||||
== {kib} role management APIs
|
||||
|
||||
Manage the roles that grant <<kibana-privileges, {kib} privileges>>.
|
||||
|
||||
WARNING: Do not use the {ref}/security-api.html#security-role-apis[{es} role management APIs] to manage {kib} roles.
|
||||
|
||||
For the latest API details, refer to {api-kibana}/group/endpoint-roles[role APIs].
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
[[saved-objects-api]]
|
||||
== Saved objects APIs
|
||||
|
||||
For the latest details, refer to the {api-kibana}/group/endpoint-saved-objects[saved objects API].
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
[role="xpack"]
|
||||
[[session-management-api]]
|
||||
== User session management APIs
|
||||
|
||||
The following <<xpack-security-session-management, user session>> management APIs are available:
|
||||
|
||||
* <<session-management-api-invalidate, Invalidate user sessions API>> to invalidate user sessions
|
||||
|
||||
include::session-management/invalidate.asciidoc[]
|
||||
|
|
@ -1,114 +0,0 @@
|
|||
[[session-management-api-invalidate]]
|
||||
=== Invalidate user sessions API
|
||||
++++
|
||||
<titleabbrev>Invalidate user sessions</titleabbrev>
|
||||
++++
|
||||
|
||||
experimental[] Invalidates user sessions that match provided query.
|
||||
|
||||
[[session-management-api-invalidate-prereqs]]
|
||||
==== Prerequisite
|
||||
|
||||
To use the invalidate user sessions API, you must be a `superuser`.
|
||||
|
||||
[[session-management-api-invalidate-request]]
|
||||
==== Request
|
||||
|
||||
`POST <kibana host>:<port>/api/security/session/_invalidate`
|
||||
|
||||
[role="child_attributes"]
|
||||
[[session-management-api-invalidate-request-body]]
|
||||
==== Request body
|
||||
|
||||
`match`::
|
||||
(Required, string) Specifies how {kib} determines which sessions to invalidate. Can either be `all` to invalidate all existing sessions, or `query` to only invalidate sessions that match the query specified in the additional `query` parameter.
|
||||
|
||||
`query`::
|
||||
(Optional, object) Specifies the query that {kib} uses to match the sessions to invalidate when the `match` parameter is set to `query`. You cannot use this parameter if `match` is set to `all`.
|
||||
+
|
||||
.Properties of `query`
|
||||
[%collapsible%open]
|
||||
=====
|
||||
`provider` :::
|
||||
(Required, object) Describes the <<authentication-security-settings, authentication providers>> for which to invalidate sessions.
|
||||
|
||||
`type` ::::
|
||||
(Required, string) The authentication provider `type`.
|
||||
|
||||
`name` ::::
|
||||
(Optional, string) The authentication provider `name`.
|
||||
|
||||
`username` :::
|
||||
(Optional, string) The username for which to invalidate sessions.
|
||||
=====
|
||||
|
||||
[[session-management-api-invalidate-response-body]]
|
||||
==== Response body
|
||||
|
||||
`total`::
|
||||
(number) The number of successfully invalidated sessions.
|
||||
|
||||
[[session-management-api-invalidate-response-codes]]
|
||||
==== Response codes
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
`403`::
|
||||
Indicates that the user may not be authorized to invalidate sessions for other users. Refer to <<session-management-api-invalidate-prereqs, prerequisites>>.
|
||||
|
||||
==== Examples
|
||||
|
||||
Invalidate all existing sessions:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/security/session/_invalidate
|
||||
{
|
||||
"match" : "all"
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
Invalidate sessions that were created by any <<saml, SAML authentication provider>>:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/security/session/_invalidate
|
||||
{
|
||||
"match" : "query",
|
||||
"query": {
|
||||
"provider" : { "type": "saml" }
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
Invalidate sessions that were created by the <<saml, SAML authentication provider>> with the name `saml1`:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/security/session/_invalidate
|
||||
{
|
||||
"match" : "query",
|
||||
"query": {
|
||||
"provider" : { "type": "saml", "name": "saml1" }
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
Invalidate sessions that were created by any <<oidc, OpenID Connect authentication provider>> for the user with the username `user@my-oidc-sso.com`:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/security/session/_invalidate
|
||||
{
|
||||
"match" : "query",
|
||||
"query": {
|
||||
"provider" : { "type": "oidc" },
|
||||
"username": "user@my-oidc-sso.com"
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
|
@ -1,16 +0,0 @@
|
|||
[[short-urls-api]]
|
||||
== Short URLs APIs
|
||||
|
||||
experimental[] Manage {kib} short URLs.
|
||||
|
||||
The following short urls APIs are available:
|
||||
|
||||
* <<short-urls-api-create, Create short URL API>>
|
||||
* <<short-urls-api-get, Get short URL API>>
|
||||
* <<short-urls-api-delete, Delete short URL API>>
|
||||
* <<short-urls-api-resolve, Resolve short URL API>>
|
||||
|
||||
include::short-urls/create-short-url.asciidoc[]
|
||||
include::short-urls/get-short-url.asciidoc[]
|
||||
include::short-urls/delete-short-url.asciidoc[]
|
||||
include::short-urls/resolve-short-url.asciidoc[]
|
||||
|
|
@ -1,86 +0,0 @@
|
|||
[[short-urls-api-create]]
|
||||
=== Create short URL API
|
||||
++++
|
||||
<titleabbrev>Create short URL</titleabbrev>
|
||||
++++
|
||||
|
||||
experimental[] Create a {kib} short URL. {kib} URLs may be long and cumbersome, short URLs are much
|
||||
easier to remember and share.
|
||||
|
||||
Short URLs are created by specifying the locator ID and locator parameters. When a short URL is
|
||||
resolved, the locator ID and locator parameters are used to redirect user to the right {kib} page.
|
||||
|
||||
|
||||
[[short-urls-api-create-request]]
|
||||
==== Request
|
||||
|
||||
`POST <kibana host>:<port>/api/short_url`
|
||||
|
||||
|
||||
[[short-urls-api-create-request-body]]
|
||||
==== Request body
|
||||
|
||||
`locatorId`::
|
||||
(Required, string) ID of the locator.
|
||||
|
||||
`params`::
|
||||
(Required, object) Object which contains all necessary parameters for the given locator to resolve
|
||||
to a {kib} location.
|
||||
+
|
||||
WARNING: When you create a short URL, locator params are not validated, which allows you to pass
|
||||
arbitrary and ill-formed data into the API that can break {kib}. Make sure
|
||||
any data that you send to the API is properly formed.
|
||||
|
||||
`slug`::
|
||||
(Optional, string) A custom short URL slug. Slug is the part of the short URL that identifies it.
|
||||
You can provide a custom slug which consists of latin alphabet letters, numbers and `-._`
|
||||
characters. The slug must be at least 3 characters long, but no longer than 255 characters.
|
||||
|
||||
`humanReadableSlug`::
|
||||
(Optional, boolean) When the `slug` parameter is omitted, the API will generate a random
|
||||
human-readable slug, if `humanReadableSlug` is set to `true`.
|
||||
|
||||
|
||||
[[short-urls-api-create-response-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
|
||||
[[short-urls-api-create-example]]
|
||||
==== Example
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/short_url -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d '
|
||||
{
|
||||
"locatorId": "LOCATOR_ID",
|
||||
"params": {},
|
||||
"humanReadableSlug": true
|
||||
}'
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns the following:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", <1>
|
||||
"slug": "adjective-adjective-noun", <2>
|
||||
"locator": {
|
||||
"id": "LOCATOR_ID",
|
||||
"version": "x.x.x", <3>
|
||||
"state": {} <4>
|
||||
},
|
||||
"accessCount": 0,
|
||||
"accessDate": 1632680100000,
|
||||
"createDate": 1632680100000
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
<1> A random ID is automatically generated.
|
||||
<2> A random human-readable slug is automatically generated if the `humanReadableSlug` parameter is set to `true`. If set to `false` a random short string is generated.
|
||||
<3> The version of {kib} when short URL was created is stored.
|
||||
<4> Locator params provided as `params` property are stored.
|
||||
|
|
@ -1,39 +0,0 @@
|
|||
[[short-urls-api-delete]]
|
||||
=== Delete short URL API
|
||||
++++
|
||||
<titleabbrev>Delete short URL</titleabbrev>
|
||||
++++
|
||||
|
||||
experimental[] Delete a {kib} short URL.
|
||||
|
||||
|
||||
[[short-urls-api-delete-request]]
|
||||
==== Request
|
||||
|
||||
`DELETE <kibana host>:<port>/api/short_url/<id>`
|
||||
|
||||
|
||||
[[short-urls-api-delete-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`id`::
|
||||
(Required, string) The short URL ID that you want to remove.
|
||||
|
||||
|
||||
[[short-urls-api-delete-response-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
|
||||
[[short-urls-api-delete-example]]
|
||||
==== Example
|
||||
|
||||
Delete a short URL `12345` ID:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X DELETE api/short_url/12345
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
|
@ -1,56 +0,0 @@
|
|||
[[short-urls-api-get]]
|
||||
=== Get short URL API
|
||||
++++
|
||||
<titleabbrev>Get short URL</titleabbrev>
|
||||
++++
|
||||
|
||||
experimental[] Retrieve a single {kib} short URL.
|
||||
|
||||
[[short-urls-api-get-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/short_url/<id>`
|
||||
|
||||
|
||||
[[short-urls-api-get-params]]
|
||||
==== Path parameters
|
||||
|
||||
`id`::
|
||||
(Required, string) The ID of the short URL.
|
||||
|
||||
|
||||
[[short-urls-api-get-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
|
||||
[[short-urls-api-get-example]]
|
||||
==== Example
|
||||
|
||||
Retrieve the short URL with the `12345` ID:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X GET api/short_url/12345
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns the following:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"id": "12345",
|
||||
"slug": "adjective-adjective-noun",
|
||||
"locator": {
|
||||
"id": "LOCATOR_ID",
|
||||
"version": "x.x.x",
|
||||
"state": {}
|
||||
},
|
||||
"accessCount": 0,
|
||||
"accessDate": 1632680100000,
|
||||
"createDate": 1632680100000
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,56 +0,0 @@
|
|||
[[short-urls-api-resolve]]
|
||||
=== Resolve short URL API
|
||||
++++
|
||||
<titleabbrev>Resolve short URL</titleabbrev>
|
||||
++++
|
||||
|
||||
experimental[] Resolve a single {kib} short URL by its slug.
|
||||
|
||||
[[short-urls-api-resolve-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/short_url/_slug/<slug>`
|
||||
|
||||
|
||||
[[short-urls-api-resolve-params]]
|
||||
==== Path parameters
|
||||
|
||||
`slug`::
|
||||
(Required, string) The slug of the short URL.
|
||||
|
||||
|
||||
[[short-urls-api-resolve-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
|
||||
[[short-urls-api-resolve-example]]
|
||||
==== Example
|
||||
|
||||
Retrieve the short URL with the `hello-world` ID:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X GET api/short_url/_slug/hello-world
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns the following:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"id": "12345",
|
||||
"slug": "hello-world",
|
||||
"locator": {
|
||||
"id": "LOCATOR_ID",
|
||||
"version": "x.x.x",
|
||||
"state": {}
|
||||
},
|
||||
"accessCount": 0,
|
||||
"accessDate": 1632680100000,
|
||||
"createDate": 1632680100000
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
[[spaces-api]]
|
||||
== {kib} spaces APIs
|
||||
|
||||
For the latest details, refer to {api-kibana}/group/endpoint-spaces[spaces APIs].
|
||||
|
|
@ -1,245 +0,0 @@
|
|||
[[add-monitor-api]]
|
||||
== Add Monitor API
|
||||
++++
|
||||
<titleabbrev>Add monitor</titleabbrev>
|
||||
++++
|
||||
|
||||
Creates a new monitor with the specified attributes. A monitor can be one of the following types: HTTP, TCP, ICMP, or Browser. The required and default fields may vary based on the monitor type.
|
||||
|
||||
=== {api-request-title}
|
||||
|
||||
`POST <kibana host>:<port>/api/synthetics/monitors`
|
||||
|
||||
`POST <kibana host>:<port>/s/<space_id>/api/synthetics/monitors`
|
||||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `all` privileges for the *Synthetics* feature in the *{observability}* section of the
|
||||
<<kibana-feature-privileges,{kib} feature privileges>>.
|
||||
|
||||
[[monitor-request-body]]
|
||||
==== Request Body
|
||||
|
||||
The request body should contain the attributes of the monitor you want to create. The required and default fields differ depending on the monitor type:
|
||||
|
||||
*Common Fields*:
|
||||
|
||||
`name`:: (Required, string): The monitor's name.
|
||||
|
||||
`type`:: (Required, string): The monitor type (e.g., `http` , `tcp` , `icmp` or `browser`).
|
||||
|
||||
`schedule`:: (Optional, number): The monitor's schedule in minutes. Supported values are `1`, `3`, `5`, `10`, `15`, `30`, `60`, `120` and `240`.
|
||||
* The default value is `3` minutes for HTTP, TCP, and ICMP monitors.
|
||||
|
||||
* The default value is `10` minutes for Browser monitors.
|
||||
|
||||
:private-locations-url: https://www.elastic.co/guide/en/observability/current/synthetics-private-location.html
|
||||
|
||||
`locations`:: (https://github.com/elastic/synthetics/blob/main/src/locations/public-locations.ts#L28-L37[`Array<SyntheticsLocationsType>`])
|
||||
Where to deploy the monitor. Monitors can be deployed in multiple locations so that you can detect differences in availability and response times across those locations.
|
||||
+
|
||||
To list available locations you can:
|
||||
+
|
||||
* Run the {locations-command}[`elastic-synthetics locations`] command
|
||||
with the deployment's {kib} URL.
|
||||
* Go to *Synthetics* -> *Management* and click *Create monitor*.
|
||||
Locations will be listed in _Locations_.
|
||||
|
||||
`private_locations` (`Array<string>`)::
|
||||
|
||||
The {private-locations-url}[Private Locations] to which the monitors will be deployed. These Private Locations refer to locations hosted and managed by you, whereas
|
||||
`locations` are hosted by Elastic. You can specify a Private Location using the location's name.
|
||||
+
|
||||
To list available Private Locations you can:
|
||||
+
|
||||
* Run the {locations-command}[`elastic-synthetics locations`] command
|
||||
with the deployment's {kib} URL.
|
||||
* Go to *Synthetics* -> *Settings* and click *Private locations*.
|
||||
Private Locations will be listed in the table.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
You may provide `locations` or `private_locations`, or both. At least one is required.
|
||||
====
|
||||
|
||||
|
||||
`enabled`:: (Optional, boolean, default: true): Whether the monitor is enabled.
|
||||
|
||||
`tags`:: (Optional, array of strings): An array of tags.
|
||||
|
||||
`alert`:: (Optional, object, default: `{ status: { enabled: true }, tls: { enabled: true } }`): Alert configuration.
|
||||
|
||||
`service.name`:: (Optional, string): The APM service name.
|
||||
|
||||
`timeout`:: (Optional, number, default: 16): The monitor timeout in seconds, monitor will fail if it doesn't complete within this time.
|
||||
|
||||
`namespace`:: (Optional, string, default: "default"): The namespace field should be lowercase and not contain spaces. The namespace must not include any of the following characters: `*`, `\`, `/`, `?`, `"`, `<`, `>`, `|`, whitespace, `,`, `#`, `:`, or `-`
|
||||
|
||||
`params`:: (Optional, string): Monitor parameters.
|
||||
|
||||
`retest_on_failure`:: (Optional, boolean, default: true): Enable or disable retesting when a monitor fails. By default, monitors are automatically retested if the monitor goes from "up" to "down". If the result of the retest is also "down", an error will be created, and if configured, an alert sent. Then the monitor will resume running according to the defined schedule. Using `retest_on_failure` can reduce noise related to transient problems.
|
||||
|
||||
|
||||
*HTTP Monitor Fields*:
|
||||
|
||||
`url`:: (Required, string): URL to monitor.
|
||||
|
||||
`ssl`:: (Optional, object): The TLS/SSL connection settings for use with the HTTPS endpoint. If you don't specify settings, the system defaults are used. See https://www.elastic.co/guide/en/beats/heartbeat/current/configuration-ssl.html for full SSL Options.
|
||||
|
||||
`max_redirects`:: (Optional, number, default: 0): The maximum number of redirects to follow.
|
||||
|
||||
`mode`:: (Optional, string, default: "any"): The mode of the monitor. Can be "all" or "any". If you’re using a DNS-load balancer and want to ping every IP address for the specified hostname, you should use all.
|
||||
|
||||
* `any`: The monitor pings only one IP address for a hostname.
|
||||
* `all`: The monitor pings all resolvable IPs for a hostname.
|
||||
|
||||
`ipv4`:: (Optional, boolean, default: true): Whether to ping using the ipv4 protocol.
|
||||
|
||||
`ipv6`:: (Optional, boolean, default: true): Whether to ping using the ipv6 protocol.
|
||||
|
||||
`username`:: (Optional, string): The username for authenticating with the server. The credentials are passed with the request.
|
||||
|
||||
`password`:: (Optional, string): The password for authenticating with the server. The credentials are passed with the request.
|
||||
|
||||
`proxy_headers`:: (Optional, object): Additional headers to send to proxies during CONNECT requests.
|
||||
|
||||
`proxy_url`:: (Optional, string): The URL of the proxy to use for this monitor.
|
||||
|
||||
`response`:: (Optional, object): Controls the indexing of the HTTP response body contents to the `http.response.body.contents` field.
|
||||
|
||||
`response.include_body`:: (Optional, boolean, default: true): Controls the indexing of the HTTP response body contents to the `http.response.body.contents` field.
|
||||
* `include_body` ("on_error" | "never" | "always", default: on_error) Set response.include_body to one of the options listed below.
|
||||
** `on_error`: Include the body if an error is encountered during the check. This is the default.
|
||||
** `never`: Never include the body.
|
||||
** `always`: Always include the body.
|
||||
* `include_body_max_bytes` (Optional, number, default: 1024) Set `response.include_body_max_bytes` to control the maximum size of the stored body contents.
|
||||
|
||||
`check`:: (Optional, object): The check request settings.
|
||||
* `request` An optional request to send to the remote host. Under check.request, specify these options:
|
||||
** `method` ("HEAD" | "GET" | "POST" | "OPTIONS"): The HTTP method to use.
|
||||
** `headers` (Optional, object): A dictionary of additional HTTP headers to send. By default Synthetics will set the User-Agent header to identify itself.
|
||||
** `body` (Optional, string): Optional request body content.
|
||||
|
||||
Example: This POSTs an x-www-form-urlencoded string to the endpoint
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"check": {
|
||||
"request": {
|
||||
"method": "POST",
|
||||
"headers": {
|
||||
"Content-Type": "application/x-www-form-urlencoded"
|
||||
},
|
||||
"body": "name=first&email=someemail%40someemailprovider.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
* `response` The expected response. Under `check.response`, specify these options:
|
||||
** `status` A list of expected status codes. 4xx and 5xx codes are considered down by default. Other codes are considered up.
|
||||
** `headers` (Optional, object): A dictionary of expected HTTP headers. If the header is not found, the check fails.
|
||||
** `body.positive`: A list of regular expressions to match the body output. Only a single expression needs to match.
|
||||
Example:
|
||||
This monitor examines the response body for the strings foo or Foo:
|
||||
** `body.negative`: A list of regular expressions to match the body output negatively. Return match failed if single expression matches. HTTP response bodies of up to 100MiB are supported.
|
||||
This monitor examines match successfully if there is no bar or Bar at all, examines match failed if there is bar or Bar in the response body:
|
||||
** `json`: A list of expressions executed against the body when parsed as JSON. Body sizes must be less than or equal to 100 MiB.
|
||||
*** `description` (string): A description of the check.
|
||||
*** `expression` (string): The following configuration shows how to check the response using https://github.com/PaesslerAG/gval[gval] expressions when the body contains JSON:
|
||||
|
||||
|
||||
|
||||
|
||||
*TCP Monitor Fields*:
|
||||
|
||||
`host`:: (Required, string): The host to monitor; it can be an IP address or a hostname. The host can include the port using a colon (e.g., "example.com:9200").
|
||||
|
||||
`ssl`:: (Optional, object): The TLS/SSL connection settings for use with the HTTPS endpoint. If you don't specify settings, the system defaults are used. See https://www.elastic.co/guide/en/beats/heartbeat/current/configuration-ssl.html for full SSL Options.
|
||||
|
||||
`check`:: An optional payload string to send to the remote host and the expected answer. If no payload is specified, the endpoint is assumed to be available if the connection attempt was successful. If send is specified without receive, any response is accepted as OK. If receive is specified without send, no payload is sent, but the client expects to receive a payload in the form of a "hello message" or "banner" on connect.
|
||||
|
||||
* `send` (Optional, string): check.send: 'Hello World'
|
||||
* `receive` (Optional, string): check.receive: 'Hello World'
|
||||
|
||||
`proxy_url`:: (Optional, string): The URL of the SOCKS5 proxy to use when connecting to the server. The value must be a URL with a scheme of `socks5://`. If the SOCKS5 proxy server requires client authentication, then a username and password can be embedded in the URL. When using a proxy, hostnames are resolved on the proxy server instead of on the client. You can change this behavior by setting the `proxy_use_local_resolver` option.
|
||||
|
||||
`proxy_use_local_resolver`:: (Optional, boolean, default: false): A Boolean value that determines whether hostnames are resolved locally instead of being resolved on the proxy server. The default value is false, which means that name resolution occurs on the proxy server.
|
||||
|
||||
*ICMP Monitor Fields*:
|
||||
|
||||
`host`:: (Required, string): Host to ping.
|
||||
`wait`:: (Optional, number, default: 1): Wait time in seconds.
|
||||
|
||||
*Browser Monitor Fields*:
|
||||
|
||||
`inline_script`:: (Required, string): The inline script.
|
||||
|
||||
`screenshots`:: (Optional, string, default: "on"): Screenshot option, either "on", "off" or "only-on-failure".
|
||||
|
||||
`synthetics_args`:: (Optional, array): Synthetics agent CLI arguments.
|
||||
|
||||
`ignore_https_errors`:: (Optional, boolean, default: false): Whether to ignore HTTPS errors.
|
||||
|
||||
`playwright_options`:: (Optional, object): Playwright options.
|
||||
|
||||
==== Examples
|
||||
|
||||
Here are some examples of creating monitors of different types:
|
||||
|
||||
**HTTP Monitor**:
|
||||
Create an HTTP monitor to check a website's availability.
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
POST /api/synthetics/monitors
|
||||
{
|
||||
"type": "http",
|
||||
"name": "Website Availability",
|
||||
"url": "https://example.com",
|
||||
"tags": ["website", "availability"],
|
||||
"locations": ["united_kingdom"]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
**TCP Monitor**:
|
||||
Create a TCP monitor to monitor a server's availability.
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
POST /api/synthetics/monitors
|
||||
{
|
||||
"type": "tcp",
|
||||
"name": "Server Availability",
|
||||
"host": "example.com",
|
||||
"private_locations": ["my_private_location"]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
**ICMP Monitor**:
|
||||
Create an ICMP monitor to perform ping checks.
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
POST /api/synthetics/monitors
|
||||
{
|
||||
"type": "icmp",
|
||||
"name": "Ping Test",
|
||||
"host": "example.com",
|
||||
"locations": ["united_kingdom"]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
**Browser Monitor**:
|
||||
Create a Browser monitor to check a website.
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
POST /api/synthetics/monitors
|
||||
{
|
||||
"type": "browser",
|
||||
"name": "Example journey",
|
||||
"inline_script": "step('Go to https://google.com.co', () => page.goto('https://www.google.com'))",
|
||||
"locations": ["united_kingdom"]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,83 +0,0 @@
|
|||
[[delete-monitors-api]]
|
||||
== Delete Monitors API
|
||||
++++
|
||||
<titleabbrev>Delete monitors</titleabbrev>
|
||||
++++
|
||||
|
||||
Deletes one or more monitors from the Synthetics app.
|
||||
|
||||
=== {api-request-title}
|
||||
|
||||
`DELETE <kibana host>:<port>/api/synthetics/monitors/<config_id>`
|
||||
|
||||
`DELETE <kibana host>:<port>/s/<space_id>/api/synthetics/monitors/<config_id>`
|
||||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `all` privileges for the *Synthetics* feature in the *{observability}* section of the
|
||||
<<kibana-feature-privileges,{kib} feature privileges>>.
|
||||
|
||||
|
||||
[[delete-monitor-api-path-params]]
|
||||
=== {api-path-parms-title}
|
||||
|
||||
`config_id`::
|
||||
(Required, string) The ID of the monitor that you want to delete.
|
||||
|
||||
Here is an example of a DELETE request to delete a monitor by ID:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
DELETE /api/synthetics/monitors/monitor1-id
|
||||
--------------------------------------------------
|
||||
|
||||
==== Bulk Delete Monitors
|
||||
|
||||
You can delete multiple monitors by sending a list of config ids to a POST request to the `/api/synthetics/monitors/_bulk_delete` endpoint.
|
||||
|
||||
|
||||
[[monitors-delete-request-body]]
|
||||
==== Request Body
|
||||
|
||||
The request body should contain an array of monitors IDs that you want to delete.
|
||||
|
||||
`ids`::
|
||||
(Required, array of strings) An array of monitor IDs to delete.
|
||||
|
||||
|
||||
Here is an example of a POST request to delete a list of monitors by ID:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
POST /api/synthetics/monitors/_bulk_delete
|
||||
{
|
||||
"ids": [
|
||||
"monitor1-id",
|
||||
"monitor2-id"
|
||||
]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
[[monitors-delete-response-example]]
|
||||
==== Response Example
|
||||
|
||||
The API response includes information about the deleted monitors, where each entry in the response array contains the following attributes:
|
||||
|
||||
- `id` (string): The unique identifier of the deleted monitor.
|
||||
- `deleted` (boolean): Indicates whether the monitor was successfully deleted (`true` if deleted, `false` if not).
|
||||
|
||||
Here's an example response for deleting multiple monitors:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
[
|
||||
{
|
||||
"id": "monitor1-id",
|
||||
"deleted": true
|
||||
},
|
||||
{
|
||||
"id": "monitor2-id",
|
||||
"deleted": true
|
||||
}
|
||||
]
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,126 +0,0 @@
|
|||
[[find-monitors-api]]
|
||||
== Find Monitors API
|
||||
++++
|
||||
<titleabbrev>Get List of Monitors API</titleabbrev>
|
||||
++++
|
||||
|
||||
Get a list of monitors based on query parameters.
|
||||
|
||||
[[find-monitor-api-req]]
|
||||
=== {api-request-title}
|
||||
|
||||
`GET <kibana host>:<port>/api/synthetics/monitors`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space_id>/api/synthetics/monitors`
|
||||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `read` privileges for the *Synthetics* feature in the *{observability}* section of the
|
||||
<<kibana-feature-privileges,{kib} feature privileges>>.
|
||||
|
||||
[[find-monitor-api-path-params]]
|
||||
=== {api-path-parms-title}
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in
|
||||
the URL, the default space is used.
|
||||
|
||||
[[find-monitors-api-query-params]]
|
||||
=== {api-query-parms-title}
|
||||
|
||||
|
||||
`page`::
|
||||
(optional, integer): Page number for paginated results.
|
||||
|
||||
`perPage`::
|
||||
(optional, integer): Number of items per page.
|
||||
|
||||
`sortField`::
|
||||
(optional, string): Field to sort the results by. Possible values: `name`, `createdAt`, `updatedAt`, `status`.
|
||||
|
||||
`sortOrder`::
|
||||
(optional, string): Sort order (asc or desc).
|
||||
|
||||
`query`::
|
||||
(optional, string): Free-text query string.
|
||||
|
||||
`filter`::
|
||||
(optional, string): Additional filtering criteria.
|
||||
|
||||
`tags`::
|
||||
(optional, string or array): Tags to filter monitors.
|
||||
|
||||
`monitorTypes`::
|
||||
(optional, string or array): Monitor types to filter, (e.g., `http` , `tcp` , `icmp` or `browser`)
|
||||
|
||||
`locations`::
|
||||
(optional, string or array): Locations to filter by.
|
||||
|
||||
`projects`::
|
||||
(optional, string or array): Projects to filter by.
|
||||
|
||||
`schedules`::
|
||||
(optional, string or array): Schedules to filter by.
|
||||
|
||||
`status`::
|
||||
(optional, string or array): Status to filter by.
|
||||
|
||||
|
||||
==== Examples
|
||||
|
||||
Here is an example of how to use this API:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
GET /api/synthetics/monitors?tags=prod&monitorTypes=http&locations=us-east-1&projects=project1&status=up
|
||||
{
|
||||
"page": 1,
|
||||
"total": 24,
|
||||
"monitors": [
|
||||
{
|
||||
"type": "icmp",
|
||||
"enabled": false,
|
||||
"alert": {
|
||||
"status": {
|
||||
"enabled": true
|
||||
},
|
||||
"tls": {
|
||||
"enabled": true
|
||||
}
|
||||
},
|
||||
"schedule": {
|
||||
"number": "3",
|
||||
"unit": "m"
|
||||
},
|
||||
"config_id": "e59142e5-1fe3-4aae-b0b0-19d6345e65a1",
|
||||
"timeout": "16",
|
||||
"name": "8.8.8.8:80",
|
||||
"locations": [
|
||||
{
|
||||
"id": "us_central",
|
||||
"label": "North America - US Central",
|
||||
"geo": {
|
||||
"lat": 41.25,
|
||||
"lon": -95.86
|
||||
},
|
||||
"isServiceManaged": true
|
||||
}
|
||||
],
|
||||
"namespace": "default",
|
||||
"origin": "ui",
|
||||
"id": "e59142e5-1fe3-4aae-b0b0-19d6345e65a1",
|
||||
"max_attempts": 2,
|
||||
"wait": "7",
|
||||
"revision": 3,
|
||||
"mode": "all",
|
||||
"ipv4": true,
|
||||
"ipv6": true,
|
||||
"created_at": "2023-11-07T09:57:04.152Z",
|
||||
"updated_at": "2023-12-04T19:19:34.039Z",
|
||||
"host": "8.8.8.8:80"
|
||||
}
|
||||
],
|
||||
"absoluteTotal": 24,
|
||||
"perPage": 10,
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,93 +0,0 @@
|
|||
[[get-monitor-api]]
|
||||
== Get Monitor API
|
||||
++++
|
||||
<titleabbrev>Get monitor</titleabbrev>
|
||||
++++
|
||||
|
||||
Get a monitor with the config_id. If the monitor is not found, then this API returns a 404 error.
|
||||
|
||||
[[get-monitor-api-req]]
|
||||
=== {api-request-title}
|
||||
|
||||
`GET <kibana host>:<port>/api/synthetics/monitors/<config_id>`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space_id>/api/synthetics/monitors/<config_id>`
|
||||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `read` privileges for the *Synthetics* feature in the *{observability}* section of the
|
||||
<<kibana-feature-privileges,{kib} feature privileges>>.
|
||||
|
||||
[[get-monitor-api-path-params]]
|
||||
=== {api-path-parms-title}
|
||||
|
||||
`config_id`::
|
||||
(Required, string) The ID of the monitor that you want to update.
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in
|
||||
the URL, the default space is used.
|
||||
|
||||
==== Examples
|
||||
|
||||
Here is an example of how to use this API:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
GET /api/synthetics/monitors/<config_id>
|
||||
{
|
||||
"type": "http",
|
||||
"enabled": true,
|
||||
"alert": {
|
||||
"status": {
|
||||
"enabled": true
|
||||
},
|
||||
"tls": {
|
||||
"enabled": true
|
||||
}
|
||||
},
|
||||
"schedule": {
|
||||
"number": "3",
|
||||
"unit": "m"
|
||||
},
|
||||
"config_id": "a8188705-d01e-4bb6-87a1-64fa5e4b07ec",
|
||||
"timeout": "16",
|
||||
"name": "am i something",
|
||||
"locations": [
|
||||
{
|
||||
"id": "us_central",
|
||||
"label": "North America - US Central",
|
||||
"geo": {
|
||||
"lat": 41.25,
|
||||
"lon": -95.86
|
||||
},
|
||||
"isServiceManaged": true
|
||||
}
|
||||
],
|
||||
"namespace": "default",
|
||||
"origin": "ui",
|
||||
"id": "a8188705-d01e-4bb6-87a1-64fa5e4b07ec",
|
||||
"max_attempts": 2,
|
||||
"__ui": {
|
||||
"is_tls_enabled": false
|
||||
},
|
||||
"max_redirects": "0",
|
||||
"response.include_body": "on_error",
|
||||
"response.include_headers": true,
|
||||
"check.request.method": "GET",
|
||||
"mode": "any",
|
||||
"response.include_body_max_bytes": "1024",
|
||||
"ipv4": true,
|
||||
"ipv6": true,
|
||||
"ssl.verification_mode": "full",
|
||||
"ssl.supported_protocols": [
|
||||
"TLSv1.1",
|
||||
"TLSv1.2",
|
||||
"TLSv1.3"
|
||||
],
|
||||
"revision": 13,
|
||||
"created_at": "2023-11-08T08:45:29.334Z",
|
||||
"updated_at": "2023-12-18T20:31:44.770Z",
|
||||
"url": "https://fast.com"
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,268 +0,0 @@
|
|||
[[update-monitor-api]]
|
||||
== Update Monitor API
|
||||
++++
|
||||
<titleabbrev>Update monitor</titleabbrev>
|
||||
++++
|
||||
|
||||
Updates a new monitor with the specified attributes. The required and default fields may vary based on the monitor type.
|
||||
|
||||
=== {api-request-title}
|
||||
|
||||
`PUT <kibana host>:<port>/api/synthetics/monitors/<config_id>`
|
||||
|
||||
`PUT <kibana host>:<port>/s/<space_id>/api/synthetics/monitors/<config_id>`
|
||||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `all` privileges for the *Synthetics* feature in the *{observability}* section of the
|
||||
<<kibana-feature-privileges,{kib} feature privileges>>.
|
||||
|
||||
|
||||
[[update-monitor-api-path-params]]
|
||||
=== {api-path-parms-title}
|
||||
|
||||
`config_id`::
|
||||
(Required, string) The ID of the monitor that you want to update.
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in
|
||||
the URL, the default space is used.
|
||||
|
||||
[[monitor-update-body]]
|
||||
==== Request Body
|
||||
|
||||
The request body should contain the attributes of the monitor you want to update. The required and default fields differ depending on the monitor type:
|
||||
|
||||
*Common Fields*:
|
||||
|
||||
`name`:: (string): The monitor's name.
|
||||
|
||||
`schedule`:: (Optional, number): The monitor's schedule in minutes. Supported values are `1`, `3`, `5`, `10`, `15`, `30`, `60`, `120` and `240`.
|
||||
* The default value is `3` minutes for HTTP, TCP, and ICMP monitors.
|
||||
|
||||
* The default value is `10` minutes for Browser monitors.
|
||||
|
||||
:private-locations-url: https://www.elastic.co/guide/en/observability/current/synthetics-private-location.html
|
||||
|
||||
`locations`:: (https://github.com/elastic/synthetics/blob/main/src/locations/public-locations.ts#L28-L37[`Array<SyntheticsLocationsType>`])
|
||||
Where to deploy the monitor. Monitors can be deployed in multiple locations so that you can detect differences in availability and response times across those locations.
|
||||
+
|
||||
To list available locations you can:
|
||||
+
|
||||
* Run the {locations-command}[`elastic-synthetics locations`] command
|
||||
with the deployment's {kib} URL.
|
||||
* Go to *Synthetics* -> *Management* and click *Create monitor*.
|
||||
Locations will be listed in _Locations_.
|
||||
|
||||
`private_locations` (`Array<string>`)::
|
||||
|
||||
The {private-locations-url}[Private Locations] to which the monitors will be deployed. These Private Locations refer to locations hosted and managed by you, whereas
|
||||
`locations` are hosted by Elastic. You can specify a Private Location using the location's name.
|
||||
+
|
||||
To list available Private Locations you can:
|
||||
+
|
||||
* Run the {locations-command}[`elastic-synthetics locations`] command
|
||||
with the deployment's {kib} URL.
|
||||
* Go to *Synthetics* -> *Settings* and click *Private locations*.
|
||||
Private Locations will be listed in the table.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
You may provide `locations` or `private_locations`, or both. At least one is required.
|
||||
====
|
||||
|
||||
|
||||
`enabled`:: (Optional, boolean, default: true): Whether the monitor is enabled.
|
||||
|
||||
`tags`:: (Optional, array of strings): An array of tags.
|
||||
|
||||
`alert`:: (Optional, object, default: `{ status: { enabled: true }, tls: { enabled: true } }`): Alert configuration.
|
||||
|
||||
`service.name`:: (Optional, string): The APM service name.
|
||||
|
||||
`timeout`:: (Optional, number, default: 16): The monitor timeout in seconds, monitor will fail if it doesn't complete within this time.
|
||||
|
||||
`namespace`:: (Optional, string, default: "default"): The namespace field should be lowercase and not contain spaces. The namespace must not include any of the following characters: `*`, `\`, `/`, `?`, `"`, `<`, `>`, `|`, whitespace, `,`, `#`, `:`, or `-`
|
||||
|
||||
`params`:: (Optional, string): Monitor parameters.
|
||||
|
||||
`retest_on_failure`:: (Optional, boolean, default: true): Enable or disable retesting when a monitor fails. By default, monitors are automatically retested if the monitor goes from "up" to "down". If the result of the retest is also "down", an error will be created, and if configured, an alert sent. Then the monitor will resume running according to the defined schedule. Using `retest_on_failure` can reduce noise related to transient problems.
|
||||
|
||||
|
||||
*HTTP Monitor Fields*:
|
||||
|
||||
`url`:: (Required, string): URL to monitor.
|
||||
|
||||
`ssl`:: (Optional, object): The TLS/SSL connection settings for use with the HTTPS endpoint. If you don't specify settings, the system defaults are used. See https://www.elastic.co/guide/en/beats/heartbeat/current/configuration-ssl.html for full SSL Options.
|
||||
|
||||
`max_redirects`:: (Optional, number, default: 0): The maximum number of redirects to follow.
|
||||
|
||||
`mode`:: (Optional, string, default: "any"): The mode of the monitor. Can be "all" or "any". If you’re using a DNS-load balancer and want to ping every IP address for the specified hostname, you should use all.
|
||||
|
||||
* `any`: The monitor pings only one IP address for a hostname.
|
||||
* `all`: The monitor pings all resolvable IPs for a hostname.
|
||||
|
||||
`ipv4`:: (Optional, boolean, default: true): Whether to ping using the ipv4 protocol.
|
||||
|
||||
`ipv6`:: (Optional, boolean, default: true): Whether to ping using the ipv6 protocol.
|
||||
|
||||
`username`:: (Optional, string): The username for authenticating with the server. The credentials are passed with the request.
|
||||
|
||||
`password`:: (Optional, string): The password for authenticating with the server. The credentials are passed with the request.
|
||||
|
||||
`proxy_headers`:: (Optional, object): Additional headers to send to proxies during CONNECT requests.
|
||||
|
||||
`proxy_url`:: (Optional, string): The URL of the proxy to use for this monitor.
|
||||
|
||||
`response`:: (Optional, object): Controls the indexing of the HTTP response body contents to the `http.response.body.contents` field.
|
||||
|
||||
`response.include_body`:: (Optional, boolean, default: true): Controls the indexing of the HTTP response body contents to the `http.response.body.contents` field.
|
||||
* `include_body` ("on_error" | "never" | "always", default: on_error) Set response.include_body to one of the options listed below.
|
||||
** `on_error`: Include the body if an error is encountered during the check. This is the default.
|
||||
** `never`: Never include the body.
|
||||
** `always`: Always include the body.
|
||||
* `include_body_max_bytes` (Optional, number, default: 1024) Set `response.include_body_max_bytes` to control the maximum size of the stored body contents.
|
||||
|
||||
`check`:: (Optional, object): The check request settings.
|
||||
* `request` An optional request to send to the remote host. Under check.request, specify these options:
|
||||
** `method` ("HEAD" | "GET" | "POST" | "OPTIONS"): The HTTP method to use.
|
||||
** `headers` (Optional, object): A dictionary of additional HTTP headers to send. By default Synthetics will set the User-Agent header to identify itself.
|
||||
** `body` (Optional, string): Optional request body content.
|
||||
|
||||
Example: This POSTs an x-www-form-urlencoded string to the endpoint
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"check": {
|
||||
"request": {
|
||||
"method": "POST",
|
||||
"headers": {
|
||||
"Content-Type": "application/x-www-form-urlencoded"
|
||||
},
|
||||
"body": "name=first&email=someemail%40someemailprovider.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
* `response` The expected response. Under `check.response`, specify these options:
|
||||
** `status` A list of expected status codes. 4xx and 5xx codes are considered down by default. Other codes are considered up.
|
||||
** `headers` (Optional, object): A dictionary of expected HTTP headers. If the header is not found, the check fails.
|
||||
** `body.positive`: A list of regular expressions to match the body output. Only a single expression needs to match.
|
||||
Example:
|
||||
This monitor examines the response body for the strings foo or Foo:
|
||||
** `body.negative`: A list of regular expressions to match the body output negatively. Return match failed if single expression matches. HTTP response bodies of up to 100MiB are supported.
|
||||
This monitor examines match successfully if there is no bar or Bar at all, examines match failed if there is bar or Bar in the response body:
|
||||
** `json`: A list of expressions executed against the body when parsed as JSON. Body sizes must be less than or equal to 100 MiB.
|
||||
*** `description` (string): A description of the check.
|
||||
*** `expression` (string): The following configuration shows how to check the response using [gval](https://github.com/PaesslerAG/gval) expressions when the body contains JSON:
|
||||
|
||||
|
||||
|
||||
|
||||
*TCP Monitor Fields*:
|
||||
|
||||
`host`:: (Required, string): The host to monitor; it can be an IP address or a hostname. The host can include the port using a colon (e.g., "example.com:9200").
|
||||
|
||||
`ssl`:: (Optional, object): The TLS/SSL connection settings for use with the HTTPS endpoint. If you don't specify settings, the system defaults are used. See https://www.elastic.co/guide/en/beats/heartbeat/current/configuration-ssl.html for full SSL Options.
|
||||
|
||||
`check`:: An optional payload string to send to the remote host and the expected answer. If no payload is specified, the endpoint is assumed to be available if the connection attempt was successful. If send is specified without receive, any response is accepted as OK. If receive is specified without send, no payload is sent, but the client expects to receive a payload in the form of a "hello message" or "banner" on connect.
|
||||
|
||||
* `send` (Optional, string): check.send: 'Hello World'
|
||||
* `receive` (Optional, string): check.receive: 'Hello World'
|
||||
|
||||
`proxy_url`:: (Optional, string): The URL of the SOCKS5 proxy to use when connecting to the server. The value must be a URL with a scheme of `socks5://`. If the SOCKS5 proxy server requires client authentication, then a username and password can be embedded in the URL. When using a proxy, hostnames are resolved on the proxy server instead of on the client. You can change this behavior by setting the `proxy_use_local_resolver` option.
|
||||
|
||||
`proxy_use_local_resolver`:: (Optional, boolean, default: false): A Boolean value that determines whether hostnames are resolved locally instead of being resolved on the proxy server. The default value is false, which means that name resolution occurs on the proxy server.
|
||||
|
||||
*ICMP Monitor Fields*:
|
||||
|
||||
`host`:: (Required, string): Host to ping.
|
||||
`wait`:: (Optional, number, default: 1): Wait time in seconds.
|
||||
|
||||
*Browser Monitor Fields*:
|
||||
|
||||
`inline_script`:: (Required, string): The inline script.
|
||||
|
||||
`screenshots`:: (Optional, string, default: "on"): Screenshot option, either "on", "off" or "only-on-failure".
|
||||
|
||||
`synthetics_args`:: (Optional, array): Synthetics agent CLI arguments.
|
||||
|
||||
`ignore_https_errors`:: (Optional, boolean, default: false): Whether to ignore HTTPS errors.
|
||||
|
||||
`playwright_options`:: (Optional, object): Playwright options.
|
||||
|
||||
==== Examples
|
||||
|
||||
Here are some examples of creating monitors of different types:
|
||||
|
||||
**HTTP Monitor**:
|
||||
Create an HTTP monitor to check a website's availability.
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
PUT /api/synthetics/monitors/<monitor_id>
|
||||
{
|
||||
"type": "http",
|
||||
"name": "Website Availability",
|
||||
"url": "https://example.com",
|
||||
"tags": ["website", "availability"],
|
||||
"locations": ["united_kingdom"]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
**TCP Monitor**:
|
||||
Create a TCP monitor to monitor a server's availability.
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
PUT /api/synthetics/monitors/<monitor_id>
|
||||
{
|
||||
"type": "tcp",
|
||||
"name": "Server Availability",
|
||||
"host": "example.com",
|
||||
"private_locations": ["my_private_location"]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
**ICMP Monitor**:
|
||||
Create an ICMP monitor to perform ping checks.
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
PUT /api/synthetics/monitors/<monitor_id>
|
||||
{
|
||||
"type": "icmp",
|
||||
"name": "Ping Test",
|
||||
"host": "example.com",
|
||||
"locations": ["united_kingdom"]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
**Browser Monitor**:
|
||||
Create a Browser monitor to check a website.
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
PUT /api/synthetics/monitors/<monitor_id>
|
||||
{
|
||||
"type": "browser",
|
||||
"name": "Example journey",
|
||||
"inline_script": "step('Go to https://google.com.co', () => page.goto('https://www.google.com'))",
|
||||
"locations": ["united_kingdom"]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
==== Partial Updates
|
||||
|
||||
You can also partially update a monitor. This will only update the fields that are specified in the request body. All other fields are left unchanged.
|
||||
Specified fields should confirm to the monitor type. For example, you can't update the `inline_scipt` field of a HTTP monitor.
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
PUT /api/synthetics/monitors/<monitor_id>
|
||||
{
|
||||
"name": "New name"
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
|
|
@ -1,123 +0,0 @@
|
|||
[[add-parameters-api]]
|
||||
== Add Parameters API
|
||||
++++
|
||||
<titleabbrev>Add Parameters</titleabbrev>
|
||||
++++
|
||||
|
||||
Adds one or more parameters to the synthetics app.
|
||||
|
||||
=== {api-request-title}
|
||||
|
||||
`POST <kibana host>:<port>/api/synthetics/params`
|
||||
|
||||
`POST <kibana host>:<port>/s/<space_id>/api/synthetics/params`
|
||||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `all` privileges for the *Synthetics* feature in the *{observability}* section of the
|
||||
<<kibana-feature-privileges,{kib} feature privileges>>.
|
||||
|
||||
|
||||
[[parameters-add-request-body]]
|
||||
==== Request body
|
||||
|
||||
The request body can contain either a single parameter object or an array of parameter objects. The parameter object schema includes the following attributes:
|
||||
|
||||
`key`::
|
||||
(Required, string) The key of the parameter.
|
||||
|
||||
`value`::
|
||||
(Required, string) The value associated with the parameter.
|
||||
|
||||
`description`::
|
||||
(Optional, string) A description of the parameter.
|
||||
|
||||
`tags`::
|
||||
(Optional, array of strings) An array of tags to categorize the parameter.
|
||||
|
||||
`share_across_spaces`::
|
||||
(Optional, boolean) Whether the parameter should be shared across spaces.
|
||||
|
||||
When adding a single parameter, provide a single object. When adding multiple parameters, provide an array of parameter objects.
|
||||
|
||||
[[parameters-add-example]]
|
||||
==== Example
|
||||
|
||||
Here are examples of POST requests to add parameters, either as a single parameter or as an array of parameters:
|
||||
|
||||
To add a single parameter:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
POST /api/synthetics/params
|
||||
{
|
||||
"key": "your-key-name",
|
||||
"value": "your-parameter-value",
|
||||
"description": "Param to use in browser monitor",
|
||||
"tags": ["authentication", "security"],
|
||||
"share_across_spaces": true
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
To add multiple parameters:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
POST /api/synthetics/params
|
||||
[
|
||||
{
|
||||
"key": "param1",
|
||||
"value": "value1"
|
||||
},
|
||||
{
|
||||
"key": "param2",
|
||||
"value": "value2"
|
||||
}
|
||||
]
|
||||
--------------------------------------------------
|
||||
|
||||
The API returns a response based on the request. If you added a single parameter, it will return a single parameter object. If you added multiple parameters, it will return an array of parameter objects.
|
||||
|
||||
[[parameters-add-response-example]]
|
||||
==== Response Example
|
||||
|
||||
The API response includes the created parameter(s) as JSON objects, where each parameter object has the following attributes:
|
||||
|
||||
- `id` (string): The unique identifier of the parameter.
|
||||
- `key` (string): The key of the parameter.
|
||||
- `value` (string): The value associated with the parameter.
|
||||
- `description` (string, optional): The description of the parameter.
|
||||
- `tags` (array of strings, optional): An array of tags associated with the parameter.
|
||||
- `share_across_spaces` (boolean, optional): Indicates whether the parameter is shared across spaces.
|
||||
|
||||
Here's an example response for a single added parameter:
|
||||
|
||||
[source,json]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"id": "unique-parameter-id",
|
||||
"key": "your-key-name",
|
||||
"value": "your-param-value",
|
||||
"description": "Param to use in browser monitor",
|
||||
"tags": ["authentication", "security"],
|
||||
"share_across_spaces": true
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
And here's an example response for adding multiple parameters:
|
||||
|
||||
[source,json]
|
||||
--------------------------------------------------
|
||||
[
|
||||
{
|
||||
"id": "param1-id",
|
||||
"key": "param1",
|
||||
"value": "value1"
|
||||
},
|
||||
{
|
||||
"id": "param2-id",
|
||||
"key": "param2",
|
||||
"value": "value2"
|
||||
}
|
||||
]
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,71 +0,0 @@
|
|||
[[delete-parameters-api]]
|
||||
== Delete Parameters API
|
||||
++++
|
||||
<titleabbrev>Delete Parameters</titleabbrev>
|
||||
++++
|
||||
|
||||
Deletes one or more parameters from the Synthetics app.
|
||||
|
||||
=== {api-request-title}
|
||||
|
||||
`DELETE <kibana host>:<port>/api/synthetics/params/<param_id>`
|
||||
|
||||
`DELETE <kibana host>:<port>/s/<space_id>/api/synthetics/params/<param_id>`
|
||||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `all` privileges for the *Synthetics* feature in the *{observability}* section of the
|
||||
<<kibana-feature-privileges,{kib} feature privileges>>.
|
||||
|
||||
You must have `all` privileges for the *Synthetics* feature in the *{observability}* section of the
|
||||
<<kibana-feature-privileges,{kib} feature privileges>>.
|
||||
|
||||
[[parameters-delete-path-param]]
|
||||
==== Path Parameters
|
||||
|
||||
The request body should contain an array of parameter IDs that you want to delete.
|
||||
|
||||
`param_id`::
|
||||
(Required, string) An id of parameter to delete.
|
||||
|
||||
Here is an example of a DELETE request to delete a parameter by its ID:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
DELETE /api/synthetics/params/param_id1
|
||||
--------------------------------------------------
|
||||
|
||||
[[parameters-delete-response-example]]
|
||||
==== Response Example
|
||||
|
||||
The API response includes information about the deleted parameters, where each entry in the response array contains the following attributes:
|
||||
|
||||
- `id` (string): The unique identifier of the deleted parameter.
|
||||
- `deleted` (boolean): Indicates whether the parameter was successfully deleted (`true` if deleted, `false` if not).
|
||||
|
||||
Here's an example response for deleting multiple parameters:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
[
|
||||
{
|
||||
"id": "param1-id",
|
||||
"deleted": true
|
||||
}
|
||||
]
|
||||
--------------------------------------------------
|
||||
|
||||
==== Bulk delete parameters
|
||||
To delete multiple parameters, you can send a POST request to `/api/synthetics/params/_bulk_delete` with an array of parameter IDs to delete via body.
|
||||
|
||||
Here is an example of a POST request to delete multiple parameters:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
POST /api/synthetics/params/_bulk_delete
|
||||
{
|
||||
"ids": ["param1-id", "param2-id"]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
|
||||
|
|
@ -1,70 +0,0 @@
|
|||
[[edit-parameter-by-id-api]]
|
||||
== Edit Parameter by ID API
|
||||
++++
|
||||
<titleabbrev>Edit Parameter</titleabbrev>
|
||||
++++
|
||||
|
||||
Edits a parameter with the specified ID.
|
||||
|
||||
=== {api-request-title}
|
||||
|
||||
`PUT <kibana host>:<port>/api/synthetics/params`
|
||||
|
||||
`PUT <kibana host>:<port>/s/<space_id>/api/synthetics/params`
|
||||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `all` privileges for the *Synthetics* feature in the *{observability}* section of the
|
||||
<<kibana-feature-privileges,{kib} feature privileges>>.
|
||||
|
||||
[[parameter-edit-path-params]]
|
||||
==== Path Parameters
|
||||
|
||||
`id`::
|
||||
(Required, string) The unique identifier of the parameter to be edited.
|
||||
|
||||
[[parameter-edit-request-body]]
|
||||
==== Request body
|
||||
|
||||
The request body can contain the following attributes, it can't be empty at least one attribute is required.:
|
||||
|
||||
`key`::
|
||||
(Optional, string) The key of the parameter.
|
||||
|
||||
`value`::
|
||||
(Optional, string) The updated value associated with the parameter.
|
||||
|
||||
`description`::
|
||||
(Optional, string) The updated description of the parameter.
|
||||
|
||||
`tags`::
|
||||
(Optional, array of strings) An array of updated tags to categorize the parameter.
|
||||
|
||||
[[parameter-edit-example]]
|
||||
==== Example
|
||||
|
||||
Here is an example of a PUT request to edit a parameter by its ID:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
PUT /api/synthetics/params/param_id1
|
||||
{
|
||||
"key": "updated_param_key",
|
||||
"value": "updated-param-value",
|
||||
"description": "Updated Param to be used in browser monitor",
|
||||
"tags": ["authentication", "security", "updated"]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
The API returns the updated parameter as follows:
|
||||
|
||||
[source,json]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"id": "param_id1",
|
||||
"key": "updated_param_key",
|
||||
"value": "updated-param-value",
|
||||
"description": "Updated Param to be used in browser monitor",
|
||||
"tags": ["authentication", "security", "updated"]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,128 +0,0 @@
|
|||
[[get-parameters-api]]
|
||||
== Get Parameters API
|
||||
++++
|
||||
<titleabbrev>Get Parameters</titleabbrev>
|
||||
++++
|
||||
|
||||
Retrieves parameters based on the provided criteria.
|
||||
|
||||
=== {api-request-title}
|
||||
|
||||
`GET <kibana host>:<port>/api/synthetics/params/{id?}`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space_id>/api/synthetics/params/{id?}`
|
||||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `read` privileges for the *Synthetics* feature in the *{observability}* section of the
|
||||
<<kibana-feature-privileges,{kib} feature privileges>>.
|
||||
|
||||
[[parameters-get-query-params]]
|
||||
==== Query Parameters
|
||||
|
||||
`id`::
|
||||
(Optional, string) The unique identifier of the parameter. If provided, this API will retrieve a specific parameter by its ID. If not provided, it will retrieve a list of all parameters.
|
||||
|
||||
[[parameters-get-response-example]]
|
||||
==== Response Example
|
||||
|
||||
The API response includes parameter(s) as JSON objects, where each parameter object has the following attributes:
|
||||
|
||||
- `id` (string): The unique identifier of the parameter.
|
||||
- `key` (string): The key of the parameter.
|
||||
|
||||
If the user has read-only permissions to the Synthetics app, the following additional attributes will be included:
|
||||
|
||||
- `description` (string, optional): The description of the parameter.
|
||||
- `tags` (array of strings, optional): An array of tags associated with the parameter.
|
||||
- `namespaces` (array of strings): Namespaces associated with the parameter.
|
||||
|
||||
If the user has write permissions, the following additional attribute will be included:
|
||||
|
||||
- `value` (string): The value associated with the parameter.
|
||||
|
||||
|
||||
Here's an example request for retrieving a single parameter by its ID:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
GET /api/synthetics/params/unique-parameter-id
|
||||
--------------------------------------------------
|
||||
|
||||
|
||||
Here's an example response for retrieving a single parameter by its ID:
|
||||
|
||||
For users with read-only permissions:
|
||||
|
||||
[source,json]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"id": "unique-parameter-id",
|
||||
"key": "your-api-key",
|
||||
"description": "Param to use in browser monitor",
|
||||
"tags": ["authentication", "security"],
|
||||
"namespaces": ["namespace1", "namespace2"]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
For users with write permissions:
|
||||
|
||||
[source,json]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"id": "unique-parameter-id",
|
||||
"key": "your-param-key",
|
||||
"description": "Param to use in browser monitor",
|
||||
"tags": ["authentication", "security"],
|
||||
"namespaces": ["namespace1", "namespace2"],
|
||||
"value": "your-param-value"
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
And here's an example response for retrieving a list of parameters:
|
||||
|
||||
For users with read-only permissions:
|
||||
|
||||
[source,json]
|
||||
--------------------------------------------------
|
||||
[
|
||||
{
|
||||
"id": "param1-id",
|
||||
"key": "param1",
|
||||
"description": "Description for param1",
|
||||
"tags": ["tag1", "tag2"],
|
||||
"namespaces": ["namespace1"]
|
||||
},
|
||||
{
|
||||
"id": "param2-id",
|
||||
"key": "param2",
|
||||
"description": "Description for param2",
|
||||
"tags": ["tag3"],
|
||||
"namespaces": ["namespace2"]
|
||||
}
|
||||
]
|
||||
--------------------------------------------------
|
||||
|
||||
For users with write permissions:
|
||||
|
||||
[source,json]
|
||||
--------------------------------------------------
|
||||
[
|
||||
{
|
||||
"id": "param1-id",
|
||||
"key": "param1",
|
||||
"description": "Description for param1",
|
||||
"tags": ["tag1", "tag2"],
|
||||
"namespaces": ["namespace1"],
|
||||
"value": "value1"
|
||||
},
|
||||
{
|
||||
"id": "param2-id",
|
||||
"key": "param2",
|
||||
"description": "Description for param2",
|
||||
"tags": ["tag3"],
|
||||
"namespaces": ["namespace2"],
|
||||
"value": "value2"
|
||||
}
|
||||
]
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,80 +0,0 @@
|
|||
[[create-private-location-api]]
|
||||
== Create Private Location API
|
||||
++++
|
||||
<titleabbrev>Create Private Location</titleabbrev>
|
||||
++++
|
||||
|
||||
Creates a private location with the following schema.
|
||||
|
||||
=== {api-request-title}
|
||||
|
||||
`POST <kibana host>:<port>/api/synthetics/private_locations`
|
||||
|
||||
`POST <kibana host>:<port>/s/<space_id>/api/synthetics/private_locations`
|
||||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `all` privileges for the *Synthetics and Uptime* feature in the *{observability}* section of the
|
||||
<<kibana-feature-privileges,{kib} feature privileges>>.
|
||||
|
||||
[[private-location-request-body]]
|
||||
==== Request body
|
||||
|
||||
The request body should contain the following attributes:
|
||||
|
||||
`label`::
|
||||
(Required, string) A label for the private location.
|
||||
|
||||
`agentPolicyId`::
|
||||
(Required, string) The ID of the agent policy associated with the private location.
|
||||
|
||||
`tags`::
|
||||
(Optional, array of strings) An array of tags to categorize the private location.
|
||||
|
||||
`geo`::
|
||||
(Optional, object) Geographic coordinates (WGS84) for the location. It should include the following attributes:
|
||||
|
||||
- `lat` (Required, number): The latitude of the location.
|
||||
- `lon` (Required, number): The longitude of the location.
|
||||
|
||||
`spaces`::
|
||||
(Optional, array of strings) An array of space IDs where the private location is available. If not provided, the private location is available in all spaces, the API will throw an error if user
|
||||
does not have access to all spaces. In that case you can provide the space ID where the private location should be available.
|
||||
|
||||
[[private-location-create-example]]
|
||||
==== Example
|
||||
|
||||
Here is an example of a POST request to create a private location:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
POST /api/private_locations
|
||||
{
|
||||
"label": "Private Location 1",
|
||||
"agentPolicyId": "abcd1234",
|
||||
"tags": ["private", "testing"],
|
||||
"geo": {
|
||||
"lat": 40.7128,
|
||||
"lon": -74.0060
|
||||
}
|
||||
"spaces": ["default"]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
The API returns the created private location as follows:
|
||||
|
||||
[source,json]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"id": "abcd1234",
|
||||
"label": "Private Location 1",
|
||||
"agentPolicyId": "abcd1234",
|
||||
"tags": ["private", "testing"],
|
||||
"geo": {
|
||||
"lat": 40.7128,
|
||||
"lon": -74.0060
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
If the `agentPolicyId` is already used by an existing private location, or if the `label` already exists, the API will return a `400 Bad Request` response with a corresponding error message.
|
||||
|
|
@ -1,41 +0,0 @@
|
|||
[[delete-private-location-api]]
|
||||
== Delete Private Location API
|
||||
++++
|
||||
<titleabbrev>Delete Private Location</titleabbrev>
|
||||
++++
|
||||
|
||||
Deletes a private location using the provided location ID.
|
||||
|
||||
=== {api-request-title}
|
||||
|
||||
`DELETE <kibana host>:<port>/api/synthetics/private_locations/<location_id>`
|
||||
|
||||
`DELETE <kibana host>:<port>/s/<space_id>/api/synthetics/private_locations/<location_id>`
|
||||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `all` privileges for the *Synthetics and Uptime* feature in the *{observability}* section of the
|
||||
<<kibana-feature-privileges,{kib} feature privileges>>.
|
||||
|
||||
|
||||
[[private-location-delete-params]]
|
||||
==== Path Parameters
|
||||
|
||||
`location_id`::
|
||||
(Required, string) The unique identifier of the private location to be deleted. It must be between 1 and 1024 characters.
|
||||
|
||||
[[private-location-delete-example]]
|
||||
==== Example
|
||||
|
||||
Here is an example of a DELETE request to delete a private location:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
DELETE /api/private-locations/<location_id>
|
||||
--------------------------------------------------
|
||||
|
||||
The API does not return a response body for deletion, but it will return an appropriate status code upon successful deletion.
|
||||
|
||||
This API will delete the private location with the specified `locationId`.
|
||||
|
||||
A location cannot be deleted if it has associated monitors in use. You must delete all monitors associated with the location before deleting the location.
|
||||
|
|
@ -1,98 +0,0 @@
|
|||
[[get-private-locations-api]]
|
||||
== Get Private Locations API
|
||||
++++
|
||||
<titleabbrev>Get Private Locations</titleabbrev>
|
||||
++++
|
||||
|
||||
Retrieves a list of private locations or a single private location by ID.
|
||||
|
||||
=== {api-request-title}
|
||||
|
||||
`GET <kibana host>:<port>/api/synthetics/private_locations`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space_id>/api/synthetics/private_locations`
|
||||
|
||||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `read` privileges for the *Synthetics and Uptime* feature in the *{observability}* section of the
|
||||
<<kibana-feature-privileges,{kib} feature privileges>>.
|
||||
|
||||
[[private-locations-list-response-example]]
|
||||
==== List Response Example
|
||||
|
||||
The API returns a JSON array of private locations when accessing the list endpoint, with each private location having the following attributes:
|
||||
|
||||
- `label` (string): A label for the private location.
|
||||
- `id` (string): The unique identifier of the private location.
|
||||
- `agentPolicyId` (string): The ID of the agent policy associated with the private location.
|
||||
- `isInvalid` (boolean): Indicates whether the location is invalid. If `true`, the location is invalid, which means the agent policy associated with the location is deleted.
|
||||
- `geo` (object): Geographic coordinates for the location, including `lat` and `lon`.
|
||||
- `namespace` (string): The namespace of the location, which is the same as the namespace of the agent policy associated with the location.
|
||||
|
||||
Here's an example list response:
|
||||
|
||||
[source,json]
|
||||
--------------------------------------------------
|
||||
[
|
||||
{
|
||||
"label": "Test private location",
|
||||
"id": "fleet-server-policy",
|
||||
"agentPolicyId": "fleet-server-policy",
|
||||
"isInvalid": false,
|
||||
"geo": {
|
||||
"lat": 0,
|
||||
"lon": 0
|
||||
},
|
||||
"namespace": "default"
|
||||
},
|
||||
{
|
||||
"label": "Test private location 2",
|
||||
"id": "691225b0-6ced-11ee-8f5a-376306ee85ae",
|
||||
"agentPolicyId": "691225b0-6ced-11ee-8f5a-376306ee85ae",
|
||||
"isInvalid": false,
|
||||
"geo": {
|
||||
"lat": 0,
|
||||
"lon": 0
|
||||
},
|
||||
"namespace": "test"
|
||||
}
|
||||
]
|
||||
--------------------------------------------------
|
||||
|
||||
[[private-location-by-id-response-example]]
|
||||
==== Get by ID/Label Response Example
|
||||
|
||||
The API returns a JSON object of a single private location when accessing the endpoint with a specific `id`, with the same attributes as in the list response.
|
||||
|
||||
Here's an example request for a single location by ID:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
GET api/synthetics/private_locations/<location_id>
|
||||
--------------------------------------------------
|
||||
|
||||
or by label:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
GET api/synthetics/private_locations/<Location label>
|
||||
--------------------------------------------------
|
||||
|
||||
Here's an example response object:
|
||||
|
||||
[source,json]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"label": "Test private location",
|
||||
"id": "test-private-location-id",
|
||||
"agentPolicyId": "test-private-location-id",
|
||||
"isServiceManaged": false,
|
||||
"isInvalid": false,
|
||||
"geo": {
|
||||
"lat": 0,
|
||||
"lon": 0
|
||||
},
|
||||
"namespace": "default"
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,42 +0,0 @@
|
|||
[[synthetics-apis]]
|
||||
== Synthetics APIs
|
||||
|
||||
The following APIs are available for Synthetics.
|
||||
|
||||
* <<add-monitor-api, Add monitor>> - Add a new monitor to Synthetics app.
|
||||
|
||||
* <<update-monitor-api, Update monitor>> - Update an existing monitor in Synthetics app.
|
||||
|
||||
* <<delete-monitors-api, Delete monitor>> - Delete an existing monitor from Synthetics app.
|
||||
|
||||
* <<get-monitor-api, Get monitor>> to get a monitor.
|
||||
|
||||
* <<find-monitors-api, Find monitors>> to find monitors.
|
||||
|
||||
* <<get-parameters-api, Get Parameters API>> to get a parameter(s).
|
||||
|
||||
* <<add-parameters-api, Create Parameter API>> to create a parameter.
|
||||
|
||||
* <<edit-parameter-by-id-api, Edit Parameter API>> to edit a parameter.
|
||||
|
||||
* <<delete-parameters-api, Delete Parameter API>> to delete a parameter.
|
||||
|
||||
* <<create-private-location-api, Create Private Location API>> to create a private location
|
||||
|
||||
* <<delete-private-location-api, Delete Private Location API>> to delete a private location
|
||||
|
||||
* <<get-private-locations-api, Get Private Locations API>> to get a list of private locations
|
||||
|
||||
include::monitors/add-monitor-api.asciidoc[leveloffset=+1]
|
||||
include::monitors/update-monitor-api.asciidoc[leveloffset=+1]
|
||||
include::monitors/delete-monitor-api.asciidoc[leveloffset=+1]
|
||||
include::monitors/get-monitor-api.asciidoc[leveloffset=+1]
|
||||
include::monitors/find-monitors-api.asciidoc[leveloffset=+1]
|
||||
include::params/add-param.asciidoc[leveloffset=+1]
|
||||
include::params/get-params.asciidoc[leveloffset=+1]
|
||||
include::params/edit-param.asciidoc[leveloffset=+1]
|
||||
include::params/delete-param.asciidoc[leveloffset=+1]
|
||||
include::private-locations/create-private-location.asciidoc[leveloffset=+1]
|
||||
include::private-locations/delete-private-location.asciidoc[leveloffset=+1]
|
||||
include::private-locations/get-private-locations.asciidoc[leveloffset=+1]
|
||||
|
||||
|
|
@ -1,135 +0,0 @@
|
|||
[[task-manager-api-health]]
|
||||
== Task Manager health API
|
||||
++++
|
||||
<titleabbrev>Get Task Manager health</titleabbrev>
|
||||
++++
|
||||
|
||||
Retrieve the health status of the {kib} Task Manager.
|
||||
|
||||
[float]
|
||||
[[task-manager-api-health-request]]
|
||||
=== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/task_manager/_health`
|
||||
|
||||
[float]
|
||||
[[task-manager-api-health-codes]]
|
||||
=== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
[float]
|
||||
[[task-manager-api-health-example]]
|
||||
=== Example
|
||||
|
||||
Retrieve the health status of the {kib} Task Manager:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X GET api/task_manager/_health
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns the following:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"id": "15415ecf-cdb0-4fef-950a-f824bd277fe4",
|
||||
"timestamp": "2021-02-16T11:38:10.077Z",
|
||||
"status": "OK",
|
||||
"last_update": "2021-02-16T11:38:09.934Z",
|
||||
"stats": {
|
||||
"configuration": {
|
||||
"timestamp": "2021-02-16T11:29:05.055Z",
|
||||
"value": {
|
||||
"request_capacity": 1000,
|
||||
"monitored_aggregated_stats_refresh_rate": 60000,
|
||||
"monitored_stats_running_average_window": 50,
|
||||
"monitored_task_execution_thresholds": {
|
||||
"default": {
|
||||
"error_threshold": 90,
|
||||
"warn_threshold": 80
|
||||
},
|
||||
"custom": {}
|
||||
},
|
||||
"poll_interval": 3000,
|
||||
"max_workers": 10
|
||||
},
|
||||
"status": "OK"
|
||||
},
|
||||
"runtime": {
|
||||
"timestamp": "2021-02-16T11:38:09.934Z",
|
||||
"value": {
|
||||
"polling": {
|
||||
"last_successful_poll": "2021-02-16T11:38:09.934Z",
|
||||
"last_polling_delay": "2021-02-16T11:29:05.053Z",
|
||||
"duration": {
|
||||
"p50": 0,
|
||||
"p90": 0,
|
||||
"p95": 0,
|
||||
"p99": 0
|
||||
},
|
||||
"claim_conflicts": {
|
||||
"p50": 0,
|
||||
"p90": 0,
|
||||
"p95": 0,
|
||||
"p99": 0
|
||||
},
|
||||
"claim_mismatches": {
|
||||
"p50": 0,
|
||||
"p90": 0,
|
||||
"p95": 0,
|
||||
"p99": 0
|
||||
},
|
||||
"result_frequency_percent_as_number": {
|
||||
"Failed": 0,
|
||||
"NoAvailableWorkers": 0,
|
||||
"NoTasksClaimed": 0,
|
||||
"RanOutOfCapacity": 0,
|
||||
"RunningAtCapacity": 0,
|
||||
"PoolFilled": 0
|
||||
}
|
||||
},
|
||||
"drift": {
|
||||
"p50": 0,
|
||||
"p90": 0,
|
||||
"p95": 0,
|
||||
"p99": 0
|
||||
},
|
||||
"load": {
|
||||
"p50": 0,
|
||||
"p90": 0,
|
||||
"p95": 0,
|
||||
"p99": 0
|
||||
},
|
||||
"execution": {
|
||||
"duration": {},
|
||||
"result_frequency_percent_as_number": {}
|
||||
}
|
||||
},
|
||||
"status": "OK"
|
||||
},
|
||||
"workload": {
|
||||
"timestamp": "2021-02-16T11:38:05.826Z",
|
||||
"value": {
|
||||
"count": 26,
|
||||
"task_types": {},
|
||||
"schedule": [],
|
||||
"overdue": 0,
|
||||
"estimated_schedule_density": []
|
||||
},
|
||||
"status": "OK"
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
The health API response is described in <<making-sense-of-task-manager-health-stats>>.
|
||||
|
||||
The health monitoring API exposes three sections:
|
||||
|
||||
* `configuration` is described in detail under <<task-manager-health-evaluate-the-configuration>>
|
||||
* `workload` is described in detail under <<task-manager-health-evaluate-the-workload>>
|
||||
* `runtime` is described in detail under <<task-manager-health-evaluate-the-runtime>>
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
[role="xpack"]
|
||||
[[upgrade-assistant-api]]
|
||||
== Upgrade assistant APIs
|
||||
|
||||
Check the upgrade status of your {es} cluster and reindex indices that were created in the previous major version. The assistant helps you prepare for the next major version of {es}.
|
||||
|
||||
The following upgrade assistant APIs are available:
|
||||
|
||||
* <<upgrade-assistant-api-status, Upgrade readiness status API>> to check the status of your cluster
|
||||
|
||||
* <<start-resume-reindex, Start or resume reindex API>> to start a new reindex or resume a paused reindex
|
||||
|
||||
* <<batch-start-resume-reindex, Batch start or resume reindex API>> to start or resume multiple reindex tasks
|
||||
|
||||
* <<batch-reindex-queue, Batch reindex queue API>> to check the current reindex batch queue
|
||||
|
||||
* <<check-reindex-status, Check reindex status API>> to check the status of the reindex operation
|
||||
|
||||
* <<cancel-reindex, Cancel reindex API>> to cancel reindexes that are waiting for the {es} reindex task to complete
|
||||
|
||||
include::upgrade-assistant/status.asciidoc[]
|
||||
include::upgrade-assistant/reindexing.asciidoc[]
|
||||
include::upgrade-assistant/batch_reindexing.asciidoc[]
|
||||
include::upgrade-assistant/batch_queue.asciidoc[]
|
||||
include::upgrade-assistant/default-field.asciidoc[]
|
||||
include::upgrade-assistant/check_reindex_status.asciidoc[]
|
||||
include::upgrade-assistant/cancel_reindex.asciidoc[]
|
||||
|
|
@ -1,68 +0,0 @@
|
|||
[[batch-reindex-queue]]
|
||||
=== Batch reindex queue API
|
||||
++++
|
||||
<titleabbrev>Batch reindex queue</titleabbrev>
|
||||
++++
|
||||
|
||||
experimental["The underlying Upgrade Assistant concepts are stable, but the APIs for managing Upgrade Assistant are experimental."]
|
||||
|
||||
Check the current reindex batch queue.
|
||||
|
||||
[[batch-reindex-queue-request]]
|
||||
==== Request
|
||||
|
||||
`GET /api/upgrade_assistant/reindex/batch/queue`
|
||||
|
||||
[[batch-reindex-queue-request-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
[[batch-reindex-queue-example]]
|
||||
==== Example
|
||||
|
||||
The API returns the following:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"queue": [ <1>
|
||||
{
|
||||
"indexName": "index1",
|
||||
"newIndexName": "reindexed-v8-index2",
|
||||
"status": 3,
|
||||
"lastCompletedStep": 0,
|
||||
"locked": null,
|
||||
"reindexTaskId": null,
|
||||
"reindexTaskPercComplete": null,
|
||||
"errorMessage": null,
|
||||
"runningReindexCount": null,
|
||||
"reindexOptions": {
|
||||
"queueSettings": {
|
||||
"queuedAt": 1583406985489
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"indexName": "index2",
|
||||
"newIndexName": "reindexed-v8-index2",
|
||||
"status": 3,
|
||||
"lastCompletedStep": 0,
|
||||
"locked": null,
|
||||
"reindexTaskId": null,
|
||||
"reindexTaskPercComplete": null,
|
||||
"errorMessage": null,
|
||||
"runningReindexCount": null,
|
||||
"reindexOptions": {
|
||||
"queueSettings": {
|
||||
"queuedAt": 1583406987334
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
<1> Items in this array indicate reindex tasks at a given point in time and the order in which they will be executed.
|
||||
|
||||
|
|
@ -1,85 +0,0 @@
|
|||
[[batch-start-resume-reindex]]
|
||||
=== Batch start or resume reindex API
|
||||
++++
|
||||
<titleabbrev>Batch start or resume reindex</titleabbrev>
|
||||
++++
|
||||
|
||||
experimental["The underlying Upgrade Assistant concepts are stable, but the APIs for managing Upgrade Assistant are experimental."]
|
||||
|
||||
Start or resume upgrading multiple indices in one request. Additionally, <<start-resume-reindex, reindexing>> tasks for upgrading
|
||||
indices that are started or resumed via the batch endpoint will be placed on a queue and executed one-by-one. This ensures that
|
||||
minimal cluster resources are consumed over time.
|
||||
|
||||
NOTE: This API does not support data streams.
|
||||
|
||||
[[batch-start-resume-reindex-request]]
|
||||
==== Request
|
||||
|
||||
`POST /api/upgrade_assistant/reindex/batch`
|
||||
|
||||
[[batch-start-resume-reindex-request-body]]
|
||||
==== Request body
|
||||
|
||||
`indexNames`::
|
||||
(Required, array) The list of index names to be reindexed.
|
||||
|
||||
[[batch-start-resume-reindex-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
[[batch-start-resume-example]]
|
||||
==== Example
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/upgrade_assistant/reindex/batch
|
||||
{
|
||||
"indexNames": [ <1>
|
||||
"index1",
|
||||
"index2"
|
||||
]
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
<1> The order of the indices determines the order that the reindex tasks are executed.
|
||||
|
||||
Similar to the <<start-resume-reindex, start or resume endpoint>>, the API returns the following:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"enqueued": [ <1>
|
||||
{
|
||||
"indexName": "index1",
|
||||
"newIndexName": "reindexed-v8-index1",
|
||||
"status": 3,
|
||||
"lastCompletedStep": 0,
|
||||
"locked": null,
|
||||
"reindexTaskId": null,
|
||||
"reindexTaskPercComplete": null,
|
||||
"errorMessage": null,
|
||||
"runningReindexCount": null,
|
||||
"reindexOptions": { <2>
|
||||
"queueSettings": {
|
||||
"queuedAt": 1583406985489 <3>
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"errors": [ <4>
|
||||
{
|
||||
"indexName": "index2",
|
||||
"message": "Something went wrong!"
|
||||
}
|
||||
]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
<1> A list of reindex tasks created, the order in the array indicates the order in which tasks will be executed.
|
||||
<2> Presence of this key indicates that the reindex job will occur in the batch.
|
||||
<3> A Unix timestamp of when the reindex task was placed in the queue.
|
||||
<4> A list of errors that may have occurred preventing the reindex task from being created.
|
||||
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
[[cancel-reindex]]
|
||||
=== Cancel reindex API
|
||||
++++
|
||||
<titleabbrev>Cancel reindex</titleabbrev>
|
||||
++++
|
||||
|
||||
experimental["The underlying Upgrade Assistant concepts are stable, but the APIs for managing Upgrade Assistant are experimental."]
|
||||
|
||||
Cancel reindexes that are waiting for the Elasticsearch reindex task to complete. For example, `lastCompletedStep` set to `40`.
|
||||
|
||||
[[cancel-reindex-request]]
|
||||
==== Request
|
||||
|
||||
`POST <kibana host>:<port>/api/upgrade_assistant/reindex/myIndex/cancel`
|
||||
|
||||
[[cancel-reindex-response-codes]]
|
||||
==== Response codes
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
[[cancel-reindex-status-example]]
|
||||
==== Example
|
||||
|
||||
The API returns the following:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,111 +0,0 @@
|
|||
[[check-reindex-status]]
|
||||
=== Check reindex status API
|
||||
++++
|
||||
<titleabbrev>Check reindex status</titleabbrev>
|
||||
++++
|
||||
|
||||
experimental["The underlying Upgrade Assistant concepts are stable, but the APIs for managing Upgrade Assistant are experimental."]
|
||||
|
||||
Check the status of the reindex task.
|
||||
|
||||
[[check-reindex-status-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/upgrade_assistant/reindex/myIndex`
|
||||
|
||||
[[check-reindex-status-response-codes]]
|
||||
==== Response codes
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
[[check-reindex-status-example]]
|
||||
==== Example
|
||||
|
||||
The API returns the following:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"reindexOp": {
|
||||
"indexName": ".ml-state",
|
||||
"newIndexName": ".reindexed-v7-ml-state", <1>
|
||||
"status": 0, <2>
|
||||
"lastCompletedStep": 40, <3>
|
||||
"reindexTaskId": "QprwvTMzRQ2MLWOW22oQ4Q:11819", <4>
|
||||
"reindexTaskPercComplete": 0.3, <5>
|
||||
"errorMessage": null <6>
|
||||
},
|
||||
"warnings": [], <7>
|
||||
"hasRequiredPrivileges": true <8>
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
<1> Name of the new index that is being created.
|
||||
<2> Current status of the reindex. For details, see <<status-code,Status codes>>.
|
||||
<3> Last successfully completed step of the reindex. For details, see <<step-code,Step codes>> table.
|
||||
<4> Task ID of the reindex task in Elasticsearch. Only present if reindexing has started.
|
||||
<5> Percentage of how far the reindexing task in Elasticsearch has progressed, in decimal form from 0 to 1.
|
||||
<6> Error that caused the reindex to fail, if it failed.
|
||||
<7> An array of any warning codes explaining what changes are required for this reindex. For details, see <<warning-code,Warning codes>>.
|
||||
<8> Specifies if the user has sufficient privileges to reindex this index. When security is unavailable or disables, returns `true`.
|
||||
|
||||
[[status-code]]
|
||||
==== Status codes
|
||||
|
||||
`0`::
|
||||
In progress
|
||||
|
||||
`1`::
|
||||
Completed
|
||||
|
||||
`2`::
|
||||
Failed
|
||||
|
||||
`3`::
|
||||
Paused
|
||||
+
|
||||
NOTE: If the {kib} node that started the reindex is shutdown or restarted, the reindex goes into a paused state after some time.
|
||||
To resume the reindex, you must submit a new POST request to the `/api/upgrade_assistant/reindex/<indexName>` endpoint.
|
||||
|
||||
`4`::
|
||||
Cancelled
|
||||
|
||||
[[step-code]]
|
||||
==== Step codes
|
||||
|
||||
`0`::
|
||||
The reindex task has been created in Kibana.
|
||||
|
||||
`10`::
|
||||
The index group services stopped. Only applies to some system indices.
|
||||
|
||||
`20`::
|
||||
The index is set to `readonly`.
|
||||
|
||||
`30`::
|
||||
The new destination index has been created.
|
||||
|
||||
`40`::
|
||||
The reindex task in Elasticsearch has started.
|
||||
|
||||
`50`::
|
||||
The reindex task in Elasticsearch has completed.
|
||||
|
||||
`60`::
|
||||
Aliases were created to point to the new index, and the old index has been deleted.
|
||||
|
||||
`70`::
|
||||
The index group services have resumed. Only applies to some system indices.
|
||||
|
||||
[[warning-code]]
|
||||
==== Warning codes
|
||||
|
||||
`0`::
|
||||
Specifies to remove the `_all` meta field.
|
||||
|
||||
`1`::
|
||||
Specifies to convert any coerced boolean values in the source document. For example, `yes`, `1`, and `off`.
|
||||
|
||||
`2`::
|
||||
Specifies to convert documents to support Elastic Common Schema. Only applies to APM indices created in 6.x.
|
||||
|
|
@ -1,113 +0,0 @@
|
|||
[[upgrade-assistant-api-default-field]]
|
||||
=== Add default field API
|
||||
++++
|
||||
<titleabbrev>Add default field</titleabbrev>
|
||||
++++
|
||||
|
||||
experimental[] In {es} 7.0 and later, some query types, such as Simple Query String, have a limit to the number of fields they can query against.
|
||||
To configure the cap in {es}, set the `indices.query.bool.max_clause_count` cluster setting, which is 1024 by default.
|
||||
|
||||
For indices with more fields than the cap, add the `index.query.default_field` index setting to inform {es} which
|
||||
fields to use by default when no field is specified for a query. Use the add default field API to add the `index.query.default_field` setting to an {es} index.
|
||||
|
||||
[[upgrade-assistant-api-default-field-request]]
|
||||
==== Request
|
||||
|
||||
To add the `index.query.default_field` setting to an {es} index, submit a POST request to `/api/upgrade_assistant/add_query_default_field/<index>`:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
GET /api/upgrade_assistant/add_query_default_field/myIndex
|
||||
{
|
||||
"fieldTypes": ["text", "keyword"], <1>
|
||||
"otherFields": ["myField.*"] <2>
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
<1> A required array of {es} field types that generate the list of fields.
|
||||
<2> An optional array of additional field names, dot-delimited.
|
||||
|
||||
To add the `index.query.default_field` index setting to the specified index, {kib} generates an array of all fields from the index mapping.
|
||||
The fields contain the types specified in `fieldTypes`. {kib} appends any other fields specified in `otherFields` to the array of default fields.
|
||||
|
||||
[[upgrade-assistant-api-default-field-response-codes]]
|
||||
==== Response codes
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
`400`::
|
||||
Indicates that the index already has the `index.query.default_field` setting. No changes are made to the index.
|
||||
|
||||
[[upgrade-assistant-api-default-field-response-body]]
|
||||
==== Response body
|
||||
|
||||
The response body contains a JSON structure, similar to the following:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
[[upgrade-assistant-api-default-field-example]]
|
||||
==== Example
|
||||
|
||||
Your index contains following mappings:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
GET /myIndex/_mappings
|
||||
{
|
||||
"myIndex": {
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"field1": { "type": "text" },
|
||||
"field2": { "type": "float" },
|
||||
"nestedfield": {
|
||||
"properties": {
|
||||
"field3": { "type": "keyword" },
|
||||
"field4": { "type": "long" },
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
Make the following request to {kib}:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
GET /api/upgrade_assistant/add_query_default_field/myIndex
|
||||
{
|
||||
"fieldTypes": ["text", "long"],
|
||||
"otherFields": ["field2"]
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
The API returns the following:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
GET /myIndex/_settings?flat_settings=true
|
||||
{
|
||||
"myIndex": {
|
||||
"settings": {
|
||||
"index.query.default_field": [
|
||||
"field1",
|
||||
"nestedfield.field4",
|
||||
"field2",
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
{kib} generates the `field1` and `nestedfield.field4` values based on the specified `fieldTypes`, then appends the `otherFields` to the array.
|
||||
|
|
@ -1,54 +0,0 @@
|
|||
[[start-resume-reindex]]
|
||||
=== Start or resume reindex API
|
||||
++++
|
||||
<titleabbrev>Start or resume reindex</titleabbrev>
|
||||
++++
|
||||
|
||||
experimental["The underlying Upgrade Assistant concepts are stable, but the APIs for managing Upgrade Assistant are experimental."]
|
||||
|
||||
Start a new reindex or resume a paused reindex. Following steps are performed during
|
||||
a reindex task:
|
||||
|
||||
. Setting the index to read-only
|
||||
. Creating a new index
|
||||
. {ref}/docs-reindex.html[Reindexing] documents into the new index
|
||||
. Creating an index alias for the new index
|
||||
. Deleting the old index
|
||||
|
||||
|
||||
|
||||
[[start-resume-reindex-request]]
|
||||
==== Request
|
||||
|
||||
`POST <kibana host>:<port>/api/upgrade_assistant/reindex/myIndex`
|
||||
|
||||
[[start-resume-reindex-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
[[start-resume-reindex-example]]
|
||||
==== Example
|
||||
|
||||
The API returns the following:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"indexName": ".ml-state",
|
||||
"newIndexName": ".reindexed-v7-ml-state", <1>
|
||||
"status": 0, <2>
|
||||
"lastCompletedStep": 0, <3>
|
||||
"reindexTaskId": null, <4>
|
||||
"reindexTaskPercComplete": null, <5>
|
||||
"errorMessage": null <6>
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
<1> The name of the new index.
|
||||
<2> The reindex status. For more information, refer to <<status-code,Status codes>>.
|
||||
<3> The last successfully completed step of the reindex. For more information, refer to <<step-code,Step codes>>.
|
||||
<4> The task ID of the {ref}/docs-reindex.html[reindex] task in {es}. Appears when the reindexing starts.
|
||||
<5> The progress of the {ref}/docs-reindex.html[reindexing] task in {es}. Appears in decimal form, from 0 to 1.
|
||||
<6> The error that caused the reindex to fail, if it failed.
|
||||
|
|
@ -1,39 +0,0 @@
|
|||
[[upgrade-assistant-api-status]]
|
||||
=== Upgrade readiness status API
|
||||
++++
|
||||
<titleabbrev>Upgrade readiness status</titleabbrev>
|
||||
++++
|
||||
|
||||
experimental["The underlying Upgrade Assistant concepts are stable, but the APIs for managing Upgrade Assistant are experimental."]
|
||||
|
||||
Check the status of your cluster.
|
||||
|
||||
[[upgrade-assistant-api-status-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/upgrade_assistant/status?targetVersion=9.0.0`
|
||||
|
||||
`targetVersion`::
|
||||
(optional, string): Version to upgrade to.
|
||||
|
||||
[[upgrade-assistant-api-status-response-codes]]
|
||||
==== Response codes
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
`403`::
|
||||
Indicates a forbidden request when the upgrade path is not supported (e.g. upgrading more than 1 major or downgrading)
|
||||
|
||||
[[upgrade-assistant-api-status-example]]
|
||||
==== Example
|
||||
|
||||
The API returns the following:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"readyForUpgrade": false,
|
||||
"details":"The following issues must be resolved before upgrading: 1 Elasticsearch deprecation issue."
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,11 +0,0 @@
|
|||
[[uptime-apis]]
|
||||
== Uptime APIs
|
||||
|
||||
The following APIs are available for Uptime.
|
||||
|
||||
* <<get-settings-api, Get settings API>> to get a settings
|
||||
|
||||
* <<update-settings-api, Update settings API>> to update the attributes for existing settings
|
||||
|
||||
include::uptime/get-settings.asciidoc[leveloffset=+1]
|
||||
include::uptime/update-settings.asciidoc[leveloffset=+1]
|
||||
|
|
@ -1,39 +0,0 @@
|
|||
[[get-settings-api]]
|
||||
== Get settings API
|
||||
++++
|
||||
<titleabbrev>Get settings</titleabbrev>
|
||||
++++
|
||||
|
||||
Retrieve uptime settings existing settings.
|
||||
|
||||
[[get-settings-api-request]]
|
||||
=== {api-request-title}
|
||||
|
||||
`GET <kibana host>:<port>/api/uptime/settings`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space_id>/api/uptime/settings`
|
||||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `read` privileges for the *uptime* feature in *{observability}* section of the
|
||||
<<kibana-feature-privileges,{kib} feature privileges>>.
|
||||
|
||||
The API returns the following:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"heartbeatIndices": "heartbeat-8*",
|
||||
"certExpirationThreshold": 30,
|
||||
"certAgeThreshold": 730,
|
||||
"defaultConnectors": [
|
||||
"08990f40-09c5-11ee-97ae-912b222b13d4",
|
||||
"db25f830-2318-11ee-9391-6b0c030836d6"
|
||||
],
|
||||
"defaultEmail": {
|
||||
"to": [],
|
||||
"cc": [],
|
||||
"bcc": []
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,117 +0,0 @@
|
|||
[[update-settings-api]]
|
||||
== Update settings API
|
||||
++++
|
||||
<titleabbrev>Update settings</titleabbrev>
|
||||
++++
|
||||
|
||||
Updates uptime settings attributes like heartbeatIndices, certExpirationThreshold, certAgeThreshold, defaultConnectors or defaultEmail
|
||||
|
||||
=== {api-request-title}
|
||||
|
||||
`PUT <kibana host>:<port>/api/uptime/settings`
|
||||
|
||||
`PUT <kibana host>:<port>/s/<space_id>/api/uptime/settings`
|
||||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `all` privileges for the *uptime* feature in *{observability}* section of the
|
||||
<<kibana-feature-privileges,{kib} feature privileges>>.
|
||||
|
||||
[[settings-api-update-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
|
||||
|
||||
[[api-update-request-body]]
|
||||
==== Request body
|
||||
|
||||
A partial update is supported, provided settings keys will be merged with existing settings.
|
||||
|
||||
`heartbeatIndices`::
|
||||
(Optional, string) index pattern string to be used within uptime app/alerts to query heartbeat data. Defaults to `heartbeat-*`.
|
||||
|
||||
|
||||
`certExpirationThreshold`::
|
||||
(Optional, number) Number of days before a certificate expires to trigger an alert. Defaults to `30`.
|
||||
|
||||
`certAgeThreshold`::
|
||||
(Optional, number) Number of days after a certificate is created to trigger an alert. Defaults to `730`.
|
||||
|
||||
`defaultConnectors`::
|
||||
(Optional, array) List of connector IDs to be used as default connectors for new alerts. Defaults to `[]`.
|
||||
|
||||
`defaultEmail`::
|
||||
(Optional, object) Default email configuration for new alerts. Defaults to `{"to": [], "cc": [], "bcc": []}`.
|
||||
|
||||
[[settings-api-update-example]]
|
||||
==== Example
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
PUT api/uptime/settings
|
||||
{
|
||||
"heartbeatIndices": "heartbeat-8*",
|
||||
"certExpirationThreshold": 30,
|
||||
"certAgeThreshold": 730,
|
||||
"defaultConnectors": [
|
||||
"08990f40-09c5-11ee-97ae-912b222b13d4",
|
||||
"db25f830-2318-11ee-9391-6b0c030836d6"
|
||||
],
|
||||
"defaultEmail": {
|
||||
"to": [],
|
||||
"cc": [],
|
||||
"bcc": []
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
The API returns the following:
|
||||
|
||||
[source,json]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"heartbeatIndices": "heartbeat-8*",
|
||||
"certExpirationThreshold": 30,
|
||||
"certAgeThreshold": 730,
|
||||
"defaultConnectors": [
|
||||
"08990f40-09c5-11ee-97ae-912b222b13d4",
|
||||
"db25f830-2318-11ee-9391-6b0c030836d6"
|
||||
],
|
||||
"defaultEmail": {
|
||||
"to": [],
|
||||
"cc": [],
|
||||
"bcc": []
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
[[settings-api-partial-update-example]]
|
||||
==== Partial update example
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
PUT api/uptime/settings
|
||||
{
|
||||
"heartbeatIndices": "heartbeat-8*",
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
The API returns the following:
|
||||
|
||||
[source,json]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"heartbeatIndices": "heartbeat-8*",
|
||||
"certExpirationThreshold": 30,
|
||||
"certAgeThreshold": 730,
|
||||
"defaultConnectors": [
|
||||
"08990f40-09c5-11ee-97ae-912b222b13d4",
|
||||
"db25f830-2318-11ee-9391-6b0c030836d6"
|
||||
],
|
||||
"defaultEmail": {
|
||||
"to": [],
|
||||
"cc": [],
|
||||
"bcc": []
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,134 +0,0 @@
|
|||
[role="xpack"]
|
||||
[[edit-workpads]]
|
||||
== Edit workpads
|
||||
|
||||
To create the look and feel that you want, apply format settings to the entire workpad, or individual elements.
|
||||
|
||||
[float]
|
||||
[[create-variables]]
|
||||
=== Create variables
|
||||
|
||||
When you frequently use copy and paste, create variables to easily reuse strings and patterns. For example, when you clone a large workpad and need to connect your elements to a new index, use variables to update
|
||||
each element instead of updating them manually.
|
||||
|
||||
. Create the variables.
|
||||
.. Expand the *Variables* options.
|
||||
.. Click *Add a variable*.
|
||||
.. Specify the variable options, then click *Save changes*.
|
||||
|
||||
. Apply the variable.
|
||||
.. Copy the variable.
|
||||
.. Select the element you want to change, then open the expression editor.
|
||||
.. Paste the variable.
|
||||
|
||||
For example, to change the {data-source} for a set of charts:
|
||||
|
||||
. Specify the variable options.
|
||||
+
|
||||
[role="screenshot"]
|
||||
image::images/specify_variable_syntax.png[Variable syntax options]
|
||||
+
|
||||
. Copy the variable, then apply it to each element you want to update in the *Expression editor*.
|
||||
+
|
||||
[role="screenshot"]
|
||||
image::images/copy_variable_syntax.png[Copied variable syntax pasted in the Expression editor]
|
||||
|
||||
[float]
|
||||
[[apply-changes-to-the-entire-workpad]]
|
||||
=== Apply changes to the entire workpad
|
||||
|
||||
With stylesheets, you can change the look of the entire workpad, including fonts, colors, layout, and more.
|
||||
|
||||
To get started, enter the changes you want to make in the *Global CSS overrides* text editor, then click *Apply stylesheet*.
|
||||
|
||||
For example, to change the background for the entire workpad, enter:
|
||||
|
||||
[source,text]
|
||||
--------------------------------------------------
|
||||
.canvasPage {
|
||||
background-color: #3990e6;
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
[float]
|
||||
[[change-the-element-settings]]
|
||||
=== Change the element settings
|
||||
|
||||
Element settings enable you to change the display options at the element level. For example, use the element settings to change the dimensions, style, or location of an element.
|
||||
|
||||
[float]
|
||||
[[change-the-display-options]]
|
||||
==== Change the display options
|
||||
|
||||
Choose the display options for your elements. The options available depend on the element you select.
|
||||
|
||||
To change the element display options, click *Display*, then make your changes in the editor.
|
||||
|
||||
To use CSS overrides:
|
||||
|
||||
. Click *+* next to *Element style*, then select *CSS*.
|
||||
. In the *CSS* text editor, enter the changes you want to make, then click *Apply stylesheet*.
|
||||
|
||||
For example, to center an element, enter:
|
||||
|
||||
[source,text]
|
||||
--------------------------------------------------
|
||||
.canvasRenderEl h1 {
|
||||
text.align: center;
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
[float]
|
||||
[[clone-elements]]
|
||||
==== Clone elements
|
||||
To use an element with the same functionality and appearance in multiple places, clone the element.
|
||||
|
||||
Select the element, then click *Edit > Clone*.
|
||||
|
||||
[float]
|
||||
[[move-and-resize-elements]]
|
||||
==== Move and resize elements
|
||||
|
||||
Canvas provides you with many options to move and resize the elements on your workpad.
|
||||
|
||||
* To move elements, click and hold the element, then drag to the new location.
|
||||
|
||||
* To move elements by 1 pixel, select the element, press and hold Shift, then use your arrow keys.
|
||||
|
||||
* To move elements by 10 pixels, select the element, then use your arrow keys.
|
||||
|
||||
* To resize elements, click and drag the resize handles to the new dimensions.
|
||||
|
||||
[float]
|
||||
[[edit-elements]]
|
||||
==== Edit elements
|
||||
|
||||
The element editing options allow you to arrange and organize the elements on your workpad page.
|
||||
|
||||
To align two or more elements:
|
||||
|
||||
. Press and hold Shift, then select the elements you want to align.
|
||||
|
||||
. Click *Edit > Alignment*, then select the alignment option.
|
||||
|
||||
To distribute three or more elements:
|
||||
|
||||
. Press and hold Shift, then select the elements you want to distribute.
|
||||
|
||||
. Click *Edit > Distribution*, then select the distribution option.
|
||||
|
||||
To reorder elements:
|
||||
|
||||
. Select the element you want to reorder.
|
||||
|
||||
. Click *Edit > Order*, then select the order option.
|
||||
|
||||
[float]
|
||||
[[delete-elements]]
|
||||
==== Delete elements
|
||||
|
||||
When you no longer need an element, delete it from your workpad.
|
||||
|
||||
. Select the element you want to delete.
|
||||
|
||||
. Click *Edit > Delete*.
|
||||
File diff suppressed because it is too large
Load diff
|
|
@ -1,39 +0,0 @@
|
|||
[role="xpack"]
|
||||
[[canvas-present-workpad]]
|
||||
== Present your workpad
|
||||
|
||||
When you are ready to present your workpad, use and enable the presentation options.
|
||||
|
||||
. Configure the autoplay options.
|
||||
|
||||
.. From the workpad menu, click *View > Autoplay settings*.
|
||||
|
||||
.. Under *Change cycling interval*, select the interval you want to use, or *Set a custom interval*.
|
||||
|
||||
. To enable autoplay, click *View > Turn autoplay on*.
|
||||
|
||||
. To start your presentation, click *View > Enter fullscreen mode*.
|
||||
|
||||
. When you are ready to exit fullscreen mode, press Esc.
|
||||
|
||||
[float]
|
||||
[[zoom-in-out]]
|
||||
=== Use the zoom options
|
||||
|
||||
To get a closer look at a portion of your workpad, use the zoom options.
|
||||
|
||||
. Click *View > Zoom*.
|
||||
|
||||
. Select the zoom option.
|
||||
|
||||
[float]
|
||||
[[configure-auto-refresh-interval]]
|
||||
=== Change the auto-refresh interval
|
||||
|
||||
Change how often the data refreshes on your workpad.
|
||||
|
||||
. Click *View > Auto refresh settings*.
|
||||
|
||||
. Select the interval you want to use, or *Set a custom interval*.
|
||||
+
|
||||
To manually refresh the data, click image:canvas/images/canvas-refresh-data.png[Canvas refresh data button].
|
||||
|
|
@ -1,974 +0,0 @@
|
|||
[role="xpack"]
|
||||
[[canvas-tinymath-functions]]
|
||||
=== TinyMath functions
|
||||
|
||||
TinyMath provides a set of functions that can be used with the Canvas expression
|
||||
language to perform complex math calculations. Read on for detailed information about
|
||||
the functions available in TinyMath, including what parameters each function accepts,
|
||||
the return value of that function, and examples of how each function behaves.
|
||||
|
||||
Most of the functions accept arrays and apply JavaScript Math methods to
|
||||
each element of that array. For the functions that accept multiple arrays as
|
||||
parameters, the function generally does the calculation index by index.
|
||||
|
||||
Any function can be wrapped by another function as long as the return type
|
||||
of the inner function matches the acceptable parameter type of the outer function.
|
||||
|
||||
[float]
|
||||
=== abs( a )
|
||||
|
||||
Calculates the absolute value of a number. For arrays, the function will be
|
||||
applied index-wise to each element.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|number \| Array.<number>
|
||||
|a number or an array of numbers
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The absolute value of `a`. Returns
|
||||
an array with the absolute values of each element if `a` is an array.
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
abs(-1) // returns 1
|
||||
abs(2) // returns 2
|
||||
abs([-1 , -2, 3, -4]) // returns [1, 2, 3, 4]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== add( ...args )
|
||||
|
||||
Calculates the sum of one or more numbers/arrays passed into the function. If at
|
||||
least one array of numbers is passed into the function, the function will calculate the sum by index.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|...args
|
||||
|number \| Array.<number>
|
||||
|one or more numbers or arrays of numbers
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The sum of all numbers in `args` if `args`
|
||||
contains only numbers. Returns an array of sums of the elements at each index,
|
||||
including all scalar numbers in `args` in the calculation at each index if `args`
|
||||
contains at least one array.
|
||||
|
||||
*Throws*: `'Array length mismatch'` if `args` contains arrays of different lengths
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
add(1, 2, 3) // returns 6
|
||||
add([10, 20, 30, 40], 10, 20, 30) // returns [70, 80, 90, 100]
|
||||
add([1, 2], 3, [4, 5], 6) // returns [(1 + 3 + 4 + 6), (2 + 3 + 5 + 6)] = [14, 16]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== cbrt( a )
|
||||
|
||||
Calculates the cube root of a number. For arrays, the function will be applied
|
||||
index-wise to each element.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|number \| Array.<number>
|
||||
|a number or an array of numbers
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The cube root of `a`. Returns an array with
|
||||
the cube roots of each element if `a` is an array.
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
cbrt(-27) // returns -3
|
||||
cbrt(94) // returns 4.546835943776344
|
||||
cbrt([27, 64, 125]) // returns [3, 4, 5]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== ceil( a )
|
||||
|
||||
Calculates the ceiling of a number, i.e., rounds a number towards positive infinity.
|
||||
For arrays, the function will be applied index-wise to each element.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|number \| Array.<number>
|
||||
|a number or an array of numbers
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The ceiling of `a`. Returns an array with
|
||||
the ceilings of each element if `a` is an array.
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
ceil(1.2) // returns 2
|
||||
ceil(-1.8) // returns -1
|
||||
ceil([1.1, 2.2, 3.3]) // returns [2, 3, 4]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== clamp( ...a, min, max )
|
||||
|
||||
Restricts value to a given range and returns closed available value. If only `min`
|
||||
is provided, values are restricted to only a lower bound.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|...a
|
||||
|number \| Array.<number>
|
||||
|one or more numbers or arrays of numbers
|
||||
|
||||
|min
|
||||
|number \| Array.<number>
|
||||
|(optional) The minimum value this function will return.
|
||||
|
||||
|max
|
||||
|number \| Array.<number>
|
||||
|(optional) The maximum value this function will return.
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The closest value between `min` (inclusive)
|
||||
and `max` (inclusive). Returns an array with values greater than or equal to `min`
|
||||
and less than or equal to `max` (if provided) at each index.
|
||||
|
||||
*Throws*:
|
||||
|
||||
- `'Array length mismatch'` if a `min` and/or `max` are arrays of different lengths
|
||||
|
||||
- `'Min must be less than max'` if `max` is less than `min`
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
clamp(1, 2, 3) // returns 2
|
||||
clamp([10, 20, 30, 40], 15, 25) // returns [15, 20, 25, 25]
|
||||
clamp(10, [15, 2, 4, 20], 25) // returns [15, 10, 10, 20]
|
||||
clamp(35, 10, [20, 30, 40, 50]) // returns [20, 30, 35, 35]
|
||||
clamp([1, 9], 3, [4, 5]) // returns [clamp([1, 3, 4]), clamp([9, 3, 5])] = [3, 5]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== count( a )
|
||||
|
||||
Returns the length of an array. Alias for size.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|Array.<any>
|
||||
|array of any values
|
||||
|===
|
||||
|
||||
*Returns*: `number`. The length of the array.
|
||||
|
||||
*Throws*: `'Must pass an array'` if `a` is not an array.
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
count([]) // returns 0
|
||||
count([-1, -2, -3, -4]) // returns 4
|
||||
count(100) // returns 1
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== cube( a )
|
||||
|
||||
Calculates the cube of a number. For arrays, the function will be applied
|
||||
index-wise to each element.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|number \| Array.<number>
|
||||
|a number or an array of numbers
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The cube of `a`. Returns an array
|
||||
with the cubes of each element if `a` is an array.
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
cube(-3) // returns -27
|
||||
cube([3, 4, 5]) // returns [27, 64, 125]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== divide( a, b )
|
||||
|
||||
Divides two numbers. If at least one array of numbers is passed into the function,
|
||||
the function will be applied index-wise to each element.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|number \| Array.<number>
|
||||
|dividend, a number or an array of numbers
|
||||
|
||||
|b
|
||||
|number \| Array.<number>
|
||||
|divisor, a number or an array of numbers, b != 0
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. Returns the quotient of `a` and `b`
|
||||
if both are numbers. Returns an array with the quotients applied index-wise to
|
||||
each element if `a` or `b` is an array.
|
||||
|
||||
*Throws*:
|
||||
|
||||
- `'Array length mismatch'` if `a` and `b` are arrays with different lengths
|
||||
|
||||
- `'Cannot divide by 0'` if `b` equals 0 or contains 0
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
divide(6, 3) // returns 2
|
||||
divide([10, 20, 30, 40], 10) // returns [1, 2, 3, 4]
|
||||
divide(10, [1, 2, 5, 10]) // returns [10, 5, 2, 1]
|
||||
divide([14, 42, 65, 108], [2, 7, 5, 12]) // returns [7, 6, 13, 9]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== exp( a )
|
||||
|
||||
Calculates _e^x_ where _e_ is Euler's number. For arrays, the function will be applied
|
||||
index-wise to each element.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|number \| Array.<number>
|
||||
|a number or an array of numbers
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. Returns an array with the values of
|
||||
`e^x` evaluated where `x` is each element of `a` if `a` is an array.
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
exp(2) // returns e^2 = 7.3890560989306495
|
||||
exp([1, 2, 3]) // returns [e^1, e^2, e^3] = [2.718281828459045, 7.3890560989306495, 20.085536923187668]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== first( a )
|
||||
|
||||
Returns the first element of an array. If anything other than an array is passed
|
||||
in, the input is returned.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|Array.<any>
|
||||
|array of any values
|
||||
|===
|
||||
|
||||
*Returns*: `*`. The first element of `a`. Returns `a` if `a` is not an array.
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
first(2) // returns 2
|
||||
first([1, 2, 3]) // returns 1
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== fix( a )
|
||||
|
||||
Calculates the fix of a number, i.e., rounds a number towards 0. For arrays, the
|
||||
function will be applied index-wise to each element.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|number \| Array.<number>
|
||||
|a number or an array of numbers
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The fix of `a`. Returns an array with
|
||||
the fixes for each element if `a` is an array.
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
fix(1.2) // returns 1
|
||||
fix(-1.8) // returns -1
|
||||
fix([1.8, 2.9, -3.7, -4.6]) // returns [1, 2, -3, -4]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== floor( a )
|
||||
|
||||
Calculates the floor of a number, i.e., rounds a number towards negative infinity.
|
||||
For arrays, the function will be applied index-wise to each element.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|number \| Array.<number>
|
||||
|a number or an array of numbers
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The floor of `a`. Returns an array
|
||||
with the floor of each element if `a` is an array.
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
floor(1.8) // returns 1
|
||||
floor(-1.2) // returns -2
|
||||
floor([1.7, 2.8, 3.9]) // returns [1, 2, 3]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== last( a )
|
||||
|
||||
Returns the last element of an array. If anything other than an array is passed
|
||||
in, the input is returned.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|Array.<any>
|
||||
|array of any values
|
||||
|===
|
||||
|
||||
*Returns*: `*`. The last element of `a`. Returns `a` if `a` is not an array.
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
last(2) // returns 2
|
||||
last([1, 2, 3]) // returns 3
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== log( a, b )
|
||||
|
||||
Calculates the logarithm of a number. For arrays, the function will be applied
|
||||
index-wise to each element.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|number \| Array.<number>
|
||||
|a number or an array of numbers, `a` must be greater than 0
|
||||
|
||||
|b
|
||||
|Object
|
||||
|(optional) base for the logarithm. If not provided a value, the default base is e, and the natural log is calculated.
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The logarithm of `a`. Returns an array
|
||||
with the the logarithms of each element if `a` is an array.
|
||||
|
||||
*Throws*:
|
||||
|
||||
- `'Base out of range'` if `b` <= 0
|
||||
|
||||
- `'Must be greater than 0'` if `a` > 0
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
log(1) // returns 0
|
||||
log(64, 8) // returns 2
|
||||
log(42, 5) // returns 2.322344707681546
|
||||
log([2, 4, 8, 16, 32], 2) // returns [1, 2, 3, 4, 5]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== log10( a )
|
||||
|
||||
Calculates the logarithm base 10 of a number. For arrays, the function will be
|
||||
applied index-wise to each element.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|number \| Array.<number>
|
||||
|a number or an array of numbers, `a` must be greater than 0
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The logarithm of `a`. Returns an array
|
||||
with the the logarithms base 10 of each element if `a` is an array.
|
||||
|
||||
*Throws*: `'Must be greater than 0'` if `a` < 0
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
log(10) // returns 1
|
||||
log(100) // returns 2
|
||||
log(80) // returns 1.9030899869919433
|
||||
log([10, 100, 1000, 10000, 100000]) // returns [1, 2, 3, 4, 5]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== max( ...args )
|
||||
|
||||
Finds the maximum value of one of more numbers/arrays of numbers passed into the function.
|
||||
If at least one array of numbers is passed into the function, the function will
|
||||
find the maximum by index.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|...args
|
||||
|number \| Array.<number>
|
||||
|one or more numbers or arrays of numbers
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The maximum value of all numbers if
|
||||
`args` contains only numbers. Returns an array with the the maximum values at each
|
||||
index, including all scalar numbers in `args` in the calculation at each index if
|
||||
`args` contains at least one array.
|
||||
|
||||
*Throws*: `'Array length mismatch'` if `args` contains arrays of different lengths
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
max(1, 2, 3) // returns 3
|
||||
max([10, 20, 30, 40], 15) // returns [15, 20, 30, 40]
|
||||
max([1, 9], 4, [3, 5]) // returns [max([1, 4, 3]), max([9, 4, 5])] = [4, 9]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== mean( ...args )
|
||||
|
||||
Finds the mean value of one of more numbers/arrays of numbers passed into the function.
|
||||
If at least one array of numbers is passed into the function, the function will
|
||||
find the mean by index.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|...args
|
||||
|number \| Array.<number>
|
||||
|one or more numbers or arrays of numbers
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The mean value of all numbers if `args`
|
||||
contains only numbers. Returns an array with the the mean values of each index,
|
||||
including all scalar numbers in `args` in the calculation at each index if `args`
|
||||
contains at least one array.
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
mean(1, 2, 3) // returns 2
|
||||
mean([10, 20, 30, 40], 20) // returns [15, 20, 25, 30]
|
||||
mean([1, 9], 5, [3, 4]) // returns [mean([1, 5, 3]), mean([9, 5, 4])] = [3, 6]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== median( ...args )
|
||||
|
||||
Finds the median value(s) of one of more numbers/arrays of numbers passed into the function.
|
||||
If at least one array of numbers is passed into the function, the function will
|
||||
find the median by index.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|...args
|
||||
|number \| Array.<number>
|
||||
|one or more numbers or arrays of numbers
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The median value of all numbers if `args`
|
||||
contains only numbers. Returns an array with the the median values of each index,
|
||||
including all scalar numbers in `args` in the calculation at each index if `args`
|
||||
contains at least one array.
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
median(1, 1, 2, 3) // returns 1.5
|
||||
median(1, 1, 2, 2, 3) // returns 2
|
||||
median([10, 20, 30, 40], 10, 20, 30) // returns [15, 20, 25, 25]
|
||||
median([1, 9], 2, 4, [3, 5]) // returns [median([1, 2, 4, 3]), median([9, 2, 4, 5])] = [2.5, 4.5]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== min( ...args )
|
||||
|
||||
Finds the minimum value of one of more numbers/arrays of numbers passed into the function.
|
||||
If at least one array of numbers is passed into the function, the function will
|
||||
find the minimum by index.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|...args
|
||||
|number \| Array.<number>
|
||||
|one or more numbers or arrays of numbers
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The minimum value of all numbers if
|
||||
`args` contains only numbers. Returns an array with the the minimum values of each
|
||||
index, including all scalar numbers in `args` in the calculation at each index if `a`
|
||||
is an array.
|
||||
|
||||
*Throws*: `'Array length mismatch'` if `args` contains arrays of different lengths.
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
min(1, 2, 3) // returns 1
|
||||
min([10, 20, 30, 40], 25) // returns [10, 20, 25, 25]
|
||||
min([1, 9], 4, [3, 5]) // returns [min([1, 4, 3]), min([9, 4, 5])] = [1, 4]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== mod( a, b )
|
||||
|
||||
Remainder after dividing two numbers. If at least one array of numbers is passed
|
||||
into the function, the function will be applied index-wise to each element.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|number \| Array.<number>
|
||||
|dividend, a number or an array of numbers
|
||||
|
||||
|b
|
||||
|number \| Array.<number>
|
||||
|divisor, a number or an array of numbers, b != 0
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The remainder of `a` divided by `b` if
|
||||
both are numbers. Returns an array with the the remainders applied index-wise to
|
||||
each element if `a` or `b` is an array.
|
||||
|
||||
*Throws*:
|
||||
|
||||
- `'Array length mismatch'` if `a` and `b` are arrays with different lengths
|
||||
|
||||
- `'Cannot divide by 0'` if `b` equals 0 or contains 0
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
mod(10, 7) // returns 3
|
||||
mod([11, 22, 33, 44], 10) // returns [1, 2, 3, 4]
|
||||
mod(100, [3, 7, 11, 23]) // returns [1, 2, 1, 8]
|
||||
mod([14, 42, 65, 108], [5, 4, 14, 2]) // returns [5, 2, 9, 0]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== mode( ...args )
|
||||
|
||||
Finds the mode value(s) of one of more numbers/arrays of numbers passed into the function.
|
||||
If at least one array of numbers is passed into the function, the function will
|
||||
find the mode by index.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|...args
|
||||
|number \| Array.<number>
|
||||
|one or more numbers or arrays of numbers
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<Array.<number>>`. An array of mode value(s) of all
|
||||
numbers if `args` contains only numbers. Returns an array of arrays with mode value(s)
|
||||
of each index, including all scalar numbers in `args` in the calculation at each index
|
||||
if `args` contains at least one array.
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
mode(1, 1, 2, 3) // returns [1]
|
||||
mode(1, 1, 2, 2, 3) // returns [1,2]
|
||||
mode([10, 20, 30, 40], 10, 20, 30) // returns [[10], [20], [30], [10, 20, 30, 40]]
|
||||
mode([1, 9], 1, 4, [3, 5]) // returns [mode([1, 1, 4, 3]), mode([9, 1, 4, 5])] = [[1], [4, 5, 9]]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== multiply( a, b )
|
||||
|
||||
Multiplies two numbers. If at least one array of numbers is passed into the function,
|
||||
the function will be applied index-wise to each element.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|number \| Array.<number>
|
||||
|a number or an array of numbers
|
||||
|
||||
|b
|
||||
|number \| Array.<number>
|
||||
|a number or an array of numbers
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The product of `a` and `b` if both are
|
||||
numbers. Returns an array with the the products applied index-wise to each element
|
||||
if `a` or `b` is an array.
|
||||
|
||||
*Throws*: `'Array length mismatch'` if `a` and `b` are arrays with different lengths
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
multiply(6, 3) // returns 18
|
||||
multiply([10, 20, 30, 40], 10) // returns [100, 200, 300, 400]
|
||||
multiply(10, [1, 2, 5, 10]) // returns [10, 20, 50, 100]
|
||||
multiply([1, 2, 3, 4], [2, 7, 5, 12]) // returns [2, 14, 15, 48]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== pow( a, b )
|
||||
|
||||
Calculates the cube root of a number. For arrays, the function will be applied
|
||||
index-wise to each element.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|number \| Array.<number>
|
||||
|a number or an array of numbers
|
||||
|
||||
|b
|
||||
|number
|
||||
|the power that `a` is raised to
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. `a` raised to the power of `b`. Returns
|
||||
an array with the each element raised to the power of `b` if `a` is an array.
|
||||
|
||||
*Throws*: `'Missing exponent'` if `b` is not provided
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
pow(2,3) // returns 8
|
||||
pow([1, 2, 3], 4) // returns [1, 16, 81]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== random( a, b )
|
||||
|
||||
Generates a random number within the given range where the lower bound is inclusive
|
||||
and the upper bound is exclusive. If no numbers are passed in, it will return a
|
||||
number between 0 and 1. If only one number is passed in, it will return a number
|
||||
between 0 and the number passed in.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|number
|
||||
|(optional) must be greater than 0 if `b` is not provided
|
||||
|
||||
|b
|
||||
|number
|
||||
|(optional) must be greater than `a`
|
||||
|===
|
||||
|
||||
*Returns*: `number`. A random number between 0 and 1 if no numbers are passed in.
|
||||
Returns a random number between 0 and `a` if only one number is passed in. Returns
|
||||
a random number between `a` and `b` if two numbers are passed in.
|
||||
|
||||
*Throws*: `'Min must be greater than max'` if `a` < 0 when only `a` is passed in
|
||||
or if `a` > `b` when both `a` and `b` are passed in
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
random() // returns a random number between 0 (inclusive) and 1 (exclusive)
|
||||
random(10) // returns a random number between 0 (inclusive) and 10 (exclusive)
|
||||
random(-10,10) // returns a random number between -10 (inclusive) and 10 (exclusive)
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== range( ...args )
|
||||
|
||||
Finds the range of one of more numbers/arrays of numbers passed into the function. If at
|
||||
least one array of numbers is passed into the function, the function will find
|
||||
the range by index.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|...args
|
||||
|number \| Array.<number>
|
||||
|one or more numbers or arrays of numbers
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The range value of all numbers if `args`
|
||||
contains only numbers. Returns an array with the range values at each index,
|
||||
including all scalar numbers in `args` in the calculation at each index if `args`
|
||||
contains at least one array.
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
range(1, 2, 3) // returns 2
|
||||
range([10, 20, 30, 40], 15) // returns [5, 5, 15, 25]
|
||||
range([1, 9], 4, [3, 5]) // returns [range([1, 4, 3]), range([9, 4, 5])] = [3, 5]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== range( ...args )
|
||||
|
||||
Finds the range of one of more numbers/arrays of numbers into the function. If at
|
||||
least one array of numbers is passed into the function, the function will find
|
||||
the range by index.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|...args
|
||||
|number \| Array.<number>
|
||||
|one or more numbers or arrays of numbers
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The range value of all numbers if `args`
|
||||
contains only numbers. Returns an array with the the range values at each index,
|
||||
including all scalar numbers in `args` in the calculation at each index if `args`
|
||||
contains at least one array.
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
range(1, 2, 3) // returns 2
|
||||
range([10, 20, 30, 40], 15) // returns [5, 5, 15, 25]
|
||||
range([1, 9], 4, [3, 5]) // returns [range([1, 4, 3]), range([9, 4, 5])] = [3, 5]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== round( a, b )
|
||||
|
||||
Rounds a number towards the nearest integer by default, or decimal place (if passed in as `b`).
|
||||
For arrays, the function will be applied index-wise to each element.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|number \| Array.<number>
|
||||
|a number or an array of numbers
|
||||
|
||||
|b
|
||||
|number
|
||||
|(optional) number of decimal places, default value: 0
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The rounded value of `a`. Returns an
|
||||
array with the the rounded values of each element if `a` is an array.
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
round(1.2) // returns 2
|
||||
round(-10.51) // returns -11
|
||||
round(-10.1, 2) // returns -10.1
|
||||
round(10.93745987, 4) // returns 10.9375
|
||||
round([2.9234, 5.1234, 3.5234, 4.49234324], 2) // returns [2.92, 5.12, 3.52, 4.49]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== size( a )
|
||||
|
||||
Returns the length of an array. Alias for count.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|Array.<any>
|
||||
|array of any values
|
||||
|===
|
||||
|
||||
*Returns*: `number`. The length of the array.
|
||||
|
||||
*Throws*: `'Must pass an array'` if `a` is not an array
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
size([]) // returns 0
|
||||
size([-1, -2, -3, -4]) // returns 4
|
||||
size(100) // returns 1
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== sqrt( a )
|
||||
|
||||
Calculates the square root of a number. For arrays, the function will be applied
|
||||
index-wise to each element.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|number \| Array.<number>
|
||||
|a number or an array of numbers
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The square root of `a`. Returns an array
|
||||
with the the square roots of each element if `a` is an array.
|
||||
|
||||
*Throws*: `'Unable find the square root of a negative number'` if `a` < 0
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
sqrt(9) // returns 3
|
||||
sqrt(30) //5.477225575051661
|
||||
sqrt([9, 16, 25]) // returns [3, 4, 5]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== square( a )
|
||||
|
||||
Calculates the square of a number. For arrays, the function will be applied
|
||||
index-wise to each element.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|number \| Array.<number>
|
||||
|a number or an array of numbers
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The square of `a`. Returns an array
|
||||
with the the squares of each element if `a` is an array.
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
square(-3) // returns 9
|
||||
square([3, 4, 5]) // returns [9, 16, 25]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== subtract( a, b )
|
||||
|
||||
Subtracts two numbers. If at least one array of numbers is passed into the function,
|
||||
the function will be applied index-wise to each element.
|
||||
|
||||
[cols="3*^<"]
|
||||
|===
|
||||
|Param |Type |Description
|
||||
|
||||
|a
|
||||
|number \| Array.<number>
|
||||
|a number or an array of numbers
|
||||
|
||||
|b
|
||||
|number \| Array.<number>
|
||||
|a number or an array of numbers
|
||||
|===
|
||||
|
||||
*Returns*: `number` | `Array.<number>`. The difference of `a` and `b` if both are
|
||||
numbers, or an array of differences applied index-wise to each element.
|
||||
|
||||
*Throws*: `'Array length mismatch'` if `a` and `b` are arrays with different lengths
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
subtract(6, 3) // returns 3
|
||||
subtract([10, 20, 30, 40], 10) // returns [0, 10, 20, 30]
|
||||
subtract(10, [1, 2, 5, 10]) // returns [9, 8, 5, 0]
|
||||
subtract([14, 42, 65, 108], [2, 7, 5, 12]) // returns [12, 35, 52, 96]
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== sum( ...args )
|
||||
|
||||
Calculates the sum of one or more numbers/arrays passed into the function. If at
|
||||
least one array is passed, the function will sum up one or more numbers/arrays of
|
||||
numbers and distinct values of an array. Sum accepts arrays of different lengths.
|
||||
|
||||
*Returns*: `number`. The sum of one or more numbers/arrays of numbers including
|
||||
distinct values in arrays
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
sum(1, 2, 3) // returns 6
|
||||
sum([10, 20, 30, 40], 10, 20, 30) // returns 160
|
||||
sum([1, 2], 3, [4, 5], 6) // returns sum(1, 2, 3, 4, 5, 6) = 21
|
||||
sum([10, 20, 30, 40], 10, [1, 2, 3], 22) // returns sum(10, 20, 30, 40, 10, 1, 2, 3, 22) = 138
|
||||
------------
|
||||
|
||||
[float]
|
||||
=== unique( a )
|
||||
|
||||
Counts the number of unique values in an array.
|
||||
|
||||
*Returns*: `number`. The number of unique values in the array. Returns 1 if `a`
|
||||
is not an array.
|
||||
|
||||
*Example*
|
||||
[source, js]
|
||||
------------
|
||||
unique(100) // returns 1
|
||||
unique([]) // returns 0
|
||||
unique([1, 2, 3, 4]) // returns 4
|
||||
unique([1, 2, 3, 4, 2, 2, 2, 3, 4, 2, 4, 5, 2, 1, 4, 2]) // returns 5
|
||||
------------
|
||||
|
|
@ -1,136 +0,0 @@
|
|||
[role="xpack"]
|
||||
[[canvas-tutorial]]
|
||||
== Tutorial: Create a workpad for monitoring sales
|
||||
|
||||
To familiarize yourself with *Canvas*, add the Sample eCommerce orders data, then use the data to create a workpad for monitoring sales at an eCommerce store.
|
||||
|
||||
[float]
|
||||
=== Open and set up Canvas
|
||||
|
||||
To create a workpad of the eCommerce store data, add the data set, then create the workpad.
|
||||
|
||||
. <<gs-get-data-into-kibana,Install the eCommerce sample data>>.
|
||||
|
||||
. Go to **Canvas** using the navigation menu or the <<kibana-navigation-search,global search field>>.
|
||||
|
||||
. Select *Create workpad*.
|
||||
|
||||
[float]
|
||||
=== Customize your workpad with images
|
||||
|
||||
To customize your workpad to look the way you want, add your own images.
|
||||
|
||||
. Click *Add element > Image > Image*.
|
||||
+
|
||||
The default Elastic logo image appears on the page.
|
||||
|
||||
. Add your own image.
|
||||
|
||||
.. Click the Elastic logo.
|
||||
|
||||
.. Drag the image file to the *Select or drag and drop an image* field.
|
||||
+
|
||||
[role="screenshot"]
|
||||
image::images/canvas_tutorialCustomImage_7.17.0.png[The Analytics logo added to the workpad]
|
||||
|
||||
[float]
|
||||
=== Customize your data with metrics
|
||||
|
||||
Customize your data by connecting it to the Sample eCommerce orders data.
|
||||
|
||||
. Click *Add element > Chart > Metric*.
|
||||
+
|
||||
By default, the element is connected to the demo data, which enables you to experiment with the element before you connect it to your own.
|
||||
|
||||
. To connect the element to your own data, make sure the element is selected, then click *Data > Demo data > Elasticsearch SQL*.
|
||||
|
||||
.. To select the total price field and set it to the sum_total_price field, enter the following in the *Query* field:
|
||||
+
|
||||
[source,text]
|
||||
--
|
||||
SELECT sum(taxless_total_price) AS sum_total_price FROM "kibana_sample_data_ecommerce"
|
||||
--
|
||||
|
||||
.. Click *Save*.
|
||||
+
|
||||
All fields are pulled from the sample eCommerce orders {data-source}.
|
||||
|
||||
. At this point, the element appears as an error, so you need to change the element display options.
|
||||
|
||||
.. Click *Display*
|
||||
|
||||
.. From the *Value* dropdowns, make sure *Unique* and *sum_total_price* are selected.
|
||||
|
||||
.. Change the *Label* to `Total sales`.
|
||||
|
||||
. The error is gone, but the element could use some formatting. To format the number, use the *Canvas* expression language.
|
||||
|
||||
.. Click *Expression editor*.
|
||||
+
|
||||
You're now looking at the raw data syntax that Canvas uses to display the element.
|
||||
|
||||
.. Change `metricFormat="0,0.[000]"` to `metricFormat="$0a"`.
|
||||
|
||||
.. Click *Run*.
|
||||
|
||||
[role="screenshot"]
|
||||
image::images/canvas_tutorialCustomMetric_7.17.0.png[The total sales metric added to the workpad using Elasticsearch SQL]
|
||||
|
||||
[float]
|
||||
=== Show off your data with charts
|
||||
|
||||
To show what your data can do, add charts, graphs, progress monitors, and more to your workpad.
|
||||
|
||||
. Click *Add element > Chart > Area*.
|
||||
|
||||
. Make sure that the element is selected, then click *Data > Demo data > Elasticsearch SQL*.
|
||||
|
||||
.. To obtain the taxless total price by date, enter the following in the *Query* field:
|
||||
+
|
||||
[source,text]
|
||||
--
|
||||
SELECT order_date, taxless_total_price FROM "kibana_sample_data_ecommerce" ORDER BY order_date
|
||||
--
|
||||
|
||||
.. Click *Save*.
|
||||
|
||||
. Change the display options.
|
||||
|
||||
.. Click *Display*
|
||||
|
||||
.. From the *X-axis* dropdown, make sure *Value* and *order_date* are selected.
|
||||
|
||||
.. From the *Y-axis* dropdown, select *Value*, then select *taxless_total_price*.
|
||||
|
||||
[role="screenshot"]
|
||||
image::images/canvas_tutorialCustomChart_7.17.0.png[Custom line chart added to the workpad using Elasticsearch SQL]
|
||||
|
||||
[float]
|
||||
=== Show how your data changes over time
|
||||
|
||||
To focus your data on a specific time range, add the time filter.
|
||||
|
||||
. Click *Add element > Filter > Time filter*.
|
||||
|
||||
. Click *Display*
|
||||
|
||||
. To use the date time field from the sample data, enter `order_date` in the *Column* field, then click *Set*.
|
||||
|
||||
[role="screenshot"]
|
||||
image::../setup/images/canvas_tutorialCustomTimeFilter_7.17.0.png[Custom time filter added to the workpad]
|
||||
|
||||
To see how the data changes, set the time filter to *Last 7 days*. As you change the time filter options, the elements automatically update.
|
||||
|
||||
Your workpad is complete!
|
||||
|
||||
[float]
|
||||
=== What's next?
|
||||
Now that you know the basics, you're ready to explore on your own.
|
||||
|
||||
Here are some things to try:
|
||||
|
||||
* Play with the {kibana-ref}/add-sample-data.html[sample Canvas workpads].
|
||||
|
||||
* Build presentations of your own data with <<create-workpads,workpads>>.
|
||||
|
||||
* Deep dive into the {kibana-ref}/canvas-function-reference.html[expression language and functions] that drive *Canvas*.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 1.3 MiB |
Binary file not shown.
|
Before Width: | Height: | Size: 615 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 1.1 MiB |
Binary file not shown.
|
Before Width: | Height: | Size: 872 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 43 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 36 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 4 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 365 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 161 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 115 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 234 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 27 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 18 KiB |
|
|
@ -1,185 +0,0 @@
|
|||
[[data-views]]
|
||||
=== Create a {data-source}
|
||||
|
||||
{kib} requires a {data-source} to access the {es} data that you want to explore.
|
||||
A {data-source} can point to one or more indices, {ref}/data-streams.html[data streams], or {ref}/alias.html[index aliases].
|
||||
For example, a {data-source} can point to your log data from yesterday,
|
||||
or all indices that contain your data.
|
||||
|
||||
[float]
|
||||
[[data-views-read-only-access]]
|
||||
=== Required permissions
|
||||
|
||||
* Access to *Data Views* requires the <<kibana-role-management, {kib} privilege>>
|
||||
`Data View Management`.
|
||||
|
||||
* To create a {data-source}, you must have the <<kibana-role-management,{es} privilege>>
|
||||
`view_index_metadata`.
|
||||
|
||||
* If a read-only indicator appears in {kib}, you have insufficient privileges
|
||||
to create or save {data-sources}. In addition, the buttons to create {data-sources} or
|
||||
save existing {data-sources} are not visible. For more information,
|
||||
refer to <<xpack-security-authorization,Granting access to {kib}>>.
|
||||
|
||||
[float]
|
||||
[[settings-create-pattern]]
|
||||
=== Create a data view
|
||||
|
||||
If you collected data using one of the {kib} <<connect-to-elasticsearch,ingest options>>,
|
||||
uploaded a file, or added sample data,
|
||||
you get a {data-source} for free, and can start exploring your data.
|
||||
If you loaded your own data, follow these steps to create a {data-source}.
|
||||
|
||||
. Open *Lens* or *Discover*, and then open the data view menu.
|
||||
+
|
||||
[role="screenshot"]
|
||||
image::images/discover-data-view.png[How to set the {data-source} in Discover, width="40%"]
|
||||
|
||||
. Click *Create a {data-source}*.
|
||||
|
||||
. Give your {data-source} a name.
|
||||
|
||||
. Start typing in the *Index pattern* field, and {kib} looks for the names of
|
||||
indices, data streams, and aliases that match your input. You can
|
||||
view all available sources or only the sources that the data view targets.
|
||||
+
|
||||
[role="screenshot"]
|
||||
image:management/index-patterns/images/create-data-view.png["Create data view"]
|
||||
+
|
||||
** To match multiple sources, use a wildcard (*). `filebeat-*` matches
|
||||
`filebeat-apache-a`, `filebeat-apache-b`, and so on.
|
||||
+
|
||||
** To match multiple single sources, enter their names,
|
||||
separated by a comma. Do not include a space after the comma.
|
||||
`filebeat-a,filebeat-b` matches two indices.
|
||||
+
|
||||
** To exclude a source, use a minus sign (-), for example, `-test3`.
|
||||
|
||||
. Open the *Timestamp field* dropdown,
|
||||
and then select the default field for filtering your data by time.
|
||||
+
|
||||
** If you don’t set a default time field, you can't use
|
||||
global time filters on your dashboards. This is useful if
|
||||
you have multiple time fields and want to create dashboards that combine visualizations
|
||||
based on different timestamps.
|
||||
+
|
||||
** If your index doesn’t have time-based data, choose *I don’t want to use the time filter*.
|
||||
|
||||
. Click *Show advanced settings* to:
|
||||
** Display hidden and system indices.
|
||||
** Specify your own {data-source} name. For example, enter your {es} index alias name.
|
||||
|
||||
. [[reload-fields]] Click *Save {data-source} to {kib}*.
|
||||
+
|
||||
You can manage your data view from *Stack Management*.
|
||||
|
||||
[float]
|
||||
==== Create a temporary {data-source}
|
||||
|
||||
Want to explore your data or create a visualization without saving it as a data view?
|
||||
Select *Use without saving* in the *Create {data-source}* form in *Discover*
|
||||
or *Lens*. With a temporary {data-source}, you can add fields and create an {es}
|
||||
query alert, just like you would a regular {data-source}. Your work won't be visible to others in your space.
|
||||
|
||||
A temporary {data-source} remains in your space until you change apps, or until you save it.
|
||||
|
||||
|
||||
[role="screenshot"]
|
||||
image::https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/blte3a4f3994c44c0cc/637eb0c95834861044c21a25/ad-hoc-data-view.gif[how to create an ad-hoc data view]
|
||||
|
||||
NOTE: Temporary {data-sources} are not available in *Stack Management.*
|
||||
|
||||
[float]
|
||||
[[rollup-data-view]]
|
||||
==== Use {data-sources} with rolled up data
|
||||
|
||||
deprecated::[8.11.0,'Rollups are deprecated and will be removed in a future version. Use {ref}/downsampling.html[downsampling] instead.']
|
||||
|
||||
A {data-source} can match one rollup index. For a combination rollup
|
||||
{data-source} with both raw and rolled up data, use the standard notation:
|
||||
|
||||
```ts
|
||||
rollup_logstash,kibana_sample_data_logs
|
||||
```
|
||||
For an example, refer to <<rollup-data-tutorial,Create and visualize rolled up data>>.
|
||||
|
||||
[float]
|
||||
[[management-cross-cluster-search]]
|
||||
==== Use {data-sources} with {ccs}
|
||||
|
||||
If your {es} clusters are configured for {ref}/modules-cross-cluster-search.html[{ccs}],
|
||||
you can create a {data-source} to search across the clusters of your choosing.
|
||||
Specify data streams, indices, and aliases in a remote cluster using the
|
||||
following syntax:
|
||||
|
||||
```ts
|
||||
<remote_cluster_name>:<target>
|
||||
```
|
||||
|
||||
To query {ls} indices across two {es} clusters
|
||||
that you set up for {ccs}, named `cluster_one` and `cluster_two`:
|
||||
|
||||
```ts
|
||||
cluster_one:logstash-*,cluster_two:logstash-*
|
||||
```
|
||||
|
||||
Use wildcards in your cluster names
|
||||
to match any number of clusters. To search {ls} indices across
|
||||
clusters named `cluster_foo`, `cluster_bar`, and so on:
|
||||
|
||||
```ts
|
||||
cluster_*:logstash-*
|
||||
```
|
||||
|
||||
To query across all {es} clusters that have been configured for {ccs},
|
||||
use a standalone wildcard for your cluster name:
|
||||
|
||||
```ts
|
||||
*:logstash-*
|
||||
```
|
||||
|
||||
To match indices starting with `logstash-`, but exclude those starting with `logstash-old`, from
|
||||
all clusters having a name starting with `cluster_`:
|
||||
|
||||
```ts
|
||||
cluster_*:logstash-*,cluster_*:-logstash-old*
|
||||
```
|
||||
|
||||
Excluding a cluster avoids sending any network calls to that cluster.
|
||||
To exclude a cluster with the name `cluster_one`:
|
||||
|
||||
```ts
|
||||
cluster_*:logstash-*,-cluster_one:*
|
||||
```
|
||||
|
||||
Once you configure a {data-source} to use the {ccs} syntax, all searches and
|
||||
aggregations using that {data-source} in {kib} take advantage of {ccs}.
|
||||
|
||||
For more information, refer to
|
||||
{ref}/modules-cross-cluster-search.html#exclude-problematic-clusters[Excluding
|
||||
clusters or indicies from cross-cluster search].
|
||||
|
||||
[float]
|
||||
[[delete-data-view]]
|
||||
=== Delete a {data-source}
|
||||
|
||||
When you delete a {data-source}, you cannot recover the associated field formatters, runtime fields, source filters,
|
||||
and field popularity data. Deleting a {data-source} does not remove any indices or data documents from {es}.
|
||||
|
||||
WARNING: Deleting a {data-source} breaks all visualizations, saved Discover sessions, and other saved objects that reference the data view.
|
||||
|
||||
. Go to the **Data Views** management page using the navigation menu or the <<kibana-navigation-search,global search field>>.
|
||||
|
||||
. Find the {data-source} that you want to delete, and then
|
||||
click image:management/index-patterns/images/delete.png[Delete icon] in the *Actions* column.
|
||||
|
||||
[float]
|
||||
[[data-view-field-cache]]
|
||||
=== {data-source} field cache
|
||||
|
||||
The browser caches {data-source} field lists for increased performance. This is particularly impactful
|
||||
for {data-sources} with a high field count that span a large number of indices and clusters. The field
|
||||
list is updated every couple of minutes in typical {kib} usage. Alternatively, use the refresh button on the {data-source}
|
||||
management detail page to get an updated field list. A force reload of {kib} has the same effect.
|
||||
|
||||
The field list may be impacted by changes in indices and user permissions.
|
||||
|
|
@ -1,50 +0,0 @@
|
|||
[[esql]]
|
||||
=== {esql}
|
||||
|
||||
The Elasticsearch Query Language, {esql}, makes it faster and easier to explore your data.
|
||||
|
||||
{esql} is a piped language which allows you to chain together multiple commands to query your data.
|
||||
Based on the query, Lens suggestions in Discover create a visualization of the query results.
|
||||
|
||||
{esql} comes with its own dedicated {esql} Compute Engine for greater efficiency. With one query you can search, aggregate, calculate and perform data transformations without leaving **Discover**. Write your query directly in **Discover** or use the **Dev Tools** with the {ref}/esql-rest.html[{esql} API].
|
||||
|
||||
You can switch to the ES|QL mode of Discover from the application menu bar.
|
||||
|
||||
{esql} also features in-app help and suggestions, so you can get started faster and don't have to leave the application to check syntax.
|
||||
|
||||
[role="screenshot"]
|
||||
image:images/esql-in-app-help.png[The ES|QL syntax reference and the autocomplete menu]
|
||||
|
||||
You can also use ES|QL queries to create panels on your dashboards, create enrich policies, and create alerting rules.
|
||||
|
||||
For more detailed information about {esql} in Kibana, refer to {ref}/esql-kibana.html[Using {esql} in {kib}].
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
{esql} is enabled by default in {kib}. It can be
|
||||
disabled using the `enableESQL` setting from the
|
||||
{kibana-ref}/advanced-options.html[Advanced Settings].
|
||||
|
||||
This will hide the {esql} user interface from various applications.
|
||||
However, users will be able to access existing {esql} artifacts like saved Discover sessions and visualizations.
|
||||
====
|
||||
|
||||
[float]
|
||||
[[esql-observability]]
|
||||
==== {observability}
|
||||
|
||||
{esql} makes it much easier to analyze metrics, logs and traces from a single query. Find performance issues fast by defining fields on the fly, enriching data with lookups, and using simultaneous query processing. Combining {esql} with {ml} and AiOps can improve detection accuracy and use aggregated value thresholds.
|
||||
|
||||
[float]
|
||||
[[esql-security]]
|
||||
==== Security
|
||||
|
||||
Use {esql} to retrieve important information for investigation by using lookups. Enrich data and create new fields on the go to gain valuable insight for faster decision-making and actions. For example, perform a lookup on an IP address to identify its geographical location, its association with known malicious entities, or whether it belongs to a known cloud service provider all from one search bar. {esql} ensures more accurate alerts by incorporating aggregated values in detection rules.
|
||||
|
||||
[float]
|
||||
[[esql-whats-next]]
|
||||
==== What's next?
|
||||
|
||||
The main documentation for {esql} lives in the {ref}/esql.html[{es} docs].
|
||||
|
||||
We also have a short tutorial in the **Discover** docs: <<try-esql,Using {esql}>>.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 128 KiB |
Some files were not shown because too many files have changed in this diff Show more
Loading…
Add table
Add a link
Reference in a new issue