Merge branch 'master' into actions/implement-generics

docs/user/introduction.asciidoc

@@ -4,9 +4,9 @@
 <titleabbrev>What is Kibana?</titleabbrev>
 ++++
 
-**_Explore and visualize your data and manage all things Elastic Stack._**
+**_Visualize and analyze your data and manage all things Elastic Stack._**
 
-Whether you’re a user or admin, {kib} makes your data actionable by providing
+Whether you’re an analyst or an admin, {kib} makes your data actionable by providing
 three key functions. Kibana is:
 
 * **An open-source analytics and visualization platform.**
@@ -24,20 +24,20 @@ image::images/intro-kibana.png[]
 
 [float]
 [[get-data-into-kibana]]
-=== Getting data into {kib}
+=== Add data
 
 {kib} is designed to use {es} as a data source. Think of Elasticsearch as the engine that stores
 and processes the data, with {kib} sitting on top.
 
-From the home page, {kib} provides these options for getting data in:
+From the home page, {kib} provides these options for adding data:
 
+* Import data using the
+https://www.elastic.co/blog/importing-csv-and-log-data-into-elasticsearch-with-file-data-visualizer[File Data visualizer].
 * Set up a data flow to Elasticsearch using our built-in tutorials.
-(If a tutorial doesn’t exist for your data, go to the
+If a tutorial doesn’t exist for your data, go to the
 {beats-ref}/beats-reference.html[Beats overview] to learn about other data shippers
-in the {beats} family.)
+in the {beats} family.
 * <<add-sample-data, Add a sample data set>> and take {kib} for a test drive without loading data yourself.
-* Import static data using the
-https://www.elastic.co/blog/importing-csv-and-log-data-into-elasticsearch-with-file-data-visualizer[file upload feature].
 * Index your data into Elasticsearch with {ref}/getting-started-index.html[REST APIs]
  or https://www.elastic.co/guide/en/elasticsearch/client/index.html[client libraries].
 +
@@ -47,9 +47,9 @@ image::images/intro-data-tutorial.png[Ways to get data in from the home page]
 
 {kib} uses an
 <<index-patterns, index pattern>> to tell it which {es} indices to explore.
-If you add sample data or run a built-in tutorial, you get an index pattern for free,
+If you add upload a file, run a built-in tutorial, or add sample data, you get an index pattern for free,
 and are good to start exploring. If you load your own data, you can create
-an index pattern in <<management, Management>>.
+an index pattern in <<management, Stack Management>>.
 
 [float]
 [[explore-and-query]]
@@ -84,22 +84,22 @@ image::images/intro-dashboard.png[]
 {kib} also offers these visualization features:
 
 * <<visualize, Visualize>> allows you to display your data in
-line charts, bar graphs, pie charts, histograms, and tables
-(just to name a few). It's also home to Lens, the drag-and-drop interface.
+charts, graphs, and tables
+(just to name a few). It's also home to Lens.
 Visualize supports the ability to add interactive
-controls to your dashboard, and filter dashboard content in real time.
+controls to your dashboard, filter dashboard content in real time, and add your own images and logos for your brand.
 
 * <<canvas, Canvas>> gives you the ability to present your data in a
 visually compelling, pixel-perfect report. Give your data the “wow” factor
-needed to impress your CEO or to captivate people with a big-screen display.
+needed to impress your CEO or to captivate coworkers with a big-screen display.
 
 * <<maps, Maps>> enables you to ask (and answer) meaningful
 questions of your location-based data. Maps supports multiple
 layers and data sources, mapping of individual geo points and shapes,
 and dynamic client-side styling.
 
 * <<TSVB, TSVB>> allows you to combine
-an infinite number of aggregations to display complex data in a meaningful way.
+an infinite number of aggregations to display complex data.
 With TSVB, you can analyze multiple index patterns and customize
 every aspect of your visualization. Choose your own date format and color
 gradients, and easily switch your data view between time series, metric,
@@ -129,7 +129,7 @@ dashboards in one space, but full access to all of Kibana’s features in anothe
 [[manage-all-things-stack]]
 === Manage all things Elastic Stack
 
-<<management, Management>> provides guided processes for managing all
+<<management, Stack Management>> provides guided processes for managing all
 things Elastic Stack &mdash; indices, clusters, licenses, UI settings, index patterns,
 and more. Want to update your {es} indices? Set user roles and privileges?
 Turn on dark mode? Kibana has UIs for all that.
@@ -162,4 +162,5 @@ You can also <<install, install {kib} on your own>> &mdash; no code, no addi
 infrastructure required.
 
 Our <<tutorial-build-dashboard, Getting Started>> and in-product guidance can
-help you get up and running, faster. Use our Help menu if you have questions or feedback.
+help you get up and running, faster. Click the help icon image:images/intro-help-icon.png[]
+in the top navigation bar for help with questions or to provide feedback.

src/core/MIGRATION_EXAMPLES.md

@@ -27,6 +27,10 @@ APIs to their New Platform equivalents.
     - [Changes in structure compared to legacy](#changes-in-structure-compared-to-legacy)
     - [Remarks](#remarks)
   - [UiSettings](#uisettings)
+  - [Elasticsearch client](#elasticsearch-client)
+    - [Client API Changes](#client-api-changes)
+    - [Accessing the client from a route handler](#accessing-the-client-from-a-route-handler)
+    - [Creating a custom client](#creating-a-custom-client)
 
 ## Configuration
 
@@ -1003,4 +1007,259 @@ setup(core: CoreSetup){
     },
   })
 }
-```
+```
+
+## Elasticsearch client
+
+The new elasticsearch client is a thin wrapper around `@elastic/elasticsearch`'s `Client` class. Even if the API
+is quite close to the legacy client Kibana was previously using, there are some subtle changes to take into account 
+during migration.
+
+[Official documentation](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/index.html) 
+
+### Client API Changes
+
+The most significant changes for the consumers are the following:
+
+- internal / current user client accessors has been renamed and are now properties instead of functions
+  - `callAsInternalUser('ping')` -> `asInternalUser.ping()`
+  - `callAsCurrentUser('ping')` -> `asCurrentUser.ping()`
+
+- the API now reflects the `Client`'s instead of leveraging the string-based endpoint names the `LegacyAPICaller` was using
+
+before:
+
+```ts
+const body = await client.callAsInternalUser('indices.get', { index: 'id' });
+```
+
+after:
+
+```ts
+const { body } = await client.asInternalUser.indices.get({ index: 'id' });
+```
+
+- calling any ES endpoint now returns the whole response object instead of only the body payload
+
+before:
+
+```ts
+const body = await legacyClient.callAsInternalUser('get', { id: 'id' });
+```
+
+after:
+
+```ts
+const { body } = await client.asInternalUser.get({ id: 'id' });
+```
+
+Note that more information from the ES response is available:
+
+```ts
+const {
+  body,        // response payload
+  statusCode,  // http status code of the response
+  headers,     // response headers
+  warnings,    // warnings returned from ES
+  meta         // meta information about the request, such as request parameters, number of attempts and so on
+} = await client.asInternalUser.get({ id: 'id' });
+```
+
+- all API methods are now generic to allow specifying the response body type
+
+before:
+
+```ts
+const body: GetResponse = await legacyClient.callAsInternalUser('get', { id: 'id' });
+```
+
+after:
+
+```ts
+// body is of type `GetResponse`
+const { body } = await client.asInternalUser.get<GetResponse>({ id: 'id' });
+// fallback to `Record<string, any>` if unspecified
+const { body } = await client.asInternalUser.get({ id: 'id' });
+```
+
+- the returned error types changed 
+
+There are no longer specific errors for every HTTP status code (such as `BadRequest` or `NotFound`). A generic
+`ResponseError` with the specific `statusCode` is thrown instead.
+
+before:
+
+```ts
+import { errors } from 'elasticsearch';
+try {
+  await legacyClient.callAsInternalUser('ping');
+} catch(e) {
+  if(e instanceof errors.NotFound) {
+    // do something
+  }
+}
+``` 
+
+after:
+
+```ts
+import { errors } from '@elastic/elasticsearch';
+try {
+  await client.asInternalUser.ping();
+} catch(e) {
+  if(e instanceof errors.ResponseError && e.statusCode === 404) {
+    // do something
+  }
+  // also possible, as all errors got a name property with the name of the class,
+  // so this slightly better in term of performances
+  if(e.name === 'ResponseError' && e.statusCode === 404) {
+    // do something
+  }
+}
+```
+
+- the parameter property names changed from camelCase to snake_case
+
+Even if technically, the javascript client accepts both formats, the typescript definitions are only defining the snake_case
+properties.
+
+before:
+
+```ts
+legacyClient.callAsCurrentUser('get', {
+  id: 'id',
+  storedFields: ['some', 'fields'],
+})
+```
+
+after:
+
+```ts
+client.asCurrentUser.get({
+  id: 'id',
+  stored_fields: ['some', 'fields'],
+})
+```
+
+- the request abortion API changed
+
+All promises returned from the client API calls now have an `abort` method that can be used to cancel the request.
+
+before:
+
+```ts
+const controller = new AbortController();
+legacyClient.callAsCurrentUser('ping', {}, {
+  signal: controller.signal,
+})
+// later
+controller.abort();
+```
+
+after:
+
+```ts
+const request = client.asCurrentUser.ping();
+// later
+request.abort();
+```
+
+- it is now possible to override headers when performing specific API calls.
+
+Note that doing so is strongly discouraged due to potential side effects with the ES service internal
+behavior when scoping as the internal or as the current user.
+
+```ts
+const request = client.asCurrentUser.ping({}, { 
+  headers: {
+    authorization: 'foo',
+    custom: 'bar',
+  }
+});
+```
+
+Please refer to the  [Breaking changes list](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/breaking-changes.html)
+for more information about the changes between the legacy and new client.
+
+### Accessing the client from a route handler
+
+Apart from the API format change, accessing the client from within a route handler
+did not change. As it was done for the legacy client, a preconfigured scoped client 
+bound to the request is accessible using `core` context provider:
+
+before:
+
+```ts
+router.get(
+  {
+    path: '/my-route',
+  },
+  async (context, req, res) => {
+    const { client } = context.core.elasticsearch.legacy;
+    // call as current user
+    const res = await client.callAsCurrentUser('ping');
+    // call as internal user
+    const res2 = await client.callAsInternalUser('search', options);
+    return res.ok({ body: 'ok' });
+  }
+);
+```
+
+after:
+
+```ts
+router.get(
+  {
+    path: '/my-route',
+  },
+  async (context, req, res) => {
+    const { client } = context.core.elasticsearch;
+    // call as current user
+    const res = await client.asCurrentUser.ping();
+    // call as internal user
+    const res2 = await client.asInternalUser.search(options);
+    return res.ok({ body: 'ok' });
+  }
+);
+```
+
+### Creating a custom client
+
+Note that the `plugins` option is now longer available on the new client. As the API is now exhaustive, adding custom
+endpoints using plugins should no longer be necessary.
+
+The API to create custom clients did not change much:
+
+before:
+
+```ts
+const customClient = coreStart.elasticsearch.legacy.createClient('my-custom-client', customConfig);
+// do something with the client, such as
+await customClient.callAsInternalUser('ping');
+// custom client are closable
+customClient.close();
+```
+
+after:
+
+```ts
+const customClient = coreStart.elasticsearch.createClient('my-custom-client', customConfig);
+// do something with the client, such as
+await customClient.asInternalUser.ping();
+// custom client are closable
+customClient.close();
+```
+
+If, for any reasons, one still needs to reach an endpoint not listed on the client API, using `request.transport` 
+is still possible:
+
+```ts
+const { body } = await client.asCurrentUser.transport.request({
+  method: 'get',
+  path: '/my-custom-endpoint',
+  body: { my: 'payload'},
+  querystring: { param: 'foo' }
+})
+```
+
+Remark: the new client creation API is now only available from the `start` contract of the elasticsearch service.

x-pack/plugins/alerting_builtins/server/alert_types/index_threshold/lib/date_range_info.test.ts

@@ -132,10 +132,11 @@ describe('getRangeInfo', () => {
   it('should handle no dateStart, dateEnd or interval specified', async () => {
     const nowM0 = Date.now();
     const nowM5 = nowM0 - 1000 * 60 * 5;
+    const digitPrecision = 1;
 
     const info = getDateRangeInfo(BaseRangeQuery);
-    expect(sloppyMilliDiff(nowM5, Date.parse(info.dateStart))).toBeCloseTo(0);
-    expect(sloppyMilliDiff(nowM0, Date.parse(info.dateEnd))).toBeCloseTo(0);
+    expect(sloppyMilliDiff(nowM5, Date.parse(info.dateStart))).toBeCloseTo(0, digitPrecision);
+    expect(sloppyMilliDiff(nowM0, Date.parse(info.dateEnd))).toBeCloseTo(0, digitPrecision);
     expect(info.dateRanges.length).toEqual(1);
     expect(info.dateRanges[0].from).toEqual(info.dateStart);
     expect(info.dateRanges[0].to).toEqual(info.dateEnd);