-
Notifications
You must be signed in to change notification settings - Fork 8.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'elastic:master' into cleanup-package
- Loading branch information
Showing
1,167 changed files
with
23,075 additions
and
7,944 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Validating CODEOWNERS rules …
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Large diffs are not rendered by default.
Oops, something went wrong.
Large diffs are not rendered by default.
Oops, something went wrong.
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| --- | ||
| id: kibDevDocsPersistableStateIntro | ||
| slug: /kibana-dev-docs/persistable-state-intro | ||
| title: Persistable State | ||
| summary: Persitable state is a key concept to understand when building a Kibana plugin. | ||
| date: 2021-02-02 | ||
| tags: ['kibana','dev', 'contributor', 'api docs'] | ||
| --- | ||
|
|
||
| “Persistable state” is developer-defined state that supports being persisted by a plugin other than the one defining it. Persistable State needs to be serializable and the owner can/should provide utilities to migrate it, extract and inject any <DocLink id="kibDevDocsSavedObjectsIntro" section="references" text="references to Saved Objects"/> it may contain, as well as telemetry collection utilities. | ||
|
|
||
| ## Exposing state that can be persisted | ||
|
|
||
| Any plugin that exposes state that another plugin might persist should implement <DocLink id="kibKibanaUtilsPluginApi" section="def-common.PersistableStateService" text="`PersistableStateService`"/> interface on their `setup` contract. This will allow plugins persisting the state to easily access migrations and other utilities. | ||
|
|
||
| Example: Data plugin allows you to generate filters. Those filters can be persisted by applications in their saved | ||
| objects or in the URL. In order to allow apps to migrate the filters in case the structure changes in the future, the Data plugin implements `PersistableStateService` on <DocLink id="kibDataQueryPluginApi" section="def-public.FilterManager" text="`data.query.filterManager`"/>. | ||
|
|
||
| note: There is currently no obvious way for a plugin to know which state is safe to persist. The developer must manually look for a matching `PersistableStateService`, or ad-hoc provided migration utilities (as is the case with Rule Type Parameters). | ||
| In the future, we hope to make it easier for producers of state to understand when they need to write a migration with changes, and also make it easier for consumers of such state, to understand whether it is safe to persist. | ||
|
|
||
| ## Exposing state that can be persisted but is not owned by plugin exposing it (registry) | ||
|
|
||
| Any plugin that owns collection of items (registry) whose state/configuration can be persisted should implement `PersistableStateService` | ||
| interface on their `setup` contract and each item in the collection should implement <DocLink id="kibKibanaUtilsPluginApi" section="def-common.PersistableStateDefinition" text="`PersistableStateDefinition`"/> interface. | ||
|
|
||
| Example: Embeddable plugin owns the registry of embeddable factories to which other plugins can register new embeddable factories. Dashboard plugin | ||
| stores a bunch of embeddable panels input in its saved object and URL. Embeddable plugin setup contract implements `PersistableStateService` | ||
| interface and each `EmbeddableFactory` needs to implement `PersistableStateDefinition` interface. | ||
|
|
||
| Embeddable plugin exposes this interfaces: | ||
| ``` | ||
| // EmbeddableInput implements Serializable | ||
| export interface EmbeddableRegistryDefinition extends PersistableStateDefinition<EmbeddableInput> { | ||
| id: string; | ||
| ... | ||
| } | ||
| export interface EmbeddableSetup extends PersistableStateService<EmbeddableInput>; | ||
| ``` | ||
|
|
||
| Note: if your plugin doesn't expose the state (it is the only one storing state), the plugin doesn't need to implement the `PersistableStateService` interface. | ||
| If the state your plugin is storing can be provided by other plugins (your plugin owns a registry) items in that registry still need to implement `PersistableStateDefinition` interface. | ||
|
|
||
| ## Storing persistable state as part of saved object | ||
|
|
||
| Any plugin that stores any persistable state as part of their saved object should make sure that its saved object migration | ||
| and reference extraction and injection methods correctly use the matching `PersistableStateService` implementation for the state they are storing. | ||
|
|
||
| Take a look at [example saved object](https://github.com/elastic/kibana/blob/master/examples/embeddable_examples/server/searchable_list_saved_object.ts#L32) which stores an embeddable state. Note how the `migrations`, `extractReferences` and `injectReferences` are defined. | ||
|
|
||
| ## Storing persistable state as part of URL | ||
|
|
||
| When storing persistable state as part of URL you must make sure your URL is versioned. When loading the state `migrateToLatest` method | ||
| of `PersistableStateService` should be called, which will migrate the state from its original version to latest. | ||
|
|
||
| note: Currently there is no recommended way on how to store version in url and its up to every application to decide on how to implement that. | ||
|
|
||
| ## Available state operations | ||
|
|
||
| ### Extraction/Injection of References | ||
|
|
||
| In order to support import and export, and space-sharing capabilities, Saved Objects need to explicitly list any references they contain to other Saved Objects. | ||
| To support persisting your state in saved objects owned by another plugin, the <DocLink id="kibKibanaUtilsPluginApi" section="def-common.PersistableState.extract" text="`extract`"/> and <DocLink id="kibKibanaUtilsPluginApi" section="def-common.PersistableState.inject" text="`inject`"/> methods of Persistable State interface should be implemented. | ||
|
|
||
| <DocLink id="kibDevTutorialSavedObject" section="references" text="Learn how to define Saved Object references"/> | ||
|
|
||
| [See example embeddable providing extract/inject functions](https://github.com/elastic/kibana/blob/master/examples/embeddable_examples/public/migrations/migrations_embeddable_factory.ts) | ||
|
|
||
| ### Migrations and Backward compatibility | ||
|
|
||
| As your plugin evolves, you may need to change your state in a breaking way. If that happens, you should write a migration to upgrade the state that existed prior to the change. | ||
|
|
||
| <DocLink id="kibDevTutorialSavedObject" section="migrations" text="How to write a migration"/>. | ||
|
|
||
| [See an example saved object storing embeddable state implementing saved object migration function](https://github.com/elastic/kibana/blob/master/examples/embeddable_examples/server/searchable_list_saved_object.ts) | ||
|
|
||
| [See example embeddable providing migration functions](https://github.com/elastic/kibana/blob/master/examples/embeddable_examples/public/migrations/migrations_embeddable_factory.ts) | ||
|
|
||
| ## Telemetry | ||
|
|
||
| You might want to collect statistics about how your state is used. If that is the case you should implement the telemetry method of Persistable State interface. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| [[machine-learning-api]] | ||
| == {ml-cap} APIs | ||
|
|
||
| //Manage {kib} saved objects, including dashboards, visualizations, and more. | ||
|
|
||
| The following {ml} API is available: | ||
|
|
||
| * <<machine-learning-api-sync, Sync API>> | ||
| //to retrieve a single {kib} saved object by ID | ||
|
|
||
| include::machine-learning/sync.asciidoc[] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,79 @@ | ||
| [[machine-learning-api-sync]] | ||
| === Sync {ml} saved objects API | ||
| ++++ | ||
| <titleabbrev>Sync {ml} saved objects</titleabbrev> | ||
| ++++ | ||
|
|
||
| Synchronizes {kib} saved objects for {ml} jobs. | ||
|
|
||
| [[machine-learning-api-sync-request]] | ||
| ==== Request | ||
|
|
||
| `GET <kibana host>:<port>/api/ml/saved_objects/sync` | ||
|
|
||
| `GET <kibana host>:<port>/s/<space_id>/api/ml/saved_objects/sync` | ||
|
|
||
|
|
||
| [[machine-learning-api-sync-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. | ||
|
|
||
| [[machine-learning-api-sync-query-params]] | ||
| ==== Query parameters | ||
|
|
||
| `simulate`:: | ||
| (Optional, boolean) When `true`, simulates the synchronization by only returning | ||
| the list actions that _would_ be performed. | ||
|
|
||
| [[machine-learning-api-sync-response-body]] | ||
| ==== Response body | ||
|
|
||
| `datafeedsAdded`:: | ||
| (array) If a saved object for an {anomaly-job} is missing a {dfeed} identifier, | ||
| it is added. This list contains the {dfeed} identifiers and indicates whether | ||
| the synchronization was successful. | ||
|
|
||
| `datafeedsRemoved`:: | ||
| (array) If saved objects exist for {dfeeds} that no longer exist, they are | ||
| deleted. This list contains the {dfeed} identifiers and indicates whether the | ||
| synchronization was successful. | ||
|
|
||
| `savedObjectsCreated`:: | ||
| (array) If saved objects are missing for {ml} jobs, they are created. This | ||
| list contains the job identifiers and indicates whether the synchronization was | ||
| successful. | ||
|
|
||
| `savedObjectsDeleted`:: | ||
| (array) If saved objects exist for jobs that no longer exist, they are deleted. | ||
| This list contains the job identifiers and indicates whether the synchronization | ||
| was successful. | ||
|
|
||
| [[machine-learning-api-sync-codes]] | ||
| ==== Response code | ||
|
|
||
| `200`:: | ||
| Indicates a successful call. | ||
|
|
||
| [[machine-learning-api-sync-example]] | ||
| ==== Example | ||
|
|
||
| Retrieve the list of {ml} saved objects that require synchronization: | ||
|
|
||
| [source,sh] | ||
| -------------------------------------------------- | ||
| $ curl -X GET api/ml/saved_objects/sync?simulate=true | ||
| -------------------------------------------------- | ||
| // KIBANA | ||
|
|
||
| If there are two jobs and a {dfeed} that need to be synchronized, for example, | ||
| the API returns the following: | ||
|
|
||
| [source,sh] | ||
| -------------------------------------------------- | ||
| {{"savedObjectsCreated":{"myjob1":{"success":true},"myjob2":{"success":true}},"savedObjectsDeleted":{},"datafeedsAdded":{},"datafeedsRemoved":{"myfeed3":{"success":true}}} | ||
| -------------------------------------------------- | ||
|
|
||
| To perform the synchronization, re-run the API and omit the `simulate` parameter. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.