Skip to content

Commit

Permalink
Merge branch 'master' into actions/implement-generics
Browse files Browse the repository at this point in the history
  • Loading branch information
elasticmachine authored Jul 22, 2020
2 parents 35f95f0 + fe5b4b8 commit 418af31
Show file tree
Hide file tree
Showing 14 changed files with 499 additions and 42 deletions.
35 changes: 18 additions & 17 deletions docs/user/introduction.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.**
Expand All @@ -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].
+
Expand All @@ -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]]
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Binary file modified docs/user/introduction/images/intro-data-tutorial.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/user/introduction/images/intro-help-icon.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/user/introduction/images/intro-kibana.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/user/introduction/images/intro-management.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
261 changes: 260 additions & 1 deletion src/core/MIGRATION_EXAMPLES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit 418af31

Please sign in to comment.