diff --git a/.buildkite/pipelines/pull_request/osquery_cypress.yml b/.buildkite/pipelines/pull_request/osquery_cypress.yml new file mode 100644 index 000000000000..766d28e0877c --- /dev/null +++ b/.buildkite/pipelines/pull_request/osquery_cypress.yml @@ -0,0 +1,11 @@ +steps: + - command: .buildkite/scripts/steps/functional/osquery_cypress.sh + label: 'Osquery Cypress Tests' + agents: + queue: ci-group-6 + depends_on: build + timeout_in_minutes: 120 + retry: + automatic: + - exit_status: '*' + limit: 1 diff --git a/.buildkite/scripts/build_kibana.sh b/.buildkite/scripts/build_kibana.sh index e811af224e9a..61a1ba4ee1ce 100755 --- a/.buildkite/scripts/build_kibana.sh +++ b/.buildkite/scripts/build_kibana.sh @@ -28,6 +28,11 @@ if [[ "${GITHUB_PR_LABELS:-}" == *"ci:deploy-cloud"* ]]; then --skip-docker-ubi \ --skip-docker-centos \ --skip-docker-contexts + + CLOUD_IMAGE=$(docker images --format "{{.Repository}}:{{.Tag}}" docker.elastic.co/kibana-ci/kibana-cloud) + cat << EOF | buildkite-agent annotate --style "info" --context cloud-image + Cloud image: $CLOUD_IMAGE +EOF fi echo "--- Archive Kibana Distribution" diff --git a/.buildkite/scripts/pipelines/pull_request/pipeline.js b/.buildkite/scripts/pipelines/pull_request/pipeline.js index d0f38dc77335..ab125d4f7337 100644 --- a/.buildkite/scripts/pipelines/pull_request/pipeline.js +++ b/.buildkite/scripts/pipelines/pull_request/pipeline.js @@ -86,6 +86,16 @@ const uploadPipeline = (pipelineContent) => { pipeline.push(getPipeline('.buildkite/pipelines/pull_request/fleet_cypress.yml')); } + if ( + (await doAnyChangesMatch([ + /^x-pack\/plugins\/osquery/, + /^x-pack\/test\/osquery_cypress/, + ])) || + process.env.GITHUB_PR_LABELS.includes('ci:all-cypress-suites') + ) { + pipeline.push(getPipeline('.buildkite/pipelines/pull_request/osquery_cypress.yml')); + } + if (await doAnyChangesMatch([/^x-pack\/plugins\/uptime/])) { pipeline.push(getPipeline('.buildkite/pipelines/pull_request/uptime.yml')); } diff --git a/.buildkite/scripts/steps/functional/osquery_cypress.sh b/.buildkite/scripts/steps/functional/osquery_cypress.sh new file mode 100755 index 000000000000..a23d41c4f8d4 --- /dev/null +++ b/.buildkite/scripts/steps/functional/osquery_cypress.sh @@ -0,0 +1,20 @@ +#!/usr/bin/env bash + +set -euo pipefail + +source .buildkite/scripts/common/util.sh + +.buildkite/scripts/bootstrap.sh +.buildkite/scripts/download_build_artifacts.sh + +export JOB=kibana-osquery-cypress + +echo "--- Osquery Cypress tests" + +cd "$XPACK_DIR" + +checks-reporter-with-killswitch "Osquery Cypress Tests" \ + node scripts/functional_tests \ + --debug --bail \ + --kibana-install-dir "$KIBANA_BUILD_LOCATION" \ + --config test/osquery_cypress/cli_config.ts diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 9b8fee1bd561..a64ab63494b3 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -22,7 +22,6 @@ # Vis Editors /x-pack/plugins/lens/ @elastic/kibana-vis-editors -/src/plugins/advanced_settings/ @elastic/kibana-vis-editors /src/plugins/charts/ @elastic/kibana-vis-editors /src/plugins/vis_default_editor/ @elastic/kibana-vis-editors /src/plugins/vis_types/metric/ @elastic/kibana-vis-editors @@ -34,10 +33,12 @@ /src/plugins/vis_types/vislib/ @elastic/kibana-vis-editors /src/plugins/vis_types/xy/ @elastic/kibana-vis-editors /src/plugins/vis_types/pie/ @elastic/kibana-vis-editors +/src/plugins/vis_types/heatmap/ @elastic/kibana-vis-editors /src/plugins/visualize/ @elastic/kibana-vis-editors /src/plugins/visualizations/ @elastic/kibana-vis-editors /src/plugins/chart_expressions/expression_tagcloud/ @elastic/kibana-vis-editors /src/plugins/chart_expressions/expression_metric/ @elastic/kibana-vis-editors +/src/plugins/chart_expressions/expression_heatmap/ @elastic/kibana-vis-editors /src/plugins/url_forwarding/ @elastic/kibana-vis-editors /packages/kbn-tinymath/ @elastic/kibana-vis-editors /x-pack/test/functional/apps/lens @elastic/kibana-vis-editors @@ -261,6 +262,7 @@ /src/plugins/home/server/*.ts @elastic/kibana-core /src/plugins/home/server/services/ @elastic/kibana-core /src/plugins/kibana_overview/ @elastic/kibana-core +/src/plugins/advanced_settings/ @elastic/kibana-core /x-pack/plugins/global_search_bar/ @elastic/kibana-core #CC# /src/core/server/csp/ @elastic/kibana-core #CC# /src/plugins/saved_objects/ @elastic/kibana-core diff --git a/.i18nrc.json b/.i18nrc.json index 80dbfee949a6..9485f5b9b84e 100644 --- a/.i18nrc.json +++ b/.i18nrc.json @@ -28,6 +28,7 @@ "expressionRepeatImage": "src/plugins/expression_repeat_image", "expressionRevealImage": "src/plugins/expression_reveal_image", "expressionShape": "src/plugins/expression_shape", + "expressionHeatmap": "src/plugins/chart_expressions/expression_heatmap", "expressionTagcloud": "src/plugins/chart_expressions/expression_tagcloud", "expressionMetricVis": "src/plugins/chart_expressions/expression_metric", "inputControl": "src/plugins/input_control_vis", @@ -69,6 +70,7 @@ "visTypeVislib": "src/plugins/vis_types/vislib", "visTypeXy": "src/plugins/vis_types/xy", "visTypePie": "src/plugins/vis_types/pie", + "visTypeHeatmap": "src/plugins/vis_types/heatmap", "visualizations": "src/plugins/visualizations", "visualize": "src/plugins/visualize", "apmOss": "src/plugins/apm_oss", diff --git a/config/kibana.yml b/config/kibana.yml index f6f85f057172..aedea8ce83bf 100644 --- a/config/kibana.yml +++ b/config/kibana.yml @@ -99,7 +99,7 @@ # Logs queries sent to Elasticsearch. #logging.loggers: -# - name: elasticsearch.queries +# - name: elasticsearch.query # level: debug # Logs http responses. diff --git a/dev_docs/contributing/standards.mdx b/dev_docs/contributing/standards.mdx index 172a83935b96..d2f31f3a4faa 100644 --- a/dev_docs/contributing/standards.mdx +++ b/dev_docs/contributing/standards.mdx @@ -67,6 +67,14 @@ Every public API should have a release tag specified at the top of it’s docume Every team should be collecting telemetry metrics on it’s public API usage. This will be important for knowing when it’s safe to make breaking changes. The Core team will be looking into ways to make this easier and an automatic part of registration (see [#112291](https://github.com/elastic/kibana/issues/112291)). +### APM + +Kibana server and client are instrumented with APM node and APM RUM clients respectively, tracking serveral types of transactions by default, such as `page-load`, `request`, etc. +You may introduce custom transactions. Please refer to the [APM documentation](https://www.elastic.co/guide/en/apm/get-started/current/index.html) and follow these guidelines when doing so: + +- Use dashed syntax for transaction types and names: `my-transaction-type` and `my-transaction-name` +- [Refrain from adding too many custom labels](https://www.elastic.co/guide/en/apm/get-started/current/metadata.html) + ### Documentation Every public API should be documented inside the [docs/api](https://github.com/elastic/kibana/tree/main/docs/api) folder in asciidoc (this content will eventually be migrated to mdx to support the new docs system). If a public REST API is undocumented, you should either document it, or make it internal. diff --git a/dev_docs/key_concepts/building_blocks.mdx b/dev_docs/key_concepts/building_blocks.mdx index da3d0f32780b..6536019f668c 100644 --- a/dev_docs/key_concepts/building_blocks.mdx +++ b/dev_docs/key_concepts/building_blocks.mdx @@ -72,7 +72,7 @@ Check out are a high-level, space-aware + are a high-level, space-aware abstraction layer that sits above Data Streams and Elasticsearch indices. Index Patterns provide users the ability to define and customize the data they wish to search and filter on, on a per-space basis. For example, users can specify a set of indices, and they can customize the field list with runtime fields, diff --git a/dev_docs/key_concepts/performance.mdx b/dev_docs/key_concepts/performance.mdx index 0201c7774f85..5d955c789dde 100644 --- a/dev_docs/key_concepts/performance.mdx +++ b/dev_docs/key_concepts/performance.mdx @@ -3,11 +3,13 @@ id: kibDevPerformance slug: /kibana-dev-docs/key-concepts/performance title: Performance summary: Performance tips for Kibana development. -date: 2021-09-02 +date: 2021-12-03 tags: ['kibana', 'onboarding', 'dev', 'performance'] --- -## Keep Kibana fast +## Client-side considerations + +### Lazy load code _tl;dr_: Load as much code lazily as possible. Everyone loves snappy applications with a responsive UI and hates spinners. Users deserve the @@ -105,3 +107,15 @@ Many OSS tools allow you to analyze the generated stats file: Webpack authors - [webpack-visualizer](https://chrisbateman.github.io/webpack-visualizer/) - [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) + +## Server-side considerations + +### Don't block the event loop + +[Node.js is single threaded](https://nodejs.dev/learn/introduction-to-nodejs) which means a single CPU-intensive server-side, synchronous operation will block any other functionality waiting to execute on the Kibana server. The affects background tasks, like alerts, and search sessions, as well as search requests and page loads. + +**When writing code that will run on the server, [don't block the event loop](https://nodejs.org/en/docs/guides/dont-block-the-event-loop/)**. Instead consider: + +- Writing async code. For example, leverage [setImmediate](https://nodejs.dev/learn/understanding-setimmediate) inside for loops. +- Executing logic on the client instead. This may not be a good option if you require a lot of data going back and forth between the server and the client, as that can also slow down the user's experience, especially over slower bandwidth internet connections. +- Worker threads are also an option if the code doesn't rely on stateful Kibana services. If you are interested in using worker threads, please reach out to a tech-lead before doing so. We will likely want to implement a worker threads pool to ensure worker threads cooperate appropriately. \ No newline at end of file diff --git a/dev_docs/tutorials/data/search.mdx b/dev_docs/tutorials/data/search.mdx index 425736ddb03b..0787c44b632e 100644 --- a/dev_docs/tutorials/data/search.mdx +++ b/dev_docs/tutorials/data/search.mdx @@ -129,6 +129,12 @@ setTimeout(() => { }, 1000); ``` + + Users might no longer be interested in search results. For example, they might start a new search + or leave your app without waiting for the results. You should handle such cases by using + `AbortController` with search API. + + #### Search strategies By default, the search service uses the DSL query and aggregation syntax and returns the response from Elasticsearch as is. It also provides several additional basic strategies, such as Async DSL (`x-pack` default) and EQL. diff --git a/dev_docs/tutorials/data_views.mdx b/dev_docs/tutorials/data_views.mdx index 453146d81c4d..76c4bff8e51e 100644 --- a/dev_docs/tutorials/data_views.mdx +++ b/dev_docs/tutorials/data_views.mdx @@ -83,4 +83,4 @@ await data.indexPatterns.delete(dataViewId); ### Data view HTTP API -Rest-like HTTP CRUD+ API - [docs](https://www.elastic.co/guide/en/kibana/master/index-patterns-api.html) +Rest-like HTTP CRUD+ API - [docs](https://www.elastic.co/guide/en/kibana/master/data-views-api.html) diff --git a/dev_docs/tutorials/endpoints.mdx b/dev_docs/tutorials/endpoints.mdx index 1d6fc0edf1e6..5f2fc7da010c 100644 --- a/dev_docs/tutorials/endpoints.mdx +++ b/dev_docs/tutorials/endpoints.mdx @@ -3,24 +3,105 @@ id: kibDevTutorialServerEndpoint slug: /kibana-dev-docs/tutorials/registering-endpoints title: Registering and accessing an endpoint summary: Learn how to register a new endpoint and access it -date: 2021-10-05 +date: 2021-11-24 tags: ['kibana', 'dev', 'architecture', 'tutorials'] --- -## Registering an endpoint +## The HTTP service API + +### The server-side HTTP service The server-side `HttpService` allows server-side plugins to register endpoints with built-in support for request validation. These endpoints may be used by client-side code or be exposed as a public API for users. Most plugins integrate directly with this service. The service allows plugins to: -- to extend the Kibana server with custom HTTP API. -- to execute custom logic on an incoming request or server response. -- to implement custom authentication and authorization strategy. +- extend the Kibana server with custom HTTP API. +- execute custom logic on an incoming request or server response. +- implement custom authentication and authorization strategy. See [the server-side HTTP service API docs](https://github.com/elastic/kibana/blob/main/docs/development/core/server/kibana-plugin-core-server.httpservicesetup.md) -**Registering a basic GET endpoint** +### The client-side HTTP service + +The client-side counterpart of the HTTP service provides an API to communicate with the Kibana server via HTTP interface. +The client-side `HttpService` is a preconfigured wrapper around `window.fetch` that includes some default behavior and automatically handles common errors (such as session expiration). + +**The service should only be used for access to backend endpoints registered by the same plugin.** Feel free to use another HTTP client library to request 3rd party services. + + + See [the client-side HTTP service API docs](https://github.com/elastic/kibana/blob/main/docs/development/core/public/kibana-plugin-core-public.httpsetup.md) + + +## Registering an endpoint + +Registering an endpoint, or `route`, is done during the `setup` lifecycle stage of a plugin. The first step to register a route +is to create a [router](https://github.com/elastic/kibana/blob/main/docs/development/core/server/kibana-plugin-core-server.irouter.md) +using the `http` core service. + +Once the router is instantiated, it is possible to use its APIs, such as `router.get` or `router.post` to create a route for the equivalent +HTTP method. All these APIs share the same signature, and receive two parameters: +- `route` - the route configuration, such as the `path` of the route, or the parameter validation schemas +- `handler` - the handler function that will be called when a request matching the route configuration is received + +When invoked, the `handler` receive three parameters: `context`, `request`, and `response`, and must return a response that will be sent to serve +the request. +- `context` is a request-bound context exposed for the request. It allows for example to use an elasticsearch client bound to the request's credentials. +- `request` contains information related to the request, such as the path and query parameter +- `response` contains factory helpers to create the response to return from the endpoint + + + See the [request](https://github.com/elastic/kibana/blob/main/docs/development/core/server/kibana-plugin-core-server.kibanarequest.md) + and [response](https://github.com/elastic/kibana/blob/main/docs/development/core/server/kibana-plugin-core-server.kibanaresponsefactory.md) + documentation + + +## Basic examples + +### Registering a GET endpoint + +The following snippet demonstrate how to create a basic `GET` endpoint on the `/api/my_plugin/get_object` path: + +```ts +import type { CoreSetup, Plugin } from 'kibana/server'; + +export class MyPlugin implements Plugin { + public setup(core: CoreSetup) { + const router = core.http.createRouter(); + router.get( + { + path: '/api/my_plugin/get_object', + validate: false, + }, + async (context, request, response) => { + return response.ok({ + body: { result: 'everything is alright'}, + }); + } + ); + } +} +``` + +consuming the endpoint from the client-side using core's `http` service would then look like: + +```ts +import { HttpStart } from 'kibana/public'; + +interface ResponseType { + result: string; +}; + +async function fetchData(http: HttpStart) { + return await http.get(`/api/my_plugin/get_object`); +} +``` + +### Using and validating path parameters + +It is possible to specify dynamic parameters in the `path` of the endpoint using the `{name}` syntax. +When doing so, the associated validation schema must be defined via the `validate.params` option +of the route definition. ```ts import { schema } from '@kbn/config-schema'; @@ -29,59 +110,329 @@ import type { CoreSetup, Plugin } from 'kibana/server'; export class MyPlugin implements Plugin { public setup(core: CoreSetup) { const router = core.http.createRouter(); - - const validate = { - params: schema.object({ - id: schema.string(), - }), - }; - - router.get({ - path: '/api/my_plugin/{id}', - validate - }, - async (context, request, response) => { - const data = await findObject(request.params.id); - if (!data) return response.notFound(); - return response.ok({ - body: data, - headers: { - 'content-type': 'application/json' + router.get( + { + path: '/api/my_plugin/get_object/{id}', + validate: { + params: schema.object({ + id: schema.string(), + }) + }, + }, + async (context, request, response) => { + const { id } = request.params; + const data = await findObject(id); + if (!data) { + return response.notFound(); } - }); - }); + return response.ok({ body: data }); + } + ); } } ``` - - See [the routing example plugin](https://github.com/elastic/kibana/blob/main/examples/routing_example) for more route registration examples. - +consuming the endpoint from the client-side using core's `http` service would then look like: + +```ts +import { HttpStart } from 'kibana/public'; +import { MyObjectType } from '../common/types'; -## Consuming the endpoint from the client-side +async function fetchData(http: HttpStart, id: string) { + return await http.get(`/api/my_plugin/get_object/${id}`); +} +``` -The client-side HTTP service provides an API to communicate with the Kibana server via HTTP interface. -The client-side `HttpService` is a preconfigured wrapper around `window.fetch` that includes some default behavior and automatically handles common errors (such as session expiration). +### Registering a POST endpoint and validating the payload -**The service should only be used for access to backend endpoints registered by the same plugin.** Feel free to use another HTTP client library to request 3rd party services. +Similar to the validation we performed against the path parameters in the previous example, the `body` validation schema +must be provided when registering a `post` handler that will access the payload. + +```ts +import { schema } from '@kbn/config-schema'; +import type { CoreSetup, Plugin } from 'kibana/server'; + +export class MyPlugin implements Plugin { + public setup(core: CoreSetup) { + const router = core.http.createRouter(); + router.post( + { + path: '/api/my_plugin/objects/{id}/update', + validate: { + params: schema.object({ + id: schema.string(), + }), + body: schema.object({ + title: schema.string(), + description: schema.string() + }), + }, + }, + async (context, request, response) => { + const { id } = request.params; + const { title, description } = request.body; + await updateObject(id, { title, description }); + return response.ok({ body: { updated: true }}); + } + ); + } +} +``` + +consuming the endpoint from the client-side using core's `http` service would then look like: ```ts import { HttpStart } from 'kibana/public'; -interface ResponseType {…}; +interface ResponseType { + updated: boolean; +}; -async function fetchData(http: HttpStart, id: string) { - return await http.get( - `/api/my_plugin/${id}`, - { query: … }, - ); +interface UpdateOptions { + title?: string; + description?: string; +} + +async function fetchData(http: HttpStart, id: string, { title, description }: UpdateOptions) { + return await http.post(`/api/my_plugin/objects/${id}/update`, { + body: JSON.stringify({ title, description }) + }); } ``` - - See [the client-side HTTP service API docs](https://github.com/elastic/kibana/blob/main/docs/development/core/public/kibana-plugin-core-public.httpsetup.md) - +### Using the query parameters + +Similar to the `body` validation, the query parameters schema has to be defined using the `validate.query` +option of the route definition to be accessible from the handler. + +```ts +import { schema } from '@kbn/config-schema'; +import type { CoreSetup, Plugin } from 'kibana/server'; + +export class MyPlugin implements Plugin { + public setup(core: CoreSetup) { + const router = core.http.createRouter(); + router.get( + { + path: '/api/my_plugin/objects/find', + validate: { + query: schema.object({ + term: schema.maybe(schema.string()), + page: schema.number({ min: 1, defaultValue: 1 }), + perPage: schema.number({ min: 5, max: 50, defaultValue: 10 }), + }), + }, + }, + async (context, request, response) => { + const { term, page, perPage } = request.query; + const results = await findObjects(term, { page, perPage }); + return response.ok({ body: { results } }); + } + ); + } +} +``` + +consuming the endpoint from the client-side using core's `http` service would then look like: + +```ts +import { HttpStart } from 'kibana/public'; +import { MyObjectType } from '../common/types'; + +interface ResponseType { + results: MyObjectType[]; +}; + +interface UpdateOptions { + term?: string; + page?: number; + perPage?: number; +} + +async function fetchData(http: HttpStart, { term, page, perPage }: UpdateOptions) { + return await http.get(`/api/my_plugin/objects/find`, { + query: { term, page, perPage }, + }); +} +``` + +## Customizing the response + +### Attaching headers to the response + +All APIs of the `response` parameter of the handler accept a `headers` property that can be used +to define headers to attach to the response. + +```ts +import type { CoreSetup, Plugin } from 'kibana/server'; + +export class MyPlugin implements Plugin { + public setup(core: CoreSetup) { + const router = core.http.createRouter(); + router.get( + { + path: '/api/my_plugin/some_text_response', + validate: false, + }, + async (context, request, response) => { + return response.ok({ + body: 'some plain text response', + headers: { + 'content-type': 'text/plain', + 'cache-control': 'must-revalidate', + }, + }); + } + ); + } +} +``` + +### Defining a specific HTTP status code for the response + +The `response` parameter of the handler already provides APIs for the most common HTTP response codes, such as +- `response.ok` for `200` +- `response.notFound` for `404` +- `response.badRequest` for `400` +- and so on + +However, some of the less commonly used return codes don't have such helpers. In that case, the `response.custom` +and/or `response.customError` APIs should be used. + +```ts +import type { CoreSetup, Plugin } from 'kibana/server'; + +export class MyPlugin implements Plugin { + public setup(core: CoreSetup) { + const router = core.http.createRouter(); + router.get( + { + path: '/api/my_plugin/some_text_response', + validate: false, + }, + async (context, request, response) => { + return response.custom({ + body: `Kibana is a teapot`, + statusCode: 418, + }); + } + ); + } +} +``` + +## Some advanced usages + +### Handling request cancellation + +Some request lifecycle events are exposed to the handler via `request.events` in the form of `rxjs` +observables, such as `request.events.aborted$` that emits if/when the request is canceled by the client. + +These observables can either be used directly, or be used to control an `AbortController`. + +```ts +import { schema } from '@kbn/config-schema'; +import type { CoreSetup, Plugin } from 'kibana/server'; + +export class MyPlugin implements Plugin { + public setup(core: CoreSetup) { + const router = core.http.createRouter(); + router.get( + { + path: '/api/my_plugin/objects/find', + validate: { + query: schema.object({ + term: schema.maybe(schema.string()), + }), + }, + }, + async (context, request, response) => { + const { term } = request.query; + const { aborted$ } = request.events; + + const abortController = new AbortController(); + aborted$.subscribe(() => { + abortController.abort(); + }); + + const results = await findObjects(term, { abortController }); + return response.ok({ body: results }); + } + ); + } +} +``` + +### Disabling authentication for an endpoint + +By default, when security is enabled, endpoints require the user to be authenticated to be accessed, +and will return a `401 - Unauthorized` otherwise. + +It is possible to disable this requirement using the `authRequired` option of the route. + +```ts +import type { CoreSetup, Plugin } from 'kibana/server'; + +export class MyPlugin implements Plugin { + public setup(core: CoreSetup) { + const router = core.http.createRouter(); + router.get( + { + path: '/api/my_plugin/get_object', + validate: false, + options: { + authRequired: false, + }, + }, + async (context, request, response) => { + return response.ok({ + body: { authenticated: request.auth.isAuthenticated }, + }); + } + ); + } +} +``` + +Note that in addition to `true` and `false`, `authRequired` accepts a third value, `'optional'`. When used, +Kibana will try to authenticate the user but will allow access to the endpoint regardless of the result. In that +case, the developer needs to manually checks if the user is authenticated via `request.auth.isAuthenticated`. + +### Accessing the url or route configuration from the handler + +In some advanced use cases, such as generic handlers being used for multiple routes, it can be useful to know, +from within the handler, the route configuration and the actual url that was requested by the user. This can +be achieved by using the `url` and `route` properties of the `request` parameter of the handler. + +request.url / request.route + +```ts +import type { CoreSetup, Plugin } from 'kibana/server'; + +export class MyPlugin implements Plugin { + public setup(core: CoreSetup) { + const router = core.http.createRouter(); + router.get( + { + path: '/api/my_plugin/get_object', + validate: false, + options: { + authRequired: false, + }, + }, + async (context, request, response) => { + const { url, route } = request; + return response.ok({ + body: `You requested ${route.method} ${url}`, + }); + } + ); + } +} +``` + +## More examples - See [the routing example plugin](https://github.com/elastic/kibana/blob/main/examples/routing_example) for more endpoint consumption examples. + See [the routing example plugin](https://github.com/elastic/kibana/blob/main/examples/routing_example) for more route registration examples. diff --git a/dev_docs/tutorials/saved_objects.mdx b/dev_docs/tutorials/saved_objects.mdx index 9583e195d1c8..a9d8cd7c6ec1 100644 --- a/dev_docs/tutorials/saved_objects.mdx +++ b/dev_docs/tutorials/saved_objects.mdx @@ -252,6 +252,8 @@ Having said that, if a document is encountered that is not in the expected shape fail an upgrade than to silently ignore a corrupt document which can cause unexpected behaviour at some future point in time. When such a scenario is encountered, the error should be verbose and informative so that the corrupt document can be corrected, if possible. +**WARNING:** Do not attempt to change the `migrationVersion`, `id`, or `type` fields within a migration function, this is not supported. + ### Testing Migrations Bugs in a migration function cause downtime for our users and therefore have a very high impact. Follow the . diff --git a/docs/api/alerting.asciidoc b/docs/api/alerting.asciidoc index ad2d358d17ba..931165ce5f48 100644 --- a/docs/api/alerting.asciidoc +++ b/docs/api/alerting.asciidoc @@ -1,7 +1,7 @@ [[alerting-apis]] == Alerting APIs -The following APIs are available for {kib} alerting. +The following APIs are available for Alerting. * <> to create a rule diff --git a/docs/api/alerting/list_rule_types.asciidoc b/docs/api/alerting/list_rule_types.asciidoc index 21ace9f3105c..e7b433064eec 100644 --- a/docs/api/alerting/list_rule_types.asciidoc +++ b/docs/api/alerting/list_rule_types.asciidoc @@ -4,7 +4,7 @@ List rule types ++++ -Retrieve a list of alerting rule types that the user is authorized to access. +Retrieve a list of rule types that the user is authorized to access. Each rule type includes a list of consumer features. Within these features, users are authorized to perform either `read` or `all` operations on rules of that type. This helps determine which rule types users can read, but not create or modify. diff --git a/docs/api/dashboard-api.asciidoc b/docs/api/dashboard-api.asciidoc index e6f54dd9156e..e8d0a829d178 100644 --- a/docs/api/dashboard-api.asciidoc +++ b/docs/api/dashboard-api.asciidoc @@ -4,7 +4,7 @@ deprecated::[7.15.0,Both of these APIs have been deprecated in favor of <> and <>.] Import and export dashboards with the corresponding saved objects, such as visualizations, saved -searches, and index patterns. +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. diff --git a/docs/api/data-views.asciidoc b/docs/api/data-views.asciidoc new file mode 100644 index 000000000000..d7380cbd97c9 --- /dev/null +++ b/docs/api/data-views.asciidoc @@ -0,0 +1,42 @@ +[[data-views-api]] +== Data views API + +experimental[] Manage data views, formerly known as {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 data views APIs for managing data views instead of lower-level <>. + +The following data views APIs are available: + +* Data views + ** <> to retrieve a single data view + ** <> to create data view + ** <> to partially updated data view + ** <> to delete a data view +* Default data views + ** <> to retrieve a default data view + ** <> to set a default data view +* Fields + ** <> to change field metadata, such as `count`, `customLabel` and `format` +* Runtime fields + ** <> to retrieve a runtime field + ** <> to create a runtime field + ** <> to create or update a runtime field + ** <> to partially update an existing runtime field + ** <> to delete a runtime field + +include::data-views/get.asciidoc[] +include::data-views/create.asciidoc[] +include::data-views/update.asciidoc[] +include::data-views/delete.asciidoc[] +include::data-views/default-get.asciidoc[] +include::data-views/default-set.asciidoc[] +include::data-views/update-fields.asciidoc[] +include::data-views/runtime-fields/get.asciidoc[] +include::data-views/runtime-fields/create.asciidoc[] +include::data-views/runtime-fields/upsert.asciidoc[] +include::data-views/runtime-fields/update.asciidoc[] +include::data-views/runtime-fields/delete.asciidoc[] + diff --git a/docs/api/index-patterns/create.asciidoc b/docs/api/data-views/create.asciidoc similarity index 64% rename from docs/api/index-patterns/create.asciidoc rename to docs/api/data-views/create.asciidoc index 521e25931ad4..c1666589b7e2 100644 --- a/docs/api/index-patterns/create.asciidoc +++ b/docs/api/data-views/create.asciidoc @@ -1,45 +1,45 @@ -[[index-patterns-api-create]] -=== Create index pattern API +[[data-views-api-create]] +=== Create data view API ++++ -Create index pattern +Create data view ++++ -experimental[] Create {kib} index patterns. +experimental[] Create data views. -[[index-patterns-api-create-request]] +[[data-views-api-create-request]] ==== Request `POST :/api/index_patterns/index_pattern` `POST :/s//api/index_patterns/index_pattern` -[[index-patterns-api-create-path-params]] +[[data-views-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]] +[[data-views-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`. +`override`:: (Optional, boolean) Overrides an existing data view if a +data view 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`. +`refresh_fields`:: (Optional, boolean) Reloads data view fields after +the data view is stored. The default is `false`. -`index_pattern`:: (Required, object) The index pattern object. All fields are optional. +`index_pattern`:: (Required, object) The data view object. All fields are optional. -[[index-patterns-api-create-request-codes]] +[[data-views-api-create-request-codes]] ==== Response code `200`:: Indicates a successful call. -[[index-patterns-api-create-example]] +[[data-views-api-create-example]] ==== Examples -Create an index pattern with a custom title: +Create a data view with a custom title: [source,sh] -------------------------------------------------- @@ -67,7 +67,7 @@ $ curl -X POST api/index_patterns/index_pattern -------------------------------------------------- // KIBANA -At creation, all index pattern fields are optional: +At creation, all data view fields are optional: [source,sh] -------------------------------------------------- @@ -92,7 +92,7 @@ $ curl -X POST api/index_patterns/index_pattern // KIBANA -The API returns the index pattern object: +The API returns the data view object: [source,sh] -------------------------------------------------- diff --git a/docs/api/index-patterns/default-get.asciidoc b/docs/api/data-views/default-get.asciidoc similarity index 59% rename from docs/api/index-patterns/default-get.asciidoc rename to docs/api/data-views/default-get.asciidoc index 5c7e8e01ce39..300a0612b18e 100644 --- a/docs/api/index-patterns/default-get.asciidoc +++ b/docs/api/data-views/default-get.asciidoc @@ -1,34 +1,34 @@ -[[index-patterns-api-default-get]] -=== Get default index pattern API +[[data-views-api-default-get]] +=== Get default data view API ++++ -Get default index pattern +Get default data view ++++ -experimental[] Retrieve a default index pattern ID. Kibana UI uses default index pattern unless user picks a different one. +experimental[] Retrieve a default data view ID. Kibana UI uses the default data view unless user picks a different one. -[[index-patterns-api-default-get-request]] +[[data-views-api-default-get-request]] ==== Request `GET :/api/index_patterns/default` `GET :/s//api/index_patterns/default` -[[index-patterns-api-default-get-params]] +[[data-views-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]] +[[data-views-api-default-get-codes]] ==== Response code `200`:: Indicates a successful call. -[[index-patterns-api-default-get-example]] +[[data-views-api-default-get-example]] ==== Example -Retrieve the default index pattern id: +Retrieve the default data view id: [source,sh] -------------------------------------------------- @@ -36,7 +36,7 @@ $ curl -X GET api/index_patterns/default -------------------------------------------------- // KIBANA -The API returns an ID of a default index pattern: +The API returns an ID of a default data view: [source,sh] -------------------------------------------------- @@ -45,7 +45,7 @@ The API returns an ID of a default index pattern: } -------------------------------------------------- -In case there is no default index pattern, the API returns: +In case there is no default data view, the API returns: [source,sh] -------------------------------------------------- diff --git a/docs/api/index-patterns/default-set.asciidoc b/docs/api/data-views/default-set.asciidoc similarity index 64% rename from docs/api/index-patterns/default-set.asciidoc rename to docs/api/data-views/default-set.asciidoc index 3b3cec6be632..752054cfb174 100644 --- a/docs/api/index-patterns/default-set.asciidoc +++ b/docs/api/data-views/default-set.asciidoc @@ -1,43 +1,43 @@ -[[index-patterns-api-default-set]] -=== Set default index pattern API +[[data-views-api-default-set]] +=== Set default data view API ++++ -Set default index pattern +Set default data view ++++ -experimental[] Set a default index pattern ID. Kibana UI will use default index pattern unless user picks a different one. +experimental[] Set a default data view ID. Kibana UI will use the default data view 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]] +[[data-views-api-default-set-request]] ==== Request `POST :/api/index_patterns/default` `POST :/s//api/index_patterns/default` -[[index-patterns-api-default-set-params]] +[[data-views-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]] +[[data-views-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. +`index_pattern_id`:: (Required, `string` or `null`) Sets a default data view id. Use `null` to unset a default data view. -`force`:: (Optional, boolean) Updates existing default index pattern id. The default is `false`. +`force`:: (Optional, boolean) Updates existing default data view id. The default is `false`. -[[index-patterns-api-default-set-codes]] +[[data-views-api-default-set-codes]] ==== Response code `200`:: Indicates a successful call. -[[index-patterns-api-default-set-example]] +[[data-views-api-default-set-example]] ==== Example -Set the default index pattern id if none is set: +Set the default data view id if none is set: [source,sh] -------------------------------------------------- @@ -49,7 +49,7 @@ $ curl -X POST api/index_patterns/default // KIBANA -Upsert the default index pattern: +Upsert the default data view: [source,sh] -------------------------------------------------- @@ -61,7 +61,7 @@ $ curl -X POST api/index_patterns/default -------------------------------------------------- // KIBANA -Unset the default index pattern: +Unset the default data view: [source,sh] -------------------------------------------------- diff --git a/docs/api/index-patterns/delete.asciidoc b/docs/api/data-views/delete.asciidoc similarity index 51% rename from docs/api/index-patterns/delete.asciidoc rename to docs/api/data-views/delete.asciidoc index a25f2f13e0b4..9bc63c89365e 100644 --- a/docs/api/index-patterns/delete.asciidoc +++ b/docs/api/data-views/delete.asciidoc @@ -1,38 +1,38 @@ -[[index-patterns-api-delete]] -=== Delete index pattern API +[[data-views-api-delete]] +=== Delete data view API ++++ -Delete index pattern +Delete data view ++++ -experimental[] Delete {kib} index patterns. +experimental[] Delete data views. -WARNING: Once you delete an index pattern, _it cannot be recovered_. +WARNING: Once you delete a data view, _it cannot be recovered_. -[[index-patterns-api-delete-request]] +[[data-views-api-delete-request]] ==== Request `DELETE :/api/index_patterns/index_pattern/` `DELETE :/s//api/index_patterns/index_pattern/` -[[index-patterns-api-delete-path-params]] +[[data-views-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. + (Required, string) The ID of the data view you want to delete. -[[index-patterns-api-delete-response-codes]] +[[data-views-api-delete-response-codes]] ==== Response code `200`:: - Indicates that index pattern is deleted. Returns an empty response body. + Indicates that data view is deleted. Returns an empty response body. ==== Example -Delete an index pattern object with the `my-pattern` ID: +Delete a data view object with the `my-pattern` ID: [source,sh] -------------------------------------------------- diff --git a/docs/api/index-patterns/get.asciidoc b/docs/api/data-views/get.asciidoc similarity index 67% rename from docs/api/index-patterns/get.asciidoc rename to docs/api/data-views/get.asciidoc index 64588e63f62a..0584dfeae1cd 100644 --- a/docs/api/index-patterns/get.asciidoc +++ b/docs/api/data-views/get.asciidoc @@ -1,40 +1,40 @@ -[[index-patterns-api-get]] -=== Get index pattern API +[[data-views-api-get]] +=== Get data view API ++++ -Get index pattern +Get data view ++++ -experimental[] Retrieve a single {kib} index pattern by ID. +experimental[] Retrieve a single data view by ID. -[[index-patterns-api-get-request]] +[[data-views-api-get-request]] ==== Request `GET :/api/index_patterns/index_pattern/` `GET :/s//api/index_patterns/index_pattern/` -[[index-patterns-api-get-params]] +[[data-views-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. +(Required, string) The ID of the data view you want to retrieve. -[[index-patterns-api-get-codes]] +[[data-views-api-get-codes]] ==== Response code `200`:: Indicates a successful call. `404`:: -The specified index pattern and ID doesn't exist. +The specified data view and ID doesn't exist. -[[index-patterns-api-get-example]] +[[data-views-api-get-example]] ==== Example -Retrieve the index pattern object with the `my-pattern` ID: +Retrieve the data view object with the `my-pattern` ID: [source,sh] -------------------------------------------------- @@ -42,7 +42,7 @@ $ curl -X GET api/index_patterns/index_pattern/my-pattern -------------------------------------------------- // KIBANA -The API returns an index pattern object: +The API returns a data view object: [source,sh] -------------------------------------------------- diff --git a/docs/api/index-patterns/runtime-fields/create.asciidoc b/docs/api/data-views/runtime-fields/create.asciidoc similarity index 74% rename from docs/api/index-patterns/runtime-fields/create.asciidoc rename to docs/api/data-views/runtime-fields/create.asciidoc index b0773c29e530..442bede9cba7 100644 --- a/docs/api/index-patterns/runtime-fields/create.asciidoc +++ b/docs/api/data-views/runtime-fields/create.asciidoc @@ -1,4 +1,4 @@ -[[index-patterns-runtime-field-api-create]] +[[data-views-runtime-field-api-create]] === Create runtime field API ++++ Create runtime field @@ -6,23 +6,23 @@ experimental[] Create a runtime field -[[index-patterns-runtime-field-create-request]] +[[data-views-runtime-field-create-request]] ==== Request `POST :/api/index_patterns/index_pattern//runtime_field` `POST :/s//api/index_patterns/index_pattern//runtime_field` -[[index-patterns-runtime-field-create-params]] +[[data-views-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. +(Required, string) The ID of the data view. -[[index-patterns-runtime-field-create-body]] +[[data-views-runtime-field-create-body]] ==== Request body `name`:: (Required, string) The name for a runtime field. @@ -30,10 +30,10 @@ experimental[] Create a runtime field `runtimeField`:: (Required, object) The runtime field definition object. -[[index-patterns-runtime-field-create-example]] +[[data-views-runtime-field-create-example]] ==== Examples -Create a runtime field on an index pattern: +Create a runtime field on a data view: [source,sh] -------------------------------------------------- @@ -50,7 +50,7 @@ $ curl -X POST api/index_patterns/index_pattern//runtime_field -------------------------------------------------- // KIBANA -The API returns created runtime field object and update index pattern object: +The API returns created runtime field object and updated data view object: [source,sh] -------------------------------------------------- diff --git a/docs/api/index-patterns/runtime-fields/delete.asciidoc b/docs/api/data-views/runtime-fields/delete.asciidoc similarity index 70% rename from docs/api/index-patterns/runtime-fields/delete.asciidoc rename to docs/api/data-views/runtime-fields/delete.asciidoc index 840789fe1ec2..b2a8e9f31047 100644 --- a/docs/api/index-patterns/runtime-fields/delete.asciidoc +++ b/docs/api/data-views/runtime-fields/delete.asciidoc @@ -1,26 +1,26 @@ -[[index-patterns-runtime-field-api-delete]] +[[data-views-runtime-field-api-delete]] === Delete runtime field API ++++ Delete runtime field ++++ -experimental[] Delete a runtime field from an index pattern. +experimental[] Delete a runtime field from a data view. -[[index-patterns-runtime-field-api-delete-request]] +[[data-views-runtime-field-api-delete-request]] ==== Request `DELETE :/api/index_patterns/index_pattern//runtime_field/` `DELETE :/s//api/index_patterns/index_pattern//runtime_field/` -[[index-patterns-runtime-field-api-delete-path-params]] +[[data-views-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. +(Required, string) The ID of the data view your want to delete a runtime field from. `name`:: (Required, string) The name of the runtime field you want to delete. @@ -28,7 +28,7 @@ experimental[] Delete a runtime field from an index pattern. ==== Example -Delete a runtime field from an index pattern: +Delete a runtime field from a data view: [source,sh] -------------------------------------------------- diff --git a/docs/api/index-patterns/runtime-fields/get.asciidoc b/docs/api/data-views/runtime-fields/get.asciidoc similarity index 78% rename from docs/api/index-patterns/runtime-fields/get.asciidoc rename to docs/api/data-views/runtime-fields/get.asciidoc index 42bd209c708b..66530ae5f3f3 100644 --- a/docs/api/index-patterns/runtime-fields/get.asciidoc +++ b/docs/api/data-views/runtime-fields/get.asciidoc @@ -1,4 +1,4 @@ -[[index-patterns-runtime-field-api-get]] +[[data-views-runtime-field-api-get]] === Get runtime field API ++++ Get runtime field @@ -6,30 +6,30 @@ experimental[] Get a runtime field -[[index-patterns-runtime-field-get-request]] +[[data-views-runtime-field-get-request]] ==== Request `GET :/api/index_patterns/index_pattern//runtime_field/` `GET :/s//api/index_patterns/index_pattern//runtime_field/` -[[index-patterns-runtime-field-get-params]] +[[data-views-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. +(Required, string) The ID of the data view. `name`:: (Required, string) The name of the runtime field you want to retrieve. -[[index-patterns-runtime-field-get-example]] +[[data-views-runtime-field-get-example]] ==== Example -Retrieve a runtime field named `foo` of index pattern with the `my-pattern` ID: +Retrieve a runtime field named `foo` of data view with the `my-pattern` ID: [source,sh] -------------------------------------------------- diff --git a/docs/api/index-patterns/runtime-fields/update.asciidoc b/docs/api/data-views/runtime-fields/update.asciidoc similarity index 75% rename from docs/api/index-patterns/runtime-fields/update.asciidoc rename to docs/api/data-views/runtime-fields/update.asciidoc index f34460896f7b..970826560f4a 100644 --- a/docs/api/index-patterns/runtime-fields/update.asciidoc +++ b/docs/api/data-views/runtime-fields/update.asciidoc @@ -1,4 +1,4 @@ -[[index-patterns-runtime-field-api-update]] +[[data-views-runtime-field-api-update]] === Update runtime field API ++++ Update runtime field @@ -6,26 +6,26 @@ experimental[] Update an existing runtime field -[[index-patterns-runtime-field-update-request]] +[[data-views-runtime-field-update-request]] ==== Request `POST :/api/index_patterns/index_pattern//runtime_field/` `POST :/s//api/index_patterns/index_pattern//runtime_field/` -[[index-patterns-runtime-field-update-params]] +[[data-views-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. +(Required, string) The ID of the data view. `name`:: (Required, string) The name of the runtime field you want to update. -[[index-patterns-runtime-field-update-body]] +[[data-views-runtime-field-update-body]] ==== Request body `runtimeField`:: (Required, object) The runtime field definition object. @@ -37,10 +37,10 @@ You can update following fields: -[[index-patterns-runtime-field-update-example]] +[[data-views-runtime-field-update-example]] ==== Examples -Update an existing runtime field on an index pattern: +Update an existing runtime field on a data view: [source,sh] -------------------------------------------------- @@ -55,7 +55,7 @@ $ curl -X POST api/index_patterns/index_pattern//runtime_field -------------------------------------------------- // KIBANA -The API returns updated runtime field object and updated index pattern object: +The API returns updated runtime field object and updated data view object: [source,sh] -------------------------------------------------- diff --git a/docs/api/index-patterns/runtime-fields/upsert.asciidoc b/docs/api/data-views/runtime-fields/upsert.asciidoc similarity index 78% rename from docs/api/index-patterns/runtime-fields/upsert.asciidoc rename to docs/api/data-views/runtime-fields/upsert.asciidoc index 1b436db19c62..427aa30afa94 100644 --- a/docs/api/index-patterns/runtime-fields/upsert.asciidoc +++ b/docs/api/data-views/runtime-fields/upsert.asciidoc @@ -1,4 +1,4 @@ -[[index-patterns-runtime-field-api-upsert]] +[[data-views-runtime-field-api-upsert]] === Upsert runtime field API ++++ Upsert runtime field @@ -6,23 +6,23 @@ experimental[] Create or update an existing runtime field -[[index-patterns-runtime-field-upsert-request]] +[[data-views-runtime-field-upsert-request]] ==== Request `PUT :/api/index_patterns/index_pattern//runtime_field` `PUT :/s//api/index_patterns/index_pattern//runtime_field` -[[index-patterns-runtime-field-upsert-params]] +[[data-views-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. +(Required, string) The ID of the data view. -[[index-patterns-runtime-field-upsert-body]] +[[data-views-runtime-field-upsert-body]] ==== Request body `name`:: (Required, string) The name for a new runtime field or a name of an existing runtime field. @@ -30,10 +30,10 @@ experimental[] Create or update an existing runtime field `runtimeField`:: (Required, object) The runtime field definition object. -[[index-patterns-runtime-field-upsert-example]] +[[data-views-runtime-field-upsert-example]] ==== Examples -Create or update an existing runtime field on an index pattern: +Create or update an existing runtime field on a data view: [source,sh] -------------------------------------------------- @@ -50,7 +50,7 @@ $ curl -X PUT api/index_patterns/index_pattern//runtime_field -------------------------------------------------- // KIBANA -The API returns created or updated runtime field object and updated index pattern object: +The API returns created or updated runtime field object and updated data view object: [source,sh] -------------------------------------------------- diff --git a/docs/api/index-patterns/update-fields.asciidoc b/docs/api/data-views/update-fields.asciidoc similarity index 79% rename from docs/api/index-patterns/update-fields.asciidoc rename to docs/api/data-views/update-fields.asciidoc index e3f98631bb52..929dee27b9da 100644 --- a/docs/api/index-patterns/update-fields.asciidoc +++ b/docs/api/data-views/update-fields.asciidoc @@ -1,43 +1,43 @@ -[[index-patterns-fields-api-update]] -=== Update index pattern fields API +[[data-views-fields-api-update]] +=== Update data view fields API ++++ -Update index pattern fields metadata +Update data view fields metadata ++++ 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]] +[[data-views-fields-api-update-request]] ==== Request `POST :/api/index_patterns/index_pattern//fields` `POST :/s//api/index_patterns/index_pattern//fields` -[[index-patterns-fields-api-update-path-params]] +[[data-views-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. +(Required, string) The ID of the data view fields you want to update. -[[index-patterns-fields-api-update-request-body]] +[[data-views-fields-api-update-request-body]] ==== Request body `fields`:: (Required, object) the field object -[[index-patterns-fields-api-update-errors-codes]] +[[data-views-fields-api-update-errors-codes]] ==== Response code `200`:: Indicates a successful call. -[[index-patterns-fields-api-update-example]] +[[data-views-fields-api-update-example]] ==== Examples Set popularity `count` for field `foo`: @@ -89,7 +89,7 @@ $ curl -X POST api/saved_objects/index-pattern/my-pattern/fields // KIBANA -The endpoint returns the updated index pattern object: +The endpoint returns the updated data view object: [source,sh] -------------------------------------------------- { diff --git a/docs/api/index-patterns/update.asciidoc b/docs/api/data-views/update.asciidoc similarity index 67% rename from docs/api/index-patterns/update.asciidoc rename to docs/api/data-views/update.asciidoc index 2d5fe882d448..6157d4688827 100644 --- a/docs/api/index-patterns/update.asciidoc +++ b/docs/api/data-views/update.asciidoc @@ -1,36 +1,36 @@ -[[index-patterns-api-update]] -=== Update index pattern API +[[data-views-api-update]] +=== Update data view API ++++ -Update index pattern +Update data view ++++ -experimental[] Update part of an index pattern. Only the specified fields are updated in the -index pattern. Unspecified fields stay as they are persisted. +experimental[] Update part of an data view. Only the specified fields are updated in the +data view. Unspecified fields stay as they are persisted. -[[index-patterns-api-update-request]] +[[data-views-api-update-request]] ==== Request `POST :/api/index_patterns/index_pattern/` `POST :/s//api/index_patterns/index_pattern/` -[[index-patterns-api-update-path-params]] +[[data-views-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. + (Required, string) The ID of the data view you want to update. -[[index-patterns-api-update-request-body]] +[[data-views-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`. +`refresh_fields`:: (Optional, boolean) Reloads the data view fields after +the data view is updated. The default is `false`. `index_pattern`:: - (Required, object) The index patterns fields you want to update. + (Required, object) The data view fields you want to update. + You can partially update the following fields: @@ -43,16 +43,16 @@ You can partially update the following fields: * `type` * `typeMeta` -[[index-patterns-api-update-errors-codes]] +[[data-views-api-update-errors-codes]] ==== Response code `200`:: Indicates a successful call. -[[index-patterns-api-update-example]] +[[data-views-api-update-example]] ==== Examples -Update a title of the `` index pattern: +Update a title of the `` data view: [source,sh] -------------------------------------------------- @@ -100,7 +100,7 @@ $ curl -X POST api/saved_objects/index-pattern/my-pattern -------------------------------------------------- // KIBANA -The API returns the updated index pattern object: +The API returns the updated data view object: [source,sh] -------------------------------------------------- diff --git a/docs/api/index-patterns.asciidoc b/docs/api/index-patterns.asciidoc deleted file mode 100644 index b343d80b4fc1..000000000000 --- a/docs/api/index-patterns.asciidoc +++ /dev/null @@ -1,42 +0,0 @@ -[[index-patterns-api]] -== Index patterns APIs - -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 <>. - -The following index patterns APIs are available: - -* Index patterns - ** <> to retrieve a single {kib} index pattern - ** <> to create {kib} index pattern - ** <> to partially updated {kib} index pattern - ** <> to delete {kib} index pattern -* Default index pattern - ** <> to retrieve a default index pattern - ** <> to set a default index pattern -* Fields - ** <> to change field metadata, such as `count`, `customLabel` and `format` -* Runtime fields - ** <> to retrieve a runtime field - ** <> to create a runtime field - ** <> to create or update a runtime field - ** <> to partially update an existing runtime field - ** <> 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[] - diff --git a/docs/api/saved-objects.asciidoc b/docs/api/saved-objects.asciidoc index 0625beb793c3..fcb4b119c06c 100644 --- a/docs/api/saved-objects.asciidoc +++ b/docs/api/saved-objects.asciidoc @@ -6,7 +6,7 @@ Manage {kib} saved objects, including dashboards, visualizations, and more. 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. -NOTE: For managing {kib} index patterns, use the <>. +NOTE: For managing {kib} index patterns, use the <>. The following saved objects APIs are available: diff --git a/docs/api/saved-objects/import.asciidoc b/docs/api/saved-objects/import.asciidoc index 923482954aa2..a214598af31a 100644 --- a/docs/api/saved-objects/import.asciidoc +++ b/docs/api/saved-objects/import.asciidoc @@ -11,11 +11,13 @@ Saved objects can only be imported into the same version, a newer minor on the s |======= | Exporting version | Importing version | Compatible? -| 6.7.0 | 6.8.1 | Yes -| 6.8.1 | 7.3.0 | Yes -| 7.3.0 | 7.11.1 | Yes -| 7.11.1 | 7.6.0 | No -| 6.8.1 | 8.0.0 | No +| 6.7.x | 6.8.x | Yes +| 6.x.x | 7.x.x | Yes +| 7.x.x | 8.x.x | Yes +| 7.1.x | 7.15.x | Yes +| 7.x.x | 6.x.x | No +| 7.15.x | 7.1.x | No +| 6.x.x | 8.x.x | No |======= [[saved-objects-api-import-request]] diff --git a/docs/apm/api.asciidoc b/docs/apm/api.asciidoc index 8bf1b3892014..a7e2a93e0944 100644 --- a/docs/apm/api.asciidoc +++ b/docs/apm/api.asciidoc @@ -10,7 +10,6 @@ Some APM app features are provided via a REST API: * <> * <> -* <> * <> [float] @@ -71,6 +70,13 @@ curl -X POST \ }' ---- +[float] +[[kibana-api]] +=== Kibana API + +In addition to the APM specific API endpoints, Kibana provides its own <> +which you can use to automate certain aspects of configuring and deploying Kibana. + //// ******************************************************* ******************************************************* @@ -474,90 +480,6 @@ curl -X POST \ ******************************************************* //// -[[kibana-api]] -=== Kibana API - -In addition to the APM specific API endpoints, Kibana provides its own <> -which you can use to automate certain aspects of configuring and deploying Kibana. -An example is below. - -[[api-create-apm-index-pattern]] -==== Customize the APM index pattern - -Use Kibana's <> to update the default APM index pattern on the fly. - -The following example sets the default APM app index pattern to `some-other-pattern-*`: - -[source,sh] ----- -curl -X PUT "localhost:5601/api/saved_objects/index-pattern/apm_static_index_pattern_id" \ <1> --H 'Content-Type: application/json' \ --H 'kbn-xsrf: true' \ --H 'Authorization: Basic ${YOUR_AUTH_TOKEN}' \ --d' { - "attributes": { - "title": "some-other-pattern-*", <2> - } - }' ----- -<1> `apm_static_index_pattern_id` is the internal, hard-coded ID of the APM index pattern. -This value should not be changed -<2> Your custom index pattern matcher. - -The API returns the following: - -[source,json] ----- -{ - "id":"apm_static_index_pattern_id", - "type":"index-pattern", - "updated_at":"2020-07-06T22:55:59.555Z", - "version":"WzYsMV0=", - "attributes":{ - "title":"some-other-pattern-*" - } -} ----- - -To view the new APM app index pattern, use the <>: - -[source,sh] ----- -curl -X GET "localhost:5601/api/saved_objects/index-pattern/apm_static_index_pattern_id" \ <1> --H 'kbn-xsrf: true' \ --H 'Authorization: Basic ${YOUR_AUTH_TOKEN}' ----- -<1> `apm_static_index_pattern_id` is the internal, hard-coded ID of the APM index pattern. - -The API returns the following: - -[source,json] ----- -{ - "id":"apm_static_index_pattern_id", - "type":"index-pattern", - "updated_at":"2020-07-06T22:55:59.555Z", - "version":"WzYsMV0=", - "attributes":{...} - "fieldFormatMap":"{...} - "fields":"[{...},{...},...] - "sourceFilters":"[{\"value\":\"sourcemap.sourcemap\"}]", - "timeFieldName":"@timestamp", - "title":"some-other-pattern-*" - }, - ... -} ----- - -// More examples will go here - -More information on Kibana's API is available in <>. - -//// -******************************************************* -******************************************************* -//// - [role="xpack"] [[rum-sourcemap-api]] === RUM source map API diff --git a/docs/apm/apm-alerts.asciidoc b/docs/apm/apm-alerts.asciidoc index 42016ac08bfc..d8ce1fafc783 100644 --- a/docs/apm/apm-alerts.asciidoc +++ b/docs/apm/apm-alerts.asciidoc @@ -107,7 +107,7 @@ From this page, you can disable, mute, and delete APM alerts. [[apm-alert-more-info]] === More information -See {kibana-ref}/alerting-getting-started.html[alerting and actions] for more information. +See {kibana-ref}/alerting-getting-started.html[Alerting] for more information. NOTE: If you are using an **on-premise** Elastic Stack deployment with security, communication between Elasticsearch and Kibana must have TLS configured. diff --git a/docs/apm/images/apm-setup.png b/docs/apm/images/apm-setup.png index 3410ebf69d84..8aadd8911c6e 100644 Binary files a/docs/apm/images/apm-setup.png and b/docs/apm/images/apm-setup.png differ diff --git a/docs/apm/set-up.asciidoc b/docs/apm/set-up.asciidoc index 3cbe45ec913b..481ac52d8ffd 100644 --- a/docs/apm/set-up.asciidoc +++ b/docs/apm/set-up.asciidoc @@ -8,28 +8,13 @@ APM is available via the navigation sidebar in {Kib}. If you have not already installed and configured Elastic APM, -the *Add data* page will get you started. +follow the three steps on the *Add data* page to get started: -[role="screenshot"] -image::apm/images/apm-setup.png[Installation instructions on the APM page in Kibana] - -[float] -[[apm-configure-index-pattern]] -=== Load the index pattern - -Index patterns tell {kib} which {es} indices you want to explore. -An APM index pattern is necessary for certain features in the APM app, like the query bar. -To set up the correct index pattern, on the *Add data* page, click *Load Kibana objects*. +. Start APM Server +. Add APM agents +. Load Kibana objects [role="screenshot"] -image::apm/images/apm-index-pattern.png[Setup index pattern for APM in Kibana] - -TIP: To use a custom index pattern, -adjust Kibana's <> or use the <>. - -[float] -[[apm-getting-started-next]] -=== Next steps +image::apm/images/apm-setup.png[Installation instructions on the APM page in Kibana] -No further configuration in the APM app is required. -Install an APM Agent library in your service to begin visualizing and analyzing your data! +That's it! You're now ready to explore your data. diff --git a/docs/concepts/data-views.asciidoc b/docs/concepts/data-views.asciidoc index 7eb95405db6b..870b923f20cf 100644 --- a/docs/concepts/data-views.asciidoc +++ b/docs/concepts/data-views.asciidoc @@ -1,7 +1,7 @@ [[data-views]] === Create a data view -{kib} requires a data view to access the {es} data that you want to explore. +{kib} requires a data view to access the {es} data that you want to explore. A data view selects the data to use and allows you to define properties of the fields. A data view can point to one or more indices, {ref}/data-streams.html[data stream], or {ref}/alias.html[index aliases]. @@ -37,7 +37,7 @@ If you loaded your own data, follow these steps to create a data view. . Click *Create data view*. [role="screenshot"] -image:management/index-patterns/images/create-index-pattern.png["Create data view"] +image:management/index-patterns/images/create-data-view.png["Create data view"] . Start typing in the *name* field, and {kib} looks for the names of indices, data streams, and aliases that match your input. @@ -87,11 +87,12 @@ For an example, refer to <: +: ``` To query {ls} indices across two {es} clusters diff --git a/docs/concepts/index.asciidoc b/docs/concepts/index.asciidoc index eac26beee1f9..457251e62ae8 100644 --- a/docs/concepts/index.asciidoc +++ b/docs/concepts/index.asciidoc @@ -40,8 +40,6 @@ image:concepts/images/global-search.png["Global search showing matches to apps a {kib} requires a data view to tell it which {es} data you want to access, and whether the data is time-based. A data view can point to one or more {es} data streams, indices, or index aliases by name. -For example, `logs-elasticsearch-prod-*` is an index pattern, -and it is time-based with a time field of `@timestamp`. The time field is not editable. Data views are typically created by an administrator when sending data to {es}. You can <> in *Stack Management*, or by using a script @@ -129,8 +127,7 @@ Previously, {kib} used the {ref}/search-aggregations-bucket-terms-aggregation.ht Structured filters are a more interactive way to create {es} queries, and are commonly used when building dashboards that are shared by multiple analysts. Each filter can be disabled, inverted, or pinned across all apps. -The structured filters are the only way to use the {es} Query DSL in JSON form, -or to target a specific index pattern for filtering. Each of the structured +Each of the structured filters is combined with AND logic on the rest of the query. [role="screenshot"] diff --git a/docs/concepts/save-query.asciidoc b/docs/concepts/save-query.asciidoc index 61113b5491c2..54137d1f9f2c 100644 --- a/docs/concepts/save-query.asciidoc +++ b/docs/concepts/save-query.asciidoc @@ -17,7 +17,7 @@ image:concepts/images/saved-query.png["Example of the saved query management pop Saved queries are different than <>, which include the *Discover* configuration—selected columns in the document table, sort order, and -index pattern—in addition to the query. +{data-source}—in addition to the query. Saved searches are primarily used for adding search results to a dashboard. [role="xpack"] diff --git a/docs/concepts/set-time-filter.asciidoc b/docs/concepts/set-time-filter.asciidoc index 116bcd6f91f7..b379c0ac279e 100644 --- a/docs/concepts/set-time-filter.asciidoc +++ b/docs/concepts/set-time-filter.asciidoc @@ -2,7 +2,7 @@ === Set the time range Display data within a specified time range when your index contains time-based events, and a time-field is configured for the -selected <>. +selected <>. The default time range is 15 minutes, but you can customize it in <>. diff --git a/docs/developer/architecture/core/saved-objects-service.asciidoc b/docs/developer/architecture/core/saved-objects-service.asciidoc index a7ce86ea4635..54a5c319c622 100644 --- a/docs/developer/architecture/core/saved-objects-service.asciidoc +++ b/docs/developer/architecture/core/saved-objects-service.asciidoc @@ -259,6 +259,9 @@ upgrade. In most scenarios, it is better to fail an upgrade than to silently ignore a corrupt document which can cause unexpected behaviour at some future point in time. +WARNING: Do not attempt to change the `migrationVersion`, `id`, or `type` fields +within a migration function, this is not supported. + It is critical that you have extensive tests to ensure that migrations behave as expected with all possible input documents. Given how simple it is to test all the branch conditions in a migration function and the high impact of a bug diff --git a/docs/developer/contributing/development-accessibility-tests.asciidoc b/docs/developer/contributing/development-accessibility-tests.asciidoc index 584d779bc7de..2fe2682a3e36 100644 --- a/docs/developer/contributing/development-accessibility-tests.asciidoc +++ b/docs/developer/contributing/development-accessibility-tests.asciidoc @@ -90,7 +90,7 @@ Failures can seem confusing if you've never seen one before. Here is a breakdown [aria-hidden-focus]: Ensures aria-hidden elements do not contain focusable elements Help: https://dequeuniversity.com/rules/axe/3.5/aria-hidden-focus?application=axeAPI Elements: - - #example + - at Accessibility.testAxeReport (test/accessibility/services/a11y/a11y.ts:90:15) at Accessibility.testAppSnapshot (test/accessibility/services/a11y/a11y.ts:58:18) at process._tickCallback (internal/process/next_tick.js:68:7) @@ -100,5 +100,5 @@ Failures can seem confusing if you've never seen one before. Here is a breakdown * "Dashboard" and "create dashboard button" are the names of the test suite and specific test that failed. * Always in brackets, "[aria-hidden-focus]" is the name of the axe rule that failed, followed by a short description. * "Help: " links to the axe documentation for that rule, including severity, remediation tips, and good and bad code examples. -* "Elements:" points to where in the DOM the failure originated (using CSS selector syntax). In this example, the problem came from an element with the ID `example`. If the selector is too complicated to find the source of the problem, use the browser plugins mentioned earlier to locate it. If you have a general idea where the issue is coming from, you can also try adding unique IDs to the page to narrow down the location. +* "Elements:" points to where in the DOM the failure originated (using HTML syntax). In this example, the problem came from a span with the `aria-hidden="true"` attribute and a nested `