From c9673e415316d31fe77a2434f19d319203497eb2 Mon Sep 17 00:00:00 2001 From: Stacey Gammon Date: Mon, 4 Oct 2021 20:43:23 -0400 Subject: [PATCH] Update doc slugs to improve analytic tracking, move to appropriate folders (#113630) (#113862) * Update the slugs to improve google analytics drilldown tracking * more slug updates * Fix some formatting issues in building blocks * update paths Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com> # Conflicts: # dev_docs/key_concepts/persistable_state.mdx # legacy_rfcs/README.md --- CONTRIBUTING.md | 2 +- STYLEGUIDE.mdx | 2 +- dev_docs/api_welcome.mdx | 2 +- .../{ => contributing}/best_practices.mdx | 2 +- .../{ => contributing}/dev_principles.mdx | 8 +- dev_docs/contributing/how_we_use_github.mdx | 2 +- dev_docs/getting_started/add_data.mdx | 2 +- dev_docs/getting_started/dev_welcome.mdx | 2 +- .../getting_started/hello_world_plugin.mdx | 2 +- .../setting_up_a_development_env.mdx | 2 +- .../{ => getting_started}/troubleshooting.mdx | 2 +- dev_docs/key_concepts/anatomy_of_a_plugin.mdx | 2 +- .../{ => key_concepts}/building_blocks.mdx | 96 +++++---- dev_docs/key_concepts/data_views.mdx | 11 +- .../kibana_platform_plugin_intro.mdx | 2 +- dev_docs/key_concepts/performance.mdx | 20 +- dev_docs/key_concepts/persistable_state.mdx | 29 +-- dev_docs/key_concepts/saved_objects.mdx | 39 ++-- .../building_a_kibana_distributable.mdx | 2 +- dev_docs/tutorials/data/search.mdx | 192 +++++++++--------- dev_docs/tutorials/debugging.mdx | 6 +- dev_docs/tutorials/saved_objects.mdx | 2 +- dev_docs/tutorials/submit_a_pull_request.mdx | 2 +- dev_docs/tutorials/testing_plugins.mdx | 2 +- src/plugins/data/README.mdx | 2 +- src/plugins/usage_collection/README.mdx | 2 +- 26 files changed, 219 insertions(+), 218 deletions(-) rename dev_docs/{ => contributing}/best_practices.mdx (99%) rename dev_docs/{ => contributing}/dev_principles.mdx (98%) rename dev_docs/{ => getting_started}/troubleshooting.mdx (94%) rename dev_docs/{ => key_concepts}/building_blocks.mdx (51%) rename dev_docs/{ => key_concepts}/kibana_platform_plugin_intro.mdx (99%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 14dfaa84cebb..8a19562eaff4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,5 @@ # Contributing to Kibana -If you are an employee at Elastic, please check out our Developer Guide [here](https://docs.elastic.dev/kibana-dev-docs/welcome). +If you are an employee at Elastic, please check out our Developer Guide [here](https://docs.elastic.dev/kibana-dev-docs/getting-started/welcome). If you are an external developer, we have a legacy developer guide [here](https://www.elastic.co/guide/en/kibana/master/development.html), or you can view the raw docs from our new, internal Developer Guide [here](./dev_docs/getting_started/dev_welcome.mdx). Eventually, our internal Developer Guide will be opened for public consumption. diff --git a/STYLEGUIDE.mdx b/STYLEGUIDE.mdx index afe00476640b..01d2734744e8 100644 --- a/STYLEGUIDE.mdx +++ b/STYLEGUIDE.mdx @@ -1,6 +1,6 @@ --- id: kibStyleGuide -slug: /kibana-dev-docs/styleguide +slug: /kibana-dev-docs/contributing/styleguide title: Style Guide summary: JavaScript/TypeScript styleguide. date: 2021-05-06 diff --git a/dev_docs/api_welcome.mdx b/dev_docs/api_welcome.mdx index be9281113b3d..00d5bfb9644a 100644 --- a/dev_docs/api_welcome.mdx +++ b/dev_docs/api_welcome.mdx @@ -1,6 +1,6 @@ --- id: kibDevDocsApiWelcome -slug: /kibana-dev-docs/api-welcome +slug: /kibana-dev-docs/api-meta/welcome title: Welcome summary: How to use our automatically generated API documentation date: 2021-02-25 diff --git a/dev_docs/best_practices.mdx b/dev_docs/contributing/best_practices.mdx similarity index 99% rename from dev_docs/best_practices.mdx rename to dev_docs/contributing/best_practices.mdx index 0f012d26d94a..d740ee307dac 100644 --- a/dev_docs/best_practices.mdx +++ b/dev_docs/contributing/best_practices.mdx @@ -1,6 +1,6 @@ --- id: kibBestPractices -slug: /kibana-dev-docs/best-practices +slug: /kibana-dev-docs/contributing/best-practices title: Best practices summary: Best practices to follow when building a Kibana plugin. date: 2021-03-17 diff --git a/dev_docs/dev_principles.mdx b/dev_docs/contributing/dev_principles.mdx similarity index 98% rename from dev_docs/dev_principles.mdx rename to dev_docs/contributing/dev_principles.mdx index 4b238ea24f69..0b8f68d23236 100644 --- a/dev_docs/dev_principles.mdx +++ b/dev_docs/contributing/dev_principles.mdx @@ -1,10 +1,10 @@ --- id: kibDevPrinciples -slug: /kibana-dev-docs/dev-principles +slug: /kibana-dev-docs/contributing/dev-principles title: Developer principles -summary: Follow our development principles to help keep our code base stable, maintainable and scalable. +summary: Follow our development principles to help keep our code base stable, maintainable and scalable. date: 2021-03-04 -tags: ['kibana','onboarding', 'dev', 'architecture'] +tags: ['kibana', 'onboarding', 'dev', 'architecture'] --- Over time, the Kibana project has been shaped by certain principles. Like Kibana itself, some of these principles were formed by intention while others were the result of evolution and circumstance, but today all are important for the continued success and maintainability of Kibana. @@ -117,4 +117,4 @@ The primary consumers of the code we write, the APIs that we create, and the fea Features that we anticipate end users, admins, and plugin developers consuming should be documented through our official docs, but module-level READMEs and code comments are also appropriate. -Documentation is critical part of developing features and code, so an undocumented feature is an incomplete feature. \ No newline at end of file +Documentation is critical part of developing features and code, so an undocumented feature is an incomplete feature. diff --git a/dev_docs/contributing/how_we_use_github.mdx b/dev_docs/contributing/how_we_use_github.mdx index f18bcbcf556f..ff7901fdf08d 100644 --- a/dev_docs/contributing/how_we_use_github.mdx +++ b/dev_docs/contributing/how_we_use_github.mdx @@ -1,6 +1,6 @@ --- id: kibGitHub -slug: /kibana-dev-docs/github +slug: /kibana-dev-docs/contributing/github title: How we use Github summary: Forking, branching, committing and using labels in the Kibana GitHub repo date: 2021-09-16 diff --git a/dev_docs/getting_started/add_data.mdx b/dev_docs/getting_started/add_data.mdx index b09e3f6262e7..46822b82fc40 100644 --- a/dev_docs/getting_started/add_data.mdx +++ b/dev_docs/getting_started/add_data.mdx @@ -1,6 +1,6 @@ --- id: kibDevAddData -slug: /kibana-dev-docs/tutorial/sample-data +slug: /kibana-dev-docs/getting-started/sample-data title: Add data summary: Learn how to add data to Kibana date: 2021-08-11 diff --git a/dev_docs/getting_started/dev_welcome.mdx b/dev_docs/getting_started/dev_welcome.mdx index 5e569bd377ee..4080e0850b94 100644 --- a/dev_docs/getting_started/dev_welcome.mdx +++ b/dev_docs/getting_started/dev_welcome.mdx @@ -1,6 +1,6 @@ --- id: kibDevDocsWelcome -slug: /kibana-dev-docs/welcome +slug: /kibana-dev-docs/getting-started/welcome title: Welcome summary: Build custom solutions and applications on top of Kibana. date: 2021-01-02 diff --git a/dev_docs/getting_started/hello_world_plugin.mdx b/dev_docs/getting_started/hello_world_plugin.mdx index 7c02d2807472..b95d0cac201f 100644 --- a/dev_docs/getting_started/hello_world_plugin.mdx +++ b/dev_docs/getting_started/hello_world_plugin.mdx @@ -1,6 +1,6 @@ --- id: kibHelloWorldApp -slug: /kibana-dev-docs/hello-world-app +slug: /kibana-dev-docs/getting-started/hello-world-app title: Hello World summary: Build a very basic plugin that registers an application that says "Hello World!". date: 2021-08-03 diff --git a/dev_docs/getting_started/setting_up_a_development_env.mdx b/dev_docs/getting_started/setting_up_a_development_env.mdx index 04e0511e255b..4338083b1bc8 100644 --- a/dev_docs/getting_started/setting_up_a_development_env.mdx +++ b/dev_docs/getting_started/setting_up_a_development_env.mdx @@ -1,6 +1,6 @@ --- id: kibDevTutorialSetupDevEnv -slug: /kibana-dev-docs/tutorial/setup-dev-env +slug: /kibana-dev-docs/getting-started/setup-dev-env title: Set up a Development Environment summary: Learn how to setup a development environment for contributing to the Kibana repository date: 2021-04-26 diff --git a/dev_docs/troubleshooting.mdx b/dev_docs/getting_started/troubleshooting.mdx similarity index 94% rename from dev_docs/troubleshooting.mdx rename to dev_docs/getting_started/troubleshooting.mdx index f624a8cd7750..e0adfbad86a8 100644 --- a/dev_docs/troubleshooting.mdx +++ b/dev_docs/getting_started/troubleshooting.mdx @@ -1,6 +1,6 @@ --- id: kibTroubleshooting -slug: /kibana-dev-docs/troubleshooting +slug: /kibana-dev-docs/getting-started/troubleshooting title: Troubleshooting summary: A collection of tips for working around strange issues. date: 2021-09-08 diff --git a/dev_docs/key_concepts/anatomy_of_a_plugin.mdx b/dev_docs/key_concepts/anatomy_of_a_plugin.mdx index 6a6f4f8b500a..3e6c391eea14 100644 --- a/dev_docs/key_concepts/anatomy_of_a_plugin.mdx +++ b/dev_docs/key_concepts/anatomy_of_a_plugin.mdx @@ -1,6 +1,6 @@ --- id: kibDevAnatomyOfAPlugin -slug: /kibana-dev-docs/anatomy-of-a-plugin +slug: /kibana-dev-docs/key-concepts/anatomy-of-a-plugin title: Anatomy of a plugin summary: Anatomy of a Kibana plugin. date: 2021-08-03 diff --git a/dev_docs/building_blocks.mdx b/dev_docs/key_concepts/building_blocks.mdx similarity index 51% rename from dev_docs/building_blocks.mdx rename to dev_docs/key_concepts/building_blocks.mdx index 6320a7db4558..da3d0f32780b 100644 --- a/dev_docs/building_blocks.mdx +++ b/dev_docs/key_concepts/building_blocks.mdx @@ -1,26 +1,28 @@ --- id: kibBuildingBlocks -slug: /kibana-dev-docs/building-blocks +slug: /kibana-dev-docs/key-concepts/building-blocks title: Building blocks summary: Consider these building blocks when developing your plugin. date: 2021-02-24 -tags: ['kibana','onboarding', 'dev', 'architecture'] +tags: ['kibana', 'onboarding', 'dev', 'architecture'] --- -When building a plugin in Kibana, there are a handful of architectural "building blocks" you can use. Some of these building blocks are "higher-level", -and some are "lower-level". High-level building blocks come +When building a plugin in Kibana, there are a handful of architectural "building blocks" you can use. Some of these building blocks are "higher-level", +and some are "lower-level". High-level building blocks come with many built-in capabilities, require less maintenance, and evolve new feature sets over time with little to no - impact on consumers. When developers use high-level building blocks, new features are exposed consistently, across all of Kibana, at the same time. - On the downside, they are not as flexible as our low-level building blocks. - - Low-level building blocks - provide greater flexibility, but require more code to stitch them together into a meaningful UX. This results in higher maintenance cost for consumers and greater UI/UX variability - across Kibana. +impact on consumers. When developers use high-level building blocks, new features are exposed consistently, across all of Kibana, at the same time. +On the downside, they are not as flexible as our low-level building blocks. - For example, if an application is using and - , - their application would automatically support runtime fields. If the app is instead using the - lower-level , additional work would be required. +Low-level building blocks +provide greater flexibility, but require more code to stitch them together into a meaningful UX. This results in higher maintenance cost for consumers and greater UI/UX variability +across Kibana. + +For example, if an application is using and , their application would +automatically support runtime fields. If the app is instead using the lower-level , additional work would be required. Armed with this knowledge, you can choose what works best for your use case! @@ -32,23 +34,15 @@ The following high-level building blocks can be rendered directly into your appl ### Query Bar -The provides a high-level Query Bar component that comes with support for Lucene, KQL, Saved Queries, -and . - -If you would like to expose the ability to search and filter on Elasticsearch data, the Query Bar provided by the - - is your go-to building block. +The provides a high-level Query Bar component that comes with support for Lucene, KQL, Saved Queries, +and . If you would like to expose the ability to search and filter on Elasticsearch data, the Query Bar provided by the is your go-to building block. **Github labels**: `Team:AppServices`, `Feature:QueryBar` ### Dashboard Embeddable Add a Dashboard Embeddable directly inside your application to provide users with a set of visualizations and graphs that work seamlessly -with the . Every feature that is added to a registered - -(Lens, Maps, Saved Searches and more) will be available automatically, as well as any - that are - added to the Embeddable context menu panel (for example, drilldowns, custom panel time ranges, and "share to" features). +with the . Every feature that is added to a registered (Lens, Maps, Saved Searches and more) will be available automatically, as well as any that are added to the Embeddable context menu panel (for example, drilldowns, custom panel time ranges, and "share to" features). The Dashboard Embeddable is one of the highest-level UI components you can add to your application. @@ -56,11 +50,7 @@ The Dashboard Embeddable is one of the highest-level UI components you can add t ### Lens Embeddable -Check out the Lens Embeddable if you wish to show users visualizations based on Elasticsearch data without worrying about query building and chart rendering. It's built on top of the - , and integrates with - - and . Using the same configuration, it's also possible to link to - a prefilled Lens editor, allowing the user to drill deeper and explore their data. +Check out the Lens Embeddable if you wish to show users visualizations based on Elasticsearch data without worrying about query building and chart rendering. It's built on top of the , and integrates with and . Using the same configuration, it's also possible to link to a prefilled Lens editor, allowing the user to drill deeper and explore their data. **Github labels**: `Team:VisEditors`, `Feature:Lens` @@ -72,7 +62,7 @@ Check out the Map Embeddable if you wish to embed a map in your application. ### KibanaPageTemplate -All Kibana pages should use KibanaPageTemplate to setup their pages. It's a thin wrapper around [EuiPageTemplate](https://elastic.github.io/eui/#/layout/page) that makes setting up common types of Kibana pages quicker and easier while also adhering to any Kibana-specific requirements. +All Kibana pages should use KibanaPageTemplate to setup their pages. It's a thin wrapper around [EuiPageTemplate](https://elastic.github.io/eui/#/layout/page) that makes setting up common types of Kibana pages quicker and easier while also adhering to any Kibana-specific requirements. Check out for more implementation guidance. @@ -82,10 +72,11 @@ Check out 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, formatting options and custom labels. + 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, +formatting options and custom labels. Index Patterns are used in many other high-level building blocks so we highly recommend you consider this building block for your search needs. @@ -93,18 +84,23 @@ Index Patterns are used in many other high-level building blocks so we highly re ### Search Source - is a high-level search service offered by the -. It requires an -, and abstracts away the raw ES DSL and search endpoint. Internally -it uses the ES . Use Search Source if you need to query data -from Elasticsearch, and you aren't already using one of the high-level UI Components that handles this internally. + is a high-level search service +offered by the . It requires +an , and abstracts away +the raw ES DSL and search endpoint. Internally it uses the ES +. Use Search Source if you need to query data from Elasticsearch, and you aren't already using one of +the high-level UI Components that handles this internally. **Github labels**: `Team:AppServices`, `Feature:Search` ### Search Strategies -Search Strategies are a low-level building block that abstracts away search details, like what REST endpoint is being called. The ES Search Strategy -is a very lightweight abstraction layer that sits just above querying ES with the elasticsearch-js client. Other search stragies are offered for other +Search Strategies are a low-level building block that abstracts away search details, like what REST endpoint is being called. The ES Search Strategy +is a very lightweight abstraction layer that sits just above querying ES with the elasticsearch-js client. Other search stragies are offered for other languages, like EQL and SQL. These are very low-level building blocks so expect a lot of glue work to make these work with the higher-level abstractions. **Github labels**: `Team:AppServices`, `Feature:Search` @@ -112,24 +108,24 @@ languages, like EQL and SQL. These are very low-level building blocks so expect ### Expressions Expressions are a low-level building block that can be used if you have advanced search needs that requiring piping results into additional functionality, like -joining and manipulating data. Lens and Canvas are built on top of Expressions. Most developers should be able to use - or - , rather than need to access the Expression language directly. +joining and manipulating data. Lens and Canvas are built on top of Expressions. Most developers should be able to use or , rather than need to +access the Expression language directly.{' '} **Github labels**: `Team:AppServices`, `Feature:ExpressionLanguage` ## Saved Objects - should be used if you need to persist application-level information. If you were building a TODO -application, each TODO item would be a `Saved Object`. Saved objects come pre-wired with support for bulk export/import, security features like space sharing and -space isolation, and tags. + should be used if you need to persist +application-level information. If you were building a TODO application, each TODO item would be a `Saved +Object`. Saved objects come pre-wired with support for bulk export/import, security features like space +sharing and space isolation, and tags. **Github labels**: `Team:Core`, `Feature:Saved Objects` # Integration building blocks Use the following building blocks to create an inter-connected, cross-application, holistic Kibana experience. These building blocks allow you to expose functionality - that promotes your own application into other applications, as well as help developers of other applications integrate into your app. +that promotes your own application into other applications, as well as help developers of other applications integrate into your app. ## UI Actions & Triggers @@ -141,6 +137,6 @@ application could register a UI Action called "View in Maps" to appear any time ## Embeddables Embeddables help you integrate your application with the Dashboard application. Register your custom UI Widget as an Embeddable and users will -be able to add it as a panel on a Dashboard. With a little extra work, it can also be exposed in Canvas workpads. +be able to add it as a panel on a Dashboard. With a little extra work, it can also be exposed in Canvas workpads. **Github labels**: `Team:AppServices`, `Feature:Embeddables` diff --git a/dev_docs/key_concepts/data_views.mdx b/dev_docs/key_concepts/data_views.mdx index e2b64c8705c4..c514af21c0cf 100644 --- a/dev_docs/key_concepts/data_views.mdx +++ b/dev_docs/key_concepts/data_views.mdx @@ -1,16 +1,16 @@ --- id: kibDataViewsKeyConcepts -slug: /kibana-dev-docs/data-view-intro +slug: /kibana-dev-docs/key-concepts/data-view-intro title: Data Views summary: Data views are the central method of defining queryable data sets in Kibana date: 2021-08-11 -tags: ['kibana','dev', 'contributor', 'api docs'] +tags: ['kibana', 'dev', 'contributor', 'api docs'] --- -*Note: Kibana index patterns are currently being renamed to data views. There will be some naming inconsistencies until the transition is complete.* +_Note: Kibana index patterns are currently being renamed to data views. There will be some naming inconsistencies until the transition is complete._ Data views (formerly Kibana index patterns or KIPs) are the central method of describing sets of indices for queries. Usage is strongly recommended -as a number of high level rely on them. Further, they provide a consistent view of data across +as a number of high level rely on them. Further, they provide a consistent view of data across a variety Kibana apps. Data views are defined by a wildcard string (an index pattern) which matches indices, data streams, and index aliases, optionally specify a @@ -20,8 +20,6 @@ on the data view via runtime fields. Schema-on-read functionality is provided by ![image](../assets/data_view_diagram.png) - - The data view API is made available via the data plugin (`data.indexPatterns`, soon to be renamed) and most commonly used with (`data.search.search.SearchSource`) to perform queries. SearchSource will apply existing filters and queries from the search bar UI. @@ -29,4 +27,3 @@ Users can create data views via [Data view management](https://www.elastic.co/gu Additionally, they can be created through the data view API. Data views also allow formatters and custom labels to be defined for fields. - diff --git a/dev_docs/kibana_platform_plugin_intro.mdx b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx similarity index 99% rename from dev_docs/kibana_platform_plugin_intro.mdx rename to dev_docs/key_concepts/kibana_platform_plugin_intro.mdx index 252a6dcd9cd8..b2255dbc8e5c 100644 --- a/dev_docs/kibana_platform_plugin_intro.mdx +++ b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx @@ -1,6 +1,6 @@ --- id: kibPlatformIntro -slug: /kibana-dev-docs/platform-intro +slug: /kibana-dev-docs/key-concepts/platform-intro title: Plugins and the Kibana platform summary: An introduction to the Kibana platform and how to use it to build a plugin. date: 2021-01-06 diff --git a/dev_docs/key_concepts/performance.mdx b/dev_docs/key_concepts/performance.mdx index 2870262825e4..0201c7774f85 100644 --- a/dev_docs/key_concepts/performance.mdx +++ b/dev_docs/key_concepts/performance.mdx @@ -1,6 +1,6 @@ --- id: kibDevPerformance -slug: /kibana-dev-docs/performance +slug: /kibana-dev-docs/key-concepts/performance title: Performance summary: Performance tips for Kibana development. date: 2021-09-02 @@ -9,13 +9,13 @@ tags: ['kibana', 'onboarding', 'dev', 'performance'] ## Keep Kibana fast -*tl;dr*: Load as much code lazily as possible. Everyone loves snappy +_tl;dr_: Load as much code lazily as possible. Everyone loves snappy applications with a responsive UI and hates spinners. Users deserve the best experience whether they run Kibana locally or in the cloud, regardless of their hardware and environment. There are 2 main aspects of the perceived speed of an application: loading time -and responsiveness to user actions. Kibana loads and bootstraps *all* +and responsiveness to user actions. Kibana loads and bootstraps _all_ the plugins whenever a user lands on any page. It means that every new application affects the overall _loading performance_, as plugin code is loaded _eagerly_ to initialize the plugin and provide plugin API to dependent @@ -60,12 +60,12 @@ export class MyPlugin implements Plugin { ### Understanding plugin bundle size -Kibana Platform plugins are pre-built with `@kbn/optimizer` +Kibana Platform plugins are pre-built with `@kbn/optimizer` and distributed as package artifacts. This means that it is no -longer necessary for us to include the `optimizer` in the +longer necessary for us to include the `optimizer` in the distributable version of Kibana Every plugin artifact contains all plugin dependencies required to run the plugin, except some -stateful dependencies shared across plugin bundles via +stateful dependencies shared across plugin bundles via `@kbn/ui-shared-deps-npm` and `@kbn/ui-shared-deps-src`. This means that plugin artifacts _tend to be larger_ than they were in the legacy platform. To understand the current size of your plugin @@ -101,7 +101,7 @@ node scripts/build_kibana_platform_plugins.js --dist --no-examples --profile Many OSS tools allow you to analyze the generated stats file: -* [An official tool](https://webpack.github.io/analyse/#modules) from -Webpack authors -* [webpack-visualizer](https://chrisbateman.github.io/webpack-visualizer/) -* [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) +- [An official tool](https://webpack.github.io/analyse/#modules) from + Webpack authors +- [webpack-visualizer](https://chrisbateman.github.io/webpack-visualizer/) +- [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) diff --git a/dev_docs/key_concepts/persistable_state.mdx b/dev_docs/key_concepts/persistable_state.mdx index 2100d7d6444d..189259cf1085 100644 --- a/dev_docs/key_concepts/persistable_state.mdx +++ b/dev_docs/key_concepts/persistable_state.mdx @@ -1,20 +1,20 @@ --- id: kibDevDocsPersistableStateIntro -slug: /kibana-dev-docs/persistable-state-intro +slug: /kibana-dev-docs/key-concepts/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'] +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 it may contain, as well as telemetry collection utilities. - +“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 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 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 . +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 . 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. @@ -26,9 +26,10 @@ interface on their `setup` contract and each item in the collection should imple 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. +interface and each `EmbeddableFactory` needs to implement `PersistableStateDefinition` interface. Embeddable plugin exposes this interfaces: + ``` // EmbeddableInput implements Serializable @@ -45,7 +46,7 @@ If the state your plugin is storing can be provided by other plugins (your plugi ## 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 +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. @@ -58,13 +59,17 @@ of `PersistableStateService` should be called, which will migrate the state from 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 and methods of Persistable State interface should be implemented. - + [See example embeddable providing extract/inject functions](https://github.com/elastic/kibana/blob/master/examples/embeddable_examples/public/migrations/migrations_embeddable_factory.ts) @@ -72,7 +77,7 @@ To support persisting your state in saved objects owned by another plugin, the < 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. -. +. [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) @@ -80,4 +85,4 @@ As your plugin evolves, you may need to change your state in a breaking way. If ## 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. +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. diff --git a/dev_docs/key_concepts/saved_objects.mdx b/dev_docs/key_concepts/saved_objects.mdx index bef92bf02869..7fe66b9eab95 100644 --- a/dev_docs/key_concepts/saved_objects.mdx +++ b/dev_docs/key_concepts/saved_objects.mdx @@ -1,39 +1,42 @@ --- id: kibDevDocsSavedObjectsIntro -slug: /kibana-dev-docs/saved-objects-intro +slug: /kibana-dev-docs/key-concepts/saved-objects-intro title: Saved Objects summary: Saved Objects are a key concept to understand when building a Kibana plugin. date: 2021-02-02 -tags: ['kibana','dev', 'contributor', 'api docs'] +tags: ['kibana', 'dev', 'contributor', 'api docs'] --- "Saved Objects" are developer defined, persisted entities, stored in the Kibana system index (which is also sometimes referred to as the `.kibana` index). The Saved Objects service allows Kibana plugins to use Elasticsearch like a primary database. Think of it as an Object Document Mapper for Elasticsearch. - Some examples of Saved Object types are dashboards, lens, canvas workpads, index patterns, cases, ml jobs, and advanced settings. Some Saved Object types are - exposed to the user in the [Saved Object management UI](https://www.elastic.co/guide/en/kibana/current/managing-saved-objects.html), but not all. +Some examples of Saved Object types are dashboards, lens, canvas workpads, index patterns, cases, ml jobs, and advanced settings. Some Saved Object types are +exposed to the user in the [Saved Object management UI](https://www.elastic.co/guide/en/kibana/current/managing-saved-objects.html), but not all. Developers create and manage their Saved Objects using the SavedObjectClient, while other data in Elasticsearch should be accessed via the data plugin's search services. ![image](../assets/saved_object_vs_data_indices.png) - - + ## 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. The parent should have a reference to it's children, not the other way around. That way when a "parent" is exported (or shared to a space), - all the "children" will be automatically included. However, when a "child" is exported, it will not include all "parents". +all the "children" will be automatically included. However, when a "child" is exported, it will not include all "parents". - + ## Migrations and Backward compatibility As your plugin evolves, you may need to change your Saved Object type in a breaking way (for example, changing the type of an attribtue, or removing an attribute). If that happens, you should write a migration to upgrade the Saved Objects that existed prior to the change. -. +. ## Security @@ -47,30 +50,30 @@ Saved Objects are "space aware". They exist in the space they were created in, a Feature controls provide another level of isolation and shareability for Saved Objects. Admins can give users and roles read, write or none permissions for each Saved Object type. -### Object level security (OLS) +### Object level security (OLS) OLS is an oft-requested feature that is not implemented yet. When it is, it will provide users with even more sharing and privacy flexibility. Individual objects can be private to the user, shared with a selection of others, or made public. Much like how sharing Google Docs works. - + ## Scalability By default all saved object types go into a single index. If you expect your saved object type to have a lot of unique fields, or if you expect there -to be many of them, you can have your objects go in a separate index by using the `indexPattern` field. Reporting and task manager are two +to be many of them, you can have your objects go in a separate index by using the `indexPattern` field. Reporting and task manager are two examples of features that use this capability. ## Searchability -Because saved objects are stored in system indices, they cannot be searched like other data can. If you see the phrase “[X] as data” it is +Because saved objects are stored in system indices, they cannot be searched like other data can. If you see the phrase “[X] as data” it is referring to this searching limitation. Users will not be able to create custom dashboards using saved object data, like they would for data stored in Elasticsearch data indices. ## Saved Objects by value Sometimes Saved Objects end up persisted inside another Saved Object. We call these Saved Objects “by value”, as opposed to "by - reference". If an end user creates a visualization and adds it to a dashboard without saving it to the visualization - library, the data ends up nested inside the dashboard Saved Object. This helps keep the visualization library smaller. It also avoids - issues with edits propagating - since an entity can only exist in a single place. - Note that from the end user stand point, we don’t use these terms “by reference” and “by value”. +reference". If an end user creates a visualization and adds it to a dashboard without saving it to the visualization +library, the data ends up nested inside the dashboard Saved Object. This helps keep the visualization library smaller. It also avoids +issues with edits propagating - since an entity can only exist in a single place. +Note that from the end user stand point, we don’t use these terms “by reference” and “by value”. ## Sharing Saved Objects @@ -80,7 +83,7 @@ on how it is registered. If you are adding a **new** object type, when you register it: 1. Use `namespaceType: 'multiple-isolated'` to make these objects exist in exactly one space -2. Use `namespaceType: 'multiple'` to make these objects exist in one *or more* spaces +2. Use `namespaceType: 'multiple'` to make these objects exist in one _or more_ spaces 3. Use `namespaceType: 'agnostic'` if you want these objects to always exist in all spaces If you have an **existing** "legacy" object type that is not shareable (using `namespaceType: 'single'`), see the [legacy developer guide diff --git a/dev_docs/tutorials/building_a_kibana_distributable.mdx b/dev_docs/tutorials/building_a_kibana_distributable.mdx index 7b06525a5b97..e73481058ab3 100644 --- a/dev_docs/tutorials/building_a_kibana_distributable.mdx +++ b/dev_docs/tutorials/building_a_kibana_distributable.mdx @@ -1,6 +1,6 @@ --- id: kibDevTutorialBuildingDistributable -slug: /kibana-dev-docs/tutorial/building-distributable +slug: /kibana-dev-docs/tutorials/building-distributable title: Building a Kibana distributable summary: Learn how to build a Kibana distributable date: 2021-05-10 diff --git a/dev_docs/tutorials/data/search.mdx b/dev_docs/tutorials/data/search.mdx index 9cf46bb96c72..81080b0c2741 100644 --- a/dev_docs/tutorials/data/search.mdx +++ b/dev_docs/tutorials/data/search.mdx @@ -2,14 +2,14 @@ id: kibDevTutorialDataSearchAndSessions slug: /kibana-dev-docs/tutorials/data/search-and-sessions title: Kibana data.search Services -summary: Kibana Search Services +summary: Kibana Search Services date: 2021-02-10 tags: ['kibana', 'onboarding', 'dev', 'tutorials', 'search', 'sessions', 'search-sessions'] --- ## Search service -### Low level search +### Low level search Searching data stored in Elasticsearch can be done in various ways, for example using the Elasticsearch REST API or using an `Elasticsearch Client` for low level access. @@ -50,7 +50,7 @@ export class MyPlugin implements Plugin { } else { // handle partial results if you want. } - }, + }, error: (e) => { // handle error thrown, for example a server hangup }, @@ -69,36 +69,36 @@ Note: The `data` plugin contains services to help you generate the `query` and ` The `search` method can throw several types of errors, for example: - - `EsError` for errors originating in Elasticsearch errors - - `PainlessError` for errors originating from a Painless script - - `AbortError` if the search was aborted via an `AbortController` - - `HttpError` in case of a network error +- `EsError` for errors originating in Elasticsearch errors +- `PainlessError` for errors originating from a Painless script +- `AbortError` if the search was aborted via an `AbortController` +- `HttpError` in case of a network error -To display the errors in the context of an application, use the helper method provided on the `data.search` service. These errors are shown in a toast message, using the `core.notifications` service. +To display the errors in the context of an application, use the helper method provided on the `data.search` service. These errors are shown in a toast message, using the `core.notifications` service. ```ts data.search.search(req).subscribe({ - next: (result) => {}, + next: (result) => {}, error: (e) => { data.search.showError(e); }, -}) +}); ``` If you decide to handle errors by yourself, watch for errors coming from `Elasticsearch`. They have an additional `attributes` property that holds the raw error from `Elasticsearch`. ```ts data.search.search(req).subscribe({ - next: (result) => {}, + next: (result) => {}, error: (e) => { if (e instanceof IEsError) { showErrorReason(e.attributes); } }, -}) +}); ``` -#### Stop a running search +#### Stop a running search The search service `search` method supports a second argument called `options`. One of these options provides an `abortSignal` to stop searches from running to completion, if the result is no longer needed. @@ -106,20 +106,22 @@ The search service `search` method supports a second argument called `options`. import { AbortError } from '../../src/data/public'; const abortController = new AbortController(); -data.search.search(req, { - abortSignal: abortController.signal, -}).subscribe({ - next: (result) => { - // handle result - }, - error: (e) => { - if (e instanceof AbortError) { - // you can ignore this error - return; - } - // handle error, for example a server hangup - }, -}); +data.search + .search(req, { + abortSignal: abortController.signal, + }) + .subscribe({ + next: (result) => { + // handle result + }, + error: (e) => { + if (e instanceof AbortError) { + // you can ignore this error + return; + } + // handle error, for example a server hangup + }, + }); // Abort the search request after a second setTimeout(() => { @@ -135,13 +137,15 @@ For example, to run an EQL query using the `data.search` service, you should to ```ts const req = getEqlRequest(); -data.search.search(req, { - strategy: EQL_SEARCH_STRATEGY, -}).subscribe({ - next: (result) => { - // handle EQL result - }, -}); +data.search + .search(req, { + strategy: EQL_SEARCH_STRATEGY, + }) + .subscribe({ + next: (result) => { + // handle EQL result + }, + }); ``` ##### Custom search strategies @@ -154,18 +158,18 @@ The following example shows how to define, register, and use a search strategy t // ./myPlugin/server/myStrategy.ts /** - * Your custom search strategy should implement the ISearchStrategy interface, requiring at minimum a `search` function. + * Your custom search strategy should implement the ISearchStrategy interface, requiring at minimum a `search` function. */ export const mySearchStrategyProvider = ( data: PluginStart ): ISearchStrategy => { const preprocessRequest = (request: IMyStrategyRequest) => { // Custom preprocessing - } + }; const formatResponse = (response: IMyStrategyResponse) => { // Custom post-processing - } + }; // Get the default search strategy const es = data.search.getSearchStrategy(ES_SEARCH_STRATEGY); @@ -179,16 +183,12 @@ export const mySearchStrategyProvider = ( ```ts // ./myPlugin/server/plugin.ts -import type { - CoreSetup, - CoreStart, - Plugin, -} from 'kibana/server'; +import type { CoreSetup, CoreStart, Plugin } from 'kibana/server'; import { mySearchStrategyProvider } from './my_strategy'; /** - * Your plugin will receive the `data` plugin contact in both the setup and start lifecycle hooks. + * Your plugin will receive the `data` plugin contact in both the setup and start lifecycle hooks. */ export interface MyPluginSetupDeps { data: PluginSetup; @@ -199,13 +199,10 @@ export interface MyPluginStartDeps { } /** - * In your custom server side plugin, register the strategy from the setup contract + * In your custom server side plugin, register the strategy from the setup contract */ export class MyPlugin implements Plugin { - public setup( - core: CoreSetup, - deps: MyPluginSetupDeps - ) { + public setup(core: CoreSetup, deps: MyPluginSetupDeps) { core.getStartServices().then(([_, depsStart]) => { const myStrategy = mySearchStrategyProvider(depsStart.data); deps.data.search.registerSearchStrategy('myCustomStrategy', myStrategy); @@ -217,13 +214,15 @@ export class MyPlugin implements Plugin { ```ts // ./myPlugin/public/plugin.ts const req = getRequest(); -data.search.search(req, { - strategy: 'myCustomStrategy', -}).subscribe({ - next: (result) => { - // handle result - }, -}); +data.search + .search(req, { + strategy: 'myCustomStrategy', + }) + .subscribe({ + next: (result) => { + // handle result + }, + }); ``` ##### Async search and custom async search strategies @@ -234,7 +233,7 @@ This synchronous execution works great in most cases. However, with the introduc The [async_search API](https://www.elastic.co/guide/en/elasticsearch/reference/current/async-search.html) is what drives more advanced `Kibana` `search` features, such as `partial results` and `search sessions`. [When available](https://www.elastic.co/subscriptions), the default search strategy of `Kibana` is automatically set to the **async** default search strategy (`ENHANCED_ES_SEARCH_STRATEGY`), empowering Kibana to run longer queries, with an **optional** duration restriction defined by the UI setting `search:timeout`. -If you are implementing your own async custom search strategy, make sure to implement `cancel` and `extend`, as shown in the following example: +If you are implementing your own async custom search strategy, make sure to implement `cancel` and `extend`, as shown in the following example: ```ts // ./myPlugin/server/myEnhancedStrategy.ts @@ -245,7 +244,7 @@ export const myEnhancedSearchStrategyProvider = ( const ese = data.search.getSearchStrategy(ENHANCED_ES_SEARCH_STRATEGY); return { search: (request, options, deps) => { - // search will be called multiple times, + // search will be called multiple times, // be sure your response formatting is capable of handling partial results, as well as the final result. return formatResponse(ese.search(request, options, deps)); }, @@ -286,7 +285,7 @@ function searchWithSearchSource() { .setField('query', query) .setField('fields', selectedFields.length ? selectedFields.map((f) => f.name) : ['*']) .setField('aggs', getAggsDsl()); - + searchSource.fetch$().subscribe({ next: () => {}, error: () => {}, @@ -296,7 +295,7 @@ function searchWithSearchSource() { ### Partial results -When searching using an `async` strategy (such as async DSL and async EQL), the search service will stream back partial results. +When searching using an `async` strategy (such as async DSL and async EQL), the search service will stream back partial results. Although you can ignore the partial results and wait for the final result before rendering, you can also use the partial results to create a more interactive experience for your users. It is highly advised, however, to make sure users are aware that the results they are seeing are partial. @@ -310,7 +309,7 @@ data.search.search(req).subscribe({ renderPartialResult(res); } }, -}) +}); // Skipping partial results const finalResult = await data.search.search(req).toPromise(); @@ -320,31 +319,29 @@ const finalResult = await data.search.search(req).toPromise(); A search session is a higher level concept than search. A search session describes a grouping of one or more async search requests with additional context. -Search sessions are handy when you want to enable a user to run something asynchronously (for example, a dashboard over a long period of time), and then quickly restore the results at a later time. The `Search Service` transparently fetches results from the `.async-search` index, instead of running each request again. +Search sessions are handy when you want to enable a user to run something asynchronously (for example, a dashboard over a long period of time), and then quickly restore the results at a later time. The `Search Service` transparently fetches results from the `.async-search` index, instead of running each request again. Internally, any search run within a search session is saved into an object, allowing Kibana to manage their lifecycle. Most saved objects are deleted automatically after a short period of time, but if a user chooses to save the search session, the saved object is persisted, so that results can be restored in a later time. -Stored search sessions are listed in the *Management* application, under *Kibana > Search Sessions*, making it easy to find, manage, and restore them. +Stored search sessions are listed in the _Management_ application, under _Kibana > Search Sessions_, making it easy to find, manage, and restore them. As a developer, you might encounter these two common, use cases: - * Running a search inside an existing search session - * Supporting search sessions in your application +- Running a search inside an existing search session +- Supporting search sessions in your application #### Running a search inside an existing search session For this example, assume you are implementing a new type of `Embeddable` that will be shown on dashboards. The same principle applies, however, to any search requests that you are running, as long as the application you are running inside is managing an active session. -Because the Dashboard application is already managing a search session, all you need to do is pass down the `searchSessionId` argument to any `search` call. This applies to both the low and high level search APIs. +Because the Dashboard application is already managing a search session, all you need to do is pass down the `searchSessionId` argument to any `search` call. This applies to both the low and high level search APIs. -The search information will be added to the saved object for the search session. +The search information will be added to the saved object for the search session. ```ts -export class SearchEmbeddable - extends Embeddable { - +export class SearchEmbeddable extends Embeddable { private async fetchData() { - // Every embeddable receives an optional `searchSessionId` input parameter. + // Every embeddable receives an optional `searchSessionId` input parameter. const { searchSessionId } = this.input; // Setup your search source @@ -355,9 +352,11 @@ export class SearchEmbeddable this.updateOutput({ loading: true, error: undefined }); // Make the request, wait for the final result - const {rawResponse: resp} = await searchSource.fetch$({ - sessionId: searchSessionId, - }).toPromise(); + const { rawResponse: resp } = await searchSource + .fetch$({ + sessionId: searchSessionId, + }) + .toPromise(); this.useSearchResult(resp); @@ -368,35 +367,37 @@ export class SearchEmbeddable } } } - -``` +``` You can also retrieve the active `Search Session ID` from the `Search Service` directly: ```ts async function fetchData(data: DataPublicPluginStart) { try { - return await searchSource.fetch$({ + return await searchSource + .fetch$({ sessionId: data.search.sessions.getSessionId(), - }).toPromise(); + }) + .toPromise(); } catch (e) { // handle search errors } } - ``` - Search sessions are initiated by the client. If you are using a route that runs server side searches, you can send the `searchSessionId` to the server, and then pass it down to the server side `data.search` function call. + Search sessions are initiated by the client. If you are using a route that runs server side + searches, you can send the `searchSessionId` to the server, and then pass it down to the server + side `data.search` function call. #### Supporting search sessions in your application Before implementing the ability to create and restore search sessions in your application, ask yourself the following questions: -1. **Does your application normally run long operations?** For example, it makes sense for a user to generate a Dashboard or a Canvas report from data stored in cold storage. However, when editing a single visualization, it is best to work with a shorter timeframe of hot or warm data. +1. **Does your application normally run long operations?** For example, it makes sense for a user to generate a Dashboard or a Canvas report from data stored in cold storage. However, when editing a single visualization, it is best to work with a shorter timeframe of hot or warm data. 2. **Does it make sense for your application to restore a search session?** For example, you might want to restore an interesting configuration of filters of older documents you found in Discover. However, a single Lens or Map visualization might not be as helpful, outside the context of a specific dashboard. -3. **What is a search session in the context of your application?** Although Discover and Dashboard start a new search session every time the time range or filters change, or when the user clicks **Refresh**, you can manage your sessions differently. For example, if your application has tabs, you might group searches from multiple tabs into a single search session. You must be able to clearly define the **state** used to create the search session`. The **state** refers to any setting that might change the queries being set to `Elasticsearch`. +3. **What is a search session in the context of your application?** Although Discover and Dashboard start a new search session every time the time range or filters change, or when the user clicks **Refresh**, you can manage your sessions differently. For example, if your application has tabs, you might group searches from multiple tabs into a single search session. You must be able to clearly define the **state** used to create the search session`. The **state** refers to any setting that might change the queries being set to `Elasticsearch`. Once you answer those questions, proceed to implement the following bits of code in your application. @@ -409,8 +410,8 @@ export class MyPlugin implements Plugin { public start(core: CoreStart, { data }: MyPluginStartDependencies) { const sessionRestorationDataProvider: SearchSessionInfoProvider = { data, - getDashboard - } + getDashboard, + }; data.search.session.enableStorage({ getName: async () => { @@ -430,32 +431,34 @@ export class MyPlugin implements Plugin { ``` - The restore state of a search session may be different from the initial state used to create it. For example, where the initial state may contain relative dates, in the restore state, those must be converted to absolute dates. Read more about the [NowProvider](). + The restore state of a search session may be different from the initial state used to create it. + For example, where the initial state may contain relative dates, in the restore state, those must + be converted to absolute dates. Read more about the [NowProvider](). - Calling `enableStorage` will also enable the `Search Session Indicator` component in the chrome component of your solution. The `Search Session Indicator` is a small button, used by default to engage users and save new search sessions. To implement your own UI, contact the Kibana application services team to decouple this behavior. + Calling `enableStorage` will also enable the `Search Session Indicator` component in the chrome + component of your solution. The `Search Session Indicator` is a small button, used by default to + engage users and save new search sessions. To implement your own UI, contact the Kibana + application services team to decouple this behavior. -##### Start a new search session +##### Start a new search session -Make sure to call `start` when the **state** you previously defined changes. +Make sure to call `start` when the **state** you previously defined changes. ```ts - function onSearchSessionConfigChange() { this.searchSessionId = data.search.sessions.start(); } - ``` -Pass the `searchSessionId` to every `search` call inside your application. If you're using `Embeddables`, pass down the `searchSessionId` as `input`. +Pass the `searchSessionId` to every `search` call inside your application. If you're using `Embeddables`, pass down the `searchSessionId` as `input`. If you can't pass the `searchSessionId` directly, you can retrieve it from the service. ```ts const currentSearchSessionId = data.search.sessions.getSessionId(); - ``` ##### Clear search sessions @@ -466,19 +469,17 @@ Creating a new search session clears the previous one. You must explicitly `clea function onDestroy() { data.search.session.clear(); } - ``` If you don't call `clear`, you will see a warning in the console while developing. However, when running in production, you will get a fatal error. This is done to avoid leakage of unrelated search requests into an existing search session left open by mistake. -##### Restore search sessions +##### Restore search sessions -The last step of the integration is restoring an existing search session. The `searchSessionId` parameter and the rest of the restore state are passed into the application via the URL. Non-URL support is planned for future releases. +The last step of the integration is restoring an existing search session. The `searchSessionId` parameter and the rest of the restore state are passed into the application via the URL. Non-URL support is planned for future releases. If you detect the presense of a `searchSessionId` parameter in the URL, call the `restore` method **instead** of calling `start`. The previous example would now become: ```ts - function onSearchSessionConfigChange(searchSessionIdFromUrl?: string) { if (searchSessionIdFromUrl) { data.search.sessions.restore(searchSessionIdFromUrl); @@ -486,7 +487,6 @@ function onSearchSessionConfigChange(searchSessionIdFromUrl?: string) { data.search.sessions.start(); } } - ``` Once you `restore` the session, as long as all `search` requests run with the same `searchSessionId`, the search session should be seamlessly restored. diff --git a/dev_docs/tutorials/debugging.mdx b/dev_docs/tutorials/debugging.mdx index c0efd249be06..c612893e4f1f 100644 --- a/dev_docs/tutorials/debugging.mdx +++ b/dev_docs/tutorials/debugging.mdx @@ -1,6 +1,6 @@ --- id: kibDevTutorialDebugging -slug: /kibana-dev-docs/tutorial/debugging +slug: /kibana-dev-docs/tutorials/debugging title: Debugging in development summary: Learn how to debug Kibana while running from source date: 2021-04-26 @@ -27,7 +27,7 @@ You will need to run Jest directly from the Node script: `node --inspect-brk scripts/functional_test_runner` -### Development Server +### Development Server `node --inspect-brk scripts/kibana` @@ -58,4 +58,4 @@ logging: level: debug - name: elasticsearch.query level: debug -``` \ No newline at end of file +``` diff --git a/dev_docs/tutorials/saved_objects.mdx b/dev_docs/tutorials/saved_objects.mdx index 35efbb97a0a0..29a0b60983d9 100644 --- a/dev_docs/tutorials/saved_objects.mdx +++ b/dev_docs/tutorials/saved_objects.mdx @@ -1,6 +1,6 @@ --- id: kibDevTutorialSavedObject -slug: /kibana-dev-docs/tutorial/saved-objects +slug: /kibana-dev-docs/tutorials/saved-objects title: Register a new saved object type summary: Learn how to register a new saved object type. date: 2021-02-05 diff --git a/dev_docs/tutorials/submit_a_pull_request.mdx b/dev_docs/tutorials/submit_a_pull_request.mdx index 2be5973bb385..5436ebf24e03 100644 --- a/dev_docs/tutorials/submit_a_pull_request.mdx +++ b/dev_docs/tutorials/submit_a_pull_request.mdx @@ -1,6 +1,6 @@ --- id: kibDevTutorialSubmitPullRequest -slug: /kibana-dev-docs/tutorial/submit-pull-request +slug: /kibana-dev-docs/tutorials/submit-pull-request title: Submitting a Kibana pull request summary: Learn how to submit a Kibana pull request date: 2021-06-24 diff --git a/dev_docs/tutorials/testing_plugins.mdx b/dev_docs/tutorials/testing_plugins.mdx index bc92af33d349..14089bc3fa31 100644 --- a/dev_docs/tutorials/testing_plugins.mdx +++ b/dev_docs/tutorials/testing_plugins.mdx @@ -1,6 +1,6 @@ --- id: kibDevTutorialTestingPlugins -slug: /kibana-dev-docs/tutorial/testing-plugins +slug: /kibana-dev-docs/tutorials/testing-plugins title: Testing Kibana Plugins summary: Learn how to test different aspects of Kibana plugins date: 2021-07-05 diff --git a/src/plugins/data/README.mdx b/src/plugins/data/README.mdx index 18b755275b4a..e24a949a0c2e 100644 --- a/src/plugins/data/README.mdx +++ b/src/plugins/data/README.mdx @@ -1,6 +1,6 @@ --- id: kibDataPlugin -slug: /kibana-dev-docs/services/data-plugin +slug: /kibana-dev-docs/key-concepts/data-plugin title: Data services image: https://source.unsplash.com/400x175/?Search summary: The data plugin contains services for searching, querying and filtering. diff --git a/src/plugins/usage_collection/README.mdx b/src/plugins/usage_collection/README.mdx index a6f6f6c8e597..a58f197818bf 100644 --- a/src/plugins/usage_collection/README.mdx +++ b/src/plugins/usage_collection/README.mdx @@ -1,6 +1,6 @@ --- id: kibUsageCollectionPlugin -slug: /kibana-dev-docs/services/usage-collection-plugin +slug: /kibana-dev-docs/key-concepts/usage-collection-plugin title: Usage collection service summary: The Usage Collection Service defines a set of APIs for other plugins to report the usage of their features. date: 2021-02-24