diff --git a/.backportrc.json b/.backportrc.json index 8f458343c51af..3f1d639e9a480 100644 --- a/.backportrc.json +++ b/.backportrc.json @@ -3,6 +3,7 @@ "targetBranchChoices": [ { "name": "master", "checked": true }, { "name": "7.x", "checked": true }, + "7.9", "7.8", "7.7", "7.6", @@ -26,7 +27,7 @@ "targetPRLabels": ["backport"], "branchLabelMapping": { "^v8.0.0$": "master", - "^v7.9.0$": "7.x", + "^v7.10.0$": "7.x", "^v(\\d+).(\\d+).\\d+$": "$1.$2" } } diff --git a/.ci/Jenkinsfile_baseline_capture b/.ci/Jenkinsfile_baseline_capture new file mode 100644 index 0000000000000..7c7cc8d98c306 --- /dev/null +++ b/.ci/Jenkinsfile_baseline_capture @@ -0,0 +1,26 @@ +#!/bin/groovy + +library 'kibana-pipeline-library' +kibanaLibrary.load() + +kibanaPipeline(timeoutMinutes: 120) { + ciStats.trackBuild { + catchError { + parallel([ + 'oss-visualRegression': { + workers.ci(name: 'oss-visualRegression', size: 's', ramDisk: false) { + kibanaPipeline.functionalTestProcess('oss-visualRegression', './test/scripts/jenkins_visual_regression.sh')(1) + } + }, + 'xpack-visualRegression': { + workers.ci(name: 'xpack-visualRegression', size: 's', ramDisk: false) { + kibanaPipeline.functionalTestProcess('xpack-visualRegression', './test/scripts/jenkins_xpack_visual_regression.sh')(1) + } + }, + ]) + } + + kibanaPipeline.sendMail() + slackNotifications.onFailure() + } +} diff --git a/.ci/Jenkinsfile_baseline_trigger b/.ci/Jenkinsfile_baseline_trigger new file mode 100644 index 0000000000000..cc9fb47ca4993 --- /dev/null +++ b/.ci/Jenkinsfile_baseline_trigger @@ -0,0 +1,64 @@ +#!/bin/groovy + +def MAXIMUM_COMMITS_TO_CHECK = 10 +def MAXIMUM_COMMITS_TO_BUILD = 5 + +if (!params.branches_yaml) { + error "'branches_yaml' parameter must be specified" +} + +def additionalBranches = [] + +def branches = readYaml(text: params.branches_yaml) + additionalBranches + +library 'kibana-pipeline-library' +kibanaLibrary.load() + +withGithubCredentials { + branches.each { branch -> + stage(branch) { + def commits = getCommits(branch, MAXIMUM_COMMITS_TO_CHECK, MAXIMUM_COMMITS_TO_BUILD) + + commits.take(MAXIMUM_COMMITS_TO_BUILD).each { commit -> + catchErrors { + githubCommitStatus.create(commit, 'pending', 'Baseline started.', 'kibana-ci-baseline') + + build( + propagate: false, + wait: false, + job: 'elastic+kibana+baseline-capture', + parameters: [ + string(name: 'branch_specifier', value: branch), + string(name: 'commit', value: commit), + ] + ) + } + } + } + } +} + +def getCommits(String branch, maximumCommitsToCheck, maximumCommitsToBuild) { + print "Getting latest commits for ${branch}..." + def commits = githubApi.get("repos/elastic/kibana/commits?sha=${branch}").take(maximumCommitsToCheck).collect { it.sha } + def commitsToBuild = [] + + for (commit in commits) { + print "Getting statuses for ${commit}" + def status = githubApi.get("repos/elastic/kibana/statuses/${commit}").find { it.context == 'kibana-ci-baseline' } + print "Commit '${commit}' already built? ${status ? 'Yes' : 'No'}" + + if (!status) { + commitsToBuild << commit + } else { + // Stop at the first commit we find that's already been triggered + break + } + + if (commitsToBuild.size() >= maximumCommitsToBuild) { + break + } + } + + return commitsToBuild.reverse() // We want the builds to trigger oldest-to-newest +} diff --git a/.ci/Jenkinsfile_visual_baseline b/.ci/Jenkinsfile_visual_baseline deleted file mode 100644 index 2a16c499fa168..0000000000000 --- a/.ci/Jenkinsfile_visual_baseline +++ /dev/null @@ -1,25 +0,0 @@ -#!/bin/groovy - -library 'kibana-pipeline-library' -kibanaLibrary.load() - -kibanaPipeline(timeoutMinutes: 120) { - ciStats.trackBuild { - catchError { - parallel([ - 'oss-visualRegression': { - workers.ci(name: 'oss-visualRegression', size: 's', ramDisk: false) { - kibanaPipeline.functionalTestProcess('oss-visualRegression', './test/scripts/jenkins_visual_regression.sh')(1) - } - }, - 'xpack-visualRegression': { - workers.ci(name: 'xpack-visualRegression', size: 's', ramDisk: false) { - kibanaPipeline.functionalTestProcess('xpack-visualRegression', './test/scripts/jenkins_xpack_visual_regression.sh')(1) - } - }, - ]) - } - - kibanaPipeline.sendMail() - } -} diff --git a/.ci/packer_cache_for_branch.sh b/.ci/packer_cache_for_branch.sh index a9fbe781915b6..ab0ab845b2dc3 100755 --- a/.ci/packer_cache_for_branch.sh +++ b/.ci/packer_cache_for_branch.sh @@ -18,7 +18,7 @@ node scripts/es snapshot --download-only; node scripts/es snapshot --license=oss --download-only; # download reporting browsers -(cd "x-pack" && yarn gulp prepare); +(cd "x-pack" && yarn gulp downloadChromium); # cache the chromedriver archive chromedriverDistVersion="$(node -e "console.log(require('chromedriver').version)")" @@ -46,7 +46,7 @@ echo "Creating bootstrap_cache archive" # archive cacheable directories mkdir -p "$HOME/.kibana/bootstrap_cache" tar -cf "$HOME/.kibana/bootstrap_cache/$branch.tar" \ - x-pack/plugins/reporting/.chromium \ + .chromium \ .es \ .chromedriver \ .geckodriver; diff --git a/.eslintignore b/.eslintignore index 9de2cc2872960..d983c4bedfaab 100644 --- a/.eslintignore +++ b/.eslintignore @@ -1,6 +1,7 @@ **/*.js.snap **/graphql/types.ts /.es +/.chromium /build /built_assets /config/apm.dev.js @@ -25,6 +26,7 @@ target /src/plugins/data/common/es_query/kuery/ast/_generated_/** /src/plugins/vis_type_timelion/public/_generated_/** /src/plugins/vis_type_timelion/public/webpackShims/jquery.flot.* +/src/plugins/timelion/public/webpackShims/jquery.flot.* /x-pack/legacy/plugins/**/__tests__/fixtures/** /x-pack/plugins/apm/e2e/**/snapshots.js /x-pack/plugins/apm/e2e/tmp/* diff --git a/.eslintrc.js b/.eslintrc.js index 8d979dc0f8645..a9ffe2850aa72 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -49,6 +49,31 @@ const ELASTIC_LICENSE_HEADER = ` */ `; +const SAFER_LODASH_SET_HEADER = ` +/* + * Elasticsearch B.V licenses this file to you under the MIT License. + * See \`packages/elastic-safer-lodash-set/LICENSE\` for more information. + */ +`; + +const SAFER_LODASH_SET_LODASH_HEADER = ` +/* + * This file is forked from the lodash project (https://lodash.com/), + * and may include modifications made by Elasticsearch B.V. + * Elasticsearch B.V. licenses this file to you under the MIT License. + * See \`packages/elastic-safer-lodash-set/LICENSE\` for more information. + */ +`; + +const SAFER_LODASH_SET_DEFINITELYTYPED_HEADER = ` +/* + * This file is forked from the DefinitelyTyped project (https://github.com/DefinitelyTyped/DefinitelyTyped), + * and may include modifications made by Elasticsearch B.V. + * Elasticsearch B.V. licenses this file to you under the MIT License. + * See \`packages/elastic-safer-lodash-set/LICENSE\` for more information. + */ +`; + const allMochaRulesOff = {}; Object.keys(require('eslint-plugin-mocha').rules).forEach((k) => { allMochaRulesOff['mocha/' + k] = 'off'; @@ -143,7 +168,12 @@ module.exports = { '@kbn/eslint/disallow-license-headers': [ 'error', { - licenses: [ELASTIC_LICENSE_HEADER], + licenses: [ + ELASTIC_LICENSE_HEADER, + SAFER_LODASH_SET_HEADER, + SAFER_LODASH_SET_LODASH_HEADER, + SAFER_LODASH_SET_DEFINITELYTYPED_HEADER, + ], }, ], }, @@ -174,7 +204,82 @@ module.exports = { '@kbn/eslint/disallow-license-headers': [ 'error', { - licenses: [APACHE_2_0_LICENSE_HEADER], + licenses: [ + APACHE_2_0_LICENSE_HEADER, + SAFER_LODASH_SET_HEADER, + SAFER_LODASH_SET_LODASH_HEADER, + SAFER_LODASH_SET_DEFINITELYTYPED_HEADER, + ], + }, + ], + }, + }, + + /** + * safer-lodash-set package requires special license headers + */ + { + files: ['packages/elastic-safer-lodash-set/**/*.{js,mjs,ts,tsx}'], + rules: { + '@kbn/eslint/require-license-header': [ + 'error', + { + license: SAFER_LODASH_SET_LODASH_HEADER, + }, + ], + '@kbn/eslint/disallow-license-headers': [ + 'error', + { + licenses: [ + ELASTIC_LICENSE_HEADER, + APACHE_2_0_LICENSE_HEADER, + SAFER_LODASH_SET_HEADER, + SAFER_LODASH_SET_DEFINITELYTYPED_HEADER, + ], + }, + ], + }, + }, + { + files: ['packages/elastic-safer-lodash-set/test/*.{js,mjs,ts,tsx}'], + rules: { + '@kbn/eslint/require-license-header': [ + 'error', + { + license: SAFER_LODASH_SET_HEADER, + }, + ], + '@kbn/eslint/disallow-license-headers': [ + 'error', + { + licenses: [ + ELASTIC_LICENSE_HEADER, + APACHE_2_0_LICENSE_HEADER, + SAFER_LODASH_SET_LODASH_HEADER, + SAFER_LODASH_SET_DEFINITELYTYPED_HEADER, + ], + }, + ], + }, + }, + { + files: ['packages/elastic-safer-lodash-set/**/*.d.ts'], + rules: { + '@kbn/eslint/require-license-header': [ + 'error', + { + license: SAFER_LODASH_SET_DEFINITELYTYPED_HEADER, + }, + ], + '@kbn/eslint/disallow-license-headers': [ + 'error', + { + licenses: [ + ELASTIC_LICENSE_HEADER, + APACHE_2_0_LICENSE_HEADER, + SAFER_LODASH_SET_HEADER, + SAFER_LODASH_SET_LODASH_HEADER, + ], }, ], }, @@ -541,9 +646,129 @@ module.exports = { * Harden specific rules */ { - files: ['test/harden/*.js'], + files: ['test/harden/*.js', 'packages/elastic-safer-lodash-set/test/*.js'], rules: allMochaRulesOff, }, + { + files: ['**/*.{js,mjs,ts,tsx}'], + rules: { + 'no-restricted-imports': [ + 2, + { + paths: [ + { + name: 'lodash', + importNames: ['set', 'setWith'], + message: 'Please use @elastic/safer-lodash-set instead', + }, + { + name: 'lodash.set', + message: 'Please use @elastic/safer-lodash-set instead', + }, + { + name: 'lodash.setwith', + message: 'Please use @elastic/safer-lodash-set instead', + }, + { + name: 'lodash/set', + message: 'Please use @elastic/safer-lodash-set instead', + }, + { + name: 'lodash/setWith', + message: 'Please use @elastic/safer-lodash-set instead', + }, + { + name: 'lodash/fp', + importNames: ['set', 'setWith', 'assoc', 'assocPath'], + message: 'Please use @elastic/safer-lodash-set instead', + }, + { + name: 'lodash/fp/set', + message: 'Please use @elastic/safer-lodash-set instead', + }, + { + name: 'lodash/fp/setWith', + message: 'Please use @elastic/safer-lodash-set instead', + }, + { + name: 'lodash/fp/assoc', + message: 'Please use @elastic/safer-lodash-set instead', + }, + { + name: 'lodash/fp/assocPath', + message: 'Please use @elastic/safer-lodash-set instead', + }, + ], + }, + ], + 'no-restricted-modules': [ + 2, + { + paths: [ + { + name: 'lodash.set', + message: 'Please use @elastic/safer-lodash-set instead', + }, + { + name: 'lodash.setwith', + message: 'Please use @elastic/safer-lodash-set instead', + }, + { + name: 'lodash/set', + message: 'Please use @elastic/safer-lodash-set instead', + }, + { + name: 'lodash/setWith', + message: 'Please use @elastic/safer-lodash-set instead', + }, + ], + }, + ], + 'no-restricted-properties': [ + 2, + { + object: 'lodash', + property: 'set', + message: 'Please use @elastic/safer-lodash-set instead', + }, + { + object: '_', + property: 'set', + message: 'Please use @elastic/safer-lodash-set instead', + }, + { + object: 'lodash', + property: 'setWith', + message: 'Please use @elastic/safer-lodash-set instead', + }, + { + object: '_', + property: 'setWith', + message: 'Please use @elastic/safer-lodash-set instead', + }, + { + object: 'lodash', + property: 'assoc', + message: 'Please use @elastic/safer-lodash-set instead', + }, + { + object: '_', + property: 'assoc', + message: 'Please use @elastic/safer-lodash-set instead', + }, + { + object: 'lodash', + property: 'assocPath', + message: 'Please use @elastic/safer-lodash-set instead', + }, + { + object: '_', + property: 'assocPath', + message: 'Please use @elastic/safer-lodash-set instead', + }, + ], + }, + }, /** * APM overrides @@ -906,6 +1131,18 @@ module.exports = { }, }, + /** + * Enterprise Search overrides + */ + { + files: ['x-pack/plugins/enterprise_search/**/*.{ts,tsx}'], + excludedFiles: ['x-pack/plugins/enterprise_search/**/*.{test,mock}.{ts,tsx}'], + rules: { + 'react-hooks/exhaustive-deps': 'off', + '@typescript-eslint/no-explicit-any': 'error', + }, + }, + /** * disable jsx-a11y for kbn-ui-framework */ diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index bec0a0a33bad2..2ad82ded6cb38 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -24,29 +24,20 @@ /src/plugins/vis_type_xy/ @elastic/kibana-app /src/plugins/visualize/ @elastic/kibana-app -# Core UI -# Exclude tutorials folder for now because they are not owned by Kibana app and most will move out soon -/src/plugins/home/public @elastic/kibana-core-ui -/src/plugins/home/server/*.ts @elastic/kibana-core-ui -/src/plugins/home/server/services/ @elastic/kibana-core-ui -# Exclude tutorial resources folder for now because they are not owned by Kibana app and most will move out soon -/src/legacy/core_plugins/kibana/public/home/*.ts @elastic/kibana-core-ui -/src/legacy/core_plugins/kibana/public/home/*.scss @elastic/kibana-core-ui -/src/legacy/core_plugins/kibana/public/home/np_ready/ @elastic/kibana-core-ui - # App Architecture +/examples/bfetch_explorer/ @elastic/kibana-app-arch +/examples/dashboard_embeddable_examples/ @elastic/kibana-app-arch +/examples/demo_search/ @elastic/kibana-app-arch /examples/developer_examples/ @elastic/kibana-app-arch +/examples/embeddable_examples/ @elastic/kibana-app-arch +/examples/embeddable_explorer/ @elastic/kibana-app-arch +/examples/state_container_examples/ @elastic/kibana-app-arch +/examples/ui_actions_examples/ @elastic/kibana-app-arch +/examples/ui_actions_explorer/ @elastic/kibana-app-arch /examples/url_generators_examples/ @elastic/kibana-app-arch /examples/url_generators_explorer/ @elastic/kibana-app-arch -/packages/kbn-interpreter/ @elastic/kibana-app-arch /packages/elastic-datemath/ @elastic/kibana-app-arch -/src/legacy/core_plugins/embeddable_api/ @elastic/kibana-app-arch -/src/legacy/core_plugins/interpreter/ @elastic/kibana-app-arch -/src/legacy/core_plugins/kibana_react/ @elastic/kibana-app-arch -/src/legacy/core_plugins/kibana/public/management/ @elastic/kibana-app-arch -/src/legacy/core_plugins/kibana/server/routes/api/management/ @elastic/kibana-app-arch -/src/legacy/core_plugins/visualizations/ @elastic/kibana-app-arch -/src/legacy/server/index_patterns/ @elastic/kibana-app-arch +/packages/kbn-interpreter/ @elastic/kibana-app-arch /src/plugins/advanced_settings/ @elastic/kibana-app-arch /src/plugins/bfetch/ @elastic/kibana-app-arch /src/plugins/data/ @elastic/kibana-app-arch @@ -61,9 +52,10 @@ /src/plugins/share/ @elastic/kibana-app-arch /src/plugins/ui_actions/ @elastic/kibana-app-arch /src/plugins/visualizations/ @elastic/kibana-app-arch -/x-pack/plugins/advanced_ui_actions/ @elastic/kibana-app-arch +/x-pack/examples/ui_actions_enhanced_examples/ @elastic/kibana-app-arch /x-pack/plugins/data_enhanced/ @elastic/kibana-app-arch -/x-pack/plugins/drilldowns/ @elastic/kibana-app-arch +/x-pack/plugins/embeddable_enhanced/ @elastic/kibana-app-arch +/x-pack/plugins/ui_actions_enhanced/ @elastic/kibana-app-arch # APM /x-pack/plugins/apm/ @elastic/apm-ui @@ -79,6 +71,16 @@ /x-pack/plugins/canvas/ @elastic/kibana-canvas /x-pack/test/functional/apps/canvas/ @elastic/kibana-canvas +# Core UI +# Exclude tutorials folder for now because they are not owned by Kibana app and most will move out soon +/src/plugins/home/public @elastic/kibana-core-ui +/src/plugins/home/server/*.ts @elastic/kibana-core-ui +/src/plugins/home/server/services/ @elastic/kibana-core-ui +# Exclude tutorial resources folder for now because they are not owned by Kibana app and most will move out soon +/src/legacy/core_plugins/kibana/public/home/*.ts @elastic/kibana-core-ui +/src/legacy/core_plugins/kibana/public/home/*.scss @elastic/kibana-core-ui +/src/legacy/core_plugins/kibana/public/home/np_ready/ @elastic/kibana-core-ui + # Observability UIs /x-pack/legacy/plugins/infra/ @elastic/logs-metrics-ui /x-pack/plugins/infra/ @elastic/logs-metrics-ui @@ -144,6 +146,7 @@ /x-pack/plugins/licensing/ @elastic/kibana-platform /x-pack/plugins/global_search/ @elastic/kibana-platform /x-pack/plugins/cloud/ @elastic/kibana-platform +/x-pack/test/saved_objects_field_count/ @elastic/kibana-platform /packages/kbn-config-schema/ @elastic/kibana-platform /src/legacy/server/config/ @elastic/kibana-platform /src/legacy/server/http/ @elastic/kibana-platform @@ -200,6 +203,11 @@ x-pack/plugins/telemetry_collection_xpack/schema/xpack_plugins.json @elastic/kib # Design **/*.scss @elastic/kibana-design +# Enterprise Search +/x-pack/plugins/enterprise_search/ @elastic/app-search-frontend @elastic/workplace-search-frontend +/x-pack/test/functional_enterprise_search/ @elastic/app-search-frontend @elastic/workplace-search-frontend +/x-pack/plugins/enterprise_search/**/*.scss @elastic/ent-search-design + # Elasticsearch UI /src/plugins/dev_tools/ @elastic/es-ui /src/plugins/console/ @elastic/es-ui diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 4cc0c8016f1d0..754043ee0ef77 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -11,7 +11,7 @@ Delete any items that are not applicable to this PR. - [ ] [Unit or functional tests](https://github.com/elastic/kibana/blob/master/CONTRIBUTING.md#cross-browser-compatibility) were updated or added to match the most common scenarios - [ ] This was checked for [keyboard-only and screenreader accessibility](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Cross_browser_testing/Accessibility#Accessibility_testing_checklist) - [ ] This renders correctly on smaller devices using a responsive layout. (You can test this [in your browser](https://www.browserstack.com/guide/responsive-testing-on-local-server) -- [ ] This was checked for cross-browser compatibility, [including a check against IE11](https://github.com/elastic/kibana/blob/master/CONTRIBUTING.md#cross-browser-compatibility) +- [ ] This was checked for [cross-browser compatibility](https://www.elastic.co/support/matrix#matrix_browsers) ### For maintainers diff --git a/.gitignore b/.gitignore index 32377ec0f1ffe..dfd02de7b1186 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ .signing-config.json .ackrc /.es +/.chromium .DS_Store .node_binaries .native_modules @@ -30,6 +31,7 @@ disabledPlugins webpackstats.json /config/* !/config/kibana.yml +!/config/node.options coverage selenium .babel_register_cache.json diff --git a/.i18nrc.json b/.i18nrc.json index 9af7f17067b8e..e8431fdb3f0e1 100644 --- a/.i18nrc.json +++ b/.i18nrc.json @@ -44,7 +44,7 @@ "src/plugins/telemetry_management_section" ], "tileMap": "src/plugins/tile_map", - "timelion": ["src/legacy/core_plugins/timelion", "src/plugins/vis_type_timelion"], + "timelion": ["src/plugins/timelion", "src/plugins/vis_type_timelion"], "uiActions": "src/plugins/ui_actions", "visDefaultEditor": "src/plugins/vis_default_editor", "visTypeMarkdown": "src/plugins/vis_type_markdown", diff --git a/.sass-lint.yml b/.sass-lint.yml index 56b85adca8a71..50cbe81cc7da2 100644 --- a/.sass-lint.yml +++ b/.sass-lint.yml @@ -1,7 +1,7 @@ files: include: - 'src/legacy/core_plugins/metrics/**/*.s+(a|c)ss' - - 'src/legacy/core_plugins/timelion/**/*.s+(a|c)ss' + - 'src/plugins/timelion/**/*.s+(a|c)ss' - 'src/plugins/vis_type_vislib/**/*.s+(a|c)ss' - 'src/plugins/vis_type_xy/**/*.s+(a|c)ss' - 'x-pack/plugins/canvas/**/*.s+(a|c)ss' diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a0aeed7a34949..11c595a1ad983 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,739 +1,5 @@ # Contributing to Kibana -We understand that you may not have days at a time to work on Kibana. We ask that you read our contributing guidelines carefully so that you spend less time, overall, struggling to push your PR through our code review processes. +We understand that you may not have days at a time to work on Kibana. We ask that you read our [developer guide](https://www.elastic.co/guide/en/kibana/master/development.html) carefully so that you spend less time, overall, struggling to push your PR through our code review processes. -At the same time, reading the contributing guidelines will give you a better idea of how to post meaningful issues that will be more easily be parsed, considered, and resolved. A big win for everyone involved! :tada: - -## Table of Contents - -A high level overview of our contributing guidelines. - -- [Effective issue reporting in Kibana](#effective-issue-reporting-in-kibana) - - [Voicing the importance of an issue](#voicing-the-importance-of-an-issue) - - ["My issue isn't getting enough attention"](#my-issue-isnt-getting-enough-attention) - - ["I want to help!"](#i-want-to-help) -- [How We Use Git and GitHub](#how-we-use-git-and-github) - - [Forking](#forking) - - [Branching](#branching) - - [Commits and Merging](#commits-and-merging) - - [Rebasing and fixing merge conflicts](#rebasing-and-fixing-merge-conflicts) - - [What Goes Into a Pull Request](#what-goes-into-a-pull-request) -- [Contributing Code](#contributing-code) - - [Setting Up Your Development Environment](#setting-up-your-development-environment) - - [Increase node.js heap size](#increase-nodejs-heap-size) - - [Running Elasticsearch Locally](#running-elasticsearch-locally) - - [Nightly snapshot (recommended)](#nightly-snapshot-recommended) - - [Keeping data between snapshots](#keeping-data-between-snapshots) - - [Source](#source) - - [Archive](#archive) - - [Sample Data](#sample-data) - - [Running Elasticsearch Remotely](#running-elasticsearch-remotely) - - [Running remote clusters](#running-remote-clusters) - - [Running Kibana](#running-kibana) - - [Running Kibana in Open-Source mode](#running-kibana-in-open-source-mode) - - [Unsupported URL Type](#unsupported-url-type) - - [Customizing `config/kibana.dev.yml`](#customizing-configkibanadevyml) - - [Potential Optimization Pitfalls](#potential-optimization-pitfalls) - - [Setting Up SSL](#setting-up-ssl) - - [Linting](#linting) - - [Setup Guide for VS Code Users](#setup-guide-for-vs-code-users) - - [Internationalization](#internationalization) - - [Localization](#localization) - - [Styling with SASS](#styling-with-sass) - - [Testing and Building](#testing-and-building) - - [Debugging server code](#debugging-server-code) - - [Instrumenting with Elastic APM](#instrumenting-with-elastic-apm) - - [Unit testing frameworks](#unit-testing-frameworks) - - [Running specific Kibana tests](#running-specific-kibana-tests) - - [Debugging Unit Tests](#debugging-unit-tests) - - [Unit Testing Plugins](#unit-testing-plugins) - - [Automated Accessibility Testing](#automated-accessibility-testing) - - [Cross-browser compatibility](#cross-browser-compatibility) - - [Testing compatibility locally](#testing-compatibility-locally) - - [Running Browser Automation Tests](#running-browser-automation-tests) - - [Building OS packages](#building-os-packages) - - [Writing documentation](#writing-documentation) - - [Release Notes Process](#release-notes-process) -- [Signing the contributor license agreement](#signing-the-contributor-license-agreement) -- [Submitting a Pull Request](#submitting-a-pull-request) -- [Code Reviewing](#code-reviewing) - - [Getting to the Code Review Stage](#getting-to-the-code-review-stage) - - [Reviewing Pull Requests](#reviewing-pull-requests) - -Don't fret, it's not as daunting as the table of contents makes it out to be! - -## Effective issue reporting in Kibana - -### Voicing the importance of an issue - -We seriously appreciate thoughtful comments. If an issue is important to you, add a comment with a solid write up of your use case and explain why it's so important. Please avoid posting comments comprised solely of a thumbs up emoji 👍. - -Granted that you share your thoughts, we might even be able to come up with creative solutions to your specific problem. If everything you'd like to say has already been brought up but you'd still like to add a token of support, feel free to add a [👍 thumbs up reaction](https://github.com/blog/2119-add-reactions-to-pull-requests-issues-and-comments) on the issue itself and on the comment which best summarizes your thoughts. - -### "My issue isn't getting enough attention" - -First of all, **sorry about that!** We want you to have a great time with Kibana. - -There's hundreds of open issues and prioritizing what to work on is an important aspect of our daily jobs. We prioritize issues according to impact and difficulty, so some issues can be neglected while we work on more pressing issues. - -Feel free to bump your issues if you think they've been neglected for a prolonged period. - -### "I want to help!" - -**Now we're talking**. If you have a bug fix or new feature that you would like to contribute to Kibana, please **find or open an issue about it before you start working on it.** Talk about what you would like to do. It may be that somebody is already working on it, or that there are particular issues that you should know about before implementing the change. - -We enjoy working with contributors to get their code accepted. There are many approaches to fixing a problem and it is important to find the best approach before writing too much code. - -## How We Use Git and GitHub - -### Forking - -We follow the [GitHub forking model](https://help.github.com/articles/fork-a-repo/) for collaborating -on Kibana code. This model assumes that you have a remote called `upstream` which points to the -official Kibana repo, which we'll refer to in later code snippets. - -### Branching - -* All work on the next major release goes into master. -* Past major release branches are named `{majorVersion}.x`. They contain work that will go into the next minor release. For example, if the next minor release is `5.2.0`, work for it should go into the `5.x` branch. -* Past minor release branches are named `{majorVersion}.{minorVersion}`. They contain work that will go into the next patch release. For example, if the next patch release is `5.3.1`, work for it should go into the `5.3` branch. -* All work is done on feature branches and merged into one of these branches. -* Where appropriate, we'll backport changes into older release branches. - -### Commits and Merging - -* Feel free to make as many commits as you want, while working on a branch. -* When submitting a PR for review, please perform an interactive rebase to present a logical history that's easy for the reviewers to follow. -* Please use your commit messages to include helpful information on your changes, e.g. changes to APIs, UX changes, bugs fixed, and an explanation of *why* you made the changes that you did. -* Resolve merge conflicts by rebasing the target branch over your feature branch, and force-pushing (see below for instructions). -* When merging, we'll squash your commits into a single commit. - -#### Rebasing and fixing merge conflicts - -Rebasing can be tricky, and fixing merge conflicts can be even trickier because it involves force pushing. This is all compounded by the fact that attempting to push a rebased branch remotely will be rejected by git, and you'll be prompted to do a `pull`, which is not at all what you should do (this will really mess up your branch's history). - -Here's how you should rebase master onto your branch, and how to fix merge conflicts when they arise. - -First, make sure master is up-to-date. - -``` -git checkout master -git fetch upstream -git rebase upstream/master -``` - -Then, check out your branch and rebase master on top of it, which will apply all of the new commits on master to your branch, and then apply all of your branch's new commits after that. - -``` -git checkout name-of-your-branch -git rebase master -``` - -You want to make sure there are no merge conflicts. If there are merge conflicts, git will pause the rebase and allow you to fix the conflicts before continuing. - -You can use `git status` to see which files contain conflicts. They'll be the ones that aren't staged for commit. Open those files, and look for where git has marked the conflicts. Resolve the conflicts so that the changes you want to make to the code have been incorporated in a way that doesn't destroy work that's been done in master. Refer to master's commit history on GitHub if you need to gain a better understanding of how code is conflicting and how best to resolve it. - -Once you've resolved all of the merge conflicts, use `git add -A` to stage them to be committed, and then use `git rebase --continue` to tell git to continue the rebase. - -When the rebase has completed, you will need to force push your branch because the history is now completely different than what's on the remote. **This is potentially dangerous** because it will completely overwrite what you have on the remote, so you need to be sure that you haven't lost any work when resolving merge conflicts. (If there weren't any merge conflicts, then you can force push without having to worry about this.) - -``` -git push origin name-of-your-branch --force -``` - -This will overwrite the remote branch with what you have locally. You're done! - -**Note that you should not run `git pull`**, for example in response to a push rejection like this: - -``` -! [rejected] name-of-your-branch -> name-of-your-branch (non-fast-forward) -error: failed to push some refs to 'https://github.com/YourGitHubHandle/kibana.git' -hint: Updates were rejected because the tip of your current branch is behind -hint: its remote counterpart. Integrate the remote changes (e.g. -hint: 'git pull ...') before pushing again. -hint: See the 'Note about fast-forwards' in 'git push --help' for details. -``` - -Assuming you've successfully rebased and you're happy with the code, you should force push instead. - -### What Goes Into a Pull Request - -* Please include an explanation of your changes in your PR description. -* Links to relevant issues, external resources, or related PRs are very important and useful. -* Please update any tests that pertain to your code, and add new tests where appropriate. -* See [Submitting a Pull Request](#submitting-a-pull-request) for more info. - -## Contributing Code - -These guidelines will help you get your Pull Request into shape so that a code review can start as soon as possible. - -### Setting Up Your Development Environment - -Fork, then clone the `kibana` repo and change directory into it - -```bash -git clone https://github.com/[YOUR_USERNAME]/kibana.git kibana -cd kibana -``` - -Install the version of Node.js listed in the `.node-version` file. This can be automated with tools such as [nvm](https://github.com/creationix/nvm), [nvm-windows](https://github.com/coreybutler/nvm-windows) or [avn](https://github.com/wbyoung/avn). As we also include a `.nvmrc` file you can switch to the correct version when using nvm by running: - -```bash -nvm use -``` - -Install the latest version of [yarn](https://yarnpkg.com). - -Bootstrap Kibana and install all the dependencies - -```bash -yarn kbn bootstrap -``` - -> Node.js native modules could be in use and node-gyp is the tool used to build them. There are tools you need to install per platform and python versions you need to be using. Please see https://github.com/nodejs/node-gyp#installation and follow the guide according your platform. - -(You can also run `yarn kbn` to see the other available commands. For more info about this tool, see https://github.com/elastic/kibana/tree/master/packages/kbn-pm.) - -When switching branches which use different versions of npm packages you may need to run; -```bash -yarn kbn clean -``` - -If you have failures during `yarn kbn bootstrap` you may have some corrupted packages in your yarn cache which you can clean with; -```bash -yarn cache clean -``` - -#### Increase node.js heap size - -Kibana is a big project and for some commands it can happen that the process hits the default heap limit and crashes with an out-of-memory error. If you run into this problem, you can increase maximum heap size by setting the `--max_old_space_size` option on the command line. To set the limit for all commands, simply add the following line to your shell config: `export NODE_OPTIONS="--max_old_space_size=2048"`. - -### Running Elasticsearch Locally - -There are a few options when it comes to running Elasticsearch locally: - -#### Nightly snapshot (recommended) - -These snapshots are built on a nightly basis which expire after a couple weeks. If running from an old, untracted branch this snapshot might not exist. In which case you might need to run from source or an archive. - -```bash -yarn es snapshot -``` - -##### Keeping data between snapshots - -If you want to keep the data inside your Elasticsearch between usages of this command, -you should use the following command, to keep your data folder outside the downloaded snapshot -folder: - -```bash -yarn es snapshot -E path.data=../data -``` - -The same parameter can be used with the source and archive command shown in the following -paragraphs. - -#### Source - -By default, it will reference an [elasticsearch](https://github.com/elastic/elasticsearch) checkout which is a sibling to the Kibana directory named `elasticsearch`. If you wish to use a checkout in another location you can provide that by supplying `--source-path` - -```bash -yarn es source -``` - -#### Archive - -Use this if you already have a distributable. For released versions, one can be obtained on the [Elasticsearch downloads](https://www.elastic.co/downloads/elasticsearch) page. - -```bash -yarn es archive -``` - -**Each of these will run Elasticsearch with a `basic` license. Additional options are available, pass `--help` for more information.** - -##### Sample Data - -If you're just getting started with Elasticsearch, you could use the following command to populate your instance with a few fake logs to hit the ground running. - -```bash -node scripts/makelogs --auth : -``` -> The default username and password combination are `elastic:changeme` - -> Make sure to execute `node scripts/makelogs` *after* elasticsearch is up and running! - -### Running Elasticsearch Remotely - -You can save some system resources, and the effort of generating sample data, if you have a remote Elasticsearch cluster to connect to. (**Elasticians: you do! Check with your team about where to find credentials**) - -You'll need to [create a `kibana.dev.yml`](#customizing-configkibanadevyml) and add the following to it: - -``` -elasticsearch.hosts: - - {{ url }} -elasticsearch.username: {{ username }} -elasticsearch.password: {{ password }} -elasticsearch.ssl.verificationMode: none -``` - -If many other users will be interacting with your remote cluster, you'll want to add the following to avoid causing conflicts: - -``` -kibana.index: '.{YourGitHubHandle}-kibana' -xpack.task_manager.index: '.{YourGitHubHandle}-task-manager-kibana' -``` - -### Running remote clusters -Setup remote clusters for cross cluster search (CCS) and cross cluster replication (CCR). - -Start your primary cluster by running: -```bash -yarn es snapshot -E path.data=../data_prod1 -``` - -Start your remote cluster by running: -```bash -yarn es snapshot -E transport.port=9500 -E http.port=9201 -E path.data=../data_prod2 -``` - -Once both clusters are running, start kibana. Kibana will connect to the primary cluster. - -Setup the remote cluster in Kibana from either `Management` -> `Elasticsearch` -> `Remote Clusters` UI or by running the following script in `Console`. -``` -PUT _cluster/settings -{ - "persistent": { - "cluster": { - "remote": { - "cluster_one": { - "seeds": [ - "localhost:9500" - ] - } - } - } - } -} -``` - -Follow the [cross-cluster search](https://www.elastic.co/guide/en/kibana/current/management-cross-cluster-search.html) instructions for setting up index patterns to search across clusters. - -### Running Kibana - -Change to your local Kibana directory. -Start the development server. - -```bash -yarn start -``` - -> On Windows, you'll need to use Git Bash, Cygwin, or a similar shell that exposes the `sh` command. And to successfully build you'll need Cygwin optional packages zip, tar, and shasum. - -Now you can point your web browser to http://localhost:5601 and start using Kibana! When running `yarn start`, Kibana will also log that it is listening on port 5603 due to the base path proxy, but you should still access Kibana on port 5601. - -By default, you can log in with username `elastic` and password `changeme`. See the `--help` options on `yarn es ` if you'd like to configure a different password. - -#### Running Kibana in Open-Source mode - -If you're looking to only work with the open-source software, supply the license type to `yarn es`: - -```bash -yarn es snapshot --license oss -``` - -And start Kibana with only open-source code: - -```bash -yarn start --oss -``` - -#### Unsupported URL Type - -If you're installing dependencies and seeing an error that looks something like - -``` -Unsupported URL Type: link:packages/eslint-config-kibana -``` - -you're likely running `npm`. To install dependencies in Kibana you need to run `yarn kbn bootstrap`. For more info, see [Setting Up Your Development Environment](#setting-up-your-development-environment) above. - -#### Customizing `config/kibana.dev.yml` - -The `config/kibana.yml` file stores user configuration directives. Since this file is checked into source control, however, developer preferences can't be saved without the risk of accidentally committing the modified version. To make customizing configuration easier during development, the Kibana CLI will look for a `config/kibana.dev.yml` file if run with the `--dev` flag. This file behaves just like the non-dev version and accepts any of the [standard settings](https://www.elastic.co/guide/en/kibana/current/settings.html). - -#### Potential Optimization Pitfalls - - - Webpack is trying to include a file in the bundle that I deleted and is now complaining about it is missing - - A module id that used to resolve to a single file now resolves to a directory, but webpack isn't adapting - - (if you discover other scenarios, please send a PR!) - -#### Setting Up SSL - -Kibana includes self-signed certificates that can be used for development purposes in the browser and for communicating with Elasticsearch: `yarn start --ssl` & `yarn es snapshot --ssl`. - -### Linting - -A note about linting: We use [eslint](http://eslint.org) to check that the [styleguide](STYLEGUIDE.md) is being followed. It runs in a pre-commit hook and as a part of the tests, but most contributors integrate it with their code editors for real-time feedback. - -Here are some hints for getting eslint setup in your favorite editor: - -Editor | Plugin ------------|------------------------------------------------------------------------------- -Sublime | [SublimeLinter-eslint](https://github.com/roadhump/SublimeLinter-eslint#installation) -Atom | [linter-eslint](https://github.com/AtomLinter/linter-eslint#installation) -VSCode | [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) -IntelliJ | Settings » Languages & Frameworks » JavaScript » Code Quality Tools » ESLint -`vi` | [scrooloose/syntastic](https://github.com/scrooloose/syntastic) - -Another tool we use for enforcing consistent coding style is EditorConfig, which can be set up by installing a plugin in your editor that dynamically updates its configuration. Take a look at the [EditorConfig](http://editorconfig.org/#download) site to find a plugin for your editor, and browse our [`.editorconfig`](https://github.com/elastic/kibana/blob/master/.editorconfig) file to see what config rules we set up. - -#### Setup Guide for VS Code Users - -Note that for VSCode, to enable "live" linting of TypeScript (and other) file types, you will need to modify your local settings, as shown below. The default for the ESLint extension is to only lint JavaScript file types. - -```json -"eslint.validate": [ - "javascript", - "javascriptreact", - { "language": "typescript", "autoFix": true }, - { "language": "typescriptreact", "autoFix": true } -] -``` - -`eslint` can automatically fix trivial lint errors when you save a file by adding this line in your setting. - -```json - "eslint.autoFixOnSave": true, -``` - -:warning: It is **not** recommended to use the [`Prettier` extension/IDE plugin](https://prettier.io/) while maintaining the Kibana project. Formatting and styling roles are set in the multiple `.eslintrc.js` files across the project and some of them use the [NPM version of Prettier](https://www.npmjs.com/package/prettier). Using the IDE extension might cause conflicts, applying the formatting to too many files that shouldn't be prettier-ized and/or highlighting errors that are actually OK. - -### Internationalization - -All user-facing labels and info texts in Kibana should be internationalized. Please take a look at the [readme](packages/kbn-i18n/README.md) and the [guideline](packages/kbn-i18n/GUIDELINE.md) of the i18n package on how to do so. - -In order to enable translations in the React parts of the application, the top most component of every `ReactDOM.render` call should be the `Context` component from the `i18n` core service: -```jsx -const I18nContext = coreStart.i18n.Context; - -ReactDOM.render( - - {myComponentTree} - , - container -); -``` - -There are a number of tools created to support internationalization in Kibana that would allow one to validate internationalized labels, -extract them to a `JSON` file or integrate translations back to Kibana. To know more, please read corresponding [readme](src/dev/i18n/README.md) file. - -### Localization - -We cannot support accepting contributions to the translations from any source other than the translators we have engaged to do the work. -We are still to develop a proper process to accept any contributed translations. We certainly appreciate that people care enough about the localization effort to want to help improve the quality. We aim to build out a more comprehensive localization process for the future and will notify you once contributions can be supported, but for the time being, we are not able to incorporate suggestions. - -### Styling with SASS - -When writing a new component, create a sibling SASS file of the same name and import directly into the JS/TS component file. Doing so ensures the styles are never separated or lost on import and allows for better modularization (smaller individual plugin asset footprint). - -All SASS (.scss) files will automatically build with the [EUI](https://elastic.github.io/eui/#/guidelines/sass) & Kibana invisibles (SASS variables, mixins, functions) from the [`globals_[theme].scss` file](src/legacy/ui/public/styles/_globals_v7light.scss). - -**Example:** - -```tsx -// component.tsx - -import './component.scss'; - -export const Component = () => { - return ( -
- ); -} -``` - -```scss -// component.scss - -.plgComponent { ... } -``` - -Do not use the underscore `_` SASS file naming pattern when importing directly into a javascript file. - -### Testing and Building - -To ensure that your changes will not break other functionality, please run the test suite and build process before submitting your Pull Request. - -Before running the tests you will need to install the projects dependencies as described above. - -Once that's done, just run: - -```bash -yarn test && yarn build --skip-os-packages -``` - -You can get all build options using the following command: - -```bash -yarn build --help -``` - -macOS users on a machine with a discrete graphics card may see significant speedups (up to 2x) when running tests by changing your terminal emulator's GPU settings. In iTerm2: -- Open Preferences (Command + ,) -- In the General tab, under the "Magic" section, ensure "GPU rendering" is checked -- Open "Advanced GPU Settings..." -- Uncheck the "Prefer integrated to discrete GPU" option -- Restart iTerm - -#### Debugging Server Code -`yarn debug` will start the server with Node's inspect flag. Kibana's development mode will start three processes on ports `9229`, `9230`, and `9231`. Chrome's developer tools need to be configured to connect to all three connections. Add `localhost:` for each Kibana process in Chrome's developer tools connection tab. - -#### Instrumenting with Elastic APM -Kibana ships with the [Elastic APM Node.js Agent](https://github.com/elastic/apm-agent-nodejs) built-in for debugging purposes. - -Its default configuration is meant to be used by core Kibana developers only, but it can easily be re-configured to your needs. -In its default configuration it's disabled and will, once enabled, send APM data to a centrally managed Elasticsearch cluster accessible only to Elastic employees. - -To change the location where data is sent, use the [`serverUrl`](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#server-url) APM config option. -To activate the APM agent, use the [`active`](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#active) APM config option. - -All config options can be set either via environment variables, or by creating an appropriate config file under `config/apm.dev.js`. -For more information about configuring the APM agent, please refer to [the documentation](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuring-the-agent.html). - -Example `config/apm.dev.js` file: - -```js -module.exports = { - active: true, -}; -``` - -APM [Real User Monitoring agent](https://www.elastic.co/guide/en/apm/agent/rum-js/current/index.html) is not available in the Kibana distributables, -however the agent can be enabled by setting `ELASTIC_APM_ACTIVE` to `true`. -flags -``` -ELASTIC_APM_ACTIVE=true yarn start -// activates both Node.js and RUM agent -``` - -Once the agent is active, it will trace all incoming HTTP requests to Kibana, monitor for errors, and collect process-level metrics. -The collected data will be sent to the APM Server and is viewable in the APM UI in Kibana. - -#### Unit testing frameworks -Kibana is migrating unit testing from Mocha to Jest. Legacy unit tests still -exist in Mocha but all new unit tests should be written in Jest. Mocha tests -are contained in `__tests__` directories. Whereas Jest tests are stored in -the same directory as source code files with the `.test.js` suffix. - -#### Running specific Kibana tests - -The following table outlines possible test file locations and how to invoke them: - -| Test runner | Test location | Runner command (working directory is kibana root) | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -| Jest | `src/**/*.test.js`
`src/**/*.test.ts` | `yarn test:jest -t regexp [test path]` | -| Jest (integration) | `**/integration_tests/**/*.test.js` | `yarn test:jest_integration -t regexp [test path]` | -| Mocha | `src/**/__tests__/**/*.js`
`!src/**/public/__tests__/*.js`
`packages/kbn-datemath/test/**/*.js`
`packages/kbn-dev-utils/src/**/__tests__/**/*.js`
`tasks/**/__tests__/**/*.js` | `node scripts/mocha --grep=regexp [test path]` | -| Functional | `test/*integration/**/config.js`
`test/*functional/**/config.js`
`test/accessibility/config.js` | `yarn test:ftr:server --config test/[directory]/config.js`
`yarn test:ftr:runner --config test/[directory]/config.js --grep=regexp` | -| Karma | `src/**/public/__tests__/*.js` | `yarn test:karma:debug` | - -For X-Pack tests located in `x-pack/` see [X-Pack Testing](x-pack/README.md#testing) - -Test runner arguments: - - Where applicable, the optional arguments `-t=regexp` or `--grep=regexp` will only run tests or test suites whose descriptions matches the regular expression. - - `[test path]` is the relative path to the test file. - - Examples: - - Run the entire elasticsearch_service test suite: - ``` - yarn test:jest src/core/server/elasticsearch/elasticsearch_service.test.ts - ``` - - Run the jest test case whose description matches `stops both admin and data clients`: - ``` - yarn test:jest -t 'stops both admin and data clients' src/core/server/elasticsearch/elasticsearch_service.test.ts - ``` - - Run the api integration test case whose description matches the given string: - ``` - yarn test:ftr:server --config test/api_integration/config.js - yarn test:ftr:runner --config test/api_integration/config.js --grep='should return 404 if id does not match any sample data sets' - ``` - -#### Debugging Unit Tests - -The standard `yarn test` task runs several sub tasks and can take several minutes to complete, making debugging failures pretty painful. In order to ease the pain specialized tasks provide alternate methods for running the tests. - -You could also add the `--debug` option so that `node` is run using the `--debug-brk` flag. You'll need to connect a remote debugger such as [`node-inspector`](https://github.com/node-inspector/node-inspector) to proceed in this mode. - -```bash -node scripts/mocha --debug -``` - -With `yarn test:karma`, you can run only the browser tests. Coverage reports are available for browser tests by running `yarn test:coverage`. You can find the results under the `coverage/` directory that will be created upon completion. - -```bash -yarn test:karma -``` - -Using `yarn test:karma:debug` initializes an environment for debugging the browser tests. Includes an dedicated instance of the kibana server for building the test bundle, and a karma server. When running this task the build is optimized for the first time and then a karma-owned instance of the browser is opened. Click the "debug" button to open a new tab that executes the unit tests. - -```bash -yarn test:karma:debug -``` - -In the screenshot below, you'll notice the URL is `localhost:9876/debug.html`. You can append a `grep` query parameter to this URL and set it to a string value which will be used to exclude tests which don't match. For example, if you changed the URL to `localhost:9876/debug.html?query=my test` and then refreshed the browser, you'd only see tests run which contain "my test" in the test description. - - -![Browser test debugging](http://i.imgur.com/DwHxgfq.png) - -#### Unit Testing Plugins - -This should work super if you're using the [Kibana plugin generator](https://github.com/elastic/kibana/tree/master/packages/kbn-plugin-generator). If you're not using the generator, well, you're on your own. We suggest you look at how the generator works. - -To run the tests for just your particular plugin run the following command from your plugin: - -```bash -yarn test:mocha -yarn test:karma:debug # remove the debug flag to run them once and close -``` - -#### Automated Accessibility Testing - -To run the tests locally: - -1. In one terminal window run `node scripts/functional_tests_server --config test/accessibility/config.ts` -2. In another terminal window run `node scripts/functional_test_runner.js --config test/accessibility/config.ts` - -To run the x-pack tests, swap the config file out for `x-pack/test/accessibility/config.ts`. - -After the server is up, you can go to this instance of Kibana at `localhost:5620`. - -The testing is done using [axe](https://github.com/dequelabs/axe-core). The same thing that runs in CI, -can be run locally using their browser plugins: - -- [Chrome](https://chrome.google.com/webstore/detail/axe-web-accessibility-tes/lhdoppojpmngadmnindnejefpokejbdd?hl=en-US) -- [Firefox](https://addons.mozilla.org/en-US/firefox/addon/axe-devtools/) - -#### Cross-browser Compatibility - -##### Testing Compatibility Locally - -###### Testing IE on OS X - -* [Download VMWare Fusion](http://www.vmware.com/products/fusion/fusion-evaluation.html). -* [Download IE virtual machines](https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/#downloads) for VMWare. -* Open VMWare and go to Window > Virtual Machine Library. Unzip the virtual machine and drag the .vmx file into your Virtual Machine Library. -* Right-click on the virtual machine you just added to your library and select "Snapshots...", and then click the "Take" button in the modal that opens. You can roll back to this snapshot when the VM expires in 90 days. -* In System Preferences > Sharing, change your computer name to be something simple, e.g. "computer". -* Run Kibana with `yarn start --host=computer.local` (substituting your computer name). -* Now you can run your VM, open the browser, and navigate to `http://computer.local:5601` to test Kibana. -* Alternatively you can use browserstack - -##### Running Browser Automation Tests - -[Read about the `FunctionalTestRunner`](https://www.elastic.co/guide/en/kibana/current/development-functional-tests.html) to learn more about how you can run and develop functional tests for Kibana core and plugins. - -You can also look into the [Scripts README.md](./scripts/README.md) to learn more about using the node scripts we provide for building Kibana, running integration tests, and starting up Kibana and Elasticsearch while you develop. - -### Building OS packages - -Packages are built using fpm, dpkg, and rpm. Package building has only been tested on Linux and is not supported on any other platform. - -```bash -apt-get install ruby-dev rpm -gem install fpm -v 1.5.0 -yarn build --skip-archives -``` - -To specify a package to build you can add `rpm` or `deb` as an argument. - -```bash -yarn build --rpm -``` - -Distributable packages can be found in `target/` after the build completes. - -### Writing documentation - -Kibana documentation is written in [asciidoc](http://asciidoc.org/) format in -the `docs/` directory. - -To build the docs, clone the [elastic/docs](https://github.com/elastic/docs) -repo as a sibling of your Kibana repo. Follow the instructions in that project's -README for getting the docs tooling set up. - -**To build the Kibana docs and open them in your browser:** - -```bash -./docs/build_docs --doc kibana/docs/index.asciidoc --chunk 1 --open -``` -or - -```bash -node scripts/docs.js --open -``` - -### Release Notes process - -Part of this process only applies to maintainers, since it requires access to GitHub labels. - -Kibana publishes [Release Notes](https://www.elastic.co/guide/en/kibana/current/release-notes.html) for major and minor releases. The Release Notes summarize what the PRs accomplish in language that is meaningful to users. To generate the Release Notes, the team runs a script against this repo to collect the merged PRs against the release. - -#### Create the Release Notes text -The text that appears in the Release Notes is pulled directly from your PR title, or a single paragraph of text that you specify in the PR description. - -To use a single paragraph of text, enter `Release note:` or a `## Release note` header in the PR description, followed by your text. For example, refer to this [PR](https://github.com/elastic/kibana/pull/65796) that uses the `## Release note` header. - -When you create the Release Notes text, use the following best practices: -* Use present tense. -* Use sentence case. -* When you create a feature PR, start with `Adds`. -* When you create an enhancement PR, start with `Improves`. -* When you create a bug fix PR, start with `Fixes`. -* When you create a deprecation PR, start with `Deprecates`. - -#### Add your labels -1. Label the PR with the targeted version (ex: `v7.3.0`). -2. Label the PR with the appropriate GitHub labels: - * For a new feature or functionality, use `release_note:enhancement`. - * For an external-facing fix, use `release_note:fix`. We do not include docs, build, and test fixes in the Release Notes, or unreleased issues that are only on `master`. - * For a deprecated feature, use `release_note:deprecation`. - * For a breaking change, use `release_note:breaking`. - * To **NOT** include your changes in the Release Notes, use `release_note:skip`. - -We also produce a blog post that details more important breaking API changes in every major and minor release. When your PR includes a breaking API change, add the `release_note:dev_docs` label, and add a brief summary of the break at the bottom of the PR using the format below: - -``` -# Dev Docs - -## Name the feature with the break (ex: Visualize Loader) - -Summary of the change. Anything Under `#Dev Docs` is used in the blog. -``` - -## Signing the contributor license agreement - -Please make sure you have signed the [Contributor License Agreement](http://www.elastic.co/contributor-agreement/). We are not asking you to assign copyright to us, but to give us the right to distribute your code without restriction. We ask this of all contributors in order to assure our users of the origin and continuing existence of the code. You only need to sign the CLA once. - -## Submitting a Pull Request - -Push your local changes to your forked copy of the repository and submit a Pull Request. In the Pull Request, describe what your changes do and mention the number of the issue where discussion has taken place, e.g., “Closes #123″. - -Always submit your pull against `master` unless the bug is only present in an older version. If the bug affects both `master` and another branch say so in your pull. - -Then sit back and wait. There will probably be discussion about the Pull Request and, if any changes are needed, we'll work with you to get your Pull Request merged into Kibana. - -## Code Reviewing - -After a pull is submitted, it needs to get to review. If you have commit permission on the Kibana repo you will probably perform these steps while submitting your Pull Request. If not, a member of the Elastic organization will do them for you, though you can help by suggesting a reviewer for your changes if you've interacted with someone while working on the issue. - -### Getting to the Code Review Stage - -1. Assign the `review` label. This signals to the team that someone needs to give this attention. -1. Do **not** assign a version label. Someone from Elastic staff will assign a version label, if necessary, when your Pull Request is ready to be merged. -1. Find someone to review your pull. Don't just pick any yahoo, pick the right person. The right person might be the original reporter of the issue, but it might also be the person most familiar with the code you've changed. If neither of those things apply, or your change is small in scope, try to find someone on the Kibana team without a ton of existing reviews on their plate. As a rule, most pulls will require 2 reviewers, but the first reviewer will pick the 2nd. - -### Reviewing Pull Requests - -So, you've been assigned a pull to review. Check out our [pull request review guidelines](https://www.elastic.co/guide/en/kibana/master/pr-review.html) for our general philosophy for pull request reviewers. - -Thank you so much for reading our guidelines! :tada: +Our developer guide is written in asciidoc and located under [./docs/developer](./docs/developer) if you want to make edits or access it in raw form. diff --git a/Jenkinsfile b/Jenkinsfile index 7869fa68788bd..69c61b5bfa988 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -41,7 +41,7 @@ kibanaPipeline(timeoutMinutes: 155, checkPrChanges: true, setCommitStatus: true) 'xpack-ciGroup9': kibanaPipeline.xpackCiGroupProcess(9), 'xpack-ciGroup10': kibanaPipeline.xpackCiGroupProcess(10), 'xpack-accessibility': kibanaPipeline.functionalTestProcess('xpack-accessibility', './test/scripts/jenkins_xpack_accessibility.sh'), - // 'xpack-pageLoadMetrics': kibanaPipeline.functionalTestProcess('xpack-pageLoadMetrics', './test/scripts/jenkins_xpack_page_load_metrics.sh'), + 'xpack-savedObjectsFieldMetrics': kibanaPipeline.functionalTestProcess('xpack-savedObjectsFieldMetrics', './test/scripts/jenkins_xpack_saved_objects_field_metrics.sh'), 'xpack-securitySolutionCypress': { processNumber -> whenChanged(['x-pack/plugins/security_solution/', 'x-pack/test/security_solution_cypress/']) { kibanaPipeline.functionalTestProcess('xpack-securitySolutionCypress', './test/scripts/jenkins_security_solution_cypress.sh')(processNumber) diff --git a/NOTICE.txt b/NOTICE.txt index 94312d46c35ec..56280e6e3883e 100644 --- a/NOTICE.txt +++ b/NOTICE.txt @@ -147,6 +147,70 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +--- +Detection Rules +Copyright 2020 Elasticsearch B.V. + +--- +This product bundles rules based on https://github.com/BlueTeamLabs/sentinel-attack +which is available under a "MIT" license. The files based on this license are: + +- defense_evasion_via_filter_manager +- discovery_process_discovery_via_tasklist_command +- persistence_priv_escalation_via_accessibility_features +- persistence_via_application_shimming +- defense_evasion_execution_via_trusted_developer_utilities + +MIT License + +Copyright (c) 2019 Edoardo Gerosa, Olaf Hartong + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies +of the Software, and to permit persons to whom the Software is furnished to do +so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +--- +This product bundles rules based on https://github.com/FSecureLABS/leonidas +which is available under a "MIT" license. The files based on this license are: + +- credential_access_secretsmanager_getsecretvalue.toml + +MIT License + +Copyright (c) 2020 F-Secure LABS + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + --- This product bundles bootstrap@3.3.6 which is available under a "MIT" license. @@ -220,38 +284,6 @@ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. ---- -This product bundles rules based on https://github.com/BlueTeamLabs/sentinel-attack -which is available under a "MIT" license. The files based on this license are: - -- windows_defense_evasion_via_filter_manager.json -- windows_process_discovery_via_tasklist_command.json -- windows_priv_escalation_via_accessibility_features.json -- windows_persistence_via_application_shimming.json -- windows_execution_via_trusted_developer_utilities.json - -MIT License - -Copyright (c) 2019 Edoardo Gerosa, Olaf Hartong - -Permission is hereby granted, free of charge, to any person obtaining a copy of -this software and associated documentation files (the "Software"), to deal in -the Software without restriction, including without limitation the rights to -use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies -of the Software, and to permit persons to whom the Software is furnished to do -so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. - --- This product includes code that is adapted from mapbox-gl-js, which is available under a "BSD-3-Clause" license. diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index 48d4f929b6851..4ea7b04ebef6d 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -3,11 +3,18 @@ This guide applies to all development within the Kibana project and is recommended for the development of all Kibana plugins. +- [General](#general) +- [HTML](#html) +- [API endpoints](#api-endpoints) +- [TypeScript/JavaScript](#typeScript/javaScript) +- [SASS files](#sass-files) +- [React](#react) + Besides the content in this style guide, the following style guides may also apply to all development within the Kibana project. Please make sure to also read them: -- [Accessibility style guide](https://elastic.github.io/eui/#/guidelines/accessibility) -- [SASS style guide](https://elastic.github.io/eui/#/guidelines/sass) +- [Accessibility style guide (EUI Docs)](https://elastic.github.io/eui/#/guidelines/accessibility) +- [SASS style guide (EUI Docs)](https://elastic.github.io/eui/#/guidelines/sass) ## General @@ -582,6 +589,39 @@ Do not use setters, they cause more problems than they can solve. [sideeffect]: http://en.wikipedia.org/wiki/Side_effect_(computer_science) +## SASS files + +When writing a new component, create a sibling SASS file of the same name and import directly into the **top** of the JS/TS component file. Doing so ensures the styles are never separated or lost on import and allows for better modularization (smaller individual plugin asset footprint). + +All SASS (.scss) files will automatically build with the [EUI](https://elastic.github.io/eui/#/guidelines/sass) & Kibana invisibles (SASS variables, mixins, functions) from the [`globals_[theme].scss` file](src/legacy/ui/public/styles/_globals_v7light.scss). + +While the styles for this component will only be loaded if the component exists on the page, +the styles **will** be global and so it is recommended to use a three letter prefix on your +classes to ensure proper scope. + +**Example:** + +```tsx +// component.tsx + +import './component.scss'; +// All other imports below the SASS import + +export const Component = () => { + return ( +
+ ); +} +``` + +```scss +// component.scss + +.plgComponent { ... } +``` + +Do not use the underscore `_` SASS file naming pattern when importing directly into a javascript file. + ## React The following style guide rules are specific for working with the React framework. diff --git a/config/node.options b/config/node.options new file mode 100644 index 0000000000000..2927d1b576716 --- /dev/null +++ b/config/node.options @@ -0,0 +1,6 @@ +## Node command line options +## See `node --help` and `node --v8-options` for available options +## Please note you should specify one option per line + +## max size of old space in megabytes +#--max-old-space-size=4096 diff --git a/docs/api/dashboard/export-dashboard.asciidoc b/docs/api/dashboard/export-dashboard.asciidoc index 36c551dee84fc..2099fb599ba67 100644 --- a/docs/api/dashboard/export-dashboard.asciidoc +++ b/docs/api/dashboard/export-dashboard.asciidoc @@ -35,7 +35,7 @@ experimental[] Export dashboards and corresponding saved objects. [source,sh] -------------------------------------------------- -$ curl -X GET "localhost:5601/api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c" <1> +$ curl -X GET api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c <1> -------------------------------------------------- // KIBANA diff --git a/docs/api/dashboard/import-dashboard.asciidoc b/docs/api/dashboard/import-dashboard.asciidoc index 320859f78c617..020ec8018b85b 100644 --- a/docs/api/dashboard/import-dashboard.asciidoc +++ b/docs/api/dashboard/import-dashboard.asciidoc @@ -42,7 +42,7 @@ Use the complete response body from the < "index1", @@ -40,7 +40,9 @@ POST /api/upgrade_assistant/reindex/batch ] } -------------------------------------------------- -<1> The order in which the indices are provided here determines the order in which the reindex tasks will be executed. +// KIBANA + +<1> The order of the indices determines the order that the reindex tasks are executed. Similar to the <>, the API returns the following: diff --git a/docs/api/upgrade-assistant/check_reindex_status.asciidoc b/docs/api/upgrade-assistant/check_reindex_status.asciidoc index 00801f201d1e1..98cf263673f73 100644 --- a/docs/api/upgrade-assistant/check_reindex_status.asciidoc +++ b/docs/api/upgrade-assistant/check_reindex_status.asciidoc @@ -64,6 +64,7 @@ The API returns the following: `3`:: Paused ++ NOTE: If the {kib} node that started the reindex is shutdown or restarted, the reindex goes into a paused state after some time. To resume the reindex, you must submit a new POST request to the `/api/upgrade_assistant/reindex/` endpoint. diff --git a/docs/api/url-shortening.asciidoc b/docs/api/url-shortening.asciidoc index a62529e11a9ba..ffe1d925e5dcb 100644 --- a/docs/api/url-shortening.asciidoc +++ b/docs/api/url-shortening.asciidoc @@ -1,5 +1,5 @@ [[url-shortening-api]] -=== Shorten URL API +== Shorten URL API ++++ Shorten URL ++++ @@ -9,34 +9,39 @@ Internet Explorer has URL length restrictions, and some wiki and markup parsers Short URLs are designed to make sharing {kib} URLs easier. +[float] [[url-shortening-api-request]] -==== Request +=== Request `POST :/api/shorten_url` +[float] [[url-shortening-api-request-body]] -==== Request body +=== Request body `url`:: (Required, string) The {kib} URL that you want to shorten, relative to `/app/kibana`. +[float] [[url-shortening-api-response-body]] -==== Response body +=== Response body urlId:: A top-level property that contains the shortened URL token for the provided request body. +[float] [[url-shortening-api-codes]] -==== Response code +=== Response code `200`:: Indicates a successful call. +[float] [[url-shortening-api-example]] -==== Example +=== Example [source,sh] -------------------------------------------------- -$ curl -X POST "localhost:5601/api/shorten_url" +$ curl -X POST api/shorten_url { "url": "/app/kibana#/dashboard?_g=()&_a=(description:'',filters:!(),fullScreenMode:!f,options:(hidePanelTitles:!f,useMargins:!t),panels:!((embeddableConfig:(),gridData:(h:15,i:'1',w:24,x:0,y:0),id:'8f4d0c00-4c86-11e8-b3d7-01146121b73d',panelIndex:'1',type:visualization,version:'7.0.0-alpha1')),query:(language:lucene,query:''),timeRestore:!f,title:'New%20Dashboard',viewMode:edit)" } diff --git a/docs/api/using-api.asciidoc b/docs/api/using-api.asciidoc index e58d9c39ee8c4..c61edfb62b079 100644 --- a/docs/api/using-api.asciidoc +++ b/docs/api/using-api.asciidoc @@ -10,7 +10,23 @@ NOTE: The {kib} Console supports only Elasticsearch APIs. You are unable to inte [float] [[api-authentication]] === Authentication -{kib} supports token-based authentication with the same username and password that you use to log into the {kib} Console. In a given HTTP tool, and when available, you can select to use its 'Basic Authentication' option, which is where the username and password are stored in order to be passed as part of the call. +The {kib} APIs support key- and token-based authentication. + +[float] +[[token-api-authentication]] +==== Token-based authentication + +To use token-based authentication, you use the same username and password that you use to log into Elastic. +In a given HTTP tool, and when available, you can select to use its 'Basic Authentication' option, +which is where the username and password are stored in order to be passed as part of the call. + +[float] +[[key-authentication]] +==== Key-based authentication + +To use key-based authentication, you create an API key using the Elastic Console, then specify the key in the header of your API calls. + +For information about API keys, refer to <>. [float] [[api-calls]] @@ -31,7 +47,7 @@ For example, the following `curl` command exports a dashboard: [source,sh] -- -curl -X POST -u $USER:$PASSWORD "localhost:5601/api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c" +curl -X POST api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c -- // KIBANA @@ -51,7 +67,8 @@ For all APIs, you must use a request header. The {kib} APIs support the `kbn-xsr * XSRF protections are disabled using the `server.xsrf.disableProtection` setting `Content-Type: application/json`:: - Applicable only when you send a payload in the API request. {kib} API requests and responses use JSON. Typically, if you include the `kbn-xsrf` header, you must also include the `Content-Type` header. + Applicable only when you send a payload in the API request. {kib} API requests and responses use JSON. + Typically, if you include the `kbn-xsrf` header, you must also include the `Content-Type` header. Request header example: diff --git a/docs/apm/api.asciidoc b/docs/apm/api.asciidoc index 54159b642dd1a..97fdcd3e13de9 100644 --- a/docs/apm/api.asciidoc +++ b/docs/apm/api.asciidoc @@ -10,6 +10,7 @@ Some APM app features are provided via a REST API: * <> * <> +* <> [float] [[apm-api-example]] @@ -355,6 +356,7 @@ allowing you to easily see how these events are impacting the performance of you By default, annotations are stored in a newly created `observability-annotations` index. The name of this index can be changed in your `config.yml` by editing `xpack.observability.annotations.index`. +If you change the default index name, you'll also need to <> accordingly. The following APIs are available: @@ -396,7 +398,7 @@ include::api.asciidoc[tag=using-the-APIs] [%collapsible%open] ====== `version` ::: - (required, string) Name of service. + (required, string) Version of service. `environment` ::: (optional, string) Environment of service. @@ -467,3 +469,87 @@ curl -X POST \ } } -------------------------------------------------- + +//// +******************************************************* +//// + +[[kibana-api]] +=== Kibana API + +In addition to the APM specific API endpoints, Kibana provides its own <> +which you can use to automate certain aspects of configuring and deploying Kibana. +An example is below. + +[[api-create-apm-index-pattern]] +==== Customize the APM index pattern + +As an alternative to updating <> in your `kibana.yml` configuration file, +you can use Kibana's <> to update the default APM index pattern on the fly. + +The following example sets the default APM app index pattern to `some-other-pattern-*`: + +[source,sh] +---- +curl -X PUT "localhost:5601/api/saved_objects/index-pattern/apm_static_index_pattern_id" \ <1> +-H 'Content-Type: application/json' \ +-H 'kbn-xsrf: true' \ +-H 'Authorization: Basic ${YOUR_AUTH_TOKEN}' \ +-d' { + "attributes": { + "title": "some-other-pattern-*", <2> + } + }' +---- +<1> `apm_static_index_pattern_id` is the internal, hard-coded ID of the APM index pattern. +This value should not be changed +<2> Your custom index pattern matcher. + +The API returns the following: + +[source,json] +---- +{ + "id":"apm_static_index_pattern_id", + "type":"index-pattern", + "updated_at":"2020-07-06T22:55:59.555Z", + "version":"WzYsMV0=", + "attributes":{ + "title":"some-other-pattern-*" + } +} +---- + +To view the new APM app index pattern, use the <>: + +[source,sh] +---- +curl -X GET "localhost:5601/api/saved_objects/index-pattern/apm_static_index_pattern_id" \ <1> +-H 'kbn-xsrf: true' \ +-H 'Authorization: Basic ${YOUR_AUTH_TOKEN}' +---- +<1> `apm_static_index_pattern_id` is the internal, hard-coded ID of the APM index pattern. + +The API returns the following: + +[source,json] +---- +{ + "id":"apm_static_index_pattern_id", + "type":"index-pattern", + "updated_at":"2020-07-06T22:55:59.555Z", + "version":"WzYsMV0=", + "attributes":{...} + "fieldFormatMap":"{...} + "fields":"[{...},{...},...] + "sourceFilters":"[{\"value\":\"sourcemap.sourcemap\"}]", + "timeFieldName":"@timestamp", + "title":"some-other-pattern-*" + }, + ... +} +---- + +// More examples will go here + +More information on Kibana's API is available in <>. diff --git a/docs/apm/apm-app-users.asciidoc b/docs/apm/apm-app-users.asciidoc index 442a07d279725..d766c866f87e4 100644 --- a/docs/apm/apm-app-users.asciidoc +++ b/docs/apm/apm-app-users.asciidoc @@ -4,7 +4,7 @@ :beat_default_index_prefix: apm :beat_kib_app: APM app -:annotation_index: `observability-annotations` +:annotation_index: observability-annotations ++++ Users and privileges @@ -102,6 +102,54 @@ Here are two examples: *********************************** *********************************** //// +[role="xpack"] +[[apm-app-annotation-user-create]] +=== APM app annotation user + +++++ +Create an annotation user +++++ + +NOTE: By default, the `apm_user` built-in role provides access to Observability annotations. +You only need to create an annotation user if the default annotation index +defined in <> has been customized. + +[[apm-app-annotation-user]] +==== Annotation user + +View deployment annotations in the APM app. + +. Create a new role, named something like `annotation_user`, +and assign the following privileges: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +|Index +|`read` on +\{ANNOTATION_INDEX\}+^1^ +|Read-only access to the observability annotation index + +|Index +|`view_index_metadata` on +\{ANNOTATION_INDEX\}+^1^ +|Read-only access to observability annotation index metadata +|==== ++ +^1^ +\{ANNOTATION_INDEX\}+ should be the index name you've defined in +<>. + +. Assign the `annotation_user` created previously, and the built-in roles necessary to create +a <> or <> APM reader to any users that need to view annotations in the APM app + +[[apm-app-annotation-api]] +==== Annotation API + +See <>. + +//// +*********************************** *********************************** +//// + [role="xpack"] [[apm-app-central-config-user]] === APM app central config user diff --git a/docs/apm/set-up.asciidoc b/docs/apm/set-up.asciidoc index c5bf5e13b640b..b2e78bd08bc93 100644 --- a/docs/apm/set-up.asciidoc +++ b/docs/apm/set-up.asciidoc @@ -25,7 +25,8 @@ simply click *Load Kibana objects* at the bottom of the Setup Instructions. [role="screenshot"] image::apm/images/apm-index-pattern.png[Setup index pattern for APM in Kibana] -To use a custom index pattern, see <>. +TIP: To use a custom index pattern, +adjust Kibana's <> or use the <>. [float] [[apm-getting-started-next]] diff --git a/docs/images/canvas-add-image.gif b/docs/canvas/images/canvas-add-image.gif similarity index 100% rename from docs/images/canvas-add-image.gif rename to docs/canvas/images/canvas-add-image.gif diff --git a/docs/images/canvas-add-pages.gif b/docs/canvas/images/canvas-add-pages.gif similarity index 100% rename from docs/images/canvas-add-pages.gif rename to docs/canvas/images/canvas-add-pages.gif diff --git a/docs/images/canvas-autoplay-interval.png b/docs/canvas/images/canvas-autoplay-interval.png similarity index 100% rename from docs/images/canvas-autoplay-interval.png rename to docs/canvas/images/canvas-autoplay-interval.png diff --git a/docs/images/canvas-background-color-picker.png b/docs/canvas/images/canvas-background-color-picker.png similarity index 100% rename from docs/images/canvas-background-color-picker.png rename to docs/canvas/images/canvas-background-color-picker.png diff --git a/docs/images/canvas-change-your-expression-chart-no-legend.png b/docs/canvas/images/canvas-change-your-expression-chart-no-legend.png similarity index 100% rename from docs/images/canvas-change-your-expression-chart-no-legend.png rename to docs/canvas/images/canvas-change-your-expression-chart-no-legend.png diff --git a/docs/images/canvas-change-your-expression-chart.png b/docs/canvas/images/canvas-change-your-expression-chart.png similarity index 100% rename from docs/images/canvas-change-your-expression-chart.png rename to docs/canvas/images/canvas-change-your-expression-chart.png diff --git a/docs/images/canvas-chart-element.png b/docs/canvas/images/canvas-chart-element.png similarity index 100% rename from docs/images/canvas-chart-element.png rename to docs/canvas/images/canvas-chart-element.png diff --git a/docs/images/canvas-create-URL.gif b/docs/canvas/images/canvas-create-URL.gif similarity index 100% rename from docs/images/canvas-create-URL.gif rename to docs/canvas/images/canvas-create-URL.gif diff --git a/docs/images/canvas-element-select.gif b/docs/canvas/images/canvas-element-select.gif similarity index 100% rename from docs/images/canvas-element-select.gif rename to docs/canvas/images/canvas-element-select.gif diff --git a/docs/images/canvas-export-workpad.png b/docs/canvas/images/canvas-export-workpad.png similarity index 100% rename from docs/images/canvas-export-workpad.png rename to docs/canvas/images/canvas-export-workpad.png diff --git a/docs/images/canvas-fullscreen.png b/docs/canvas/images/canvas-fullscreen.png similarity index 100% rename from docs/images/canvas-fullscreen.png rename to docs/canvas/images/canvas-fullscreen.png diff --git a/docs/images/canvas-functions-can-take-arguments-donut-chart.png b/docs/canvas/images/canvas-functions-can-take-arguments-donut-chart.png similarity index 100% rename from docs/images/canvas-functions-can-take-arguments-donut-chart.png rename to docs/canvas/images/canvas-functions-can-take-arguments-donut-chart.png diff --git a/docs/images/canvas-functions-can-take-arguments-pie-chart.png b/docs/canvas/images/canvas-functions-can-take-arguments-pie-chart.png similarity index 100% rename from docs/images/canvas-functions-can-take-arguments-pie-chart.png rename to docs/canvas/images/canvas-functions-can-take-arguments-pie-chart.png diff --git a/docs/images/canvas-generate-pdf.gif b/docs/canvas/images/canvas-generate-pdf.gif similarity index 100% rename from docs/images/canvas-generate-pdf.gif rename to docs/canvas/images/canvas-generate-pdf.gif diff --git a/docs/images/canvas-gs-example.png b/docs/canvas/images/canvas-gs-example.png similarity index 100% rename from docs/images/canvas-gs-example.png rename to docs/canvas/images/canvas-gs-example.png diff --git a/docs/images/canvas-image-element.png b/docs/canvas/images/canvas-image-element.png similarity index 100% rename from docs/images/canvas-image-element.png rename to docs/canvas/images/canvas-image-element.png diff --git a/docs/images/canvas-map-embed.gif b/docs/canvas/images/canvas-map-embed.gif similarity index 100% rename from docs/images/canvas-map-embed.gif rename to docs/canvas/images/canvas-map-embed.gif diff --git a/docs/images/canvas-metric-element.png b/docs/canvas/images/canvas-metric-element.png similarity index 100% rename from docs/images/canvas-metric-element.png rename to docs/canvas/images/canvas-metric-element.png diff --git a/docs/images/canvas-refresh-interval.png b/docs/canvas/images/canvas-refresh-interval.png similarity index 100% rename from docs/images/canvas-refresh-interval.png rename to docs/canvas/images/canvas-refresh-interval.png diff --git a/docs/images/canvas-timefilter-element.png b/docs/canvas/images/canvas-timefilter-element.png similarity index 100% rename from docs/images/canvas-timefilter-element.png rename to docs/canvas/images/canvas-timefilter-element.png diff --git a/docs/images/canvas-zoom-controls.png b/docs/canvas/images/canvas-zoom-controls.png similarity index 100% rename from docs/images/canvas-zoom-controls.png rename to docs/canvas/images/canvas-zoom-controls.png diff --git a/docs/images/canvas_element_options.png b/docs/canvas/images/canvas_element_options.png similarity index 100% rename from docs/images/canvas_element_options.png rename to docs/canvas/images/canvas_element_options.png diff --git a/docs/images/canvas_save_element.png b/docs/canvas/images/canvas_save_element.png similarity index 100% rename from docs/images/canvas_save_element.png rename to docs/canvas/images/canvas_save_element.png diff --git a/docs/images/settings.png b/docs/dev-tools/console/images/settings.png similarity index 100% rename from docs/images/settings.png rename to docs/dev-tools/console/images/settings.png diff --git a/docs/developer/add-data-guide.asciidoc b/docs/developer/add-data-guide.asciidoc deleted file mode 100644 index e00e46868bb2d..0000000000000 --- a/docs/developer/add-data-guide.asciidoc +++ /dev/null @@ -1,38 +0,0 @@ -[[add-data-guide]] -== Add Data Guide - -`Add Data` in the Kibana Home application contains tutorials for setting up data flows in the Elastic stack. - -Each tutorial contains three sets of instructions: - -* `On Premise.` Set up a data flow when both Kibana and Elasticsearch are running on premise. -* `On Premise Elastic Cloud.` Set up a data flow when Kibana is running on premise and Elasticsearch is running on Elastic Cloud. -* `Elastic Cloud.` Set up a data flow when both Kibana and Elasticsearch are running on Elastic Cloud. - -[float] -=== Creating a new tutorial -1. Create a new directory in the link:https://github.com/elastic/kibana/tree/master/src/plugins/home/server/tutorials[tutorials directory]. -2. In the new directory, create a file called `index.ts` that exports a function. -The function must return a function object that conforms to the `TutorialSchema` interface link:https://github.com/elastic/kibana/blob/master/src/plugins/home/server/services/tutorials/lib/tutorial_schema.ts[tutorial schema]. -3. Register the tutorial in link:https://github.com/elastic/kibana/blob/master/src/plugins/home/server/tutorials/register.ts[register.ts] by adding it to the `builtInTutorials`. -// TODO update path once assets are migrated -4. Add image assets to the link:https://github.com/elastic/kibana/tree/master/src/legacy/core_plugins/kibana/public/home/tutorial_resources[tutorial_resources directory]. -5. Run Kibana locally to preview the tutorial. -6. Create a PR and go through the review process to get the changes approved. - -If you are creating a new plugin and the tutorial is only related to that plugin, you can also place the `TutorialSchema` object into your plugin folder. Add `home` to the `requiredPlugins` list in your `kibana.json` file. -Then register the tutorial object by calling `home.tutorials.registerTutorial(tutorialObject)` in the `setup` lifecycle of your server plugin. - -[float] -==== Variables -String values can contain variables that are substituted when rendered. Variables are specified by `{}`. -For example: `{config.docs.version}` is rendered as `6.2` when running the tutorial in Kibana 6.2. - -link:https://github.com/elastic/kibana/blob/master/src/legacy/core_plugins/kibana/public/home/np_ready/components/tutorial/replace_template_strings.js#L23[Provided variables] - -[float] -==== Markdown -String values can contain limited Markdown syntax. - -link:https://github.com/elastic/kibana/blob/master/src/legacy/core_plugins/kibana/public/home/components/tutorial/content.js#L8[Enabled Markdown grammars] - diff --git a/docs/developer/advanced/development-basepath.asciidoc b/docs/developer/advanced/development-basepath.asciidoc new file mode 100644 index 0000000000000..f0b760a21ea0c --- /dev/null +++ b/docs/developer/advanced/development-basepath.asciidoc @@ -0,0 +1,18 @@ +[[development-basepath]] +=== Considerations for basepath + +In dev mode, {kib} by default runs behind a proxy which adds a random path component to its URL. + +You can set this explicitly using `server.basePath` in <>. + +Use the server.rewriteBasePath setting to tell {kib} if it should remove the basePath from requests it receives, and to prevent a deprecation warning at startup. This setting cannot end in a slash (/). + +If you want to turn off the basepath when in development mode, start {kib} with the `--no-basepath` flag + +[source,bash] +---- +yarn start --no-basepath +---- + + + diff --git a/docs/developer/core/development-es-snapshots.asciidoc b/docs/developer/advanced/development-es-snapshots.asciidoc similarity index 90% rename from docs/developer/core/development-es-snapshots.asciidoc rename to docs/developer/advanced/development-es-snapshots.asciidoc index 4cd4f31e582db..92fae7a241edf 100644 --- a/docs/developer/core/development-es-snapshots.asciidoc +++ b/docs/developer/advanced/development-es-snapshots.asciidoc @@ -1,7 +1,7 @@ [[development-es-snapshots]] === Daily Elasticsearch Snapshots -For local development and CI, Kibana, by default, uses Elasticsearch snapshots that are built daily when running tasks that require Elasticsearch (e.g. functional tests). +For local development and CI, {kib}, by default, uses Elasticsearch snapshots that are built daily when running tasks that require Elasticsearch (e.g. functional tests). A snapshot is just a group of tarballs, one for each supported distribution/architecture/os of Elasticsearch, and a JSON-based manifest file containing metadata about the distributions. @@ -9,13 +9,13 @@ https://ci.kibana.dev/es-snapshots[A dashboard] is available that shows the curr ==== Process Overview -1. Elasticsearch snapshots are built for each current tracked branch of Kibana. +1. Elasticsearch snapshots are built for each current tracked branch of {kib}. 2. Each snapshot is uploaded to a public Google Cloud Storage bucket, `kibana-ci-es-snapshots-daily`. ** At this point, the snapshot is not automatically used in CI or local development. It needs to be tested/verified first. -3. Each snapshot is tested with the latest commit of the corresponding Kibana branch, using the full CI suite. +3. Each snapshot is tested with the latest commit of the corresponding {kib} branch, using the full CI suite. 4. After CI ** If the snapshot passes, it is promoted and automatically used in CI and local development. -** If the snapshot fails, the issue must be investigated and resolved. A new incompatibility may exist between Elasticsearch and Kibana. +** If the snapshot fails, the issue must be investigated and resolved. A new incompatibility may exist between Elasticsearch and {kib}. ==== Using the latest snapshot @@ -39,7 +39,7 @@ KBN_ES_SNAPSHOT_USE_UNVERIFIED=true node scripts/functional_tests_server Currently, there is not a way to run your pull request with the latest unverified snapshot without a code change. You can, however, do it with a small code change. -1. Edit `Jenkinsfile` in the root of the Kibana repo +1. Edit `Jenkinsfile` in the root of the {kib} repo 2. Add `env.KBN_ES_SNAPSHOT_USE_UNVERIFIED = 'true'` at the top of the file. 3. Commit the change @@ -75,13 +75,13 @@ The file structure for this bucket looks like this: ==== How snapshots are built, tested, and promoted -Each day, a https://kibana-ci.elastic.co/job/elasticsearch+snapshots+trigger/[Jenkins job] runs that triggers Elasticsearch builds for each currently tracked branch/version. This job is automatically updated with the correct branches whenever we release new versions of Kibana. +Each day, a https://kibana-ci.elastic.co/job/elasticsearch+snapshots+trigger/[Jenkins job] runs that triggers Elasticsearch builds for each currently tracked branch/version. This job is automatically updated with the correct branches whenever we release new versions of {kib}. ===== Build https://kibana-ci.elastic.co/job/elasticsearch+snapshots+build/[This Jenkins job] builds the Elasticsearch snapshots and uploads them to GCS. -The Jenkins job pipeline definition is https://github.com/elastic/kibana/blob/master/.ci/es-snapshots/Jenkinsfile_build_es[in the kibana repo]. +The Jenkins job pipeline definition is https://github.com/elastic/kibana/blob/master/.ci/es-snapshots/Jenkinsfile_build_es[in the {kib} repo]. 1. Checkout Elasticsearch repo for the given branch/version. 2. Run `./gradlew -p distribution/archives assemble --parallel` to create all of the Elasticsearch distributions. @@ -91,15 +91,15 @@ The Jenkins job pipeline definition is https://github.com/elastic/kibana/blob/ma ** e.g. `/archives/` 6. Replace `/manifest-latest.json` in GCS with this newest manifest. ** This allows the `KBN_ES_SNAPSHOT_USE_UNVERIFIED` flag to work. -7. Trigger the verification job, to run the full Kibana CI test suite with this snapshot. +7. Trigger the verification job, to run the full {kib} CI test suite with this snapshot. ===== Verification and Promotion -https://kibana-ci.elastic.co/job/elasticsearch+snapshots+verify/[This Jenkins job] tests the latest Elasticsearch snapshot with the full Kibana CI pipeline, and promotes if it there are no test failures. +https://kibana-ci.elastic.co/job/elasticsearch+snapshots+verify/[This Jenkins job] tests the latest Elasticsearch snapshot with the full {kib} CI pipeline, and promotes if it there are no test failures. -The Jenkins job pipeline definition is https://github.com/elastic/kibana/blob/master/.ci/es-snapshots/Jenkinsfile_verify_es[in the kibana repo]. +The Jenkins job pipeline definition is https://github.com/elastic/kibana/blob/master/.ci/es-snapshots/Jenkinsfile_verify_es[in the {kib} repo]. -1. Checkout Kibana and set up CI environment as normal. +1. Checkout {kib} and set up CI environment as normal. 2. Set the `ES_SNAPSHOT_MANIFEST` env var to point to the latest snapshot manifest. 3. Run CI (functional tests, integration tests, etc). 4. After CI diff --git a/docs/developer/advanced/index.asciidoc b/docs/developer/advanced/index.asciidoc new file mode 100644 index 0000000000000..139940ee42fe2 --- /dev/null +++ b/docs/developer/advanced/index.asciidoc @@ -0,0 +1,12 @@ +[[advanced]] +== Advanced + +* <> +* <> +* <> + +include::development-es-snapshots.asciidoc[] + +include::running-elasticsearch.asciidoc[] + +include::development-basepath.asciidoc[] \ No newline at end of file diff --git a/docs/developer/advanced/running-elasticsearch.asciidoc b/docs/developer/advanced/running-elasticsearch.asciidoc new file mode 100644 index 0000000000000..b03c231678eee --- /dev/null +++ b/docs/developer/advanced/running-elasticsearch.asciidoc @@ -0,0 +1,118 @@ +[[running-elasticsearch]] +=== Running elasticsearch during development + +There are many ways to run Elasticsearch while you are developing. + +[float] + +==== By snapshot + +This will run a snapshot of elasticsearch that is usually built nightly. Read more about <>. + +[source,bash] +---- +yarn es snapshot +---- + +See all available options, like how to specify a specific license, with the `--help` flag. + +[source,bash] +---- +yarn es snapshot --help +---- + +`trial` will give you access to all capabilities. + +**Keeping data between snapshots** + +If you want to keep the data inside your Elasticsearch between usages of this command, you should use the following command, to keep your data folder outside the downloaded snapshot folder: + +[source,bash] +---- +yarn es snapshot -E path.data=../data +---- + +==== By source + +If you have the Elasticsearch repo checked out locally and wish to run against that, use `source`. By default, it will reference an elasticsearch checkout which is a sibling to the {kib} directory named elasticsearch. If you wish to use a checkout in another location you can provide that by supplying --source-path + +[source,bash] +---- +yarn es source +---- + +==== From an archive + +Use this if you already have a distributable. For released versions, one can be obtained on the Elasticsearch downloads page. + +[source,bash] +---- +yarn es archive +---- + +Each of these will run Elasticsearch with a basic license. Additional options are available, pass --help for more information. + +==== From a remote host + +You can save some system resources, and the effort of generating sample data, if you have a remote Elasticsearch cluster to connect to. (Elasticians: you do! Check with your team about where to find credentials) + +You'll need to create a kibana.dev.yml (<>) and add the following to it: + +[source,bash] +---- +elasticsearch.hosts: + - {{ url }} +elasticsearch.username: {{ username }} +elasticsearch.password: {{ password }} +elasticsearch.ssl.verificationMode: none +---- + +If many other users will be interacting with your remote cluster, you'll want to add the following to avoid causing conflicts: + +[source,bash] +---- +kibana.index: '.{YourGitHubHandle}-kibana' +xpack.task_manager.index: '.{YourGitHubHandle}-task-manager-kibana' +---- + +===== Running remote clusters + +Setup remote clusters for cross cluster search (CCS) and cross cluster replication (CCR). + +Start your primary cluster by running: + +[source,bash] +---- +yarn es snapshot -E path.data=../data_prod1 +---- + +Start your remote cluster by running: + +[source,bash] +---- +yarn es snapshot -E transport.port=9500 -E http.port=9201 -E path.data=../data_prod2 +---- + +Once both clusters are running, start {kib}. {kib} will connect to the primary cluster. + +Setup the remote cluster in {kib} from either Management -> Elasticsearch -> Remote Clusters UI or by running the following script in Console. + +[source,bash] +---- +PUT _cluster/settings +{ + "persistent": { + "cluster": { + "remote": { + "cluster_one": { + "seeds": [ + "localhost:9500" + ] + } + } + } + } +} +---- + +Follow the cross-cluster search instructions for setting up index patterns to search across clusters (<>). \ No newline at end of file diff --git a/docs/developer/architecture/add-data-tutorials.asciidoc b/docs/developer/architecture/add-data-tutorials.asciidoc new file mode 100644 index 0000000000000..e16b1bc039a10 --- /dev/null +++ b/docs/developer/architecture/add-data-tutorials.asciidoc @@ -0,0 +1,38 @@ +[[add-data-tutorials]] +=== Add data tutorials + +`Add Data` in the {kib} Home application contains tutorials for setting up data flows in the Elastic stack. + +Each tutorial contains three sets of instructions: + +* `On Premise.` Set up a data flow when both {kib} and Elasticsearch are running on premise. +* `On Premise Elastic Cloud.` Set up a data flow when {kib} is running on premise and Elasticsearch is running on Elastic Cloud. +* `Elastic Cloud.` Set up a data flow when both {kib} and Elasticsearch are running on Elastic Cloud. + +[float] +==== Creating a new tutorial +1. Create a new directory in the link:https://github.com/elastic/kibana/tree/master/src/plugins/home/server/tutorials[tutorials directory]. +2. In the new directory, create a file called `index.ts` that exports a function. +The function must return a function object that conforms to the `TutorialSchema` interface link:{kib-repo}tree/{branch}/src/plugins/home/server/services/tutorials/lib/tutorial_schema.ts[tutorial schema]. +3. Register the tutorial in link:{kib-repo}tree/{branch}/src/plugins/home/server/tutorials/register.ts[register.ts] by adding it to the `builtInTutorials`. +// TODO update path once assets are migrated +4. Add image assets to the link:{kib-repo}tree/{branch}/src/legacy/core_plugins/kibana/public/home/tutorial_resources[tutorial_resources directory]. +5. Run {kib} locally to preview the tutorial. +6. Create a PR and go through the review process to get the changes approved. + +If you are creating a new plugin and the tutorial is only related to that plugin, you can also place the `TutorialSchema` object into your plugin folder. Add `home` to the `requiredPlugins` list in your `kibana.json` file. +Then register the tutorial object by calling `home.tutorials.registerTutorial(tutorialObject)` in the `setup` lifecycle of your server plugin. + +[float] +===== Variables +String values can contain variables that are substituted when rendered. Variables are specified by `{}`. +For example: `{config.docs.version}` is rendered as `6.2` when running the tutorial in {kib} 6.2. + +link:{kib-repo}tree/{branch}/src/legacy/core_plugins/kibana/public/home/np_ready/components/tutorial/replace_template_strings.js#L23[Provided variables] + +[float] +===== Markdown +String values can contain limited Markdown syntax. + +link:{kib-repo}tree/{branch}/src/legacy/core_plugins/kibana/public/home/components/tutorial/content.js#L8[Enabled Markdown grammars] + diff --git a/docs/developer/visualize/development-visualize-index.asciidoc b/docs/developer/architecture/development-visualize-index.asciidoc similarity index 85% rename from docs/developer/visualize/development-visualize-index.asciidoc rename to docs/developer/architecture/development-visualize-index.asciidoc index ac824b4702a3c..551c41833fb72 100644 --- a/docs/developer/visualize/development-visualize-index.asciidoc +++ b/docs/developer/architecture/development-visualize-index.asciidoc @@ -1,13 +1,13 @@ [[development-visualize-index]] -== Developing Visualizations +=== Developing Visualizations [IMPORTANT] ============================================== -These pages document internal APIs and are not guaranteed to be supported across future versions of Kibana. +These pages document internal APIs and are not guaranteed to be supported across future versions of {kib}. ============================================== The internal APIs for creating custom visualizations are in a state of heavy churn as -they are being migrated to the new Kibana platform, and large refactorings have been +they are being migrated to the new {kib} platform, and large refactorings have been happening across minor releases in the `7.x` series. In particular, in `7.5` and later we have made significant changes to the legacy APIs as we work to gradually replace them. @@ -20,7 +20,7 @@ If you would like to keep up with progress on the visualizations plugin in the m here are a few resources: * The <> documentation, where we try to capture any changes to the APIs as they occur across minors. -* link:https://github.com/elastic/kibana/issues/44121[Meta issue] which is tracking the move of the plugin to the new Kibana platform +* link:https://github.com/elastic/kibana/issues/44121[Meta issue] which is tracking the move of the plugin to the new {kib} platform * Our link:https://www.elastic.co/blog/join-our-elastic-stack-workspace-on-slack[Elastic Stack workspace on Slack]. * The {kib-repo}blob/{branch}/src/plugins/visualizations[source code], which will continue to be the most accurate source of information. diff --git a/docs/developer/architecture/index.asciidoc b/docs/developer/architecture/index.asciidoc new file mode 100644 index 0000000000000..d726a8bd3642d --- /dev/null +++ b/docs/developer/architecture/index.asciidoc @@ -0,0 +1,25 @@ +[[kibana-architecture]] +== Architecture + +[IMPORTANT] +============================================== +{kib} developer services and apis are in a state of constant development. We cannot provide backwards compatibility at this time due to the high rate of change. +============================================== + +Our developer services are changing all the time. One of the best ways to discover and learn about them is to read the available +READMEs from all the plugins inside our {kib-repo}tree/{branch}/src/plugins[open source plugins folder] and our +{kib-repo}/tree/{branch}/x-pack/plugins[commercial plugins folder]. + +A few services also automatically generate api documentation which can be browsed inside the {kib-repo}tree/{branch}/docs/development[docs/development section of our repo] + +A few notable services are called out below. + +* <> +* <> +* <> + +include::add-data-tutorials.asciidoc[] + +include::development-visualize-index.asciidoc[] + +include::security/index.asciidoc[] diff --git a/docs/developer/architecture/security/feature-registration.asciidoc b/docs/developer/architecture/security/feature-registration.asciidoc new file mode 100644 index 0000000000000..164f6d1cf9c74 --- /dev/null +++ b/docs/developer/architecture/security/feature-registration.asciidoc @@ -0,0 +1,274 @@ +[[development-plugin-feature-registration]] +==== Plugin feature registration + +If your plugin will be used with {kib}'s default distribution, then you have the ability to register the features that your plugin provides. Features are typically apps in {kib}; once registered, you can toggle them via Spaces, and secure them via Roles when security is enabled. + +===== UI Capabilities + +Registering features also gives your plugin access to “UI Capabilities”. These capabilities are boolean flags that you can use to conditionally render your interface, based on the current user's permissions. For example, you can hide or disable a Save button if the current user is not authorized. + +===== Registering a feature + +Feature registration is controlled via the built-in `xpack_main` plugin. To register a feature, call `xpack_main`'s `registerFeature` function from your plugin's `init` function, and provide the appropriate details: + +["source","javascript"] +----------- +init(server) { + const xpackMainPlugin = server.plugins.xpack_main; + xpackMainPlugin.registerFeature({ + // feature details here. + }); +} +----------- + +===== Feature details +Registering a feature consists of the following fields. For more information, consult the {kib-repo}blob/{branch}/x-pack/plugins/features/server/feature_registry.ts[feature registry interface]. + + +[cols="1a, 1a, 1a, 1a"] +|=== +|Field name |Data type |Example |Description + +|`id` (required) +|`string` +|`"sample_feature"` +|A unique identifier for your feature. Usually, the ID of your plugin is sufficient. + +|`name` (required) +|`string` +|`"Sample Feature"` +|A human readable name for your feature. + +|`app` (required) +|`string[]` +|`["sample_app", "kibana"]` +|An array of applications this feature enables. Typically, all of your plugin's apps (from `uiExports`) will be included here. + +|`privileges` (required) +|{kib-repo}blob/{branch}/x-pack/plugins/features/common/feature.ts[`FeatureConfig`]. +|See <> and <> +|The set of privileges this feature requires to function. + +|`subFeatures` (optional) +|{kib-repo}blob/{branch}/x-pack/plugins/features/common/feature.ts[`FeatureConfig`]. +|See <> +|The set of subfeatures that enables finer access control than the `all` and `read` feature privileges. These options are only available in the Gold subscription level and higher. + +|`icon` +|`string` +|"discoverApp" +|An https://elastic.github.io/eui/#/display/icons[EUI Icon] to use for this feature. + +|`navLinkId` +|`string` +|"sample_app" +|The ID of the navigation link associated with your feature. +|=== + +====== Privilege definition +The `privileges` section of feature registration allows plugins to implement read/write and read-only modes for their applications. + +For a full explanation of fields and options, consult the {kib-repo}blob/{branch}/x-pack/plugins/features/server/feature_registry.ts[feature registry interface]. + +===== Using UI Capabilities + +UI Capabilities are available to your public (client) plugin code. These capabilities are read-only, and are used to inform the UI. This object is namespaced by feature id. For example, if your feature id is “foo”, then your UI Capabilities are stored at `uiCapabilities.foo`. +To access capabilities, import them from `ui/capabilities`: + +["source","javascript"] +----------- +import { uiCapabilities } from 'ui/capabilities'; + +const canUserSave = uiCapabilities.foo.save; +if (canUserSave) { + // show save button +} +----------- + +[[example-1-canvas]] +===== Example 1: Canvas Application +["source","javascript"] +----------- +init(server) { + const xpackMainPlugin = server.plugins.xpack_main; + xpackMainPlugin.registerFeature({ + id: 'canvas', + name: 'Canvas', + icon: 'canvasApp', + navLinkId: 'canvas', + app: ['canvas', 'kibana'], + catalogue: ['canvas'], + privileges: { + all: { + savedObject: { + all: ['canvas-workpad'], + read: ['index-pattern'], + }, + ui: ['save'], + }, + read: { + savedObject: { + all: [], + read: ['index-pattern', 'canvas-workpad'], + }, + ui: [], + }, + }, + }); +} +----------- + +This shows how the Canvas application might register itself as a {kib} feature. +Note that it specifies different `savedObject` access levels for each privilege: + +- Users with read/write access (`all` privilege) need to be able to read/write `canvas-workpad` saved objects, and they need read-only access to `index-pattern` saved objects. +- Users with read-only access (`read` privilege) do not need to have read/write access to any saved objects, but instead get read-only access to `index-pattern` and `canvas-workpad` saved objects. + +Additionally, Canvas registers the `canvas` UI app and `canvas` catalogue entry. This tells {kib} that these entities are available for users with either the `read` or `all` privilege. + +The `all` privilege defines a single “save” UI Capability. To access this in the UI, Canvas could: + +["source","javascript"] +----------- +import { uiCapabilities } from 'ui/capabilities'; + +const canUserSave = uiCapabilities.canvas.save; +if (canUserSave) { + // show save button +} +----------- + +Because the `read` privilege does not define the `save` capability, users with read-only access will have their `uiCapabilities.canvas.save` flag set to `false`. + +[[example-2-dev-tools]] +===== Example 2: Dev Tools + +["source","javascript"] +----------- +init(server) { + const xpackMainPlugin = server.plugins.xpack_main; + xpackMainPlugin.registerFeature({ + id: 'dev_tools', + name: i18n.translate('xpack.features.devToolsFeatureName', { + defaultMessage: 'Dev Tools', + }), + icon: 'devToolsApp', + navLinkId: 'dev_tools', + app: ['kibana'], + catalogue: ['console', 'searchprofiler', 'grokdebugger'], + privileges: { + all: { + api: ['console'], + savedObject: { + all: [], + read: [], + }, + ui: ['show'], + }, + read: { + api: ['console'], + savedObject: { + all: [], + read: [], + }, + ui: ['show'], + }, + }, + privilegesTooltip: i18n.translate('xpack.features.devToolsPrivilegesTooltip', { + defaultMessage: + 'User should also be granted the appropriate Elasticsearch cluster and index privileges', + }), + }); +} +----------- + +Unlike the Canvas example, Dev Tools does not require access to any saved objects to function. Dev Tools does specify an API endpoint, however. When this is configured, the Security plugin will automatically authorize access to any server API route that is tagged with `access:console`, similar to the following: + +["source","javascript"] +----------- +server.route({ + path: '/api/console/proxy', + method: 'POST', + config: { + tags: ['access:console'], + handler: async (req, h) => { + // ... + } + } +}); +----------- + +[[example-3-discover]] +===== Example 3: Discover + +Discover takes advantage of subfeature privileges to allow fine-grained access control. In this example, +a single "Create Short URLs" subfeature privilege is defined, which allows users to grant access to this feature without having to grant the `all` privilege to Discover. In other words, you can grant `read` access to Discover, and also grant the ability to create short URLs. + +["source","javascript"] +----------- +init(server) { + const xpackMainPlugin = server.plugins.xpack_main; + xpackMainPlugin.registerFeature({ + { + id: 'discover', + name: i18n.translate('xpack.features.discoverFeatureName', { + defaultMessage: 'Discover', + }), + order: 100, + icon: 'discoverApp', + navLinkId: 'discover', + app: ['kibana'], + catalogue: ['discover'], + privileges: { + all: { + app: ['kibana'], + catalogue: ['discover'], + savedObject: { + all: ['search', 'query'], + read: ['index-pattern'], + }, + ui: ['show', 'save', 'saveQuery'], + }, + read: { + app: ['kibana'], + catalogue: ['discover'], + savedObject: { + all: [], + read: ['index-pattern', 'search', 'query'], + }, + ui: ['show'], + }, + }, + subFeatures: [ + { + name: i18n.translate('xpack.features.ossFeatures.discoverShortUrlSubFeatureName', { + defaultMessage: 'Short URLs', + }), + privilegeGroups: [ + { + groupType: 'independent', + privileges: [ + { + id: 'url_create', + name: i18n.translate( + 'xpack.features.ossFeatures.discoverCreateShortUrlPrivilegeName', + { + defaultMessage: 'Create Short URLs', + } + ), + includeIn: 'all', + savedObject: { + all: ['url'], + read: [], + }, + ui: ['createShortUrl'], + }, + ], + }, + ], + }, + ], + } + }); +} +----------- diff --git a/docs/developer/architecture/security/index.asciidoc b/docs/developer/architecture/security/index.asciidoc new file mode 100644 index 0000000000000..55b2450caf7a7 --- /dev/null +++ b/docs/developer/architecture/security/index.asciidoc @@ -0,0 +1,12 @@ +[[development-security]] +=== Security + +{kib} has generally been able to implement security transparently to core and plugin developers, and this largely remains the case. {kib} on two methods that the elasticsearch `Cluster` provides: `callWithRequest` and `callWithInternalUser`. + +`callWithRequest` executes requests against Elasticsearch using the authentication credentials of the {kib} end-user. So, if you log into {kib} with the user of `foo` when `callWithRequest` is used, {kib} execute the request against Elasticsearch as the user `foo`. Historically, `callWithRequest` has been used extensively to perform actions that are initiated at the request of {kib} end-users. + +`callWithInternalUser` executes requests against Elasticsearch using the internal {kib} server user, and has historically been used for performing actions that aren't initiated by {kib} end users; for example, creating the initial `.kibana` index or performing health checks against Elasticsearch. + +However, with the changes that role-based access control (RBAC) introduces, this is no longer cut and dry. {kib} now requires all access to the `.kibana` index goes through the `SavedObjectsClient`. This used to be a best practice, as the `SavedObjectsClient` was responsible for translating the documents stored in Elasticsearch to and from Saved Objects, but RBAC is now taking advantage of this abstraction to implement access control and determine when to use `callWithRequest` versus `callWithInternalUser`. + +include::rbac.asciidoc[] diff --git a/docs/developer/security/rbac.asciidoc b/docs/developer/architecture/security/rbac.asciidoc similarity index 96% rename from docs/developer/security/rbac.asciidoc rename to docs/developer/architecture/security/rbac.asciidoc index 02b8233a9a3df..ae1979e856e23 100644 --- a/docs/developer/security/rbac.asciidoc +++ b/docs/developer/architecture/security/rbac.asciidoc @@ -1,5 +1,5 @@ [[development-security-rbac]] -=== Role-based access control +==== Role-based access control Role-based access control (RBAC) in {kib} relies upon the {ref}/security-privileges.html#application-privileges[application privileges] @@ -11,7 +11,7 @@ consumers when using `request.getSavedObjectsClient()` or `savedObjects.getScopedSavedObjectsClient()`. [[development-rbac-privileges]] -==== {kib} Privileges +===== {kib} Privileges When {kib} first starts up, it executes the following `POST` request against {es}. This synchronizes the definition of the privileges with various `actions` which are later used to authorize a user: @@ -19,7 +19,7 @@ When {kib} first starts up, it executes the following `POST` request against {es ---------------------------------- POST /_security/privilege Content-Type: application/json -Authorization: Basic kibana changeme +Authorization: Basic {kib} changeme { "kibana-.kibana":{ @@ -56,7 +56,7 @@ The application is created by concatenating the prefix of `kibana-` with the val ============================================== [[development-rbac-assigning-privileges]] -==== Assigning {kib} Privileges +===== Assigning {kib} Privileges {kib} privileges are assigned to specific roles using the `applications` element. For example, the following role assigns the <> privilege at `*` `resources` (which will in the future be used to secure spaces) to the default {kib} `application`: @@ -81,7 +81,7 @@ Roles that grant <> should be managed using the <> +* <> +* <> + +include::stability.asciidoc[] + +include::security.asciidoc[] diff --git a/docs/developer/best-practices/security.asciidoc b/docs/developer/best-practices/security.asciidoc new file mode 100644 index 0000000000000..26fcc73ce2b90 --- /dev/null +++ b/docs/developer/best-practices/security.asciidoc @@ -0,0 +1,55 @@ +[[security-best-practices]] +=== Security best practices + +* XSS +** Check for usages of `dangerouslySetInnerHtml`, `Element.innerHTML`, +`Element.outerHTML` +** Ensure all user input is properly escaped. +** Ensure any input in `$.html`, `$.append`, `$.appendTo`, +latexmath:[$.prepend`, `$].prependTo`is escaped. Instead use`$.text`, or +don’t use jQuery at all. +* CSRF +** Ensure all APIs are running inside the {kib} HTTP service. +* RCE +** Ensure no usages of `eval` +** Ensure no usages of dynamic requires +** Check for template injection +** Check for usages of templating libraries, including `_.template`, and +ensure that user provided input isn’t influencing the template and is +only used as data for rendering the template. +** Check for possible prototype pollution. +* Prototype Pollution +** Check for instances of `anObject[a][b] = c` where a, b, and c are +user defined. This includes code paths where the following logical code +steps could be performed in separate files by completely different +operations, or recursively using dynamic operations. +** Validate any user input, including API +url-parameters/query-parameters/payloads, preferable against a schema +which only allows specific keys/values. At a very minimum, black-list +`__proto__` and `prototype.constructor` for use within keys +** When calling APIs which spawn new processes or potentially perform +code generation from strings, defensively protect against Prototype +Pollution by checking `Object.hasOwnProperty` if the arguments to the +APIs originate from an Object. An example is the Code app’s +https://github.com/elastic/kibana/blob/b49192626a8528af5d888545fb14cd1ce66a72e7/x-pack/legacy/plugins/code/server/lsp/workspace_command.ts#L40-L44[spawnProcess]. +*** Common Node.js offenders: `child_process.spawn`, +`child_process.exec`, `eval`, `Function('some string')`, +`vm.runIn*Context(x)` +*** Common Client-side offenders: `eval`, `Function('some string')`, +`setTimeout('some string', num)`, `setInterval('some string', num)` +* Check for accidental reveal of sensitive information +** The biggest culprit is errors which contain stack traces or other +sensitive information which end up in the HTTP Response +* Checked for Mishandled API requests +** Ensure no sensitive cookies are forwarded to external resources. +** Ensure that all user controllable variables that are used in +constructing a URL are escaped properly. This is relevant when using +`transport.request` with the Elasticsearch client as no automatic +escaping is performed. +* Reverse tabnabbing - +https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/HTML5_Security_Cheat_Sheet.md#tabnabbing +** When there are user controllable links or hard-coded links to +third-party domains that specify target="_blank" or target="_window", the a tag should have the rel="noreferrer noopener" attribute specified. +Allowing users to input markdown is a common culprit, a custom link renderer should be used +* SSRF - https://www.owasp.org/index.php/Server_Side_Request_Forgery +All network requests made from the {kib} server should use an explicit configuration or white-list specified in the kibana.yml \ No newline at end of file diff --git a/docs/developer/best-practices/stability.asciidoc b/docs/developer/best-practices/stability.asciidoc new file mode 100644 index 0000000000000..68237a034be52 --- /dev/null +++ b/docs/developer/best-practices/stability.asciidoc @@ -0,0 +1,66 @@ +[[stability]] +=== Stability + +Ensure your feature will work under all possible {kib} scenarios. + +[float] +==== Environmental configuration scenarios + +* Cloud +** Does the feature work on *cloud environment*? +** Does it create a setting that needs to be exposed, or configured +differently than the default, on Cloud? (whitelisting of certain +settings/users? Ref: +https://www.elastic.co/guide/en/cloud/current/ec-add-user-settings.html +, +https://www.elastic.co/guide/en/cloud/current/ec-manage-kibana-settings.html) +** Is there a significant performance impact that may affect Cloud +{kib} instances? +** Does it need to be aware of running in a container? (for example +monitoring) +* Multiple {kib} instances +** Pointing to the same index +** Pointing to different indexes +*** Should make sure that the {kib} index is not hardcoded anywhere. +*** Should not be storing a bunch of stuff in {kib} memory. +*** Should emulate a high availability deployment. +*** Anticipating different timing related issues due to shared resource +access. +*** We need to make sure security is set up in a specific way for +non-standard {kib} indices. (create their own custom roles) +* {kib} running behind a reverse proxy or load balancer, without sticky +sessions. (we have had many discuss/SDH tickets around this) +* If a proxy/loadbalancer is running between ES and {kib} + +[float] +==== Kibana.yml settings + +* Using a custom {kib} index alias +* When optional dependencies are disabled +** Ensure all your required dependencies are listed in kibana.json +dependency list! + +[float] +==== Test coverage + +* Does the feature have sufficient unit test coverage? (does it handle +storeinSessions?) +* Does the feature have sufficient Functional UI test coverage? +* Does the feature have sufficient Rest API coverage test coverage? +* Does the feature have sufficient Integration test coverage? + +[float] +==== Browser coverage + +Refer to the list of browsers and OS {kib} supports +https://www.elastic.co/support/matrix + +Does the feature work efficiently on the list of supported browsers? + +[float] +==== Upgrade Scenarios - Migration scenarios- + +Does the feature affect old +indices, saved objects ? - Has the feature been tested with {kib} +aliases - Read/Write privileges of the indices before and after the +upgrade? diff --git a/docs/developer/contributing/development-accessibility-tests.asciidoc b/docs/developer/contributing/development-accessibility-tests.asciidoc new file mode 100644 index 0000000000000..a3ffefb94cd2a --- /dev/null +++ b/docs/developer/contributing/development-accessibility-tests.asciidoc @@ -0,0 +1,23 @@ +[[development-accessibility-tests]] +==== Automated Accessibility Testing + +To run the tests locally: + +[arabic] +. In one terminal window run +`node scripts/functional_tests_server --config test/accessibility/config.ts` +. In another terminal window run +`node scripts/functional_test_runner.js --config test/accessibility/config.ts` + +To run the x-pack tests, swap the config file out for +`x-pack/test/accessibility/config.ts`. + +After the server is up, you can go to this instance of {kib} at +`localhost:5620`. + +The testing is done using https://github.com/dequelabs/axe-core[axe]. +The same thing that runs in CI, can be run locally using their browser +plugins: + +* https://chrome.google.com/webstore/detail/axe-web-accessibility-tes/lhdoppojpmngadmnindnejefpokejbdd?hl=en-US[Chrome] +* https://addons.mozilla.org/en-US/firefox/addon/axe-devtools/[Firefox] \ No newline at end of file diff --git a/docs/developer/contributing/development-documentation.asciidoc b/docs/developer/contributing/development-documentation.asciidoc new file mode 100644 index 0000000000000..d9fae42eef87e --- /dev/null +++ b/docs/developer/contributing/development-documentation.asciidoc @@ -0,0 +1,34 @@ +[[development-documentation]] +=== Documentation during development + +Docs should be written during development and accompany PRs when relevant. There are multiple types of documentation, and different places to add each. + +[float] +==== Developer services documentation + +Documentation about specific services a plugin offers should be encapsulated in: + +* README.asciidoc at the base of the plugin folder. +* Typescript comments for all public services. + +[float] +==== End user documentation + +Documentation about user facing features should be written in http://asciidoc.org/[asciidoc] at +{kib-repo}/tree/master/docs[https://github.com/elastic/kibana/tree/master/docs] + +To build the docs, you must clone the https://github.com/elastic/docs[elastic/docs] +repo as a sibling of your {kib} repo. Follow the instructions in that project's +README for getting the docs tooling set up. + +**To build the docs:** + +```bash +node scripts/docs.js --open +``` + +[float] +==== General developer documentation and guidelines + +General developer guildlines and documentation, like this right here, should be written in http://asciidoc.org/[asciidoc] +at {kib-repo}/tree/master/docs/developer[https://github.com/elastic/kibana/tree/master/docs/developer] diff --git a/docs/developer/core/development-functional-tests.asciidoc b/docs/developer/contributing/development-functional-tests.asciidoc similarity index 90% rename from docs/developer/core/development-functional-tests.asciidoc rename to docs/developer/contributing/development-functional-tests.asciidoc index 2b091d9abb9fc..442fc1ac755d3 100644 --- a/docs/developer/core/development-functional-tests.asciidoc +++ b/docs/developer/contributing/development-functional-tests.asciidoc @@ -1,38 +1,39 @@ [[development-functional-tests]] === Functional Testing -We use functional tests to make sure the Kibana UI works as expected. It replaces hours of manual testing by automating user interaction. To have better control over our functional test environment, and to make it more accessible to plugin authors, Kibana uses a tool called the `FunctionalTestRunner`. +We use functional tests to make sure the {kib} UI works as expected. It replaces hours of manual testing by automating user interaction. To have better control over our functional test environment, and to make it more accessible to plugin authors, {kib} uses a tool called the `FunctionalTestRunner`. [float] ==== Running functional tests -The `FunctionalTestRunner` is very bare bones and gets most of its functionality from its config file, located at {blob}test/functional/config.js[test/functional/config.js]. If you’re writing a plugin you will have your own config file. See <> for more info. +The `FunctionalTestRunner` is very bare bones and gets most of its functionality from its config file, located at {blob}test/functional/config.js[test/functional/config.js]. If you’re writing a plugin outside the {kib} repo, you will have your own config file. + See <> for more info. There are three ways to run the tests depending on your goals: 1. Easiest option: -** Description: Starts up Kibana & Elasticsearch servers, followed by running tests. This is much slower when running the tests multiple times because slow startup time for the servers. Recommended for single-runs. +** Description: Starts up {kib} & Elasticsearch servers, followed by running tests. This is much slower when running the tests multiple times because slow startup time for the servers. Recommended for single-runs. ** `node scripts/functional_tests` -*** does everything in a single command, including running Elasticsearch and Kibana locally +*** does everything in a single command, including running Elasticsearch and {kib} locally *** tears down everything after the tests run *** exit code reports success/failure of the tests 2. Best for development: -** Description: Two commands, run in separate terminals, separate the components that are long-running and slow from those that are ephemeral and fast. Tests can be re-run much faster, and this still runs Elasticsearch & Kibana locally. +** Description: Two commands, run in separate terminals, separate the components that are long-running and slow from those that are ephemeral and fast. Tests can be re-run much faster, and this still runs Elasticsearch & {kib} locally. ** `node scripts/functional_tests_server` -*** starts Elasticsearch and Kibana servers +*** starts Elasticsearch and {kib} servers *** slow to start *** can be reused for multiple executions of the tests, thereby saving some time when re-running tests -*** automatically restarts the Kibana server when relevant changes are detected +*** automatically restarts the {kib} server when relevant changes are detected ** `node scripts/functional_test_runner` -*** runs the tests against Kibana & Elasticsearch servers that were started by `node scripts/functional_tests_server` +*** runs the tests against {kib} & Elasticsearch servers that were started by `node scripts/functional_tests_server` *** exit code reports success or failure of the tests 3. Custom option: -** Description: Runs tests against instances of Elasticsearch & Kibana started some other way (like Elastic Cloud, or an instance you are managing in some other way). +** Description: Runs tests against instances of Elasticsearch & {kib} started some other way (like Elastic Cloud, or an instance you are managing in some other way). ** just executes the functional tests -** url, credentials, etc. for Elasticsearch and Kibana are specified via environment variables -** Here's an example that runs against an Elastic Cloud instance. Note that you must run the same branch of tests as the version of Kibana you're testing. +** url, credentials, etc. for Elasticsearch and {kib} are specified via environment variables +** Here's an example that runs against an Elastic Cloud instance. Note that you must run the same branch of tests as the version of {kib} you're testing. + ["source","shell"] ---------- @@ -95,10 +96,10 @@ node scripts/functional_test_runner --exclude-tag skipCloud When run without any arguments the `FunctionalTestRunner` automatically loads the configuration in the standard location, but you can override that behavior with the `--config` flag. List configs with multiple --config arguments. -* `--config test/functional/config.js` starts Elasticsearch and Kibana servers with the WebDriver tests configured to run in Chrome. -* `--config test/functional/config.firefox.js` starts Elasticsearch and Kibana servers with the WebDriver tests configured to run in Firefox. -* `--config test/api_integration/config.js` starts Elasticsearch and Kibana servers with the api integration tests configuration. -* `--config test/accessibility/config.ts` starts Elasticsearch and Kibana servers with the WebDriver tests configured to run an accessibility audit using https://www.deque.com/axe/[axe]. +* `--config test/functional/config.js` starts Elasticsearch and {kib} servers with the WebDriver tests configured to run in Chrome. +* `--config test/functional/config.firefox.js` starts Elasticsearch and {kib} servers with the WebDriver tests configured to run in Firefox. +* `--config test/api_integration/config.js` starts Elasticsearch and {kib} servers with the api integration tests configuration. +* `--config test/accessibility/config.ts` starts Elasticsearch and {kib} servers with the WebDriver tests configured to run an accessibility audit using https://www.deque.com/axe/[axe]. There are also command line flags for `--bail` and `--grep`, which behave just like their mocha counterparts. For instance, use `--grep=foo` to run only tests that match a regular expression. @@ -117,7 +118,7 @@ The tests are written in https://mochajs.org[mocha] using https://github.com/ela We use https://www.w3.org/TR/webdriver1/[WebDriver Protocol] to run tests in both Chrome and Firefox with the help of https://sites.google.com/a/chromium.org/chromedriver/[chromedriver] and https://firefox-source-docs.mozilla.org/testing/geckodriver/[geckodriver]. When the `FunctionalTestRunner` launches, remote service creates a new webdriver session, which starts the driver and a stripped-down browser instance. We use `browser` service and `webElementWrapper` class to wrap up https://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/[Webdriver API]. -The `FunctionalTestRunner` automatically transpiles functional tests using babel, so that tests can use the same ECMAScript features that Kibana source code uses. See {blob}style_guides/js_style_guide.md[style_guides/js_style_guide.md]. +The `FunctionalTestRunner` automatically transpiles functional tests using babel, so that tests can use the same ECMAScript features that {kib} source code uses. See {blob}style_guides/js_style_guide.md[style_guides/js_style_guide.md]. [float] ===== Definitions @@ -304,9 +305,9 @@ The `FunctionalTestRunner` comes with three built-in services: * Phases include: `beforeLoadTests`, `beforeTests`, `beforeEachTest`, `cleanup` [float] -===== Kibana Services +===== {kib} Services -The Kibana functional tests define the vast majority of the actual functionality used by tests. +The {kib} functional tests define the vast majority of the actual functionality used by tests. **browser**::: * Source: {blob}test/functional/services/browser.ts[test/functional/services/browser.ts] @@ -356,7 +357,7 @@ await testSubjects.click(‘containerButton’); **kibanaServer:**::: * Source: {blob}test/common/services/kibana_server/kibana_server.js[test/common/services/kibana_server/kibana_server.js] -* Helpers for interacting with Kibana's server +* Helpers for interacting with {kib}'s server * Commonly used methods: ** `kibanaServer.uiSettings.update()` ** `kibanaServer.version.get()` @@ -501,3 +502,13 @@ const log = getService(‘log’); // log.debug only writes when using the `--debug` or `--verbose` flag. log.debug(‘done clicking menu’); ----------- + +[float] +==== MacOS testing performance tip + +macOS users on a machine with a discrete graphics card may see significant speedups (up to 2x) when running tests by changing your terminal emulator's GPU settings. In iTerm2: +* Open Preferences (Command + ,) +* In the General tab, under the "Magic" section, ensure "GPU rendering" is checked +* Open "Advanced GPU Settings..." +* Uncheck the "Prefer integrated to discrete GPU" option +* Restart iTerm \ No newline at end of file diff --git a/docs/developer/contributing/development-github.asciidoc b/docs/developer/contributing/development-github.asciidoc new file mode 100644 index 0000000000000..027b4e73aa9de --- /dev/null +++ b/docs/developer/contributing/development-github.asciidoc @@ -0,0 +1,112 @@ +[[development-github]] +=== How we use git and github + +[float] +==== Forking + +We follow the https://help.github.com/articles/fork-a-repo/[GitHub +forking model] for collaborating on {kib} code. This model assumes that +you have a remote called `upstream` which points to the official {kib} +repo, which we'll refer to in later code snippets. + +[float] +==== Branching + +* All work on the next major release goes into master. +* Past major release branches are named `{majorVersion}.x`. They contain +work that will go into the next minor release. For example, if the next +minor release is `5.2.0`, work for it should go into the `5.x` branch. +* Past minor release branches are named `{majorVersion}.{minorVersion}`. +They contain work that will go into the next patch release. For example, +if the next patch release is `5.3.1`, work for it should go into the +`5.3` branch. +* All work is done on feature branches and merged into one of these +branches. +* Where appropriate, we'll backport changes into older release branches. + +[float] +==== Commits and Merging + +* Feel free to make as many commits as you want, while working on a +branch. +* When submitting a PR for review, please perform an interactive rebase +to present a logical history that's easy for the reviewers to follow. +* Please use your commit messages to include helpful information on your +changes, e.g. changes to APIs, UX changes, bugs fixed, and an +explanation of _why_ you made the changes that you did. +* Resolve merge conflicts by rebasing the target branch over your +feature branch, and force-pushing (see below for instructions). +* When merging, we'll squash your commits into a single commit. + +[float] +===== Rebasing and fixing merge conflicts + +Rebasing can be tricky, and fixing merge conflicts can be even trickier +because it involves force pushing. This is all compounded by the fact +that attempting to push a rebased branch remotely will be rejected by +git, and you'll be prompted to do a `pull`, which is not at all what you +should do (this will really mess up your branch's history). + +Here's how you should rebase master onto your branch, and how to fix +merge conflicts when they arise. + +First, make sure master is up-to-date. + +["source","shell"] +----------- +git checkout master +git fetch upstream +git rebase upstream/master +----------- + +Then, check out your branch and rebase master on top of it, which will +apply all of the new commits on master to your branch, and then apply +all of your branch's new commits after that. + +["source","shell"] +----------- +git checkout name-of-your-branch +git rebase master +----------- + +You want to make sure there are no merge conflicts. If there are merge +conflicts, git will pause the rebase and allow you to fix the conflicts +before continuing. + +You can use `git status` to see which files contain conflicts. They'll +be the ones that aren't staged for commit. Open those files, and look +for where git has marked the conflicts. Resolve the conflicts so that +the changes you want to make to the code have been incorporated in a way +that doesn't destroy work that's been done in master. Refer to master's +commit history on GitHub if you need to gain a better understanding of how code is conflicting and how best to resolve it. + +Once you've resolved all of the merge conflicts, use `git add -A` to stage them to be committed, and then use + `git rebase --continue` to tell git to continue the rebase. + +When the rebase has completed, you will need to force push your branch because the history is now completely different than what's on the remote. This is potentially dangerous because it will completely overwrite what you have on the remote, so you need to be sure that you haven't lost any work when resolving merge conflicts. (If there weren't any merge conflicts, then you can force push without having to worry about this.) + +["source","shell"] +----------- +git push origin name-of-your-branch --force +----------- + +This will overwrite the remote branch with what you have locally. You're done! + +**Note that you should not run git pull**, for example in response to a push rejection like this: + +["source","shell"] +----------- +! [rejected] name-of-your-branch -> name-of-your-branch (non-fast-forward) +error: failed to push some refs to 'https://github.com/YourGitHubHandle/kibana.git' +hint: Updates were rejected because the tip of your current branch is behind +hint: its remote counterpart. Integrate the remote changes (e.g. +hint: 'git pull ...') before pushing again. +hint: See the 'Note about fast-forwards' in 'git push --help' for details. +----------- + +Assuming you've successfully rebased and you're happy with the code, you should force push instead. + +[float] +==== Creating a pull request + +See <> for the next steps on getting your code changes merged into {kib}. \ No newline at end of file diff --git a/docs/developer/contributing/development-pull-request.asciidoc b/docs/developer/contributing/development-pull-request.asciidoc new file mode 100644 index 0000000000000..5d3c30fec7383 --- /dev/null +++ b/docs/developer/contributing/development-pull-request.asciidoc @@ -0,0 +1,32 @@ +[[development-pull-request]] +=== Submitting a pull request + +[float] +==== What Goes Into a Pull Request + +* Please include an explanation of your changes in your PR description. +* Links to relevant issues, external resources, or related PRs are very important and useful. +* Please update any tests that pertain to your code, and add new tests where appropriate. +* Update or add docs when appropriate. Read more about <>. + +[float] +==== Submitting a Pull Request + + 1. Push your local changes to your forked copy of the repository and submit a pull request. + 2. Describe what your changes do and mention the number of the issue where discussion has taken place, e.g., “Closes #123″. + 3. Assign the `review` and `💝community` label (assuming you are not a member of the Elastic organization). This signals to the team that someone needs to give this attention. + 4. Do *not* assign a version label. Someone from Elastic staff will assign a version label, if necessary, when your Pull Request is ready to be merged. + 5. If you would like someone specific to review your pull request, assign them. Otherwise an Elastic staff member will assign the appropriate person. + +Always submit your pull against master unless the bug is only present in an older version. If the bug affects both master and another branch say so in your pull. + +Then sit back and wait. There will probably be discussion about the Pull Request and, if any changes are needed, we'll work with you to get your Pull Request merged into {kib}. + +[float] +==== What to expect during the pull request review process + +Most PRs go through several iterations of feedback and updates. Depending on the scope and complexity of the PR, the process can take weeks. Please +be patient and understand we hold our code base to a high standard. + +Check out our <> for our general philosophy for pull request reviews. + diff --git a/docs/developer/contributing/development-tests.asciidoc b/docs/developer/contributing/development-tests.asciidoc new file mode 100644 index 0000000000000..b470ea61669b2 --- /dev/null +++ b/docs/developer/contributing/development-tests.asciidoc @@ -0,0 +1,96 @@ +[[development-tests]] +=== Testing + +To ensure that your changes will not break other functionality, please run the test suite and build (<>) before submitting your Pull Request. + +[float] +==== Running specific {kib} tests + +The following table outlines possible test file locations and how to +invoke them: + +[width="100%",cols="7%,59%,34%",options="header",] +|=== +|Test runner |Test location |Runner command (working directory is {kib} +root) +|Jest |`src/**/*.test.js` `src/**/*.test.ts` +|`yarn test:jest -t regexp [test path]` + +|Jest (integration) |`**/integration_tests/**/*.test.js` +|`yarn test:jest_integration -t regexp [test path]` + +|Mocha +|`src/**/__tests__/**/*.js` `!src/**/public/__tests__/*.js``packages/kbn-datemath/test/**/*.js` `packages/kbn-dev-utils/src/**/__tests__/**/*.js` `tasks/**/__tests__/**/*.js` +|`node scripts/mocha --grep=regexp [test path]` + +|Functional +|`test/*integration/**/config.js` `test/*functional/**/config.js` `test/accessibility/config.js` +|`yarn test:ftr:server --config test/[directory]/config.js``yarn test:ftr:runner --config test/[directory]/config.js --grep=regexp` + +|Karma |`src/**/public/__tests__/*.js` |`yarn test:karma:debug` +|=== + +For X-Pack tests located in `x-pack/` see +link:{kib-repo}tree/{branch}/x-pack/README.md#testing[X-Pack Testing] + +Test runner arguments: - Where applicable, the optional arguments +`-t=regexp` or `--grep=regexp` will only run tests or test suites +whose descriptions matches the regular expression. - `[test path]` is +the relative path to the test file. + +Examples: - Run the entire elasticsearch_service test suite: +`yarn test:jest src/core/server/elasticsearch/elasticsearch_service.test.ts` +- Run the jest test case whose description matches +`stops both admin and data clients`: +`yarn test:jest -t 'stops both admin and data clients' src/core/server/elasticsearch/elasticsearch_service.test.ts` +- Run the api integration test case whose description matches the given +string: ``` yarn test:ftr:server –config test/api_integration/config.js +yarn test:ftr:runner –config test/api_integration/config + +[float] +==== Cross-browser compatibility + +**Testing IE on OS X** + +* http://www.vmware.com/products/fusion/fusion-evaluation.html[Download +VMWare Fusion]. +* https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/#downloads[Download +IE virtual machines] for VMWare. +* Open VMWare and go to Window > Virtual Machine Library. Unzip the +virtual machine and drag the .vmx file into your Virtual Machine +Library. +* Right-click on the virtual machine you just added to your library and +select "`Snapshots…`", and then click the "`Take`" button in the modal +that opens. You can roll back to this snapshot when the VM expires in 90 +days. +* In System Preferences > Sharing, change your computer name to be +something simple, e.g. "`computer`". +* Run {kib} with `yarn start --host=computer.local` (substituting +your computer name). +* Now you can run your VM, open the browser, and navigate to +`http://computer.local:5601` to test {kib}. +* Alternatively you can use browserstack + +[float] +==== Running browser automation tests + +Check out <> to learn more about how you can run +and develop functional tests for {kib} core and plugins. + +You can also look into the {kib-repo}tree/{branch}/scripts/README.md[Scripts README.md] +to learn more about using the node scripts we provide for building +{kib}, running integration tests, and starting up {kib} and +Elasticsearch while you develop. + +[float] +==== More testing information: + +* <> +* <> +* <> + +include::development-functional-tests.asciidoc[] + +include::development-unit-tests.asciidoc[] + +include::development-accessibility-tests.asciidoc[] \ No newline at end of file diff --git a/docs/developer/contributing/development-unit-tests.asciidoc b/docs/developer/contributing/development-unit-tests.asciidoc new file mode 100644 index 0000000000000..0009533c9a7c4 --- /dev/null +++ b/docs/developer/contributing/development-unit-tests.asciidoc @@ -0,0 +1,145 @@ +[[development-unit-tests]] +==== Unit testing frameworks + +{kib} is migrating unit testing from `Mocha` to `Jest`. Legacy unit tests +still exist in Mocha but all new unit tests should be written in Jest. + +[float] +===== Mocha (legacy) + +Mocha tests are contained in `__tests__` directories. + +*Running Mocha Unit Tests* + +["source","shell"] +----------- +yarn test:mocha +----------- + +[float] +==== Jest +Jest tests are stored in the same directory as source code files with the `.test.{js,mjs,ts,tsx}` suffix. + +*Running Jest Unit Tests* + +["source","shell"] +----------- +yarn test:jest +----------- + +[float] +====== Writing Jest Unit Tests + +In order to write those tests there are two main things you need to be aware of. +The first one is the different between `jest.mock` and `jest.doMock` +and the second one our `jest mocks file pattern`. As we are running `js` and `ts` +test files with `babel-jest` both techniques are needed +specially for the tests implemented on Typescript in order to benefit from the +auto-inference types feature. + +[float] +====== Jest.mock vs Jest.doMock + +Both methods are essentially the same on their roots however the `jest.mock` +calls will get hoisted to the top of the file and can only reference variables +prefixed with `mock`. On the other hand, `jest.doMock` won't be hoisted and can +reference pretty much any variable we want, however we have to assure those referenced +variables are instantiated at the time we need them which lead us to the next +section where we'll talk about our jest mock files pattern. + +[float] +====== Jest Mock Files Pattern + +Specially on typescript it is pretty common to have in unit tests +`jest.doMock` calls which reference for example imported types. Any error +will thrown from doing that however the test will fail. The reason behind that +is because despite the `jest.doMock` isn't being hoisted by `babel-jest` the +import with the types we are referencing will be hoisted to the top and at the +time we'll call the function that variable would not be defined. + +In order to prevent that we develop a protocol that should be followed: + +- Each module could provide a standard mock in `mymodule.mock.ts` in case +there are other tests that could benefit from using definitions here. +This file would not have any `jest.mock` calls, just dummy objects. + +- Each test defines its mocks in `mymodule.test.mocks.ts`. This file +could import relevant mocks from the generalised module's mocks +file `(*.mock.ts)` and call `jest.mock` for each of them. If there is +any relevant dummy mock objects to generalise (and to be used by +other tests), the dummy objects could be defined directly on this file. + +- Each test would import its mocks from the test mocks +file mymodule.test.mocks.ts. `mymodule.test.ts` has an import +like: `import * as Mocks from './mymodule.test.mocks'`, +`import { mockX } from './mymodule.test.mocks'` +or just `import './mymodule.test.mocks'` if there isn't anything +exported to be used. + +[float] +[[debugging-unit-tests]] +===== Debugging Unit Tests + +The standard `yarn test` task runs several sub tasks and can take +several minutes to complete, making debugging failures pretty painful. +In order to ease the pain specialized tasks provide alternate methods +for running the tests. + +You could also add the `--debug` option so that `node` is run using +the `--debug-brk` flag. You’ll need to connect a remote debugger such +as https://github.com/node-inspector/node-inspector[`node-inspector`] +to proceed in this mode. + +[source,bash] +---- +node scripts/mocha --debug +---- + +With `yarn test:karma`, you can run only the browser tests. Coverage +reports are available for browser tests by running +`yarn test:coverage`. You can find the results under the `coverage/` +directory that will be created upon completion. + +[source,bash] +---- +yarn test:karma +---- + +Using `yarn test:karma:debug` initializes an environment for debugging +the browser tests. Includes an dedicated instance of the {kib} server +for building the test bundle, and a karma server. When running this task +the build is optimized for the first time and then a karma-owned +instance of the browser is opened. Click the "`debug`" button to open a +new tab that executes the unit tests. + +[source,bash] +---- +yarn test:karma:debug +---- + +In the screenshot below, you’ll notice the URL is +`localhost:9876/debug.html`. You can append a `grep` query parameter +to this URL and set it to a string value which will be used to exclude +tests which don’t match. For example, if you changed the URL to +`localhost:9876/debug.html?query=my test` and then refreshed the +browser, you’d only see tests run which contain "`my test`" in the test +description. + +image:http://i.imgur.com/DwHxgfq.png[Browser test debugging] + +[float] +===== Unit Testing Plugins + +This should work super if you’re using the +https://github.com/elastic/kibana/tree/master/packages/kbn-plugin-generator[Kibana +plugin generator]. If you’re not using the generator, well, you’re on +your own. We suggest you look at how the generator works. + +To run the tests for just your particular plugin run the following +command from your plugin: + +[source,bash] +---- +yarn test:mocha +yarn test:karma:debug # remove the debug flag to run them once and close +---- \ No newline at end of file diff --git a/docs/developer/contributing/index.asciidoc b/docs/developer/contributing/index.asciidoc new file mode 100644 index 0000000000000..4f987f31cf1f6 --- /dev/null +++ b/docs/developer/contributing/index.asciidoc @@ -0,0 +1,89 @@ +[[contributing]] +== Contributing + +Whether you want to fix a bug, implement a feature, or add some other improvements or apis, the following sections will +guide you on the process. + +Read <> to get your environment up and running, then read <>. + +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> + +[discrete] +[[signing-contributor-agreement]] +=== Signing the contributor license agreement + +Please make sure you have signed the [Contributor License Agreement](http://www.elastic.co/contributor-agreement/). We are not asking you to assign copyright to us, but to give us the right to distribute your code without restriction. We ask this of all contributors in order to assure our users of the origin and continuing existence of the code. You only need to sign the CLA once. + +[float] +[[kibana-localization]] +=== Localization + +Read <> for details on our localization practices. + +Note that we cannot support accepting contributions to the translations from any source other than the translators we have engaged to do the work. +We are still to develop a proper process to accept any contributed translations. We certainly appreciate that people care enough about the localization effort to want to help improve the quality. We aim to build out a more comprehensive localization process for the future and will notify you once contributions can be supported, but for the time being, we are not able to incorporate suggestions. + +[float] +[[kibana-release-notes-process]] +=== Release Notes Process + +Part of this process only applies to maintainers, since it requires +access to GitHub labels. + +{kib} publishes https://www.elastic.co/guide/en/kibana/current/release-notes.html[Release Notes] for major and minor releases. +The Release Notes summarize what the PRs accomplish in language that is meaningful to users. + To generate the Release Notes, the team runs a script against this repo to collect the merged PRs against the release. + +[float] +==== Create the Release Notes text + +The text that appears in the Release Notes is pulled directly from your PR title, or a single paragraph of text that you specify in the PR description. + +To use a single paragraph of text, enter `Release note:` or a `## Release note` header in the PR description, followed by your text. For example, refer to this https://github.com/elastic/kibana/pull/65796[PR] that uses the `## Release note` header. + +When you create the Release Notes text, use the following best practices: + +* Use present tense. +* Use sentence case. +* When you create a feature PR, start with `Adds`. +* When you create an enhancement PR, start with `Improves`. +* When you create a bug fix PR, start with `Fixes`. +* When you create a deprecation PR, start with `Deprecates`. + +[float] +==== Add your labels + +[arabic] +. Label the PR with the targeted version (ex: `v7.3.0`). +. Label the PR with the appropriate GitHub labels: + * For a new feature or functionality, use `release_note:enhancement`. + * For an external-facing fix, use `release_note:fix`. We do not include docs, build, and test fixes in the Release Notes, or unreleased issues that are only on `master`. + * For a deprecated feature, use `release_note:deprecation`. + * For a breaking change, use `release_note:breaking`. + * To **NOT** include your changes in the Release Notes, use `release_note:skip`. + + +include::development-github.asciidoc[] + +include::development-tests.asciidoc[] + +include::interpreting-ci-failures.asciidoc[] + +include::development-documentation.asciidoc[] + +include::development-pull-request.asciidoc[] + +include::kibana-issue-reporting.asciidoc[] + +include::pr-review.asciidoc[] + +include::linting.asciidoc[] diff --git a/docs/developer/testing/interpreting-ci-failures.asciidoc b/docs/developer/contributing/interpreting-ci-failures.asciidoc similarity index 84% rename from docs/developer/testing/interpreting-ci-failures.asciidoc rename to docs/developer/contributing/interpreting-ci-failures.asciidoc index bc237928cf5aa..ba3999a310198 100644 --- a/docs/developer/testing/interpreting-ci-failures.asciidoc +++ b/docs/developer/contributing/interpreting-ci-failures.asciidoc @@ -1,23 +1,23 @@ [[interpreting-ci-failures]] -== Interpreting CI Failures +=== Interpreting CI Failures -Kibana CI uses a Jenkins feature called "Pipelines" to automate testing of the code in pull requests and on tracked branches. Pipelines are defined within the repository via the `Jenkinsfile` at the root of the project. +{kib} CI uses a Jenkins feature called "Pipelines" to automate testing of the code in pull requests and on tracked branches. Pipelines are defined within the repository via the `Jenkinsfile` at the root of the project. More information about Jenkins Pipelines can be found link:https://jenkins.io/doc/book/pipeline/[in the Jenkins book]. [float] -=== Github Checks +==== Github Checks When a test fails it will be reported to Github via Github Checks. We currently bucket tests into several categories which run in parallel to make CI faster. Groups like `ciGroup{X}` get a single check in Github, and other tests like linting, or type checks, get their own checks. Clicking the link next to the check in the conversation tab of a pull request will take you to the log output from that section of the tests. If that log output is truncated, or doesn't clearly identify what happened, you can usually get more complete information by visiting Jenkins directly. [float] -=== Viewing Job Executions in Jenkins +==== Viewing Job Executions in Jenkins To view the results of a job execution in Jenkins, either click the link in the comment left by `@elasticmachine` or search for the `kibana-ci` check in the list at the bottom of the PR. This link will take you to the top-level page for the specific job execution that failed. -image::images/jenkins/job_view.png[] +image::images/job_view.png[] 1. *Git Changes:* the list of commits that were in this build which weren't in the previous build. For Pull Requests this list is calculated by comparing against the most recent Pull Request which was tested, it is not limited to build for this specific Pull Request, so it's not very useful. 2. *Test Results:* A link to the test results screen, and shortcuts to the failed tests. Functional tests capture and store the log output from each specific test, and make it visible at these links. For other test runners only the error message is visible and log output must be tracked down in the *Pipeline Steps*. @@ -25,10 +25,10 @@ image::images/jenkins/job_view.png[] 4. *Pipeline Steps:*: A breakdown of the pipline that was executed, along with individual log output for each step in the pipeline. [float] -=== Viewing ciGroup/test Logs +==== Viewing ciGroup/test Logs To view the logs for a failed specific ciGroup, jest, mocha, type checkers, linters, etc., click on the *Pipeline Steps* link in from the Job page. -image::images/jenkins/pipeline_steps_view.png[] +image::images/pipeline_steps_view.png[] Scroll down the page until you find a failed step *(1)*, and then look up a few lines for the `Branch:` step to see which specific job this is. If this is the job you're looking for click the little terminal icon next to the failed step *(1)* to view the logs for that specific step in the Pipeline. \ No newline at end of file diff --git a/docs/developer/contributing/kibana-issue-reporting.asciidoc b/docs/developer/contributing/kibana-issue-reporting.asciidoc new file mode 100644 index 0000000000000..36c50b612d675 --- /dev/null +++ b/docs/developer/contributing/kibana-issue-reporting.asciidoc @@ -0,0 +1,46 @@ +[[kibana-issue-reporting]] +=== Effective issue reporting in {kib} + +[float] +==== Voicing the importance of an issue + +We seriously appreciate thoughtful comments. If an issue is important to +you, add a comment with a solid write up of your use case and explain +why it’s so important. Please avoid posting comments comprised solely of +a thumbs up emoji 👍. + +Granted that you share your thoughts, we might even be able to come up +with creative solutions to your specific problem. If everything you’d +like to say has already been brought up but you’d still like to add a +token of support, feel free to add a +https://github.com/blog/2119-add-reactions-to-pull-requests-issues-and-comments[👍 +thumbs up reaction] on the issue itself and on the comment which best +summarizes your thoughts. + +[float] +==== "`My issue isn’t getting enough attention`" + +First of all, *sorry about that!* We want you to have a great time with +{kib}. + +There’s hundreds of open issues and prioritizing what to work on is an +important aspect of our daily jobs. We prioritize issues according to +impact and difficulty, so some issues can be neglected while we work on +more pressing issues. + +Feel free to bump your issues if you think they’ve been neglected for a +prolonged period. + +[float] +==== "`I want to help!`" + +*Now we’re talking*. If you have a bug fix or new feature that you would +like to contribute to {kib}, please *find or open an issue about it +before you start working on it.* Talk about what you would like to do. +It may be that somebody is already working on it, or that there are +particular issues that you should know about before implementing the +change. + +We enjoy working with contributors to get their code accepted. There are +many approaches to fixing a problem and it is important to find the best +approach before writing too much code. \ No newline at end of file diff --git a/docs/developer/contributing/linting.asciidoc b/docs/developer/contributing/linting.asciidoc new file mode 100644 index 0000000000000..234bd90478907 --- /dev/null +++ b/docs/developer/contributing/linting.asciidoc @@ -0,0 +1,70 @@ +[[kibana-linting]] +=== Linting + +A note about linting: We use http://eslint.org[eslint] to check that the +link:STYLEGUIDE.md[styleguide] is being followed. It runs in a +pre-commit hook and as a part of the tests, but most contributors +integrate it with their code editors for real-time feedback. + +Here are some hints for getting eslint setup in your favorite editor: + +[width="100%",cols="13%,87%",options="header",] +|=== +|Editor |Plugin +|Sublime +|https://github.com/roadhump/SublimeLinter-eslint#installation[SublimeLinter-eslint] + +|Atom +|https://github.com/AtomLinter/linter-eslint#installation[linter-eslint] + +|VSCode +|https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint[ESLint] + +|IntelliJ |Settings » Languages & Frameworks » JavaScript » Code Quality +Tools » ESLint + +|`vi` |https://github.com/scrooloose/syntastic[scrooloose/syntastic] +|=== + +Another tool we use for enforcing consistent coding style is +EditorConfig, which can be set up by installing a plugin in your editor +that dynamically updates its configuration. Take a look at the +http://editorconfig.org/#download[EditorConfig] site to find a plugin +for your editor, and browse our +https://github.com/elastic/kibana/blob/master/.editorconfig[`.editorconfig`] +file to see what config rules we set up. + +[float] +==== Setup Guide for VS Code Users + +Note that for VSCode, to enable "`live`" linting of TypeScript (and +other) file types, you will need to modify your local settings, as shown +below. The default for the ESLint extension is to only lint JavaScript +file types. + +[source,json] +---- +"eslint.validate": [ + "javascript", + "javascriptreact", + { "language": "typescript", "autoFix": true }, + { "language": "typescriptreact", "autoFix": true } +] +---- + +`eslint` can automatically fix trivial lint errors when you save a +file by adding this line in your setting. + +[source,json] +---- + "eslint.autoFixOnSave": true, +---- + +:warning: It is *not* recommended to use the +https://prettier.io/[`Prettier` extension/IDE plugin] while +maintaining the {kib} project. Formatting and styling roles are set in +the multiple `.eslintrc.js` files across the project and some of them +use the https://www.npmjs.com/package/prettier[NPM version of Prettier]. +Using the IDE extension might cause conflicts, applying the formatting +to too many files that shouldn’t be prettier-ized and/or highlighting +errors that are actually OK. \ No newline at end of file diff --git a/docs/developer/pr-review.asciidoc b/docs/developer/contributing/pr-review.asciidoc similarity index 90% rename from docs/developer/pr-review.asciidoc rename to docs/developer/contributing/pr-review.asciidoc index 304718e437dc5..ebab3b24aaaee 100644 --- a/docs/developer/pr-review.asciidoc +++ b/docs/developer/contributing/pr-review.asciidoc @@ -1,7 +1,7 @@ [[pr-review]] -== Pull request review guidelines +=== Pull request review guidelines -Every change made to Kibana must be held to a high standard, and while the responsibility for quality in a pull request ultimately lies with the author, Kibana team members have the responsibility as reviewers to verify during their review process. +Every change made to {kib} must be held to a high standard, and while the responsibility for quality in a pull request ultimately lies with the author, {kib} team members have the responsibility as reviewers to verify during their review process. Frankly, it's impossible to build a concrete list of requirements that encompass all of the possible situations we'll encounter when reviewing pull requests, so instead this document tries to lay out a common set of the few obvious requirements while also outlining a general philosophy that we should have when approaching any PR review. @@ -11,15 +11,15 @@ While the review process is always done by Elastic staff members, these guidelin [float] -=== Target audience +==== Target audience -The target audience for this document are pull request reviewers. For Kibana maintainers, the PR review is the only part of the contributing process in which we have complete control. The author of any given pull request may not be up to speed on the latest expectations we have for pull requests, and they may have never read our guidelines at all. It's our responsibility as reviewers to guide folks through this process, but it's hard to do that consistently without a common set of documented principles. +The target audience for this document are pull request reviewers. For {kib} maintainers, the PR review is the only part of the contributing process in which we have complete control. The author of any given pull request may not be up to speed on the latest expectations we have for pull requests, and they may have never read our guidelines at all. It's our responsibility as reviewers to guide folks through this process, but it's hard to do that consistently without a common set of documented principles. Pull request authors can benefit from reading this document as well because it'll help establish a common set of expectations between authors and reviewers early. [float] -=== Reject fast +==== Reject fast Every pull request is different, and before reviewing any given PR, reviewers should consider the optimal way to approach the PR review so that if the change is ultimately rejected, it is done so as early in the process as possible. @@ -27,7 +27,7 @@ For example, a reviewer may want to do a product level review as early as possib [float] -=== The big three +==== The big three There are a lot of discrete requirements and guidelines we want to follow in all of our pull requests, but three things in particular stand out as important above all the rest. @@ -58,24 +58,24 @@ This isn't simply a question of enough test files. The code in the tests themsel All of our code should have unit tests that verify its behaviors, including not only the "happy path", but also edge cases, error handling, etc. When you change an existing API of a module, then there should always be at least one failing unit test, which in turn means we need to verify that all code consuming that API properly handles the change if necessary. For modules at a high enough level, this will mean we have breaking change in the product, which we'll need to handle accordingly. -In addition to extensive unit test coverage, PRs should include relevant functional and integration tests. In some cases, we may simply be testing a programmatic interface (e.g. a service) that is integrating with the file system, the network, Elasticsearch, etc. In other cases, we'll be testing REST APIs over HTTP or comparing screenshots/snapshots with prior known acceptable state. In the worst case, we are doing browser-based functional testing on a running instance of Kibana using selenium. +In addition to extensive unit test coverage, PRs should include relevant functional and integration tests. In some cases, we may simply be testing a programmatic interface (e.g. a service) that is integrating with the file system, the network, Elasticsearch, etc. In other cases, we'll be testing REST APIs over HTTP or comparing screenshots/snapshots with prior known acceptable state. In the worst case, we are doing browser-based functional testing on a running instance of {kib} using selenium. Enhancements are pretty much always going to have extensive unit tests as a base as well as functional and integration testing. Bug fixes should always include regression tests to ensure that same bug does not manifest again in the future. -- [float] -=== Product level review +==== Product level review Reviewers are not simply evaluating the code itself, they are also evaluating the quality of the user-facing change in the product. This generally means they need to check out the branch locally and "play around" with it. In addition to the "do we want this change in the product" details, the reviewer should be looking for bugs and evaluating how approachable and useful the feature is as implemented. Special attention should be given to error scenarios and edge cases to ensure they are all handled well within the product. [float] -=== Consistency, style, readability +==== Consistency, style, readability Having a relatively consistent codebase is an important part of us building a sustainable project. With dozens of active contributors at any given time, we rely on automation to help ensure consistency - we enforce a comprehensive set of linting rules through CI. We're also rolling out prettier to make this even more automatic. -For things that can't be easily automated, we maintain a link:https://github.com/elastic/kibana/blob/master/STYLEGUIDE.md[style guide] that authors should adhere to and reviewers should keep in mind when they review a pull request. +For things that can't be easily automated, we maintain a link:{kib-repo}tree/{branch}/STYLEGUIDE.md[style guide] that authors should adhere to and reviewers should keep in mind when they review a pull request. Beyond that, we're into subjective territory. Statements like "this isn't very readable" are hardly helpful since they can't be qualified, but that doesn't mean a reviewer should outright ignore code that is hard to understand due to how it is written. There isn't one definitively "best" way to write any particular code, so pursuing such shouldn't be our goal. Instead, reviewers and authors alike must accept that there are likely many different appropriate ways to accomplish the same thing with code, and so long as the contribution is utilizing one of those ways, then we're in good shape. @@ -87,7 +87,7 @@ There may also be times when a person is inspired by a particular contribution t [float] -=== Nitpicking +==== Nitpicking Nitpicking is when a reviewer identifies trivial and unimportant details in a pull request and asks the author to change them. This is a completely subjective category that is impossible to define universally, and it's equally impractical to define a blanket policy on nitpicking that everyone will be happy with. @@ -97,13 +97,13 @@ Often, reviewers have an opinion about whether the feedback they are about to gi [float] -=== Handling disagreements +==== Handling disagreements Conflicting opinions between reviewers and authors happen, and sometimes it is hard to reconcile those opinions. Ideally folks can work together in the spirit of these guidelines toward a consensus, but if that doesn't work out it may be best to bring a third person into the discussion. Our pull requests generally have two reviewers, so an appropriate third person may already be obvious. Otherwise, reach out to the functional area that is most appropriate or to technical leadership if an area isn't obvious. [float] -=== Inappropriate review feedback +==== Inappropriate review feedback Whether or not a bit of feedback is appropriate for a pull request is often dependent on the motivation for giving the feedback in the first place. @@ -113,7 +113,7 @@ Inflammatory feedback such as "this is crap" isn't feedback at all. It's both me [float] -=== A checklist +==== A checklist Establishing a comprehensive checklist for all of the things that should happen in all possible pull requests is impractical, but that doesn't mean we lack a concrete set of minimum requirements that we can enumerate. The following items should be double checked for any pull request: diff --git a/docs/developer/core-development.asciidoc b/docs/developer/core-development.asciidoc deleted file mode 100644 index 8f356abd095f2..0000000000000 --- a/docs/developer/core-development.asciidoc +++ /dev/null @@ -1,24 +0,0 @@ -[[core-development]] -== Core Development - -* <> -* <> -* <> -* <> -* <> -* <> -* <> - -include::core/development-basepath.asciidoc[] - -include::core/development-dependencies.asciidoc[] - -include::core/development-modules.asciidoc[] - -include::core/development-elasticsearch.asciidoc[] - -include::core/development-unit-tests.asciidoc[] - -include::core/development-functional-tests.asciidoc[] - -include::core/development-es-snapshots.asciidoc[] diff --git a/docs/developer/core/development-basepath.asciidoc b/docs/developer/core/development-basepath.asciidoc deleted file mode 100644 index d49dfe2938fad..0000000000000 --- a/docs/developer/core/development-basepath.asciidoc +++ /dev/null @@ -1,85 +0,0 @@ -[[development-basepath]] -=== Considerations for basePath - -All communication from the Kibana UI to the server needs to respect the -`server.basePath`. Here are the "blessed" strategies for dealing with this -based on the context: - -[float] -==== Getting a static asset url - -Use webpack to import the asset into the build. This will give you a URL in -JavaScript and gives webpack a chance to perform optimizations and -cache-busting. - -["source","shell"] ------------ -// in plugin/public/main.js -import uiChrome from 'ui/chrome'; -import logoUrl from 'plugins/facechimp/assets/banner.png'; - -uiChrome.setBrand({ - logo: `url(${logoUrl}) center no-repeat` -}); ------------ - -[float] -==== API requests from the front-end - -Use `chrome.addBasePath()` to append the basePath to the front of the url. - -["source","shell"] ------------ -import chrome from 'ui/chrome'; -$http.get(chrome.addBasePath('/api/plugin/things')); ------------ - -[float] -==== Server side - -Append `request.getBasePath()` to any absolute URL path. - -["source","shell"] ------------ -const basePath = server.config().get('server.basePath'); -server.route({ - path: '/redirect', - handler(request, h) { - return h.redirect(`${request.getBasePath()}/otherLocation`); - } -}); ------------ - -[float] -==== BasePathProxy in dev mode - -The Kibana dev server automatically runs behind a proxy with a random -`server.basePath`. This way developers will be constantly verifying that their -code works with basePath, while they write it. - -To accomplish this the `serve` task does a few things: - -1. change the port for the server to the `dev.basePathProxyTarget` setting (default `5603`) -2. start a `BasePathProxy` at `server.port` - - picks a random 3-letter value for `randomBasePath` - - redirects from `/` to `/{randomBasePath}` - - redirects from `/{any}/app/{appName}` to `/{randomBasePath}/app/{appName}` so that refreshes should work - - proxies all requests starting with `/{randomBasePath}/` to the Kibana server - -If you're writing scripts that interact with the Kibana API, the base path proxy will likely -make this difficult. To bypass the base path proxy for a single request, prefix urls with -`__UNSAFE_bypassBasePath` and the request will be routed to the development Kibana server. - -["source","shell"] ------------ -curl "http://elastic:changeme@localhost:5601/__UNSAFE_bypassBasePath/api/status" ------------ - -This proxy can sometimes have unintended side effects in development, so when -needed you can opt out by passing the `--no-base-path` flag to the `serve` task -or `yarn start`. - -["source","shell"] ------------ -yarn start --no-base-path ------------ diff --git a/docs/developer/core/development-dependencies.asciidoc b/docs/developer/core/development-dependencies.asciidoc deleted file mode 100644 index 285d338a23a0d..0000000000000 --- a/docs/developer/core/development-dependencies.asciidoc +++ /dev/null @@ -1,103 +0,0 @@ -[[development-dependencies]] -=== Managing Dependencies - -While developing plugins for use in the Kibana front-end environment you will -probably want to include a library or two (at least). While that should be -simple to do 90% of the time, there are always outliers, and some of those -outliers are very popular projects. - -Before you can use an external library with Kibana you have to install it. You -do that using... - -[float] -==== yarn (preferred method) - -Once you've http://npmsearch.com[found] a dependency you want to add, you can -install it like so: - -["source","shell"] ------------ -yarn add some-neat-library ------------ - -At the top of a javascript file, just import the library using it's name: - -["source","shell"] ------------ -import someNeatLibrary from 'some-neat-library'; ------------ - -Just like working in node.js, front-end code can require node modules installed -by yarn without any additional configuration. - -[float] -==== webpackShims - -When a library you want to use does use es6 or common.js modules but is not -available with yarn, you can copy the source of the library into a webpackShim. - -["source","shell"] ------------ -# create a directory for our new library to live -mkdir -p webpackShims/some-neat-library -# download the library you want to use into that directory -curl https://cdnjs.com/some-neat-library/library.js > webpackShims/some-neat-library/index.js ------------ - -Then include the library in your JavaScript code as you normally would: - -["source","shell"] ------------ -import someNeatLibrary from 'some-neat-library'; ------------ - -[float] -==== Shimming third party code - -Some JavaScript libraries do not declare their dependencies in a way that tools -like webpack can understand. It is also often the case that libraries do not -`export` their provided values, but simply write them to a global variable name -(or something to that effect). - -When pulling code like this into Kibana we need to write "shims" that will -adapt the third party code to work with our application, other libraries, and -module system. To do this we can utilize the `webpackShims` directory. - -The easiest way to explain how to write a shim is to show you some. Here is our -webpack shim for jQuery: - -["source","shell"] ------------ -// webpackShims/jquery.js - -module.exports = window.jQuery = window.$ = require('../node_modules/jquery/dist/jquery'); -require('ui/jquery/findTestSubject')(window.$); ------------ - -This shim is loaded up anytime an `import 'jquery';` statement is found by -webpack, because of the way that `webpackShims` behaves like `node_modules`. -When that happens, the shim does two things: - -. Assign the exported value of the actual jQuery module to the window at `$` and `jQuery`, allowing libraries like angular to detect that jQuery is available, and use it as the module's export value. -. Finally, a jQuery plugin that we wrote is included so that every time a file imports jQuery it will get both jQuery and the `$.findTestSubject` helper function. - -Here is what our webpack shim for angular looks like: - -["source","shell"] ------------ -// webpackShims/angular.js - -require('jquery'); -require('../node_modules/angular/angular'); -require('../node_modules/angular-elastic/elastic'); -require('ui/modules').get('kibana', ['monospaced.elastic']); -module.exports = window.angular; ------------ - -What this shim does is fairly simple if you go line by line: - -. makes sure that jQuery is loaded before angular (which actually runs the shim) -. load the angular.js file from the node_modules directory -. load the angular-elastic plugin, a plugin we want to always be included whenever we import angular -. use the `ui/modules` module to add the module exported by angular-elastic as a dependency to the `kibana` angular module -. finally, export the window.angular variable. This means that writing `import angular from 'angular';` will properly set the angular variable to the angular library, rather than undefined which is the default behavior. diff --git a/docs/developer/core/development-elasticsearch.asciidoc b/docs/developer/core/development-elasticsearch.asciidoc deleted file mode 100644 index 89f85cfc19fbf..0000000000000 --- a/docs/developer/core/development-elasticsearch.asciidoc +++ /dev/null @@ -1,40 +0,0 @@ -[[development-elasticsearch]] -=== Communicating with Elasticsearch - -Kibana exposes two clients on the server and browser for communicating with elasticsearch. -There is an 'admin' client which is used for managing Kibana's state, and a 'data' client for all -other requests. The clients use the {jsclient-current}/index.html[elasticsearch.js library]. - -[float] -[[client-server]] -=== Server clients - -Server clients are exposed through the elasticsearch plugin. -[source,javascript] ----- - const adminCluster = server.plugins.elasticsearch.getCluster('admin'); - const dataCluster = server.plugins.elasticsearch.getCluster('data'); - - //ping as the configured elasticsearch.user in kibana.yml - adminCluster.callWithInternalUser('ping'); - - //ping as the user specified in the current requests header - adminCluster.callWithRequest(req, 'ping'); ----- - -[float] -[[client-browser]] -=== Browser clients - -Browser clients are exposed through AngularJS services. - -[source,javascript] ----- -uiModules.get('kibana') -.run(function (es) { - es.ping() - .catch(err => { - console.log('error pinging servers'); - }); -}); ----- diff --git a/docs/developer/core/development-modules.asciidoc b/docs/developer/core/development-modules.asciidoc deleted file mode 100644 index cc5cd69ed8cb9..0000000000000 --- a/docs/developer/core/development-modules.asciidoc +++ /dev/null @@ -1,63 +0,0 @@ -[[development-modules]] -=== Modules and Autoloading - -[float] -==== Autoloading - -Because of the disconnect between JS modules and angular directives, filters, -and services it is difficult to know what you need to import. It is even more -difficult to know if you broke something by removing an import that looked -unused. - -To prevent this from being an issue the ui module provides "autoloading" -modules. The sole purpose of these modules is to extend the environment with -certain components. Here is a breakdown of those modules: - -- *`import 'ui/autoload/modules'`* - Imports angular and several ui services and "components" which Kibana - depends on without importing. The full list of imports is hard coded in the - module. Hopefully this list will shrink over time as we properly map out - the required modules and import them were they are actually necessary. - -- *`import 'ui/autoload/all'`* - Imports all of the modules - -[float] -==== Resolving Require Paths - -Kibana uses Webpack to bundle Kibana's dependencies. - -Here is how import/require statements are resolved to a file: - -. Check the beginning of the module path - * if the path starts with a '.' - ** append it the directory of the current file - ** proceed to *3* - * if the path starts with a '/' - ** search for this exact path - ** proceed to *3* - * proceed to *2* -. Search for a named module - * `moduleName` = dirname(require path)` - * match if `moduleName` is or starts with one of these aliases - ** replace the alias with the match and continue to ***3*** - * match when any of these conditions are met: - ** `./webpackShims/${moduleName}` is a directory - ** `./node_modules/${moduleName}` is a directory - * if no match was found - ** move to the parent directory - ** start again at *2.iii* until reaching the root directory or a match is found - * if a match was found - ** replace the `moduleName` prefix from the require statement with the full path of the match and proceed to *3* -. Search for a file - * the first of the following paths that resolves to a **file** is our match - ** path + '.js' - ** path + '.json' - ** path - ** path/${basename(path)} + '.js' - ** path/${basename(path)} + '.json' - ** path/${basename(path)} - ** path/index + '.js' - ** path/index + '.json' - ** path/index - * if none of the paths matches then an error is thrown diff --git a/docs/developer/core/development-unit-tests.asciidoc b/docs/developer/core/development-unit-tests.asciidoc deleted file mode 100644 index 04cce0dfec901..0000000000000 --- a/docs/developer/core/development-unit-tests.asciidoc +++ /dev/null @@ -1,83 +0,0 @@ -[[development-unit-tests]] -=== Unit Testing - -We use unit tests to make sure that individual software units of {kib} perform as they were designed to. - -[float] -=== Current Frameworks - -{kib} is migrating unit testing from `Mocha` to `Jest`. Legacy unit tests still exist in `Mocha` but all new unit tests should be written in `Jest`. - -[float] -==== Mocha (legacy) - -Mocha tests are contained in `__tests__` directories. - -*Running Mocha Unit Tests* - -["source","shell"] ------------ -yarn test:mocha ------------ - -[float] -==== Jest -Jest tests are stored in the same directory as source code files with the `.test.{js,mjs,ts,tsx}` suffix. - -*Running Jest Unit Tests* - -["source","shell"] ------------ -yarn test:jest ------------ - -[float] -===== Writing Jest Unit Tests - -In order to write those tests there are two main things you need to be aware of. -The first one is the different between `jest.mock` and `jest.doMock` -and the second one our `jest mocks file pattern`. As we are running `js` and `ts` -test files with `babel-jest` both techniques are needed -specially for the tests implemented on Typescript in order to benefit from the -auto-inference types feature. - -[float] -===== Jest.mock vs Jest.doMock - -Both methods are essentially the same on their roots however the `jest.mock` -calls will get hoisted to the top of the file and can only reference variables -prefixed with `mock`. On the other hand, `jest.doMock` won't be hoisted and can -reference pretty much any variable we want, however we have to assure those referenced -variables are instantiated at the time we need them which lead us to the next -section where we'll talk about our jest mock files pattern. - -[float] -===== Jest Mock Files Pattern - -Specially on typescript it is pretty common to have in unit tests -`jest.doMock` calls which reference for example imported types. Any error -will thrown from doing that however the test will fail. The reason behind that -is because despite the `jest.doMock` isn't being hoisted by `babel-jest` the -import with the types we are referencing will be hoisted to the top and at the -time we'll call the function that variable would not be defined. - -In order to prevent that we develop a protocol that should be followed: - -- Each module could provide a standard mock in `mymodule.mock.ts` in case -there are other tests that could benefit from using definitions here. -This file would not have any `jest.mock` calls, just dummy objects. - -- Each test defines its mocks in `mymodule.test.mocks.ts`. This file -could import relevant mocks from the generalised module's mocks -file `(*.mock.ts)` and call `jest.mock` for each of them. If there is -any relevant dummy mock objects to generalise (and to be used by -other tests), the dummy objects could be defined directly on this file. - -- Each test would import its mocks from the test mocks -file mymodule.test.mocks.ts. `mymodule.test.ts` has an import -like: `import * as Mocks from './mymodule.test.mocks'`, -`import { mockX } from './mymodule.test.mocks'` -or just `import './mymodule.test.mocks'` if there isn't anything -exported to be used. - - diff --git a/docs/developer/getting-started/building-kibana.asciidoc b/docs/developer/getting-started/building-kibana.asciidoc new file mode 100644 index 0000000000000..e1f1ca336a5da --- /dev/null +++ b/docs/developer/getting-started/building-kibana.asciidoc @@ -0,0 +1,39 @@ +[[building-kibana]] +=== Building a {kib} distributable + +The following commands will build a {kib} production distributable. + +[source,bash] +---- +yarn build --skip-os-packages +---- + +You can get all build options using the following command: + +[source,bash] +---- +yarn build --help +---- + +[float] +==== Building OS packages + +Packages are built using fpm, dpkg, and rpm. Package building has only been tested on Linux and is not supported on any other platform. + + +[source,bash] +---- +apt-get install ruby-dev rpm +gem install fpm -v 1.5.0 +yarn build --skip-archives +---- + +To specify a package to build you can add `rpm` or `deb` as an argument. + + +[source,bash] +---- +yarn build --rpm +---- + +Distributable packages can be found in `target/` after the build completes. \ No newline at end of file diff --git a/docs/developer/getting-started/debugging.asciidoc b/docs/developer/getting-started/debugging.asciidoc new file mode 100644 index 0000000000000..b369dcda748af --- /dev/null +++ b/docs/developer/getting-started/debugging.asciidoc @@ -0,0 +1,59 @@ +[[kibana-debugging]] +=== Debugging {kib} + +For information about how to debug unit tests, refer to <>. + +[float] +==== Server Code + +`yarn debug` will start the server with Node's inspect flag. {kib}'s development mode will start three processes on ports `9229`, `9230`, and `9231`. Chrome's developer tools need to be configured to connect to all three connections. Add `localhost:` for each {kib} process in Chrome's developer tools connection tab. + +[float] +==== Instrumenting with Elastic APM + +{kib} ships with the +https://github.com/elastic/apm-agent-nodejs[Elastic APM Node.js Agent] +built-in for debugging purposes. + +Its default configuration is meant to be used by core {kib} developers +only, but it can easily be re-configured to your needs. In its default +configuration it’s disabled and will, once enabled, send APM data to a +centrally managed Elasticsearch cluster accessible only to Elastic +employees. + +To change the location where data is sent, use the +https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#server-url[`serverUrl`] +APM config option. To activate the APM agent, use the +https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#active[`active`] +APM config option. + +All config options can be set either via environment variables, or by +creating an appropriate config file under `config/apm.dev.js`. For +more information about configuring the APM agent, please refer to +https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuring-the-agent.html[the +documentation]. + +Example `config/apm.dev.js` file: + +[source,js] +---- +module.exports = { + active: true, +}; +---- + +APM +https://www.elastic.co/guide/en/apm/agent/rum-js/current/index.html[Real +User Monitoring agent] is not available in the {kib} distributables, +however the agent can be enabled by setting `ELASTIC_APM_ACTIVE` to +`true`. flags + +.... +ELASTIC_APM_ACTIVE=true yarn start +// activates both Node.js and RUM agent +.... + +Once the agent is active, it will trace all incoming HTTP requests to +{kib}, monitor for errors, and collect process-level metrics. The +collected data will be sent to the APM Server and is viewable in the APM +UI in {kib}. \ No newline at end of file diff --git a/docs/developer/getting-started/development-plugin-resources.asciidoc b/docs/developer/getting-started/development-plugin-resources.asciidoc new file mode 100644 index 0000000000000..dfe8efc4fef57 --- /dev/null +++ b/docs/developer/getting-started/development-plugin-resources.asciidoc @@ -0,0 +1,61 @@ +[[development-plugin-resources]] +=== Plugin Resources + +Here are some resources that are helpful for getting started with plugin development. + +[float] +==== Some light reading +If you haven't already, start with <>. If you are planning to add your plugin to the {kib} repo, read the <> guide, if you are building a plugin externally, read <>. In both cases, read up on our recommended <>. + +[float] +==== Creating an empty plugin + +You can use the <> to get a basic structure for a new plugin. Plugins that are not part of the +{kib} repo should be developed inside the `plugins` folder. If you are building a new plugin to check in to the {kib} repo, +you will choose between a few locations: + + - {kib-repo}tree/{branch}/x-pack/plugins[x-pack/plugins] for commercially licensed plugins + - {kib-repo}tree/{branch}/src/plugins[src/plugins] for open source licensed plugins + - {kib-repo}tree/{branch}/examples[examples] for developer example plugins (these will not be included in the distributables) + +[float] +==== Elastic UI Framework +If you're developing a plugin that has a user interface, take a look at our https://elastic.github.io/eui[Elastic UI Framework]. +It documents the CSS and React components we use to build {kib}'s user interface. + +You're welcome to use these components, but be aware that they are rapidly evolving, and we might introduce breaking changes that will disrupt your plugin's UI. + +[float] +==== TypeScript Support +We recommend your plugin code is written in http://www.typescriptlang.org/[TypeScript]. +To enable TypeScript support, create a `tsconfig.json` file at the root of your plugin that looks something like this: + +["source","js"] +----------- +{ + // extend {kib}'s tsconfig, or use your own settings + "extends": "../../kibana/tsconfig.json", + + // tell the TypeScript compiler where to find your source files + "include": [ + "server/**/*", + "public/**/*" + ] +} +----------- + +TypeScript code is automatically converted into JavaScript during development, +but not in the distributable version of {kib}. If you use the +{kib-repo}blob/{branch}/packages/kbn-plugin-helpers[@kbn/plugin-helpers] to build your plugin, then your `.ts` and `.tsx` files will be permanently transpiled before your plugin is archived. If you have your own build process, make sure to run the TypeScript compiler on your source files and ship the compilation output so that your plugin will work with the distributable version of {kib}. + +[float] +==== {kib} platform migration guide + +{kib-repo}blob/{branch}/src/core/MIGRATION.md#migrating-legacy-plugins-to-the-new-platform[This guide] +provides an action plan for moving a legacy plugin to the new platform. + +[float] +==== Externally developed plugins + +If you are building a plugin outside of the {kib} repo, read <>. + diff --git a/docs/developer/getting-started/index.asciidoc b/docs/developer/getting-started/index.asciidoc new file mode 100644 index 0000000000000..47c4a52daf303 --- /dev/null +++ b/docs/developer/getting-started/index.asciidoc @@ -0,0 +1,140 @@ +[[development-getting-started]] +== Getting started + +Get started building your own plugins, or contributing directly to the {kib} repo. + +[float] +[[get-kibana-code]] +=== Get the code + +https://help.github.com/en/github/getting-started-with-github/fork-a-repo[Fork], then https://help.github.com/en/github/getting-started-with-github/fork-a-repo#step-2-create-a-local-clone-of-your-fork[clone] the {kib-repo}[{kib} repo] and change directory into it: + +[source,bash] +---- +git clone https://github.com/[YOUR_USERNAME]/kibana.git kibana +cd kibana +---- + +[float] +=== Install dependencies + +Install the version of Node.js listed in the `.node-version` file. This +can be automated with tools such as +https://github.com/creationix/nvm[nvm], +https://github.com/coreybutler/nvm-windows[nvm-windows] or +https://github.com/wbyoung/avn[avn]. As we also include a `.nvmrc` file +you can switch to the correct version when using nvm by running: + +[source,bash] +---- +nvm use +---- + +Install the latest version of https://yarnpkg.com[yarn]. + +Bootstrap {kib} and install all the dependencies: + +[source,bash] +---- +yarn kbn bootstrap +---- + +____ +Node.js native modules could be in use and node-gyp is the tool used to +build them. There are tools you need to install per platform and python +versions you need to be using. Please see +https://github.com/nodejs/node-gyp#installation[https://github.com/nodejs/node-gyp#installation] +and follow the guide according your platform. +____ + +(You can also run `yarn kbn` to see the other available commands. For +more info about this tool, see +{kib-repo}tree/{branch}/packages/kbn-pm[{kib-repo}tree/{branch}packages/kbn-pm].) + +When switching branches which use different versions of npm packages you +may need to run: + +[source,bash] +---- +yarn kbn clean +---- + +If you have failures during `yarn kbn bootstrap` you may have some +corrupted packages in your yarn cache which you can clean with: + +[source,bash] +---- +yarn cache clean +---- + +[float] +=== Configure environmental settings + +[[increase-nodejs-heap-size]] +[float] +==== Increase node.js heap size + +{kib} is a big project and for some commands it can happen that the +process hits the default heap limit and crashes with an out-of-memory +error. If you run into this problem, you can increase maximum heap size +by setting the `--max_old_space_size` option on the command line. To set +the limit for all commands, simply add the following line to your shell +config: `export NODE_OPTIONS="--max_old_space_size=2048"`. + +[float] +=== Run Elasticsearch + +Run the latest Elasticsearch snapshot. Specify an optional license with the `--license` flag. + +[source,bash] +---- +yarn es snapshot --license trial +---- + +`trial` will give you access to all capabilities. + +Read about more options for <>, like connecting to a remote host, running from source, +preserving data inbetween runs, running remote cluster, etc. + +[float] +=== Run {kib} + +In another terminal window, start up {kib}. Include developer examples by adding an optional `--run-examples` flag. + +[source,bash] +---- +yarn start --run-examples +---- + +View all available options by running `yarn start --help` + +Read about more advanced options for <>. + +[float] +=== Code away! + +You are now ready to start developing. Changes to your files should be picked up automatically. Server side changes will +cause the {kib} server to reboot. + +[float] +=== More information + +* <> + +* <> + +* <> + +* <> + +* <> + +include::running-kibana-advanced.asciidoc[] + +include::sample-data.asciidoc[] + +include::debugging.asciidoc[] + +include::building-kibana.asciidoc[] + +include::development-plugin-resources.asciidoc[] \ No newline at end of file diff --git a/docs/developer/getting-started/running-kibana-advanced.asciidoc b/docs/developer/getting-started/running-kibana-advanced.asciidoc new file mode 100644 index 0000000000000..e36f38de1b366 --- /dev/null +++ b/docs/developer/getting-started/running-kibana-advanced.asciidoc @@ -0,0 +1,87 @@ +[[running-kibana-advanced]] +=== Running {kib} + +Change to your local {kib} directory. Start the development server. + +[source,bash] +---- +yarn start +---- + +____ +On Windows, you’ll need to use Git Bash, Cygwin, or a similar shell that +exposes the `sh` command. And to successfully build you’ll need Cygwin +optional packages zip, tar, and shasum. +____ + +Now you can point your web browser to http://localhost:5601 and start +using {kib}! When running `yarn start`, {kib} will also log that it +is listening on port 5603 due to the base path proxy, but you should +still access {kib} on port 5601. + +By default, you can log in with username `elastic` and password +`changeme`. See the `--help` options on `yarn es ` if +you’d like to configure a different password. + +[float] +==== Running {kib} in Open-Source mode + +If you’re looking to only work with the open-source software, supply the +license type to `yarn es`: + +[source,bash] +---- +yarn es snapshot --license oss +---- + +And start {kib} with only open-source code: + +[source,bash] +---- +yarn start --oss +---- + +[float] +==== Unsupported URL Type + +If you’re installing dependencies and seeing an error that looks +something like + +.... +Unsupported URL Type: link:packages/eslint-config-kibana +.... + +you’re likely running `npm`. To install dependencies in {kib} you +need to run `yarn kbn bootstrap`. For more info, see +link:#setting-up-your-development-environment[Setting Up Your +Development Environment] above. + +[float] +[[customize-kibana-yml]] +==== Customizing `config/kibana.dev.yml` + +The `config/kibana.yml` file stores user configuration directives. +Since this file is checked into source control, however, developer +preferences can’t be saved without the risk of accidentally committing +the modified version. To make customizing configuration easier during +development, the {kib} CLI will look for a `config/kibana.dev.yml` +file if run with the `--dev` flag. This file behaves just like the +non-dev version and accepts any of the +https://www.elastic.co/guide/en/kibana/current/settings.html[standard +settings]. + +[float] +==== Potential Optimization Pitfalls + +* Webpack is trying to include a file in the bundle that I deleted and +is now complaining about it is missing +* A module id that used to resolve to a single file now resolves to a +directory, but webpack isn’t adapting +* (if you discover other scenarios, please send a PR!) + +[float] +==== Setting Up SSL + +{kib} includes self-signed certificates that can be used for +development purposes in the browser and for communicating with +Elasticsearch: `yarn start --ssl` & `yarn es snapshot --ssl`. \ No newline at end of file diff --git a/docs/developer/getting-started/sample-data.asciidoc b/docs/developer/getting-started/sample-data.asciidoc new file mode 100644 index 0000000000000..376211ceb2634 --- /dev/null +++ b/docs/developer/getting-started/sample-data.asciidoc @@ -0,0 +1,31 @@ +[[sample-data]] +=== Installing sample data + +There are a couple ways to easily get data ingested into Elasticsearch. + +[float] +==== Sample data packages available for one click installation + +The easiest is to install one or more of our vailable sample data packages. If you have no data, you should be +prompted to install when running {kib} for the first time. You can also access and install the sample data packages +by going to the home page and clicking "add sample data". + +[float] +==== makelogs script + +The provided `makelogs` script will generate sample data. + +[source,bash] +---- +node scripts/makelogs --auth : +---- + +The default username and password combination are `elastic:changeme` + +Make sure to execute `node scripts/makelogs` *after* elasticsearch is up and running! + +[float] +==== CSV upload + +If running with a platinum or trial license, you can also use the CSV uploader provided inside the Machine learning app. +Navigate to the Data visualizer to upload your data from a file. \ No newline at end of file diff --git a/docs/images/jenkins/job_view.png b/docs/developer/images/job_view.png similarity index 100% rename from docs/images/jenkins/job_view.png rename to docs/developer/images/job_view.png diff --git a/docs/images/jenkins/pipeline_steps_view.png b/docs/developer/images/pipeline_steps_view.png similarity index 100% rename from docs/images/jenkins/pipeline_steps_view.png rename to docs/developer/images/pipeline_steps_view.png diff --git a/docs/developer/index.asciidoc b/docs/developer/index.asciidoc index 50e41a4e18207..db57815a1285a 100644 --- a/docs/developer/index.asciidoc +++ b/docs/developer/index.asciidoc @@ -3,25 +3,27 @@ [partintro] -- -Contributing to Kibana can be daunting at first, but it doesn't have to be. If -you're planning a pull request to the Kibana repository, you may want to start -with <>. +Contributing to {kib} can be daunting at first, but it doesn't have to be. The following sections should get you up and +running in no time. If you have any problems, file an issue in the https://github.com/elastic/kibana/issues[Kibana repo]. -If you'd prefer to use Kibana's internal plugin API, then check out -<>. --- +* <> +* <> +* <> +* <> +* <> +* <> -include::core-development.asciidoc[] +-- -include::plugin-development.asciidoc[] +include::getting-started/index.asciidoc[] -include::visualize/development-visualize-index.asciidoc[] +include::best-practices/index.asciidoc[] -include::add-data-guide.asciidoc[] +include::architecture/index.asciidoc[] -include::security/index.asciidoc[] +include::contributing/index.asciidoc[] -include::pr-review.asciidoc[] +include::plugin/index.asciidoc[] -include::testing/interpreting-ci-failures.asciidoc[] +include::advanced/index.asciidoc[] diff --git a/docs/developer/plugin-development.asciidoc b/docs/developer/plugin-development.asciidoc deleted file mode 100644 index 691fdb0412fd2..0000000000000 --- a/docs/developer/plugin-development.asciidoc +++ /dev/null @@ -1,24 +0,0 @@ -[[plugin-development]] -== Plugin Development - -[IMPORTANT] -============================================== -The Kibana plugin interfaces are in a state of constant development. We cannot provide backwards compatibility for plugins due to the high rate of change. Kibana enforces that the installed plugins match the version of Kibana itself. Plugin developers will have to release a new version of their plugin for each new Kibana release as a result. -============================================== - -* <> -* <> -* <> -* <> -* <> - -include::plugin/development-plugin-resources.asciidoc[] - -include::plugin/development-uiexports.asciidoc[] - -include::plugin/development-plugin-feature-registration.asciidoc[] - -include::plugin/development-plugin-functional-tests.asciidoc[] - -include::plugin/development-plugin-localization.asciidoc[] - diff --git a/docs/developer/plugin/development-plugin-feature-registration.asciidoc b/docs/developer/plugin/development-plugin-feature-registration.asciidoc deleted file mode 100644 index 203cc201ee626..0000000000000 --- a/docs/developer/plugin/development-plugin-feature-registration.asciidoc +++ /dev/null @@ -1,274 +0,0 @@ -[[development-plugin-feature-registration]] -=== Plugin feature registration - -If your plugin will be used with {kib}'s default distribution, then you have the ability to register the features that your plugin provides. Features are typically apps in {kib}; once registered, you can toggle them via Spaces, and secure them via Roles when security is enabled. - -==== UI Capabilities - -Registering features also gives your plugin access to “UI Capabilities”. These capabilities are boolean flags that you can use to conditionally render your interface, based on the current user's permissions. For example, you can hide or disable a Save button if the current user is not authorized. - -==== Registering a feature - -Feature registration is controlled via the built-in `xpack_main` plugin. To register a feature, call `xpack_main`'s `registerFeature` function from your plugin's `init` function, and provide the appropriate details: - -["source","javascript"] ------------ -init(server) { - const xpackMainPlugin = server.plugins.xpack_main; - xpackMainPlugin.registerFeature({ - // feature details here. - }); -} ------------ - -===== Feature details -Registering a feature consists of the following fields. For more information, consult the {kib-repo}blob/{branch}/x-pack/plugins/features/server/feature_registry.ts[feature registry interface]. - - -[cols="1a, 1a, 1a, 1a"] -|=== -|Field name |Data type |Example |Description - -|`id` (required) -|`string` -|`"sample_feature"` -|A unique identifier for your feature. Usually, the ID of your plugin is sufficient. - -|`name` (required) -|`string` -|`"Sample Feature"` -|A human readable name for your feature. - -|`app` (required) -|`string[]` -|`["sample_app", "kibana"]` -|An array of applications this feature enables. Typically, all of your plugin's apps (from `uiExports`) will be included here. - -|`privileges` (required) -|{kib-repo}blob/{branch}/x-pack/plugins/features/common/feature.ts[`FeatureConfig`]. -|See <> and <> -|The set of privileges this feature requires to function. - -|`subFeatures` (optional) -|{kib-repo}blob/{branch}/x-pack/plugins/features/common/feature.ts[`FeatureConfig`]. -|See <> -|The set of subfeatures that enables finer access control than the `all` and `read` feature privileges. These options are only available in the Gold subscription level and higher. - -|`icon` -|`string` -|"discoverApp" -|An https://elastic.github.io/eui/#/display/icons[EUI Icon] to use for this feature. - -|`navLinkId` -|`string` -|"sample_app" -|The ID of the navigation link associated with your feature. -|=== - -===== Privilege definition -The `privileges` section of feature registration allows plugins to implement read/write and read-only modes for their applications. - -For a full explanation of fields and options, consult the {kib-repo}blob/{branch}/x-pack/plugins/features/server/feature_registry.ts[feature registry interface]. - -==== Using UI Capabilities - -UI Capabilities are available to your public (client) plugin code. These capabilities are read-only, and are used to inform the UI. This object is namespaced by feature id. For example, if your feature id is “foo”, then your UI Capabilities are stored at `uiCapabilities.foo`. -To access capabilities, import them from `ui/capabilities`: - -["source","javascript"] ------------ -import { uiCapabilities } from 'ui/capabilities'; - -const canUserSave = uiCapabilities.foo.save; -if (canUserSave) { - // show save button -} ------------ - -[[example-1-canvas]] -==== Example 1: Canvas Application -["source","javascript"] ------------ -init(server) { - const xpackMainPlugin = server.plugins.xpack_main; - xpackMainPlugin.registerFeature({ - id: 'canvas', - name: 'Canvas', - icon: 'canvasApp', - navLinkId: 'canvas', - app: ['canvas', 'kibana'], - catalogue: ['canvas'], - privileges: { - all: { - savedObject: { - all: ['canvas-workpad'], - read: ['index-pattern'], - }, - ui: ['save'], - }, - read: { - savedObject: { - all: [], - read: ['index-pattern', 'canvas-workpad'], - }, - ui: [], - }, - }, - }); -} ------------ - -This shows how the Canvas application might register itself as a Kibana feature. -Note that it specifies different `savedObject` access levels for each privilege: - -- Users with read/write access (`all` privilege) need to be able to read/write `canvas-workpad` saved objects, and they need read-only access to `index-pattern` saved objects. -- Users with read-only access (`read` privilege) do not need to have read/write access to any saved objects, but instead get read-only access to `index-pattern` and `canvas-workpad` saved objects. - -Additionally, Canvas registers the `canvas` UI app and `canvas` catalogue entry. This tells Kibana that these entities are available for users with either the `read` or `all` privilege. - -The `all` privilege defines a single “save” UI Capability. To access this in the UI, Canvas could: - -["source","javascript"] ------------ -import { uiCapabilities } from 'ui/capabilities'; - -const canUserSave = uiCapabilities.canvas.save; -if (canUserSave) { - // show save button -} ------------ - -Because the `read` privilege does not define the `save` capability, users with read-only access will have their `uiCapabilities.canvas.save` flag set to `false`. - -[[example-2-dev-tools]] -==== Example 2: Dev Tools - -["source","javascript"] ------------ -init(server) { - const xpackMainPlugin = server.plugins.xpack_main; - xpackMainPlugin.registerFeature({ - id: 'dev_tools', - name: i18n.translate('xpack.features.devToolsFeatureName', { - defaultMessage: 'Dev Tools', - }), - icon: 'devToolsApp', - navLinkId: 'dev_tools', - app: ['kibana'], - catalogue: ['console', 'searchprofiler', 'grokdebugger'], - privileges: { - all: { - api: ['console'], - savedObject: { - all: [], - read: [], - }, - ui: ['show'], - }, - read: { - api: ['console'], - savedObject: { - all: [], - read: [], - }, - ui: ['show'], - }, - }, - privilegesTooltip: i18n.translate('xpack.features.devToolsPrivilegesTooltip', { - defaultMessage: - 'User should also be granted the appropriate Elasticsearch cluster and index privileges', - }), - }); -} ------------ - -Unlike the Canvas example, Dev Tools does not require access to any saved objects to function. Dev Tools does specify an API endpoint, however. When this is configured, the Security plugin will automatically authorize access to any server API route that is tagged with `access:console`, similar to the following: - -["source","javascript"] ------------ -server.route({ - path: '/api/console/proxy', - method: 'POST', - config: { - tags: ['access:console'], - handler: async (req, h) => { - // ... - } - } -}); ------------ - -[[example-3-discover]] -==== Example 3: Discover - -Discover takes advantage of subfeature privileges to allow fine-grained access control. In this example, -a single "Create Short URLs" subfeature privilege is defined, which allows users to grant access to this feature without having to grant the `all` privilege to Discover. In other words, you can grant `read` access to Discover, and also grant the ability to create short URLs. - -["source","javascript"] ------------ -init(server) { - const xpackMainPlugin = server.plugins.xpack_main; - xpackMainPlugin.registerFeature({ - { - id: 'discover', - name: i18n.translate('xpack.features.discoverFeatureName', { - defaultMessage: 'Discover', - }), - order: 100, - icon: 'discoverApp', - navLinkId: 'discover', - app: ['kibana'], - catalogue: ['discover'], - privileges: { - all: { - app: ['kibana'], - catalogue: ['discover'], - savedObject: { - all: ['search', 'query'], - read: ['index-pattern'], - }, - ui: ['show', 'save', 'saveQuery'], - }, - read: { - app: ['kibana'], - catalogue: ['discover'], - savedObject: { - all: [], - read: ['index-pattern', 'search', 'query'], - }, - ui: ['show'], - }, - }, - subFeatures: [ - { - name: i18n.translate('xpack.features.ossFeatures.discoverShortUrlSubFeatureName', { - defaultMessage: 'Short URLs', - }), - privilegeGroups: [ - { - groupType: 'independent', - privileges: [ - { - id: 'url_create', - name: i18n.translate( - 'xpack.features.ossFeatures.discoverCreateShortUrlPrivilegeName', - { - defaultMessage: 'Create Short URLs', - } - ), - includeIn: 'all', - savedObject: { - all: ['url'], - read: [], - }, - ui: ['createShortUrl'], - }, - ], - }, - ], - }, - ], - } - }); -} ------------ diff --git a/docs/developer/plugin/development-plugin-functional-tests.asciidoc b/docs/developer/plugin/development-plugin-functional-tests.asciidoc deleted file mode 100644 index eda2ceb627fce..0000000000000 --- a/docs/developer/plugin/development-plugin-functional-tests.asciidoc +++ /dev/null @@ -1,89 +0,0 @@ -[[development-plugin-functional-tests]] -=== Functional Tests for Plugins - -Plugins use the `FunctionalTestRunner` by running it out of the Kibana repo. Ensure that your Kibana Development Environment is setup properly before continuing. - -[float] -==== Writing your own configuration - -Every project or plugin should have its own `FunctionalTestRunner` config file. Just like Kibana's, this config file will define all of the test files to load, providers for Services and PageObjects, as well as configuration options for certain services. - -To get started copy and paste this example to `test/functional/config.js`: - -["source","js"] ------------ -import { resolve } from 'path'; -import { resolveKibanaPath } from '@kbn/plugin-helpers'; - -import { MyServiceProvider } from './services/my_service'; -import { MyAppPageProvider } from './services/my_app_page'; - -// the default export of config files must be a config provider -// that returns an object with the projects config values -export default async function ({ readConfigFile }) { - - // read the Kibana config file so that we can utilize some of - // its services and PageObjects - const kibanaConfig = await readConfigFile(resolveKibanaPath('test/functional/config.js')); - - return { - // list paths to the files that contain your plugins tests - testFiles: [ - resolve(__dirname, './my_test_file.js'), - ], - - // define the name and providers for services that should be - // available to your tests. If you don't specify anything here - // only the built-in services will be available - services: { - ...kibanaConfig.get('services'), - myService: MyServiceProvider, - }, - - // just like services, PageObjects are defined as a map of - // names to Providers. Merge in Kibana's or pick specific ones - pageObjects: { - management: kibanaConfig.get('pageObjects.management'), - myApp: MyAppPageProvider, - }, - - // the apps section defines the urls that - // `PageObjects.common.navigateTo(appKey)` will use. - // Merge urls for your plugin with the urls defined in - // Kibana's config in order to use this helper - apps: { - ...kibanaConfig.get('apps'), - myApp: { - pathname: '/app/my_app', - } - }, - - // choose where esArchiver should load archives from - esArchiver: { - directory: resolve(__dirname, './es_archives'), - }, - - // choose where screenshots should be saved - screenshots: { - directory: resolve(__dirname, './tmp/screenshots'), - } - - // more settings, like timeouts, mochaOpts, etc are - // defined in the config schema. See {blob}src/functional_test_runner/lib/config/schema.js[src/functional_test_runner/lib/config/schema.js] - }; -} - ------------ - -From the root of your repo you should now be able to run the `FunctionalTestRunner` script from your plugin project. - -["source","shell"] ------------ -node ../../kibana/scripts/functional_test_runner ------------ - -[float] -==== Using esArchiver - -We're working on documentation for this, but for now the best place to look is the original {kibana-pull}10359[pull request]. - diff --git a/docs/developer/plugin/development-plugin-localization.asciidoc b/docs/developer/plugin/development-plugin-localization.asciidoc deleted file mode 100644 index b0b543bd9fe33..0000000000000 --- a/docs/developer/plugin/development-plugin-localization.asciidoc +++ /dev/null @@ -1,167 +0,0 @@ -[[development-plugin-localization]] -=== Localization for plugins - -To introduce localization for your plugin, use our i18n tool to create IDs and default messages. You can then extract these IDs with respective default messages into localization JSON files for Kibana to use when running your plugin. - -[float] -==== Adding localization to your plugin - -You must add a `translations` directory at the root of your plugin. This directory will contain the translation files that Kibana uses. - -["source","shell"] ------------ -. -├── translations -│ ├── en.json -│ ├── ja-JP.json -│ └── zh-CN.json -└── .i18nrc.json ------------ - - -[float] -==== Using Kibana i18n tooling -To simplify the localization process, Kibana provides tools for the following functions: - -* Verify all translations have translatable strings and extract default messages from templates -* Verify translation files and integrate them into Kibana - -To use Kibana i18n tooling, create a `.i18nrc.json` file with the following configs: - -* `paths`. The directory from which the i18n translation IDs are extracted. -* `exclude`. The list of files to exclude while parsing paths. -* `translations`. The list of translations where JSON localizations are found. - -["source","json"] ------------ -{ - "paths": { - "myPlugin": "src/ui", - }, - "exclude": [ - ], - "translations": [ - "translations/zh-CN.json", - "translations/ja-JP.json" - ] -} ------------ - -An example Kibana `.i18nrc.json` is {blob}.i18nrc.json[here]. - -Full documentation about i18n tooling is {blob}src/dev/i18n/README.md[here]. - -[float] -==== Extracting default messages -To extract the default messages from your plugin, run the following command: - -["source","shell"] ------------ -node scripts/i18n_extract --output-dir ./translations --include-config ../kibana-extra/myPlugin/.i18nrc.json ------------ - -This outputs a `en.json` file inside the `translations` directory. To localize other languages, clone the file and translate each string. - -[float] -==== Checking i18n messages - -Checking i18n does the following: - -* Checks all existing labels for violations. -* Takes translations from `.i18nrc.json` and compares them to the messages extracted and validated. -** Checks for unused translations. If you remove a label that has a corresponding translation, you must also remove the label from the translations file. -** Checks for incompatible translations. If you add or remove a new parameter from an existing string, you must also remove the label from the translations file. - -To check your i18n translations, run the following command: - -["source","shell"] ------------ -node scripts/i18n_check --fix --include-config ../kibana-extra/myPlugin/.i18nrc.json ------------ - - -[float] -==== Implementing i18n in the UI - -Kibana relies on several UI frameworks (ReactJS and AngularJS) and -requires localization in different environments (browser and NodeJS). -The internationalization engine is framework agnostic and consumable in -all parts of Kibana (ReactJS, AngularJS and NodeJS). - -To simplify -internationalization in UI frameworks, additional abstractions are -built around the I18n engine: `react-intl` for React and custom -components for AngularJS. https://github.com/yahoo/react-intl[React-intl] -is built around https://github.com/yahoo/intl-messageformat[intl-messageformat], -so both React and AngularJS frameworks use the same engine and the same -message syntax. - - -[float] -===== i18n for vanilla JavaScript - -["source","js"] ------------ -import { i18n } from '@kbn/i18n'; - -export const HELLO_WORLD = i18n.translate('hello.wonderful.world', { - defaultMessage: 'Greetings, planet Earth!', -}); ------------ - -Full details are {kib-repo}tree/master/packages/kbn-i18n#vanilla-js[here]. - -[float] -===== i18n for React - -To localize strings in React, use either `FormattedMessage` or `i18n.translate`. - - -["source","js"] ------------ -import { i18n } from '@kbn/i18n'; -import { FormattedMessage } from '@kbn/i18n/react'; - -export const Component = () => { - return ( -
- {i18n.translate('xpack.someText', { defaultMessage: 'Some text' })} - - -
- ); -}; ------------ - -Full details are {kib-repo}tree/master/packages/kbn-i18n#react[here]. - - - -[float] -===== i18n for Angular - -You are encouraged to use `i18n.translate()` by statically importing `i18n` from `@kbn/i18n` wherever possible in your Angular code. Angular wrappers use the translation `service` with the i18n engine under the hood. - -The translation directive has the following syntax: -["source","js"] ------------ - ------------ - -Full details are {kib-repo}tree/master/packages/kbn-i18n#angularjs[here]. - - -[float] -==== Resources - -To learn more about i18n tooling, see {blob}src/dev/i18n/README.md[i18n dev tooling]. - -To learn more about implementing i18n in the UI, use the following links: - -* {blob}packages/kbn-i18n/README.md[i18n plugin] -* {blob}packages/kbn-i18n/GUIDELINE.md[i18n guidelines] diff --git a/docs/developer/plugin/development-plugin-resources.asciidoc b/docs/developer/plugin/development-plugin-resources.asciidoc deleted file mode 100644 index 3a32c49e40e0f..0000000000000 --- a/docs/developer/plugin/development-plugin-resources.asciidoc +++ /dev/null @@ -1,73 +0,0 @@ -[[development-plugin-resources]] -=== Plugin Resources - -Here are some resources that are helpful for getting started with plugin development. - -[float] -==== Some light reading -Our {kib-repo}blob/master/CONTRIBUTING.md[contributing guide] can help you get a development environment going. - -[float] -==== Plugin Generator - -We recommend that you kick-start your plugin by generating it with the {kib-repo}tree/{branch}/packages/kbn-plugin-generator[Kibana Plugin Generator]. Run the following in the Kibana repo, and you will be asked a couple questions, see some progress bars, and have a freshly generated plugin ready for you to play with in Kibana's `plugins` folder. - -["source","shell"] ------------ -node scripts/generate_plugin my_plugin_name # replace "my_plugin_name" with your desired plugin name ------------ - - -[float] -==== Directory structure for plugins - -The Kibana directory must be named `kibana`, and your plugin directory should be located in the root of `kibana` in a `plugins` directory, for example: - -["source","shell"] ----- -. -└── kibana - └── plugins - ├── foo-plugin - └── bar-plugin ----- - -[float] -==== References in the code - - {kib-repo}blob/{branch}/src/legacy/server/plugins/lib/plugin.js[Plugin class]: What options does the `kibana.Plugin` class accept? - - <>: What type of exports are available? - -[float] -==== Elastic UI Framework -If you're developing a plugin that has a user interface, take a look at our https://elastic.github.io/eui[Elastic UI Framework]. -It documents the CSS and React components we use to build Kibana's user interface. - -You're welcome to use these components, but be aware that they are rapidly evolving, and we might introduce breaking changes that will disrupt your plugin's UI. - -[float] -==== TypeScript Support -Plugin code can be written in http://www.typescriptlang.org/[TypeScript] if desired. -To enable TypeScript support, create a `tsconfig.json` file at the root of your plugin that looks something like this: - -["source","js"] ------------ -{ - // extend Kibana's tsconfig, or use your own settings - "extends": "../../kibana/tsconfig.json", - - // tell the TypeScript compiler where to find your source files - "include": [ - "server/**/*", - "public/**/*" - ] -} ------------ - -TypeScript code is automatically converted into JavaScript during development, -but not in the distributable version of Kibana. If you use the -{kib-repo}blob/{branch}/packages/kbn-plugin-helpers[@kbn/plugin-helpers] to build your plugin, then your `.ts` and `.tsx` files will be permanently transpiled before your plugin is archived. If you have your own build process, make sure to run the TypeScript compiler on your source files and ship the compilation output so that your plugin will work with the distributable version of Kibana. - -==== {kib} platform migration guide - -{kib-repo}blob/{branch}/src/core/MIGRATION.md#migrating-legacy-plugins-to-the-new-platform[This guide] -provides an action plan for moving a legacy plugin to the new platform. diff --git a/docs/developer/plugin/development-uiexports.asciidoc b/docs/developer/plugin/development-uiexports.asciidoc deleted file mode 100644 index 18d326cbfb9c0..0000000000000 --- a/docs/developer/plugin/development-uiexports.asciidoc +++ /dev/null @@ -1,16 +0,0 @@ -[[development-uiexports]] -=== UI Exports - -An aggregate list of available UiExport types: - -[cols=" { + return ( +
+ {i18n.translate('xpack.someText', { defaultMessage: 'Some text' })} + + +
+ ); +}; +----------- + +Full details are {kib-repo}tree/master/packages/kbn-i18n#react[here]. + + + +[float] +===== i18n for Angular + +You are encouraged to use `i18n.translate()` by statically importing `i18n` from `@kbn/i18n` wherever possible in your Angular code. Angular wrappers use the translation `service` with the i18n engine under the hood. + +The translation directive has the following syntax: +["source","js"] +----------- + +----------- + +Full details are {kib-repo}tree/master/packages/kbn-i18n#angularjs[here]. + + +[float] +==== Resources + +To learn more about i18n tooling, see {blob}src/dev/i18n/README.md[i18n dev tooling]. + +To learn more about implementing i18n in the UI, use the following links: + +* {blob}packages/kbn-i18n/README.md[i18n plugin] +* {blob}packages/kbn-i18n/GUIDELINE.md[i18n guidelines] diff --git a/docs/developer/plugin/index.asciidoc b/docs/developer/plugin/index.asciidoc new file mode 100644 index 0000000000000..73f1d2c908fa7 --- /dev/null +++ b/docs/developer/plugin/index.asciidoc @@ -0,0 +1,42 @@ +[[external-plugin-development]] +== External plugin development + +[IMPORTANT] +============================================== +The {kib} plugin interfaces are in a state of constant development. We cannot provide backwards compatibility for plugins due to the high rate of change. {kib} enforces that the installed plugins match the version of {kib} itself. Plugin developers will have to release a new version of their plugin for each new {kib} release as a result. +============================================== + +Most developers who contribute code directly to the {kib} repo are writing code inside plugins, so our <> docs are the best place to +start. However, there are a few differences when developing plugins outside the {kib} repo. These differences are covered here. + +[float] +[[automatic-plugin-generator]] +==== Automatic plugin generator + +We recommend that you kick-start your plugin by generating it with the {kib-repo}tree/{branch}/packages/kbn-plugin-generator[Kibana Plugin Generator]. Run the following in the {kib} repo, and you will be asked a couple questions, see some progress bars, and have a freshly generated plugin ready for you to play with in {kib}'s `plugins` folder. + +["source","shell"] +----------- +node scripts/generate_plugin my_plugin_name # replace "my_plugin_name" with your desired plugin name +----------- + +[float] +=== Plugin location + +The {kib} directory must be named `kibana`, and your plugin directory should be located in the root of `kibana` in a `plugins` directory, for example: + +["source","shell"] +---- +. +└── kibana + └── plugins + ├── foo-plugin + └── bar-plugin +---- + +* <> +* <> + +include::external-plugin-functional-tests.asciidoc[] + +include::external-plugin-localization.asciidoc[] diff --git a/docs/developer/security/index.asciidoc b/docs/developer/security/index.asciidoc deleted file mode 100644 index e7ef0b85930e4..0000000000000 --- a/docs/developer/security/index.asciidoc +++ /dev/null @@ -1,12 +0,0 @@ -[[development-security]] -== Security - -Kibana has generally been able to implement security transparently to core and plugin developers, and this largely remains the case. {kib} on two methods that the <>'s `Cluster` provides: `callWithRequest` and `callWithInternalUser`. - -`callWithRequest` executes requests against Elasticsearch using the authentication credentials of the Kibana end-user. So, if you log into Kibana with the user of `foo` when `callWithRequest` is used, {kib} execute the request against Elasticsearch as the user `foo`. Historically, `callWithRequest` has been used extensively to perform actions that are initiated at the request of Kibana end-users. - -`callWithInternalUser` executes requests against Elasticsearch using the internal Kibana server user, and has historically been used for performing actions that aren't initiated by Kibana end users; for example, creating the initial `.kibana` index or performing health checks against Elasticsearch. - -However, with the changes that role-based access control (RBAC) introduces, this is no longer cut and dry. {kib} now requires all access to the `.kibana` index goes through the `SavedObjectsClient`. This used to be a best practice, as the `SavedObjectsClient` was responsible for translating the documents stored in Elasticsearch to and from Saved Objects, but RBAC is now taking advantage of this abstraction to implement access control and determine when to use `callWithRequest` versus `callWithInternalUser`. - -include::rbac.asciidoc[] diff --git a/docs/development/core/public/kibana-plugin-core-public.savedobjectsfindoptions.md b/docs/development/core/public/kibana-plugin-core-public.savedobjectsfindoptions.md index 5f33d62382818..70ad235fb8971 100644 --- a/docs/development/core/public/kibana-plugin-core-public.savedobjectsfindoptions.md +++ b/docs/development/core/public/kibana-plugin-core-public.savedobjectsfindoptions.md @@ -8,7 +8,7 @@ Signature: ```typescript -export interface SavedObjectsFindOptions extends SavedObjectsBaseOptions +export interface SavedObjectsFindOptions ``` ## Properties @@ -19,6 +19,7 @@ export interface SavedObjectsFindOptions extends SavedObjectsBaseOptions | [fields](./kibana-plugin-core-public.savedobjectsfindoptions.fields.md) | string[] | An array of fields to include in the results | | [filter](./kibana-plugin-core-public.savedobjectsfindoptions.filter.md) | string | | | [hasReference](./kibana-plugin-core-public.savedobjectsfindoptions.hasreference.md) | {
type: string;
id: string;
} | | +| [namespaces](./kibana-plugin-core-public.savedobjectsfindoptions.namespaces.md) | string[] | | | [page](./kibana-plugin-core-public.savedobjectsfindoptions.page.md) | number | | | [perPage](./kibana-plugin-core-public.savedobjectsfindoptions.perpage.md) | number | | | [preference](./kibana-plugin-core-public.savedobjectsfindoptions.preference.md) | string | An optional ES preference value to be used for the query \* | diff --git a/docs/development/core/public/kibana-plugin-core-public.savedobjectsfindoptions.namespaces.md b/docs/development/core/public/kibana-plugin-core-public.savedobjectsfindoptions.namespaces.md new file mode 100644 index 0000000000000..9cc9d64db1f65 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-core-public.savedobjectsfindoptions.namespaces.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-core-public](./kibana-plugin-core-public.md) > [SavedObjectsFindOptions](./kibana-plugin-core-public.savedobjectsfindoptions.md) > [namespaces](./kibana-plugin-core-public.savedobjectsfindoptions.namespaces.md) + +## SavedObjectsFindOptions.namespaces property + +Signature: + +```typescript +namespaces?: string[]; +``` diff --git a/docs/development/core/server/kibana-plugin-core-server.auditableevent.md b/docs/development/core/server/kibana-plugin-core-server.auditableevent.md new file mode 100644 index 0000000000000..aa109c5064887 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.auditableevent.md @@ -0,0 +1,25 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [AuditableEvent](./kibana-plugin-core-server.auditableevent.md) + +## AuditableEvent interface + +Event to audit. + +Signature: + +```typescript +export interface AuditableEvent +``` + +## Remarks + +Not a complete interface. + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [message](./kibana-plugin-core-server.auditableevent.message.md) | string | | +| [type](./kibana-plugin-core-server.auditableevent.type.md) | string | | + diff --git a/docs/development/core/server/kibana-plugin-core-server.auditableevent.message.md b/docs/development/core/server/kibana-plugin-core-server.auditableevent.message.md new file mode 100644 index 0000000000000..3ac4167c6998b --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.auditableevent.message.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [AuditableEvent](./kibana-plugin-core-server.auditableevent.md) > [message](./kibana-plugin-core-server.auditableevent.message.md) + +## AuditableEvent.message property + +Signature: + +```typescript +message: string; +``` diff --git a/docs/development/core/server/kibana-plugin-core-server.auditableevent.type.md b/docs/development/core/server/kibana-plugin-core-server.auditableevent.type.md new file mode 100644 index 0000000000000..3748748366684 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.auditableevent.type.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [AuditableEvent](./kibana-plugin-core-server.auditableevent.md) > [type](./kibana-plugin-core-server.auditableevent.type.md) + +## AuditableEvent.type property + +Signature: + +```typescript +type: string; +``` diff --git a/docs/development/core/server/kibana-plugin-core-server.auditor.add.md b/docs/development/core/server/kibana-plugin-core-server.auditor.add.md new file mode 100644 index 0000000000000..40245a93753fc --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.auditor.add.md @@ -0,0 +1,36 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [Auditor](./kibana-plugin-core-server.auditor.md) > [add](./kibana-plugin-core-server.auditor.add.md) + +## Auditor.add() method + +Add a record to audit log. Service attaches to a log record: - metadata about an end-user initiating an operation - scope name, if presents + +Signature: + +```typescript +add(event: AuditableEvent): void; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| event | AuditableEvent | | + +Returns: + +`void` + +## Example + +How to add a record in audit log: + +```typescript +router.get({ path: '/my_endpoint', validate: false }, async (context, request, response) => { + context.core.auditor.withAuditScope('my_plugin_operation'); + const value = await context.core.elasticsearch.legacy.client.callAsCurrentUser('...'); + context.core.add({ type: 'operation.type', message: 'perform an operation in ... endpoint' }); + +``` + diff --git a/docs/development/core/server/kibana-plugin-core-server.auditor.md b/docs/development/core/server/kibana-plugin-core-server.auditor.md new file mode 100644 index 0000000000000..191a34df647ab --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.auditor.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [Auditor](./kibana-plugin-core-server.auditor.md) + +## Auditor interface + +Provides methods to log user actions and access events. + +Signature: + +```typescript +export interface Auditor +``` + +## Methods + +| Method | Description | +| --- | --- | +| [add(event)](./kibana-plugin-core-server.auditor.add.md) | Add a record to audit log. Service attaches to a log record: - metadata about an end-user initiating an operation - scope name, if presents | +| [withAuditScope(name)](./kibana-plugin-core-server.auditor.withauditscope.md) | Add a high-level scope name for logged events. It helps to identify the root cause of low-level events. | + diff --git a/docs/development/core/server/kibana-plugin-core-server.auditor.withauditscope.md b/docs/development/core/server/kibana-plugin-core-server.auditor.withauditscope.md new file mode 100644 index 0000000000000..0ae0c48ab92f4 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.auditor.withauditscope.md @@ -0,0 +1,24 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [Auditor](./kibana-plugin-core-server.auditor.md) > [withAuditScope](./kibana-plugin-core-server.auditor.withauditscope.md) + +## Auditor.withAuditScope() method + +Add a high-level scope name for logged events. It helps to identify the root cause of low-level events. + +Signature: + +```typescript +withAuditScope(name: string): void; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| name | string | | + +Returns: + +`void` + diff --git a/docs/development/core/server/kibana-plugin-core-server.auditorfactory.asscoped.md b/docs/development/core/server/kibana-plugin-core-server.auditorfactory.asscoped.md new file mode 100644 index 0000000000000..4a60931e60940 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.auditorfactory.asscoped.md @@ -0,0 +1,22 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [AuditorFactory](./kibana-plugin-core-server.auditorfactory.md) > [asScoped](./kibana-plugin-core-server.auditorfactory.asscoped.md) + +## AuditorFactory.asScoped() method + +Signature: + +```typescript +asScoped(request: KibanaRequest): Auditor; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| request | KibanaRequest | | + +Returns: + +`Auditor` + diff --git a/docs/development/core/server/kibana-plugin-core-server.auditorfactory.md b/docs/development/core/server/kibana-plugin-core-server.auditorfactory.md new file mode 100644 index 0000000000000..fd4760caa3552 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.auditorfactory.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [AuditorFactory](./kibana-plugin-core-server.auditorfactory.md) + +## AuditorFactory interface + +Creates [Auditor](./kibana-plugin-core-server.auditor.md) instance bound to the current user credentials. + +Signature: + +```typescript +export interface AuditorFactory +``` + +## Methods + +| Method | Description | +| --- | --- | +| [asScoped(request)](./kibana-plugin-core-server.auditorfactory.asscoped.md) | | + diff --git a/docs/development/core/server/kibana-plugin-core-server.audittrailsetup.md b/docs/development/core/server/kibana-plugin-core-server.audittrailsetup.md new file mode 100644 index 0000000000000..50885232a088e --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.audittrailsetup.md @@ -0,0 +1,18 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [AuditTrailSetup](./kibana-plugin-core-server.audittrailsetup.md) + +## AuditTrailSetup interface + +Signature: + +```typescript +export interface AuditTrailSetup +``` + +## Methods + +| Method | Description | +| --- | --- | +| [register(auditor)](./kibana-plugin-core-server.audittrailsetup.register.md) | Register a custom [AuditorFactory](./kibana-plugin-core-server.auditorfactory.md) implementation. | + diff --git a/docs/development/core/server/kibana-plugin-core-server.audittrailsetup.register.md b/docs/development/core/server/kibana-plugin-core-server.audittrailsetup.register.md new file mode 100644 index 0000000000000..36695844ced73 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.audittrailsetup.register.md @@ -0,0 +1,24 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [AuditTrailSetup](./kibana-plugin-core-server.audittrailsetup.md) > [register](./kibana-plugin-core-server.audittrailsetup.register.md) + +## AuditTrailSetup.register() method + +Register a custom [AuditorFactory](./kibana-plugin-core-server.auditorfactory.md) implementation. + +Signature: + +```typescript +register(auditor: AuditorFactory): void; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auditor | AuditorFactory | | + +Returns: + +`void` + diff --git a/docs/development/core/server/kibana-plugin-core-server.audittrailstart.md b/docs/development/core/server/kibana-plugin-core-server.audittrailstart.md new file mode 100644 index 0000000000000..4fb9f5cb93549 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.audittrailstart.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [AuditTrailStart](./kibana-plugin-core-server.audittrailstart.md) + +## AuditTrailStart type + +Signature: + +```typescript +export declare type AuditTrailStart = AuditorFactory; +``` diff --git a/docs/development/core/server/kibana-plugin-core-server.coresetup.audittrail.md b/docs/development/core/server/kibana-plugin-core-server.coresetup.audittrail.md new file mode 100644 index 0000000000000..1aa7a75b7a086 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.coresetup.audittrail.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [CoreSetup](./kibana-plugin-core-server.coresetup.md) > [auditTrail](./kibana-plugin-core-server.coresetup.audittrail.md) + +## CoreSetup.auditTrail property + +[AuditTrailSetup](./kibana-plugin-core-server.audittrailsetup.md) + +Signature: + +```typescript +auditTrail: AuditTrailSetup; +``` diff --git a/docs/development/core/server/kibana-plugin-core-server.coresetup.md b/docs/development/core/server/kibana-plugin-core-server.coresetup.md index 32221a320d2a1..597bb9bc2376a 100644 --- a/docs/development/core/server/kibana-plugin-core-server.coresetup.md +++ b/docs/development/core/server/kibana-plugin-core-server.coresetup.md @@ -16,6 +16,7 @@ export interface CoreSetupAuditTrailSetup | [AuditTrailSetup](./kibana-plugin-core-server.audittrailsetup.md) | | [capabilities](./kibana-plugin-core-server.coresetup.capabilities.md) | CapabilitiesSetup | [CapabilitiesSetup](./kibana-plugin-core-server.capabilitiessetup.md) | | [context](./kibana-plugin-core-server.coresetup.context.md) | ContextSetup | [ContextSetup](./kibana-plugin-core-server.contextsetup.md) | | [elasticsearch](./kibana-plugin-core-server.coresetup.elasticsearch.md) | ElasticsearchServiceSetup | [ElasticsearchServiceSetup](./kibana-plugin-core-server.elasticsearchservicesetup.md) | diff --git a/docs/development/core/server/kibana-plugin-core-server.corestart.audittrail.md b/docs/development/core/server/kibana-plugin-core-server.corestart.audittrail.md new file mode 100644 index 0000000000000..879e0df836190 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.corestart.audittrail.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [CoreStart](./kibana-plugin-core-server.corestart.md) > [auditTrail](./kibana-plugin-core-server.corestart.audittrail.md) + +## CoreStart.auditTrail property + +[AuditTrailSetup](./kibana-plugin-core-server.audittrailsetup.md) + +Signature: + +```typescript +auditTrail: AuditTrailStart; +``` diff --git a/docs/development/core/server/kibana-plugin-core-server.corestart.md b/docs/development/core/server/kibana-plugin-core-server.corestart.md index acd23f0f47386..610c85c71e362 100644 --- a/docs/development/core/server/kibana-plugin-core-server.corestart.md +++ b/docs/development/core/server/kibana-plugin-core-server.corestart.md @@ -16,6 +16,7 @@ export interface CoreStart | Property | Type | Description | | --- | --- | --- | +| [auditTrail](./kibana-plugin-core-server.corestart.audittrail.md) | AuditTrailStart | [AuditTrailSetup](./kibana-plugin-core-server.audittrailsetup.md) | | [capabilities](./kibana-plugin-core-server.corestart.capabilities.md) | CapabilitiesStart | [CapabilitiesStart](./kibana-plugin-core-server.capabilitiesstart.md) | | [elasticsearch](./kibana-plugin-core-server.corestart.elasticsearch.md) | ElasticsearchServiceStart | [ElasticsearchServiceStart](./kibana-plugin-core-server.elasticsearchservicestart.md) | | [http](./kibana-plugin-core-server.corestart.http.md) | HttpServiceStart | [HttpServiceStart](./kibana-plugin-core-server.httpservicestart.md) | diff --git a/docs/development/core/server/kibana-plugin-core-server.discoveredplugin.md b/docs/development/core/server/kibana-plugin-core-server.discoveredplugin.md index 0e2b9bd60ab67..b88a179c5c4b3 100644 --- a/docs/development/core/server/kibana-plugin-core-server.discoveredplugin.md +++ b/docs/development/core/server/kibana-plugin-core-server.discoveredplugin.md @@ -19,5 +19,6 @@ export interface DiscoveredPlugin | [configPath](./kibana-plugin-core-server.discoveredplugin.configpath.md) | ConfigPath | Root configuration path used by the plugin, defaults to "id" in snake\_case format. | | [id](./kibana-plugin-core-server.discoveredplugin.id.md) | PluginName | Identifier of the plugin. | | [optionalPlugins](./kibana-plugin-core-server.discoveredplugin.optionalplugins.md) | readonly PluginName[] | An optional list of the other plugins that if installed and enabled \*\*may be\*\* leveraged by this plugin for some additional functionality but otherwise are not required for this plugin to work properly. | +| [requiredBundles](./kibana-plugin-core-server.discoveredplugin.requiredbundles.md) | readonly PluginName[] | List of plugin ids that this plugin's UI code imports modules from that are not in requiredPlugins. | | [requiredPlugins](./kibana-plugin-core-server.discoveredplugin.requiredplugins.md) | readonly PluginName[] | An optional list of the other plugins that \*\*must be\*\* installed and enabled for this plugin to function properly. | diff --git a/docs/development/core/server/kibana-plugin-core-server.discoveredplugin.requiredbundles.md b/docs/development/core/server/kibana-plugin-core-server.discoveredplugin.requiredbundles.md new file mode 100644 index 0000000000000..6d54adb5236ea --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.discoveredplugin.requiredbundles.md @@ -0,0 +1,18 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [DiscoveredPlugin](./kibana-plugin-core-server.discoveredplugin.md) > [requiredBundles](./kibana-plugin-core-server.discoveredplugin.requiredbundles.md) + +## DiscoveredPlugin.requiredBundles property + +List of plugin ids that this plugin's UI code imports modules from that are not in `requiredPlugins`. + +Signature: + +```typescript +readonly requiredBundles: readonly PluginName[]; +``` + +## Remarks + +The plugins listed here will be loaded in the browser, even if the plugin is disabled. Required by `@kbn/optimizer` to support cross-plugin imports. "core" and plugins already listed in `requiredPlugins` do not need to be duplicated here. + diff --git a/docs/development/core/server/kibana-plugin-core-server.httpserverinfo.host.md b/docs/development/core/server/kibana-plugin-core-server.httpserverinfo.host.md deleted file mode 100644 index 903a5193c0383..0000000000000 --- a/docs/development/core/server/kibana-plugin-core-server.httpserverinfo.host.md +++ /dev/null @@ -1,13 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [HttpServerInfo](./kibana-plugin-core-server.httpserverinfo.md) > [host](./kibana-plugin-core-server.httpserverinfo.host.md) - -## HttpServerInfo.host property - -The hostname of the server - -Signature: - -```typescript -host: string; -``` diff --git a/docs/development/core/server/kibana-plugin-core-server.httpserverinfo.hostname.md b/docs/development/core/server/kibana-plugin-core-server.httpserverinfo.hostname.md new file mode 100644 index 0000000000000..194a8aea16269 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.httpserverinfo.hostname.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [HttpServerInfo](./kibana-plugin-core-server.httpserverinfo.md) > [hostname](./kibana-plugin-core-server.httpserverinfo.hostname.md) + +## HttpServerInfo.hostname property + +The hostname of the server + +Signature: + +```typescript +hostname: string; +``` diff --git a/docs/development/core/server/kibana-plugin-core-server.httpserverinfo.md b/docs/development/core/server/kibana-plugin-core-server.httpserverinfo.md index 637e8a232a9ef..3541824a2e81e 100644 --- a/docs/development/core/server/kibana-plugin-core-server.httpserverinfo.md +++ b/docs/development/core/server/kibana-plugin-core-server.httpserverinfo.md @@ -15,7 +15,7 @@ export interface HttpServerInfo | Property | Type | Description | | --- | --- | --- | -| [host](./kibana-plugin-core-server.httpserverinfo.host.md) | string | The hostname of the server | +| [hostname](./kibana-plugin-core-server.httpserverinfo.hostname.md) | string | The hostname of the server | | [name](./kibana-plugin-core-server.httpserverinfo.name.md) | string | The name of the Kibana server | | [port](./kibana-plugin-core-server.httpserverinfo.port.md) | number | The port the server is listening on | | [protocol](./kibana-plugin-core-server.httpserverinfo.protocol.md) | 'http' | 'https' | 'socket' | The protocol used by the server | diff --git a/docs/development/core/server/kibana-plugin-core-server.httpservicesetup.md b/docs/development/core/server/kibana-plugin-core-server.httpservicesetup.md index b12983836d9e5..474dc6b7d6f28 100644 --- a/docs/development/core/server/kibana-plugin-core-server.httpservicesetup.md +++ b/docs/development/core/server/kibana-plugin-core-server.httpservicesetup.md @@ -88,8 +88,9 @@ async (context, request, response) => { | [csp](./kibana-plugin-core-server.httpservicesetup.csp.md) | ICspConfig | The CSP config used for Kibana. | | [getServerInfo](./kibana-plugin-core-server.httpservicesetup.getserverinfo.md) | () => HttpServerInfo | Provides common [information](./kibana-plugin-core-server.httpserverinfo.md) about the running http server. | | [registerAuth](./kibana-plugin-core-server.httpservicesetup.registerauth.md) | (handler: AuthenticationHandler) => void | To define custom authentication and/or authorization mechanism for incoming requests. | -| [registerOnPostAuth](./kibana-plugin-core-server.httpservicesetup.registeronpostauth.md) | (handler: OnPostAuthHandler) => void | To define custom logic to perform for incoming requests. | -| [registerOnPreAuth](./kibana-plugin-core-server.httpservicesetup.registeronpreauth.md) | (handler: OnPreAuthHandler) => void | To define custom logic to perform for incoming requests. | +| [registerOnPostAuth](./kibana-plugin-core-server.httpservicesetup.registeronpostauth.md) | (handler: OnPostAuthHandler) => void | To define custom logic after Auth interceptor did make sure a user has access to the requested resource. | +| [registerOnPreAuth](./kibana-plugin-core-server.httpservicesetup.registeronpreauth.md) | (handler: OnPreAuthHandler) => void | To define custom logic to perform for incoming requests before the Auth interceptor performs a check that user has access to requested resources. | | [registerOnPreResponse](./kibana-plugin-core-server.httpservicesetup.registeronpreresponse.md) | (handler: OnPreResponseHandler) => void | To define custom logic to perform for the server response. | +| [registerOnPreRouting](./kibana-plugin-core-server.httpservicesetup.registeronprerouting.md) | (handler: OnPreRoutingHandler) => void | To define custom logic to perform for incoming requests before server performs a route lookup. | | [registerRouteHandlerContext](./kibana-plugin-core-server.httpservicesetup.registerroutehandlercontext.md) | <T extends keyof RequestHandlerContext>(contextName: T, provider: RequestHandlerContextProvider<T>) => RequestHandlerContextContainer | Register a context provider for a route handler. | diff --git a/docs/development/core/server/kibana-plugin-core-server.httpservicesetup.registeronpostauth.md b/docs/development/core/server/kibana-plugin-core-server.httpservicesetup.registeronpostauth.md index 01294693e282f..eff53b7b75fa5 100644 --- a/docs/development/core/server/kibana-plugin-core-server.httpservicesetup.registeronpostauth.md +++ b/docs/development/core/server/kibana-plugin-core-server.httpservicesetup.registeronpostauth.md @@ -4,7 +4,7 @@ ## HttpServiceSetup.registerOnPostAuth property -To define custom logic to perform for incoming requests. +To define custom logic after Auth interceptor did make sure a user has access to the requested resource. Signature: @@ -14,5 +14,5 @@ registerOnPostAuth: (handler: OnPostAuthHandler) => void; ## Remarks -Runs the handler after Auth interceptor did make sure a user has access to the requested resource. The auth state is available at stage via http.auth.get(..) Can register any number of registerOnPreAuth, which are called in sequence (from the first registered to the last). See [OnPostAuthHandler](./kibana-plugin-core-server.onpostauthhandler.md). +The auth state is available at stage via http.auth.get(..) Can register any number of registerOnPreRouting, which are called in sequence (from the first registered to the last). See [OnPostAuthHandler](./kibana-plugin-core-server.onpostauthhandler.md). diff --git a/docs/development/core/server/kibana-plugin-core-server.httpservicesetup.registeronpreauth.md b/docs/development/core/server/kibana-plugin-core-server.httpservicesetup.registeronpreauth.md index f11453c8cda98..ce4cacb1c8749 100644 --- a/docs/development/core/server/kibana-plugin-core-server.httpservicesetup.registeronpreauth.md +++ b/docs/development/core/server/kibana-plugin-core-server.httpservicesetup.registeronpreauth.md @@ -4,7 +4,7 @@ ## HttpServiceSetup.registerOnPreAuth property -To define custom logic to perform for incoming requests. +To define custom logic to perform for incoming requests before the Auth interceptor performs a check that user has access to requested resources. Signature: @@ -14,5 +14,5 @@ registerOnPreAuth: (handler: OnPreAuthHandler) => void; ## Remarks -Runs the handler before Auth interceptor performs a check that user has access to requested resources, so it's the only place when you can forward a request to another URL right on the server. Can register any number of registerOnPostAuth, which are called in sequence (from the first registered to the last). See [OnPreAuthHandler](./kibana-plugin-core-server.onpreauthhandler.md). +Can register any number of registerOnPostAuth, which are called in sequence (from the first registered to the last). See [OnPreRoutingHandler](./kibana-plugin-core-server.onpreroutinghandler.md). diff --git a/docs/development/core/server/kibana-plugin-core-server.httpservicesetup.registeronprerouting.md b/docs/development/core/server/kibana-plugin-core-server.httpservicesetup.registeronprerouting.md new file mode 100644 index 0000000000000..bdf5f15828669 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.httpservicesetup.registeronprerouting.md @@ -0,0 +1,18 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [HttpServiceSetup](./kibana-plugin-core-server.httpservicesetup.md) > [registerOnPreRouting](./kibana-plugin-core-server.httpservicesetup.registeronprerouting.md) + +## HttpServiceSetup.registerOnPreRouting property + +To define custom logic to perform for incoming requests before server performs a route lookup. + +Signature: + +```typescript +registerOnPreRouting: (handler: OnPreRoutingHandler) => void; +``` + +## Remarks + +It's the only place when you can forward a request to another URL right on the server. Can register any number of registerOnPreRouting, which are called in sequence (from the first registered to the last). See [OnPreRoutingHandler](./kibana-plugin-core-server.onpreroutinghandler.md). + diff --git a/docs/development/core/server/kibana-plugin-core-server.legacyclusterclient._constructor_.md b/docs/development/core/server/kibana-plugin-core-server.legacyclusterclient._constructor_.md index 823f34bd7dd23..6a56d31bbd55f 100644 --- a/docs/development/core/server/kibana-plugin-core-server.legacyclusterclient._constructor_.md +++ b/docs/development/core/server/kibana-plugin-core-server.legacyclusterclient._constructor_.md @@ -9,7 +9,7 @@ Constructs a new instance of the `LegacyClusterClient` class Signature: ```typescript -constructor(config: LegacyElasticsearchClientConfig, log: Logger, getAuthHeaders?: GetAuthHeaders); +constructor(config: LegacyElasticsearchClientConfig, log: Logger, getAuditorFactory: () => AuditorFactory, getAuthHeaders?: GetAuthHeaders); ``` ## Parameters @@ -18,5 +18,6 @@ constructor(config: LegacyElasticsearchClientConfig, log: Logger, getAuthHeaders | --- | --- | --- | | config | LegacyElasticsearchClientConfig | | | log | Logger | | +| getAuditorFactory | () => AuditorFactory | | | getAuthHeaders | GetAuthHeaders | | diff --git a/docs/development/core/server/kibana-plugin-core-server.legacyclusterclient.md b/docs/development/core/server/kibana-plugin-core-server.legacyclusterclient.md index 4f218ae552c99..c51f1858c97a5 100644 --- a/docs/development/core/server/kibana-plugin-core-server.legacyclusterclient.md +++ b/docs/development/core/server/kibana-plugin-core-server.legacyclusterclient.md @@ -15,7 +15,7 @@ export declare class LegacyClusterClient implements ILegacyClusterClient | Constructor | Modifiers | Description | | --- | --- | --- | -| [(constructor)(config, log, getAuthHeaders)](./kibana-plugin-core-server.legacyclusterclient._constructor_.md) | | Constructs a new instance of the LegacyClusterClient class | +| [(constructor)(config, log, getAuditorFactory, getAuthHeaders)](./kibana-plugin-core-server.legacyclusterclient._constructor_.md) | | Constructs a new instance of the LegacyClusterClient class | ## Properties diff --git a/docs/development/core/server/kibana-plugin-core-server.legacyscopedclusterclient._constructor_.md b/docs/development/core/server/kibana-plugin-core-server.legacyscopedclusterclient._constructor_.md index bd1cd1e9f3d9b..ffadab7656602 100644 --- a/docs/development/core/server/kibana-plugin-core-server.legacyscopedclusterclient._constructor_.md +++ b/docs/development/core/server/kibana-plugin-core-server.legacyscopedclusterclient._constructor_.md @@ -9,7 +9,7 @@ Constructs a new instance of the `LegacyScopedClusterClient` class Signature: ```typescript -constructor(internalAPICaller: LegacyAPICaller, scopedAPICaller: LegacyAPICaller, headers?: Headers | undefined); +constructor(internalAPICaller: LegacyAPICaller, scopedAPICaller: LegacyAPICaller, headers?: Headers | undefined, auditor?: Auditor | undefined); ``` ## Parameters @@ -19,4 +19,5 @@ constructor(internalAPICaller: LegacyAPICaller, scopedAPICaller: LegacyAPICaller | internalAPICaller | LegacyAPICaller | | | scopedAPICaller | LegacyAPICaller | | | headers | Headers | undefined | | +| auditor | Auditor | undefined | | diff --git a/docs/development/core/server/kibana-plugin-core-server.legacyscopedclusterclient.md b/docs/development/core/server/kibana-plugin-core-server.legacyscopedclusterclient.md index f3d8a69b8ed05..c4a94d8661c47 100644 --- a/docs/development/core/server/kibana-plugin-core-server.legacyscopedclusterclient.md +++ b/docs/development/core/server/kibana-plugin-core-server.legacyscopedclusterclient.md @@ -15,7 +15,7 @@ export declare class LegacyScopedClusterClient implements ILegacyScopedClusterCl | Constructor | Modifiers | Description | | --- | --- | --- | -| [(constructor)(internalAPICaller, scopedAPICaller, headers)](./kibana-plugin-core-server.legacyscopedclusterclient._constructor_.md) | | Constructs a new instance of the LegacyScopedClusterClient class | +| [(constructor)(internalAPICaller, scopedAPICaller, headers, auditor)](./kibana-plugin-core-server.legacyscopedclusterclient._constructor_.md) | | Constructs a new instance of the LegacyScopedClusterClient class | ## Methods diff --git a/docs/development/core/server/kibana-plugin-core-server.md b/docs/development/core/server/kibana-plugin-core-server.md index f73595ea0a8ff..a665327454c1a 100644 --- a/docs/development/core/server/kibana-plugin-core-server.md +++ b/docs/development/core/server/kibana-plugin-core-server.md @@ -56,6 +56,10 @@ The plugin integrates with the core system via lifecycle events: `setup` | --- | --- | | [AssistanceAPIResponse](./kibana-plugin-core-server.assistanceapiresponse.md) | | | [AssistantAPIClientParams](./kibana-plugin-core-server.assistantapiclientparams.md) | | +| [AuditableEvent](./kibana-plugin-core-server.auditableevent.md) | Event to audit. | +| [Auditor](./kibana-plugin-core-server.auditor.md) | Provides methods to log user actions and access events. | +| [AuditorFactory](./kibana-plugin-core-server.auditorfactory.md) | Creates [Auditor](./kibana-plugin-core-server.auditor.md) instance bound to the current user credentials. | +| [AuditTrailSetup](./kibana-plugin-core-server.audittrailsetup.md) | | | [Authenticated](./kibana-plugin-core-server.authenticated.md) | | | [AuthNotHandled](./kibana-plugin-core-server.authnothandled.md) | | | [AuthRedirected](./kibana-plugin-core-server.authredirected.md) | | @@ -118,7 +122,8 @@ The plugin integrates with the core system via lifecycle events: `setup` | [OnPreAuthToolkit](./kibana-plugin-core-server.onpreauthtoolkit.md) | A tool set defining an outcome of OnPreAuth interceptor for incoming request. | | [OnPreResponseExtensions](./kibana-plugin-core-server.onpreresponseextensions.md) | Additional data to extend a response. | | [OnPreResponseInfo](./kibana-plugin-core-server.onpreresponseinfo.md) | Response status code. | -| [OnPreResponseToolkit](./kibana-plugin-core-server.onpreresponsetoolkit.md) | A tool set defining an outcome of OnPreAuth interceptor for incoming request. | +| [OnPreResponseToolkit](./kibana-plugin-core-server.onpreresponsetoolkit.md) | A tool set defining an outcome of OnPreRouting interceptor for incoming request. | +| [OnPreRoutingToolkit](./kibana-plugin-core-server.onpreroutingtoolkit.md) | A tool set defining an outcome of OnPreRouting interceptor for incoming request. | | [OpsMetrics](./kibana-plugin-core-server.opsmetrics.md) | Regroups metrics gathered by all the collectors. This contains metrics about the os/runtime, the kibana process and the http server. | | [OpsOsMetrics](./kibana-plugin-core-server.opsosmetrics.md) | OS related metrics | | [OpsProcessMetrics](./kibana-plugin-core-server.opsprocessmetrics.md) | Process related metrics | @@ -150,7 +155,7 @@ The plugin integrates with the core system via lifecycle events: `setup` | [SavedObjectsBulkUpdateResponse](./kibana-plugin-core-server.savedobjectsbulkupdateresponse.md) | | | [SavedObjectsClientProviderOptions](./kibana-plugin-core-server.savedobjectsclientprovideroptions.md) | Options to control the creation of the Saved Objects Client. | | [SavedObjectsClientWrapperOptions](./kibana-plugin-core-server.savedobjectsclientwrapperoptions.md) | Options passed to each SavedObjectsClientWrapperFactory to aid in creating the wrapper instance. | -| [SavedObjectsComplexFieldMapping](./kibana-plugin-core-server.savedobjectscomplexfieldmapping.md) | See [SavedObjectsFieldMapping](./kibana-plugin-core-server.savedobjectsfieldmapping.md) for documentation.Note: this type intentially doesn't include a type definition for defining the dynamic mapping parameter. Saved Object fields should always inherit the dynamic: 'strict' paramater. If you are unsure of the shape of your data use type: 'object', enabled: false instead. | +| [SavedObjectsComplexFieldMapping](./kibana-plugin-core-server.savedobjectscomplexfieldmapping.md) | See [SavedObjectsFieldMapping](./kibana-plugin-core-server.savedobjectsfieldmapping.md) for documentation. | | [SavedObjectsCoreFieldMapping](./kibana-plugin-core-server.savedobjectscorefieldmapping.md) | See [SavedObjectsFieldMapping](./kibana-plugin-core-server.savedobjectsfieldmapping.md) for documentation. | | [SavedObjectsCreateOptions](./kibana-plugin-core-server.savedobjectscreateoptions.md) | | | [SavedObjectsDeleteByNamespaceOptions](./kibana-plugin-core-server.savedobjectsdeletebynamespaceoptions.md) | | @@ -212,6 +217,7 @@ The plugin integrates with the core system via lifecycle events: `setup` | Type Alias | Description | | --- | --- | | [AppenderConfigType](./kibana-plugin-core-server.appenderconfigtype.md) | | +| [AuditTrailStart](./kibana-plugin-core-server.audittrailstart.md) | | | [AuthenticationHandler](./kibana-plugin-core-server.authenticationhandler.md) | See [AuthToolkit](./kibana-plugin-core-server.authtoolkit.md). | | [AuthHeaders](./kibana-plugin-core-server.authheaders.md) | Auth Headers map | | [AuthResult](./kibana-plugin-core-server.authresult.md) | | @@ -251,7 +257,8 @@ The plugin integrates with the core system via lifecycle events: `setup` | [MutatingOperationRefreshSetting](./kibana-plugin-core-server.mutatingoperationrefreshsetting.md) | Elasticsearch Refresh setting for mutating operation | | [OnPostAuthHandler](./kibana-plugin-core-server.onpostauthhandler.md) | See [OnPostAuthToolkit](./kibana-plugin-core-server.onpostauthtoolkit.md). | | [OnPreAuthHandler](./kibana-plugin-core-server.onpreauthhandler.md) | See [OnPreAuthToolkit](./kibana-plugin-core-server.onpreauthtoolkit.md). | -| [OnPreResponseHandler](./kibana-plugin-core-server.onpreresponsehandler.md) | See [OnPreAuthToolkit](./kibana-plugin-core-server.onpreauthtoolkit.md). | +| [OnPreResponseHandler](./kibana-plugin-core-server.onpreresponsehandler.md) | See [OnPreRoutingToolkit](./kibana-plugin-core-server.onpreroutingtoolkit.md). | +| [OnPreRoutingHandler](./kibana-plugin-core-server.onpreroutinghandler.md) | See [OnPreRoutingToolkit](./kibana-plugin-core-server.onpreroutingtoolkit.md). | | [PluginConfigSchema](./kibana-plugin-core-server.pluginconfigschema.md) | Dedicated type for plugin configuration schema. | | [PluginInitializer](./kibana-plugin-core-server.plugininitializer.md) | The plugin export at the root of a plugin's server directory should conform to this interface. | | [PluginName](./kibana-plugin-core-server.pluginname.md) | Dedicated type for plugin name/id that is supposed to make Map/Set/Arrays that use it as a key or value more obvious. | diff --git a/docs/development/core/server/kibana-plugin-core-server.onpreauthtoolkit.md b/docs/development/core/server/kibana-plugin-core-server.onpreauthtoolkit.md index 4097cb32c397a..8031dbc64fa6d 100644 --- a/docs/development/core/server/kibana-plugin-core-server.onpreauthtoolkit.md +++ b/docs/development/core/server/kibana-plugin-core-server.onpreauthtoolkit.md @@ -17,5 +17,4 @@ export interface OnPreAuthToolkit | Property | Type | Description | | --- | --- | --- | | [next](./kibana-plugin-core-server.onpreauthtoolkit.next.md) | () => OnPreAuthResult | To pass request to the next handler | -| [rewriteUrl](./kibana-plugin-core-server.onpreauthtoolkit.rewriteurl.md) | (url: string) => OnPreAuthResult | Rewrite requested resources url before is was authenticated and routed to a handler | diff --git a/docs/development/core/server/kibana-plugin-core-server.onpreauthtoolkit.rewriteurl.md b/docs/development/core/server/kibana-plugin-core-server.onpreauthtoolkit.rewriteurl.md deleted file mode 100644 index 7ecde62f88302..0000000000000 --- a/docs/development/core/server/kibana-plugin-core-server.onpreauthtoolkit.rewriteurl.md +++ /dev/null @@ -1,13 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [OnPreAuthToolkit](./kibana-plugin-core-server.onpreauthtoolkit.md) > [rewriteUrl](./kibana-plugin-core-server.onpreauthtoolkit.rewriteurl.md) - -## OnPreAuthToolkit.rewriteUrl property - -Rewrite requested resources url before is was authenticated and routed to a handler - -Signature: - -```typescript -rewriteUrl: (url: string) => OnPreAuthResult; -``` diff --git a/docs/development/core/server/kibana-plugin-core-server.onpreresponsehandler.md b/docs/development/core/server/kibana-plugin-core-server.onpreresponsehandler.md index e7eab8ee34d6f..10696fb79a2f6 100644 --- a/docs/development/core/server/kibana-plugin-core-server.onpreresponsehandler.md +++ b/docs/development/core/server/kibana-plugin-core-server.onpreresponsehandler.md @@ -4,7 +4,7 @@ ## OnPreResponseHandler type -See [OnPreAuthToolkit](./kibana-plugin-core-server.onpreauthtoolkit.md). +See [OnPreRoutingToolkit](./kibana-plugin-core-server.onpreroutingtoolkit.md). Signature: diff --git a/docs/development/core/server/kibana-plugin-core-server.onpreresponsetoolkit.md b/docs/development/core/server/kibana-plugin-core-server.onpreresponsetoolkit.md index 8e33e945b4ef9..306c375ba4a3c 100644 --- a/docs/development/core/server/kibana-plugin-core-server.onpreresponsetoolkit.md +++ b/docs/development/core/server/kibana-plugin-core-server.onpreresponsetoolkit.md @@ -4,7 +4,7 @@ ## OnPreResponseToolkit interface -A tool set defining an outcome of OnPreAuth interceptor for incoming request. +A tool set defining an outcome of OnPreRouting interceptor for incoming request. Signature: diff --git a/docs/development/core/server/kibana-plugin-core-server.onpreroutinghandler.md b/docs/development/core/server/kibana-plugin-core-server.onpreroutinghandler.md new file mode 100644 index 0000000000000..46016bcd5476a --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.onpreroutinghandler.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [OnPreRoutingHandler](./kibana-plugin-core-server.onpreroutinghandler.md) + +## OnPreRoutingHandler type + +See [OnPreRoutingToolkit](./kibana-plugin-core-server.onpreroutingtoolkit.md). + +Signature: + +```typescript +export declare type OnPreRoutingHandler = (request: KibanaRequest, response: LifecycleResponseFactory, toolkit: OnPreRoutingToolkit) => OnPreRoutingResult | KibanaResponse | Promise; +``` diff --git a/docs/development/core/server/kibana-plugin-core-server.onpreroutingtoolkit.md b/docs/development/core/server/kibana-plugin-core-server.onpreroutingtoolkit.md new file mode 100644 index 0000000000000..c564896b46a27 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.onpreroutingtoolkit.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [OnPreRoutingToolkit](./kibana-plugin-core-server.onpreroutingtoolkit.md) + +## OnPreRoutingToolkit interface + +A tool set defining an outcome of OnPreRouting interceptor for incoming request. + +Signature: + +```typescript +export interface OnPreRoutingToolkit +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [next](./kibana-plugin-core-server.onpreroutingtoolkit.next.md) | () => OnPreRoutingResult | To pass request to the next handler | +| [rewriteUrl](./kibana-plugin-core-server.onpreroutingtoolkit.rewriteurl.md) | (url: string) => OnPreRoutingResult | Rewrite requested resources url before is was authenticated and routed to a handler | + diff --git a/docs/development/core/server/kibana-plugin-core-server.onpreroutingtoolkit.next.md b/docs/development/core/server/kibana-plugin-core-server.onpreroutingtoolkit.next.md new file mode 100644 index 0000000000000..7fb0b2ce67ba5 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.onpreroutingtoolkit.next.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [OnPreRoutingToolkit](./kibana-plugin-core-server.onpreroutingtoolkit.md) > [next](./kibana-plugin-core-server.onpreroutingtoolkit.next.md) + +## OnPreRoutingToolkit.next property + +To pass request to the next handler + +Signature: + +```typescript +next: () => OnPreRoutingResult; +``` diff --git a/docs/development/core/server/kibana-plugin-core-server.onpreroutingtoolkit.rewriteurl.md b/docs/development/core/server/kibana-plugin-core-server.onpreroutingtoolkit.rewriteurl.md new file mode 100644 index 0000000000000..346a12711c723 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.onpreroutingtoolkit.rewriteurl.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [OnPreRoutingToolkit](./kibana-plugin-core-server.onpreroutingtoolkit.md) > [rewriteUrl](./kibana-plugin-core-server.onpreroutingtoolkit.rewriteurl.md) + +## OnPreRoutingToolkit.rewriteUrl property + +Rewrite requested resources url before is was authenticated and routed to a handler + +Signature: + +```typescript +rewriteUrl: (url: string) => OnPreRoutingResult; +``` diff --git a/docs/development/core/server/kibana-plugin-core-server.pluginmanifest.md b/docs/development/core/server/kibana-plugin-core-server.pluginmanifest.md index 5edee51d6c523..6db2f89590149 100644 --- a/docs/development/core/server/kibana-plugin-core-server.pluginmanifest.md +++ b/docs/development/core/server/kibana-plugin-core-server.pluginmanifest.md @@ -25,6 +25,7 @@ Should never be used in code outside of Core but is exported for documentation p | [id](./kibana-plugin-core-server.pluginmanifest.id.md) | PluginName | Identifier of the plugin. Must be a string in camelCase. Part of a plugin public contract. Other plugins leverage it to access plugin API, navigate to the plugin, etc. | | [kibanaVersion](./kibana-plugin-core-server.pluginmanifest.kibanaversion.md) | string | The version of Kibana the plugin is compatible with, defaults to "version". | | [optionalPlugins](./kibana-plugin-core-server.pluginmanifest.optionalplugins.md) | readonly PluginName[] | An optional list of the other plugins that if installed and enabled \*\*may be\*\* leveraged by this plugin for some additional functionality but otherwise are not required for this plugin to work properly. | +| [requiredBundles](./kibana-plugin-core-server.pluginmanifest.requiredbundles.md) | readonly string[] | List of plugin ids that this plugin's UI code imports modules from that are not in requiredPlugins. | | [requiredPlugins](./kibana-plugin-core-server.pluginmanifest.requiredplugins.md) | readonly PluginName[] | An optional list of the other plugins that \*\*must be\*\* installed and enabled for this plugin to function properly. | | [server](./kibana-plugin-core-server.pluginmanifest.server.md) | boolean | Specifies whether plugin includes some server-side specific functionality. | | [ui](./kibana-plugin-core-server.pluginmanifest.ui.md) | boolean | Specifies whether plugin includes some client/browser specific functionality that should be included into client bundle via public/ui_plugin.js file. | diff --git a/docs/development/core/server/kibana-plugin-core-server.pluginmanifest.requiredbundles.md b/docs/development/core/server/kibana-plugin-core-server.pluginmanifest.requiredbundles.md new file mode 100644 index 0000000000000..98505d07101fe --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.pluginmanifest.requiredbundles.md @@ -0,0 +1,18 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [PluginManifest](./kibana-plugin-core-server.pluginmanifest.md) > [requiredBundles](./kibana-plugin-core-server.pluginmanifest.requiredbundles.md) + +## PluginManifest.requiredBundles property + +List of plugin ids that this plugin's UI code imports modules from that are not in `requiredPlugins`. + +Signature: + +```typescript +readonly requiredBundles: readonly string[]; +``` + +## Remarks + +The plugins listed here will be loaded in the browser, even if the plugin is disabled. Required by `@kbn/optimizer` to support cross-plugin imports. "core" and plugins already listed in `requiredPlugins` do not need to be duplicated here. + diff --git a/docs/development/core/server/kibana-plugin-core-server.requesthandlercontext.core.md b/docs/development/core/server/kibana-plugin-core-server.requesthandlercontext.core.md index b09fb121b8a63..2d31c24a077cb 100644 --- a/docs/development/core/server/kibana-plugin-core-server.requesthandlercontext.core.md +++ b/docs/development/core/server/kibana-plugin-core-server.requesthandlercontext.core.md @@ -20,5 +20,6 @@ core: { uiSettings: { client: IUiSettingsClient; }; + auditor: Auditor; }; ``` diff --git a/docs/development/core/server/kibana-plugin-core-server.requesthandlercontext.md b/docs/development/core/server/kibana-plugin-core-server.requesthandlercontext.md index 55d6e931ac158..07e6dcbdae125 100644 --- a/docs/development/core/server/kibana-plugin-core-server.requesthandlercontext.md +++ b/docs/development/core/server/kibana-plugin-core-server.requesthandlercontext.md @@ -18,5 +18,5 @@ export interface RequestHandlerContext | Property | Type | Description | | --- | --- | --- | -| [core](./kibana-plugin-core-server.requesthandlercontext.core.md) | {
savedObjects: {
client: SavedObjectsClientContract;
typeRegistry: ISavedObjectTypeRegistry;
};
elasticsearch: {
legacy: {
client: ILegacyScopedClusterClient;
};
};
uiSettings: {
client: IUiSettingsClient;
};
} | | +| [core](./kibana-plugin-core-server.requesthandlercontext.core.md) | {
savedObjects: {
client: SavedObjectsClientContract;
typeRegistry: ISavedObjectTypeRegistry;
};
elasticsearch: {
legacy: {
client: ILegacyScopedClusterClient;
};
};
uiSettings: {
client: IUiSettingsClient;
};
auditor: Auditor;
} | | diff --git a/docs/development/core/server/kibana-plugin-core-server.savedobjectscomplexfieldmapping.dynamic.md b/docs/development/core/server/kibana-plugin-core-server.savedobjectscomplexfieldmapping.dynamic.md new file mode 100644 index 0000000000000..b01da3c62fda6 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.savedobjectscomplexfieldmapping.dynamic.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [SavedObjectsComplexFieldMapping](./kibana-plugin-core-server.savedobjectscomplexfieldmapping.md) > [dynamic](./kibana-plugin-core-server.savedobjectscomplexfieldmapping.dynamic.md) + +## SavedObjectsComplexFieldMapping.dynamic property + +The dynamic property of the mapping, either `false` or `'strict'`. If unspecified `dynamic: 'strict'` will be inherited from the top-level index mappings. + +Note: To limit the number of mapping fields Saved Object types should \*never\* use `dynamic: true`. + +Signature: + +```typescript +dynamic?: false | 'strict'; +``` diff --git a/docs/development/core/server/kibana-plugin-core-server.savedobjectscomplexfieldmapping.enabled.md b/docs/development/core/server/kibana-plugin-core-server.savedobjectscomplexfieldmapping.enabled.md new file mode 100644 index 0000000000000..08513aa2a849b --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.savedobjectscomplexfieldmapping.enabled.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [SavedObjectsComplexFieldMapping](./kibana-plugin-core-server.savedobjectscomplexfieldmapping.md) > [enabled](./kibana-plugin-core-server.savedobjectscomplexfieldmapping.enabled.md) + +## SavedObjectsComplexFieldMapping.enabled property + +Signature: + +```typescript +enabled?: boolean; +``` diff --git a/docs/development/core/server/kibana-plugin-core-server.savedobjectscomplexfieldmapping.md b/docs/development/core/server/kibana-plugin-core-server.savedobjectscomplexfieldmapping.md index cb81686b424ec..fc262cad54f18 100644 --- a/docs/development/core/server/kibana-plugin-core-server.savedobjectscomplexfieldmapping.md +++ b/docs/development/core/server/kibana-plugin-core-server.savedobjectscomplexfieldmapping.md @@ -6,8 +6,6 @@ See [SavedObjectsFieldMapping](./kibana-plugin-core-server.savedobjectsfieldmapping.md) for documentation. -Note: this type intentially doesn't include a type definition for defining the `dynamic` mapping parameter. Saved Object fields should always inherit the `dynamic: 'strict'` paramater. If you are unsure of the shape of your data use `type: 'object', enabled: false` instead. - Signature: ```typescript @@ -19,6 +17,8 @@ export interface SavedObjectsComplexFieldMapping | Property | Type | Description | | --- | --- | --- | | [doc\_values](./kibana-plugin-core-server.savedobjectscomplexfieldmapping.doc_values.md) | boolean | | +| [dynamic](./kibana-plugin-core-server.savedobjectscomplexfieldmapping.dynamic.md) | false | 'strict' | The dynamic property of the mapping, either false or 'strict'. If unspecified dynamic: 'strict' will be inherited from the top-level index mappings.Note: To limit the number of mapping fields Saved Object types should \*never\* use dynamic: true. | +| [enabled](./kibana-plugin-core-server.savedobjectscomplexfieldmapping.enabled.md) | boolean | | | [properties](./kibana-plugin-core-server.savedobjectscomplexfieldmapping.properties.md) | SavedObjectsMappingProperties | | | [type](./kibana-plugin-core-server.savedobjectscomplexfieldmapping.type.md) | string | | diff --git a/docs/development/core/server/kibana-plugin-core-server.savedobjectscorefieldmapping.enabled.md b/docs/development/core/server/kibana-plugin-core-server.savedobjectscorefieldmapping.enabled.md deleted file mode 100644 index c0b556e99ebc3..0000000000000 --- a/docs/development/core/server/kibana-plugin-core-server.savedobjectscorefieldmapping.enabled.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [SavedObjectsCoreFieldMapping](./kibana-plugin-core-server.savedobjectscorefieldmapping.md) > [enabled](./kibana-plugin-core-server.savedobjectscorefieldmapping.enabled.md) - -## SavedObjectsCoreFieldMapping.enabled property - -Signature: - -```typescript -enabled?: boolean; -``` diff --git a/docs/development/core/server/kibana-plugin-core-server.savedobjectscorefieldmapping.md b/docs/development/core/server/kibana-plugin-core-server.savedobjectscorefieldmapping.md index b9e726eac799d..e9b9c2bcf51b5 100644 --- a/docs/development/core/server/kibana-plugin-core-server.savedobjectscorefieldmapping.md +++ b/docs/development/core/server/kibana-plugin-core-server.savedobjectscorefieldmapping.md @@ -17,7 +17,6 @@ export interface SavedObjectsCoreFieldMapping | Property | Type | Description | | --- | --- | --- | | [doc\_values](./kibana-plugin-core-server.savedobjectscorefieldmapping.doc_values.md) | boolean | | -| [enabled](./kibana-plugin-core-server.savedobjectscorefieldmapping.enabled.md) | boolean | | | [fields](./kibana-plugin-core-server.savedobjectscorefieldmapping.fields.md) | {
[subfield: string]: {
type: string;
ignore_above?: number;
};
} | | | [index](./kibana-plugin-core-server.savedobjectscorefieldmapping.index.md) | boolean | | | [null\_value](./kibana-plugin-core-server.savedobjectscorefieldmapping.null_value.md) | number | boolean | string | | diff --git a/docs/development/core/server/kibana-plugin-core-server.savedobjectsfindoptions.md b/docs/development/core/server/kibana-plugin-core-server.savedobjectsfindoptions.md index 6db16d979f1fe..67e931f0cb3b3 100644 --- a/docs/development/core/server/kibana-plugin-core-server.savedobjectsfindoptions.md +++ b/docs/development/core/server/kibana-plugin-core-server.savedobjectsfindoptions.md @@ -8,7 +8,7 @@ Signature: ```typescript -export interface SavedObjectsFindOptions extends SavedObjectsBaseOptions +export interface SavedObjectsFindOptions ``` ## Properties @@ -19,6 +19,7 @@ export interface SavedObjectsFindOptions extends SavedObjectsBaseOptions | [fields](./kibana-plugin-core-server.savedobjectsfindoptions.fields.md) | string[] | An array of fields to include in the results | | [filter](./kibana-plugin-core-server.savedobjectsfindoptions.filter.md) | string | | | [hasReference](./kibana-plugin-core-server.savedobjectsfindoptions.hasreference.md) | {
type: string;
id: string;
} | | +| [namespaces](./kibana-plugin-core-server.savedobjectsfindoptions.namespaces.md) | string[] | | | [page](./kibana-plugin-core-server.savedobjectsfindoptions.page.md) | number | | | [perPage](./kibana-plugin-core-server.savedobjectsfindoptions.perpage.md) | number | | | [preference](./kibana-plugin-core-server.savedobjectsfindoptions.preference.md) | string | An optional ES preference value to be used for the query \* | diff --git a/docs/development/core/server/kibana-plugin-core-server.savedobjectsfindoptions.namespaces.md b/docs/development/core/server/kibana-plugin-core-server.savedobjectsfindoptions.namespaces.md new file mode 100644 index 0000000000000..cae707baa58c0 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-core-server.savedobjectsfindoptions.namespaces.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-core-server](./kibana-plugin-core-server.md) > [SavedObjectsFindOptions](./kibana-plugin-core-server.savedobjectsfindoptions.md) > [namespaces](./kibana-plugin-core-server.savedobjectsfindoptions.namespaces.md) + +## SavedObjectsFindOptions.namespaces property + +Signature: + +```typescript +namespaces?: string[]; +``` diff --git a/docs/development/core/server/kibana-plugin-core-server.savedobjectsrepository.find.md b/docs/development/core/server/kibana-plugin-core-server.savedobjectsrepository.find.md index 8b89c802ec9ce..6c41441302c0b 100644 --- a/docs/development/core/server/kibana-plugin-core-server.savedobjectsrepository.find.md +++ b/docs/development/core/server/kibana-plugin-core-server.savedobjectsrepository.find.md @@ -7,14 +7,14 @@ Signature: ```typescript -find({ search, defaultSearchOperator, searchFields, hasReference, page, perPage, sortField, sortOrder, fields, namespace, type, filter, preference, }: SavedObjectsFindOptions): Promise>; +find({ search, defaultSearchOperator, searchFields, hasReference, page, perPage, sortField, sortOrder, fields, namespaces, type, filter, preference, }: SavedObjectsFindOptions): Promise>; ``` ## Parameters | Parameter | Type | Description | | --- | --- | --- | -| { search, defaultSearchOperator, searchFields, hasReference, page, perPage, sortField, sortOrder, fields, namespace, type, filter, preference, } | SavedObjectsFindOptions | | +| { search, defaultSearchOperator, searchFields, hasReference, page, perPage, sortField, sortOrder, fields, namespaces, type, filter, preference, } | SavedObjectsFindOptions | | Returns: diff --git a/docs/development/core/server/kibana-plugin-core-server.savedobjectsrepository.md b/docs/development/core/server/kibana-plugin-core-server.savedobjectsrepository.md index b9a92561f29fb..5b02707a3c0f4 100644 --- a/docs/development/core/server/kibana-plugin-core-server.savedobjectsrepository.md +++ b/docs/development/core/server/kibana-plugin-core-server.savedobjectsrepository.md @@ -23,7 +23,7 @@ export declare class SavedObjectsRepository | [delete(type, id, options)](./kibana-plugin-core-server.savedobjectsrepository.delete.md) | | Deletes an object | | [deleteByNamespace(namespace, options)](./kibana-plugin-core-server.savedobjectsrepository.deletebynamespace.md) | | Deletes all objects from the provided namespace. | | [deleteFromNamespaces(type, id, namespaces, options)](./kibana-plugin-core-server.savedobjectsrepository.deletefromnamespaces.md) | | Removes one or more namespaces from a given multi-namespace saved object. If no namespaces remain, the saved object is deleted entirely. This method and \[addToNamespaces\][SavedObjectsRepository.addToNamespaces()](./kibana-plugin-core-server.savedobjectsrepository.addtonamespaces.md) are the only ways to change which Spaces a multi-namespace saved object is shared to. | -| [find({ search, defaultSearchOperator, searchFields, hasReference, page, perPage, sortField, sortOrder, fields, namespace, type, filter, preference, })](./kibana-plugin-core-server.savedobjectsrepository.find.md) | | | +| [find({ search, defaultSearchOperator, searchFields, hasReference, page, perPage, sortField, sortOrder, fields, namespaces, type, filter, preference, })](./kibana-plugin-core-server.savedobjectsrepository.find.md) | | | | [get(type, id, options)](./kibana-plugin-core-server.savedobjectsrepository.get.md) | | Gets a single object | | [incrementCounter(type, id, counterFieldName, options)](./kibana-plugin-core-server.savedobjectsrepository.incrementcounter.md) | | Increases a counter field by one. Creates the document if one doesn't exist for the given id. | | [update(type, id, attributes, options)](./kibana-plugin-core-server.savedobjectsrepository.update.md) | | Updates an object | diff --git a/docs/development/core/server/kibana-plugin-core-server.savedobjectstypemappingdefinition.dynamic.md b/docs/development/core/server/kibana-plugin-core-server.savedobjectstypemappingdefinition.dynamic.md index 74efa75768f9c..70775760ac77d 100644 --- a/docs/development/core/server/kibana-plugin-core-server.savedobjectstypemappingdefinition.dynamic.md +++ b/docs/development/core/server/kibana-plugin-core-server.savedobjectstypemappingdefinition.dynamic.md @@ -4,7 +4,7 @@ ## SavedObjectsTypeMappingDefinition.dynamic property -The dynamic property of the mapping. either `false` or 'strict'. Defaults to `false` +The dynamic property of the mapping, either `false` or `'strict'`. If unspecified `dynamic: 'strict'` will be inherited from the top-level index mappings. Signature: diff --git a/docs/development/core/server/kibana-plugin-core-server.savedobjectstypemappingdefinition.md b/docs/development/core/server/kibana-plugin-core-server.savedobjectstypemappingdefinition.md index 77ded4389c0a0..3d3b73880fa7f 100644 --- a/docs/development/core/server/kibana-plugin-core-server.savedobjectstypemappingdefinition.md +++ b/docs/development/core/server/kibana-plugin-core-server.savedobjectstypemappingdefinition.md @@ -41,6 +41,6 @@ const typeDefinition: SavedObjectsTypeMappingDefinition = { | Property | Type | Description | | --- | --- | --- | -| [dynamic](./kibana-plugin-core-server.savedobjectstypemappingdefinition.dynamic.md) | false | 'strict' | The dynamic property of the mapping. either false or 'strict'. Defaults to false | +| [dynamic](./kibana-plugin-core-server.savedobjectstypemappingdefinition.dynamic.md) | false | 'strict' | The dynamic property of the mapping, either false or 'strict'. If unspecified dynamic: 'strict' will be inherited from the top-level index mappings. | | [properties](./kibana-plugin-core-server.savedobjectstypemappingdefinition.properties.md) | SavedObjectsMappingProperties | The underlying properties of the type mapping | diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.embeddable.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.embeddable.md new file mode 100644 index 0000000000000..027ae4209b77f --- /dev/null +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.embeddable.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [ApplyGlobalFilterActionContext](./kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.md) > [embeddable](./kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.embeddable.md) + +## ApplyGlobalFilterActionContext.embeddable property + +Signature: + +```typescript +embeddable?: IEmbeddable; +``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.filters.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.filters.md new file mode 100644 index 0000000000000..6d1d20580fb19 --- /dev/null +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.filters.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [ApplyGlobalFilterActionContext](./kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.md) > [filters](./kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.filters.md) + +## ApplyGlobalFilterActionContext.filters property + +Signature: + +```typescript +filters: Filter[]; +``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.md new file mode 100644 index 0000000000000..62817cd0a1e33 --- /dev/null +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [ApplyGlobalFilterActionContext](./kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.md) + +## ApplyGlobalFilterActionContext interface + +Signature: + +```typescript +export interface ApplyGlobalFilterActionContext +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [embeddable](./kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.embeddable.md) | IEmbeddable | | +| [filters](./kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.filters.md) | Filter[] | | +| [timeFieldName](./kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.timefieldname.md) | string | | + diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.timefieldname.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.timefieldname.md new file mode 100644 index 0000000000000..a5cf58018ec65 --- /dev/null +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.timefieldname.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [ApplyGlobalFilterActionContext](./kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.md) > [timeFieldName](./kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.timefieldname.md) + +## ApplyGlobalFilterActionContext.timeFieldName property + +Signature: + +```typescript +timeFieldName?: string; +``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.baseformatterspublic.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.baseformatterspublic.md index ddbf1a8459d1f..25f046983cbce 100644 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.baseformatterspublic.md +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.baseformatterspublic.md @@ -7,5 +7,5 @@ Signature: ```typescript -baseFormattersPublic: (import("../../common").FieldFormatInstanceType | typeof DateFormat)[] +baseFormattersPublic: (import("../../common").FieldFormatInstanceType | typeof DateNanosFormat | typeof DateFormat)[] ``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.esaggsexpressionfunctiondefinition.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.esaggsexpressionfunctiondefinition.md new file mode 100644 index 0000000000000..6cf05dde27627 --- /dev/null +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.esaggsexpressionfunctiondefinition.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [EsaggsExpressionFunctionDefinition](./kibana-plugin-plugins-data-public.esaggsexpressionfunctiondefinition.md) + +## EsaggsExpressionFunctionDefinition type + +Signature: + +```typescript +export declare type EsaggsExpressionFunctionDefinition = ExpressionFunctionDefinition<'esaggs', Input, Arguments, Output>; +``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.getquerylog.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.getquerylog.md deleted file mode 100644 index e933245e81623..0000000000000 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.getquerylog.md +++ /dev/null @@ -1,25 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [getQueryLog](./kibana-plugin-plugins-data-public.getquerylog.md) - -## getQueryLog() function - -Signature: - -```typescript -export declare function getQueryLog(uiSettings: IUiSettingsClient, storage: IStorageWrapper, appName: string, language: string): PersistedLog; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| uiSettings | IUiSettingsClient | | -| storage | IStorageWrapper | | -| appName | string | | -| language | string | | - -Returns: - -`PersistedLog` - diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.getsearchparamsfromrequest.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.getsearchparamsfromrequest.md index 1923f0e2e4ea1..5bd1694cbeea3 100644 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.getsearchparamsfromrequest.md +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.getsearchparamsfromrequest.md @@ -10,16 +10,7 @@ export declare function getSearchParamsFromRequest(searchRequest: SearchRequest, dependencies: { injectedMetadata: CoreStart['injectedMetadata']; uiSettings: IUiSettingsClient; -}): { - rest_total_hits_as_int: boolean; - ignore_unavailable: boolean; - ignore_throttled: boolean; - max_concurrent_shard_requests: any; - preference: any; - timeout: string | undefined; - index: any; - body: any; -}; +}): ISearchRequestParams; ``` ## Parameters @@ -31,14 +22,5 @@ export declare function getSearchParamsFromRequest(searchRequest: SearchRequest, Returns: -`{ - rest_total_hits_as_int: boolean; - ignore_unavailable: boolean; - ignore_throttled: boolean; - max_concurrent_shard_requests: any; - preference: any; - timeout: string | undefined; - index: any; - body: any; -}` +`ISearchRequestParams` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iessearchrequest.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iessearchrequest.md index ed24ca613cdf6..fee34378339af 100644 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iessearchrequest.md +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iessearchrequest.md @@ -15,5 +15,5 @@ export interface IEsSearchRequest extends IKibanaSearchRequest | Property | Type | Description | | --- | --- | --- | | [indexType](./kibana-plugin-plugins-data-public.iessearchrequest.indextype.md) | string | | -| [params](./kibana-plugin-plugins-data-public.iessearchrequest.params.md) | SearchParams | | +| [params](./kibana-plugin-plugins-data-public.iessearchrequest.params.md) | ISearchRequestParams | | diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iessearchrequest.params.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iessearchrequest.params.md index 2ca8c83d3f1ef..24107faa28e8c 100644 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iessearchrequest.params.md +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iessearchrequest.params.md @@ -7,5 +7,5 @@ Signature: ```typescript -params: SearchParams; +params?: ISearchRequestParams; ``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iessearchresponse.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iessearchresponse.md index a5027ef292ef8..ea7e2aef00d6e 100644 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iessearchresponse.md +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iessearchresponse.md @@ -7,12 +7,12 @@ Signature: ```typescript -export interface IEsSearchResponse extends IKibanaSearchResponse +export interface IEsSearchResponse extends IKibanaSearchResponse ``` ## Properties | Property | Type | Description | | --- | --- | --- | -| [rawResponse](./kibana-plugin-plugins-data-public.iessearchresponse.rawresponse.md) | SearchResponse<Hits> | | +| [rawResponse](./kibana-plugin-plugins-data-public.iessearchresponse.rawresponse.md) | SearchResponse<any> | | diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iessearchresponse.rawresponse.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iessearchresponse.rawresponse.md index 8f6563a1cea84..d7912f377ca9f 100644 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iessearchresponse.rawresponse.md +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iessearchresponse.rawresponse.md @@ -7,5 +7,5 @@ Signature: ```typescript -rawResponse: SearchResponse; +rawResponse: SearchResponse; ``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.indexpattern.destroy.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.indexpattern.destroy.md deleted file mode 100644 index 3a8e1b9dae5a6..0000000000000 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.indexpattern.destroy.md +++ /dev/null @@ -1,15 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [IndexPattern](./kibana-plugin-plugins-data-public.indexpattern.md) > [destroy](./kibana-plugin-plugins-data-public.indexpattern.destroy.md) - -## IndexPattern.destroy() method - -Signature: - -```typescript -destroy(): Promise<{}> | undefined; -``` -Returns: - -`Promise<{}> | undefined` - diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.indexpattern.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.indexpattern.md index bc999a3bb48e3..a37f115358922 100644 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.indexpattern.md +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.indexpattern.md @@ -39,7 +39,6 @@ export declare class IndexPattern implements IIndexPattern | [\_fetchFields()](./kibana-plugin-plugins-data-public.indexpattern._fetchfields.md) | | | | [addScriptedField(name, script, fieldType, lang)](./kibana-plugin-plugins-data-public.indexpattern.addscriptedfield.md) | | | | [create(allowOverride)](./kibana-plugin-plugins-data-public.indexpattern.create.md) | | | -| [destroy()](./kibana-plugin-plugins-data-public.indexpattern.destroy.md) | | | | [getAggregationRestrictions()](./kibana-plugin-plugins-data-public.indexpattern.getaggregationrestrictions.md) | | | | [getComputedFields()](./kibana-plugin-plugins-data-public.indexpattern.getcomputedfields.md) | | | | [getFieldByName(name)](./kibana-plugin-plugins-data-public.indexpattern.getfieldbyname.md) | | | diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.irequesttypesmap.es.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.irequesttypesmap.es.md deleted file mode 100644 index 0b31968f06425..0000000000000 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.irequesttypesmap.es.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [IRequestTypesMap](./kibana-plugin-plugins-data-public.irequesttypesmap.md) > [es](./kibana-plugin-plugins-data-public.irequesttypesmap.es.md) - -## IRequestTypesMap.es property - -Signature: - -```typescript -[ES_SEARCH_STRATEGY]: IEsSearchRequest; -``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.irequesttypesmap.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.irequesttypesmap.md deleted file mode 100644 index 4ca5e9eab665a..0000000000000 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.irequesttypesmap.md +++ /dev/null @@ -1,19 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [IRequestTypesMap](./kibana-plugin-plugins-data-public.irequesttypesmap.md) - -## IRequestTypesMap interface - -Signature: - -```typescript -export interface IRequestTypesMap -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [es](./kibana-plugin-plugins-data-public.irequesttypesmap.es.md) | IEsSearchRequest | | -| [SYNC\_SEARCH\_STRATEGY](./kibana-plugin-plugins-data-public.irequesttypesmap.sync_search_strategy.md) | ISyncSearchRequest | | - diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.irequesttypesmap.sync_search_strategy.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.irequesttypesmap.sync_search_strategy.md deleted file mode 100644 index 28b87111a75ad..0000000000000 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.irequesttypesmap.sync_search_strategy.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [IRequestTypesMap](./kibana-plugin-plugins-data-public.irequesttypesmap.md) > [SYNC\_SEARCH\_STRATEGY](./kibana-plugin-plugins-data-public.irequesttypesmap.sync_search_strategy.md) - -## IRequestTypesMap.SYNC\_SEARCH\_STRATEGY property - -Signature: - -```typescript -[SYNC_SEARCH_STRATEGY]: ISyncSearchRequest; -``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iresponsetypesmap.es.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iresponsetypesmap.es.md deleted file mode 100644 index 8056d0b16a66e..0000000000000 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iresponsetypesmap.es.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [IResponseTypesMap](./kibana-plugin-plugins-data-public.iresponsetypesmap.md) > [es](./kibana-plugin-plugins-data-public.iresponsetypesmap.es.md) - -## IResponseTypesMap.es property - -Signature: - -```typescript -[ES_SEARCH_STRATEGY]: IEsSearchResponse; -``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iresponsetypesmap.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iresponsetypesmap.md deleted file mode 100644 index b6ec3aa38c96a..0000000000000 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iresponsetypesmap.md +++ /dev/null @@ -1,19 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [IResponseTypesMap](./kibana-plugin-plugins-data-public.iresponsetypesmap.md) - -## IResponseTypesMap interface - -Signature: - -```typescript -export interface IResponseTypesMap -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [es](./kibana-plugin-plugins-data-public.iresponsetypesmap.es.md) | IEsSearchResponse | | -| [SYNC\_SEARCH\_STRATEGY](./kibana-plugin-plugins-data-public.iresponsetypesmap.sync_search_strategy.md) | IKibanaSearchResponse | | - diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iresponsetypesmap.sync_search_strategy.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iresponsetypesmap.sync_search_strategy.md deleted file mode 100644 index c9fad4ced534c..0000000000000 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.iresponsetypesmap.sync_search_strategy.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [IResponseTypesMap](./kibana-plugin-plugins-data-public.iresponsetypesmap.md) > [SYNC\_SEARCH\_STRATEGY](./kibana-plugin-plugins-data-public.iresponsetypesmap.sync_search_strategy.md) - -## IResponseTypesMap.SYNC\_SEARCH\_STRATEGY property - -Signature: - -```typescript -[SYNC_SEARCH_STRATEGY]: IKibanaSearchResponse; -``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isearch.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isearch.md index 1a58b41052caf..79f667a70571a 100644 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isearch.md +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isearch.md @@ -7,5 +7,5 @@ Signature: ```typescript -export declare type ISearch = (request: IRequestTypesMap[T], options?: ISearchOptions) => Observable; +export declare type ISearch = (request: IKibanaSearchRequest, options?: ISearchOptions) => Observable; ``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isearchgeneric.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isearchgeneric.md index e118dac31c296..cdf19cd15a298 100644 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isearchgeneric.md +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isearchgeneric.md @@ -7,5 +7,5 @@ Signature: ```typescript -export declare type ISearchGeneric = (request: IRequestTypesMap[T], options?: ISearchOptions, strategy?: T) => Observable; +export declare type ISearchGeneric = (request: IEsSearchRequest, options?: IStrategyOptions) => Observable; ``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isearchstrategy.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isearchstrategy.md deleted file mode 100644 index 9e74bc0e60a73..0000000000000 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isearchstrategy.md +++ /dev/null @@ -1,20 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [ISearchStrategy](./kibana-plugin-plugins-data-public.isearchstrategy.md) - -## ISearchStrategy interface - -Search strategy interface contains a search method that takes in a request and returns a promise that resolves to a response. - -Signature: - -```typescript -export interface ISearchStrategy -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [search](./kibana-plugin-plugins-data-public.isearchstrategy.search.md) | ISearch<T> | | - diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isearchstrategy.search.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isearchstrategy.search.md deleted file mode 100644 index e2e4264b7c6e0..0000000000000 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isearchstrategy.search.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [ISearchStrategy](./kibana-plugin-plugins-data-public.isearchstrategy.md) > [search](./kibana-plugin-plugins-data-public.isearchstrategy.search.md) - -## ISearchStrategy.search property - -Signature: - -```typescript -search: ISearch; -``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isyncsearchrequest.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isyncsearchrequest.md deleted file mode 100644 index 29befdbf295dc..0000000000000 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isyncsearchrequest.md +++ /dev/null @@ -1,18 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [ISyncSearchRequest](./kibana-plugin-plugins-data-public.isyncsearchrequest.md) - -## ISyncSearchRequest interface - -Signature: - -```typescript -export interface ISyncSearchRequest extends IKibanaSearchRequest -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [serverStrategy](./kibana-plugin-plugins-data-public.isyncsearchrequest.serverstrategy.md) | string | | - diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isyncsearchrequest.serverstrategy.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isyncsearchrequest.serverstrategy.md deleted file mode 100644 index f30f274a3b9b6..0000000000000 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isyncsearchrequest.serverstrategy.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [ISyncSearchRequest](./kibana-plugin-plugins-data-public.isyncsearchrequest.md) > [serverStrategy](./kibana-plugin-plugins-data-public.isyncsearchrequest.serverstrategy.md) - -## ISyncSearchRequest.serverStrategy property - -Signature: - -```typescript -serverStrategy: string; -``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.md index feeb686a1f5ed..db41936f35cca 100644 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.md +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.md @@ -38,7 +38,6 @@ | --- | --- | | [getDefaultQuery(language)](./kibana-plugin-plugins-data-public.getdefaultquery.md) | | | [getEsPreference(uiSettings, sessionId)](./kibana-plugin-plugins-data-public.getespreference.md) | | -| [getQueryLog(uiSettings, storage, appName, language)](./kibana-plugin-plugins-data-public.getquerylog.md) | | | [getSearchErrorType({ message })](./kibana-plugin-plugins-data-public.getsearcherrortype.md) | | | [getSearchParamsFromRequest(searchRequest, dependencies)](./kibana-plugin-plugins-data-public.getsearchparamsfromrequest.md) | | | [getTime(indexPattern, timeRange, options)](./kibana-plugin-plugins-data-public.gettime.md) | | @@ -49,6 +48,7 @@ | Interface | Description | | --- | --- | | [AggParamOption](./kibana-plugin-plugins-data-public.aggparamoption.md) | | +| [ApplyGlobalFilterActionContext](./kibana-plugin-plugins-data-public.applyglobalfilteractioncontext.md) | | | [DataPublicPluginSetup](./kibana-plugin-plugins-data-public.datapublicpluginsetup.md) | | | [DataPublicPluginStart](./kibana-plugin-plugins-data-public.datapublicpluginstart.md) | | | [EsQueryConfig](./kibana-plugin-plugins-data-public.esqueryconfig.md) | | @@ -67,11 +67,7 @@ | [IKibanaSearchResponse](./kibana-plugin-plugins-data-public.ikibanasearchresponse.md) | | | [IndexPatternAttributes](./kibana-plugin-plugins-data-public.indexpatternattributes.md) | Use data plugin interface instead | | [IndexPatternTypeMeta](./kibana-plugin-plugins-data-public.indexpatterntypemeta.md) | | -| [IRequestTypesMap](./kibana-plugin-plugins-data-public.irequesttypesmap.md) | | -| [IResponseTypesMap](./kibana-plugin-plugins-data-public.iresponsetypesmap.md) | | | [ISearchOptions](./kibana-plugin-plugins-data-public.isearchoptions.md) | | -| [ISearchStrategy](./kibana-plugin-plugins-data-public.isearchstrategy.md) | Search strategy interface contains a search method that takes in a request and returns a promise that resolves to a response. | -| [ISyncSearchRequest](./kibana-plugin-plugins-data-public.isyncsearchrequest.md) | | | [KueryNode](./kibana-plugin-plugins-data-public.kuerynode.md) | | | [OptionedValueProp](./kibana-plugin-plugins-data-public.optionedvalueprop.md) | | | [Query](./kibana-plugin-plugins-data-public.query.md) | | @@ -83,6 +79,7 @@ | [RefreshInterval](./kibana-plugin-plugins-data-public.refreshinterval.md) | | | [SavedQuery](./kibana-plugin-plugins-data-public.savedquery.md) | | | [SavedQueryService](./kibana-plugin-plugins-data-public.savedqueryservice.md) | | +| [SearchInterceptorDeps](./kibana-plugin-plugins-data-public.searchinterceptordeps.md) | | | [SearchSourceFields](./kibana-plugin-plugins-data-public.searchsourcefields.md) | | | [TabbedAggColumn](./kibana-plugin-plugins-data-public.tabbedaggcolumn.md) | \* | | [TabbedTable](./kibana-plugin-plugins-data-public.tabbedtable.md) | \* | @@ -118,7 +115,6 @@ | [QueryStringInput](./kibana-plugin-plugins-data-public.querystringinput.md) | | | [search](./kibana-plugin-plugins-data-public.search.md) | | | [SearchBar](./kibana-plugin-plugins-data-public.searchbar.md) | | -| [SYNC\_SEARCH\_STRATEGY](./kibana-plugin-plugins-data-public.sync_search_strategy.md) | | | [syncQueryStateWithUrl](./kibana-plugin-plugins-data-public.syncquerystatewithurl.md) | Helper to setup syncing of global data with the URL | | [UI\_SETTINGS](./kibana-plugin-plugins-data-public.ui_settings.md) | | @@ -130,6 +126,7 @@ | [AggGroupName](./kibana-plugin-plugins-data-public.agggroupname.md) | | | [AggParam](./kibana-plugin-plugins-data-public.aggparam.md) | | | [CustomFilter](./kibana-plugin-plugins-data-public.customfilter.md) | | +| [EsaggsExpressionFunctionDefinition](./kibana-plugin-plugins-data-public.esaggsexpressionfunctiondefinition.md) | | | [EsQuerySortValue](./kibana-plugin-plugins-data-public.esquerysortvalue.md) | | | [ExistsFilter](./kibana-plugin-plugins-data-public.existsfilter.md) | | | [FieldFormatId](./kibana-plugin-plugins-data-public.fieldformatid.md) | id type is needed for creating custom converters. | diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.plugin.setup.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.plugin.setup.md index 51bc46bbdccc8..a0c9b38792825 100644 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.plugin.setup.md +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.plugin.setup.md @@ -7,15 +7,15 @@ Signature: ```typescript -setup(core: CoreSetup, { expressions, uiActions }: DataSetupDependencies): DataPublicPluginSetup; +setup(core: CoreSetup, { expressions, uiActions, usageCollection }: DataSetupDependencies): DataPublicPluginSetup; ``` ## Parameters | Parameter | Type | Description | | --- | --- | --- | -| core | CoreSetup | | -| { expressions, uiActions } | DataSetupDependencies | | +| core | CoreSetup<DataStartDependencies, DataPublicPluginStart> | | +| { expressions, uiActions, usageCollection } | DataSetupDependencies | | Returns: diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.querystringinput.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.querystringinput.md index a25f4a0c373b2..e139b326b7500 100644 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.querystringinput.md +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.querystringinput.md @@ -7,5 +7,5 @@ Signature: ```typescript -QueryStringInput: React.FC> +QueryStringInput: React.FC> ``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.search.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.search.md index 67c4eac67a9e6..6c8f7fbdb170b 100644 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.search.md +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.search.md @@ -21,6 +21,7 @@ search: { })[]; InvalidEsCalendarIntervalError: typeof InvalidEsCalendarIntervalError; InvalidEsIntervalFormatError: typeof InvalidEsIntervalFormatError; + Ipv4Address: typeof Ipv4Address; isDateHistogramBucketAggConfig: typeof isDateHistogramBucketAggConfig; isNumberType: (agg: import("./search").AggConfig) => boolean; isStringType: (agg: import("./search").AggConfig) => boolean; diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor._constructor_.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor._constructor_.md index 6eabefb9eb912..6f5dd1076fb40 100644 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor._constructor_.md +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor._constructor_.md @@ -9,14 +9,13 @@ This class should be instantiated with a `requestTimeout` corresponding with how Signature: ```typescript -constructor(toasts: ToastsStart, application: ApplicationStart, requestTimeout?: number | undefined); +constructor(deps: SearchInterceptorDeps, requestTimeout?: number | undefined); ``` ## Parameters | Parameter | Type | Description | | --- | --- | --- | -| toasts | ToastsStart | | -| application | ApplicationStart | | +| deps | SearchInterceptorDeps | | | requestTimeout | number | undefined | | diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.application.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.application.md deleted file mode 100644 index e44910161aa60..0000000000000 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.application.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [SearchInterceptor](./kibana-plugin-plugins-data-public.searchinterceptor.md) > [application](./kibana-plugin-plugins-data-public.searchinterceptor.application.md) - -## SearchInterceptor.application property - -Signature: - -```typescript -protected readonly application: ApplicationStart; -``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.deps.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.deps.md new file mode 100644 index 0000000000000..b517fb036798a --- /dev/null +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.deps.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [SearchInterceptor](./kibana-plugin-plugins-data-public.searchinterceptor.md) > [deps](./kibana-plugin-plugins-data-public.searchinterceptor.deps.md) + +## SearchInterceptor.deps property + +Signature: + +```typescript +protected readonly deps: SearchInterceptorDeps; +``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.getpendingcount_.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.getpendingcount_.md index 59b107c92424f..db2c5d6957ad7 100644 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.getpendingcount_.md +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.getpendingcount_.md @@ -9,5 +9,5 @@ Returns an `Observable` over the current number of pending searches. This could Signature: ```typescript -getPendingCount$: () => import("rxjs").Observable; +getPendingCount$: () => Observable; ``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.md index 0c7b123be72af..4d2fac0287035 100644 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.md +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.md @@ -14,20 +14,28 @@ export declare class SearchInterceptor | Constructor | Modifiers | Description | | --- | --- | --- | -| [(constructor)(toasts, application, requestTimeout)](./kibana-plugin-plugins-data-public.searchinterceptor._constructor_.md) | | This class should be instantiated with a requestTimeout corresponding with how many ms after requests are initiated that they should automatically cancel. | +| [(constructor)(deps, requestTimeout)](./kibana-plugin-plugins-data-public.searchinterceptor._constructor_.md) | | This class should be instantiated with a requestTimeout corresponding with how many ms after requests are initiated that they should automatically cancel. | ## Properties | Property | Modifiers | Type | Description | | --- | --- | --- | --- | | [abortController](./kibana-plugin-plugins-data-public.searchinterceptor.abortcontroller.md) | | AbortController | abortController used to signal all searches to abort. | -| [application](./kibana-plugin-plugins-data-public.searchinterceptor.application.md) | | ApplicationStart | | -| [getPendingCount$](./kibana-plugin-plugins-data-public.searchinterceptor.getpendingcount_.md) | | () => import("rxjs").Observable<number> | Returns an Observable over the current number of pending searches. This could mean that one of the search requests is still in flight, or that it has only received partial responses. | +| [deps](./kibana-plugin-plugins-data-public.searchinterceptor.deps.md) | | SearchInterceptorDeps | | +| [getPendingCount$](./kibana-plugin-plugins-data-public.searchinterceptor.getpendingcount_.md) | | () => Observable<number> | Returns an Observable over the current number of pending searches. This could mean that one of the search requests is still in flight, or that it has only received partial responses. | | [hideToast](./kibana-plugin-plugins-data-public.searchinterceptor.hidetoast.md) | | () => void | | | [longRunningToast](./kibana-plugin-plugins-data-public.searchinterceptor.longrunningtoast.md) | | Toast | The current long-running toast (if there is one). | +| [pendingCount](./kibana-plugin-plugins-data-public.searchinterceptor.pendingcount.md) | | number | The number of pending search requests. | +| [pendingCount$](./kibana-plugin-plugins-data-public.searchinterceptor.pendingcount_.md) | | BehaviorSubject<number> | Observable that emits when the number of pending requests changes. | | [requestTimeout](./kibana-plugin-plugins-data-public.searchinterceptor.requesttimeout.md) | | number | undefined | | -| [search](./kibana-plugin-plugins-data-public.searchinterceptor.search.md) | | (search: ISearchGeneric, request: IKibanaSearchRequest, options?: ISearchOptions | undefined) => import("rxjs").Observable<import("../../common/search").IEsSearchResponse<unknown>> | Searches using the given search method. Overrides the AbortSignal with one that will abort either when cancelPending is called, when the request times out, or when the original AbortSignal is aborted. Updates the pendingCount when the request is started/finalized. | | [showToast](./kibana-plugin-plugins-data-public.searchinterceptor.showtoast.md) | | () => void | | -| [timeoutSubscriptions](./kibana-plugin-plugins-data-public.searchinterceptor.timeoutsubscriptions.md) | | Set<Subscription> | The subscriptions from scheduling the automatic timeout for each request. | -| [toasts](./kibana-plugin-plugins-data-public.searchinterceptor.toasts.md) | | ToastsStart | | +| [timeoutSubscriptions](./kibana-plugin-plugins-data-public.searchinterceptor.timeoutsubscriptions.md) | | Subscription | The subscriptions from scheduling the automatic timeout for each request. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [runSearch(request, combinedSignal)](./kibana-plugin-plugins-data-public.searchinterceptor.runsearch.md) | | | +| [search(request, options)](./kibana-plugin-plugins-data-public.searchinterceptor.search.md) | | Searches using the given search method. Overrides the AbortSignal with one that will abort either when cancelPending is called, when the request times out, or when the original AbortSignal is aborted. Updates the pendingCount when the request is started/finalized. | +| [setupTimers(options)](./kibana-plugin-plugins-data-public.searchinterceptor.setuptimers.md) | | | diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.pendingcount.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.pendingcount.md new file mode 100644 index 0000000000000..7dd2bd3e6703f --- /dev/null +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.pendingcount.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [SearchInterceptor](./kibana-plugin-plugins-data-public.searchinterceptor.md) > [pendingCount](./kibana-plugin-plugins-data-public.searchinterceptor.pendingcount.md) + +## SearchInterceptor.pendingCount property + +The number of pending search requests. + +Signature: + +```typescript +protected pendingCount: number; +``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.pendingcount_.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.pendingcount_.md new file mode 100644 index 0000000000000..dad0fca0bfe08 --- /dev/null +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.pendingcount_.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [SearchInterceptor](./kibana-plugin-plugins-data-public.searchinterceptor.md) > [pendingCount$](./kibana-plugin-plugins-data-public.searchinterceptor.pendingcount_.md) + +## SearchInterceptor.pendingCount$ property + +Observable that emits when the number of pending requests changes. + +Signature: + +```typescript +protected pendingCount$: BehaviorSubject; +``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.runsearch.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.runsearch.md new file mode 100644 index 0000000000000..385d4f6a238d4 --- /dev/null +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.runsearch.md @@ -0,0 +1,23 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [SearchInterceptor](./kibana-plugin-plugins-data-public.searchinterceptor.md) > [runSearch](./kibana-plugin-plugins-data-public.searchinterceptor.runsearch.md) + +## SearchInterceptor.runSearch() method + +Signature: + +```typescript +protected runSearch(request: IEsSearchRequest, combinedSignal: AbortSignal): Observable; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| request | IEsSearchRequest | | +| combinedSignal | AbortSignal | | + +Returns: + +`Observable` + diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.search.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.search.md index 80c98ab84fb40..38ddda7b4e184 100644 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.search.md +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.search.md @@ -2,12 +2,24 @@ [Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [SearchInterceptor](./kibana-plugin-plugins-data-public.searchinterceptor.md) > [search](./kibana-plugin-plugins-data-public.searchinterceptor.search.md) -## SearchInterceptor.search property +## SearchInterceptor.search() method Searches using the given `search` method. Overrides the `AbortSignal` with one that will abort either when `cancelPending` is called, when the request times out, or when the original `AbortSignal` is aborted. Updates the `pendingCount` when the request is started/finalized. Signature: ```typescript -search: (search: ISearchGeneric, request: IKibanaSearchRequest, options?: ISearchOptions | undefined) => import("rxjs").Observable>; +search(request: IEsSearchRequest, options?: ISearchOptions): Observable; ``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| request | IEsSearchRequest | | +| options | ISearchOptions | | + +Returns: + +`Observable` + diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.setuptimers.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.setuptimers.md new file mode 100644 index 0000000000000..fe35655258b4c --- /dev/null +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.setuptimers.md @@ -0,0 +1,28 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [SearchInterceptor](./kibana-plugin-plugins-data-public.searchinterceptor.md) > [setupTimers](./kibana-plugin-plugins-data-public.searchinterceptor.setuptimers.md) + +## SearchInterceptor.setupTimers() method + +Signature: + +```typescript +protected setupTimers(options?: ISearchOptions): { + combinedSignal: AbortSignal; + cleanup: () => void; + }; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| options | ISearchOptions | | + +Returns: + +`{ + combinedSignal: AbortSignal; + cleanup: () => void; + }` + diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.timeoutsubscriptions.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.timeoutsubscriptions.md index 072f67591f097..12f200e037784 100644 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.timeoutsubscriptions.md +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.timeoutsubscriptions.md @@ -9,5 +9,5 @@ The subscriptions from scheduling the automatic timeout for each request. Signature: ```typescript -protected timeoutSubscriptions: Set; +protected timeoutSubscriptions: Subscription; ``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.toasts.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.toasts.md deleted file mode 100644 index 4953d17c89c39..0000000000000 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptor.toasts.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [SearchInterceptor](./kibana-plugin-plugins-data-public.searchinterceptor.md) > [toasts](./kibana-plugin-plugins-data-public.searchinterceptor.toasts.md) - -## SearchInterceptor.toasts property - -Signature: - -```typescript -protected readonly toasts: ToastsStart; -``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptordeps.application.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptordeps.application.md new file mode 100644 index 0000000000000..a8cd1b170a595 --- /dev/null +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptordeps.application.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [SearchInterceptorDeps](./kibana-plugin-plugins-data-public.searchinterceptordeps.md) > [application](./kibana-plugin-plugins-data-public.searchinterceptordeps.application.md) + +## SearchInterceptorDeps.application property + +Signature: + +```typescript +application: ApplicationStart; +``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptordeps.http.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptordeps.http.md new file mode 100644 index 0000000000000..1146179c13d63 --- /dev/null +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptordeps.http.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [SearchInterceptorDeps](./kibana-plugin-plugins-data-public.searchinterceptordeps.md) > [http](./kibana-plugin-plugins-data-public.searchinterceptordeps.http.md) + +## SearchInterceptorDeps.http property + +Signature: + +```typescript +http: CoreStart['http']; +``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptordeps.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptordeps.md new file mode 100644 index 0000000000000..1291af5359887 --- /dev/null +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptordeps.md @@ -0,0 +1,22 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [SearchInterceptorDeps](./kibana-plugin-plugins-data-public.searchinterceptordeps.md) + +## SearchInterceptorDeps interface + +Signature: + +```typescript +export interface SearchInterceptorDeps +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [application](./kibana-plugin-plugins-data-public.searchinterceptordeps.application.md) | ApplicationStart | | +| [http](./kibana-plugin-plugins-data-public.searchinterceptordeps.http.md) | CoreStart['http'] | | +| [toasts](./kibana-plugin-plugins-data-public.searchinterceptordeps.toasts.md) | ToastsStart | | +| [uiSettings](./kibana-plugin-plugins-data-public.searchinterceptordeps.uisettings.md) | CoreStart['uiSettings'] | | +| [usageCollector](./kibana-plugin-plugins-data-public.searchinterceptordeps.usagecollector.md) | SearchUsageCollector | | + diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptordeps.toasts.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptordeps.toasts.md new file mode 100644 index 0000000000000..0023b34af10c3 --- /dev/null +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptordeps.toasts.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [SearchInterceptorDeps](./kibana-plugin-plugins-data-public.searchinterceptordeps.md) > [toasts](./kibana-plugin-plugins-data-public.searchinterceptordeps.toasts.md) + +## SearchInterceptorDeps.toasts property + +Signature: + +```typescript +toasts: ToastsStart; +``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptordeps.uisettings.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptordeps.uisettings.md new file mode 100644 index 0000000000000..425e177ec9300 --- /dev/null +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptordeps.uisettings.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [SearchInterceptorDeps](./kibana-plugin-plugins-data-public.searchinterceptordeps.md) > [uiSettings](./kibana-plugin-plugins-data-public.searchinterceptordeps.uisettings.md) + +## SearchInterceptorDeps.uiSettings property + +Signature: + +```typescript +uiSettings: CoreStart['uiSettings']; +``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptordeps.usagecollector.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptordeps.usagecollector.md new file mode 100644 index 0000000000000..21afce1927676 --- /dev/null +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.searchinterceptordeps.usagecollector.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [SearchInterceptorDeps](./kibana-plugin-plugins-data-public.searchinterceptordeps.md) > [usageCollector](./kibana-plugin-plugins-data-public.searchinterceptordeps.usagecollector.md) + +## SearchInterceptorDeps.usageCollector property + +Signature: + +```typescript +usageCollector?: SearchUsageCollector; +``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.sync_search_strategy.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.sync_search_strategy.md deleted file mode 100644 index 3681fe6d6274c..0000000000000 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.sync_search_strategy.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) > [SYNC\_SEARCH\_STRATEGY](./kibana-plugin-plugins-data-public.sync_search_strategy.md) - -## SYNC\_SEARCH\_STRATEGY variable - -Signature: - -```typescript -SYNC_SEARCH_STRATEGY = "SYNC_SEARCH_STRATEGY" -``` diff --git a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.ui_settings.md b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.ui_settings.md index a48f4920b3d26..e515c3513df6c 100644 --- a/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.ui_settings.md +++ b/docs/development/plugins/data/public/kibana-plugin-plugins-data-public.ui_settings.md @@ -8,32 +8,33 @@ ```typescript UI_SETTINGS: { - META_FIELDS: string; - DOC_HIGHLIGHT: string; - QUERY_STRING_OPTIONS: string; - QUERY_ALLOW_LEADING_WILDCARDS: string; - SEARCH_QUERY_LANGUAGE: string; - SORT_OPTIONS: string; - COURIER_IGNORE_FILTER_IF_FIELD_NOT_IN_INDEX: string; - COURIER_SET_REQUEST_PREFERENCE: string; - COURIER_CUSTOM_REQUEST_PREFERENCE: string; - COURIER_MAX_CONCURRENT_SHARD_REQUESTS: string; - COURIER_BATCH_SEARCHES: string; - SEARCH_INCLUDE_FROZEN: string; - HISTOGRAM_BAR_TARGET: string; - HISTOGRAM_MAX_BARS: string; - HISTORY_LIMIT: string; - SHORT_DOTS_ENABLE: string; - FORMAT_DEFAULT_TYPE_MAP: string; - FORMAT_NUMBER_DEFAULT_PATTERN: string; - FORMAT_PERCENT_DEFAULT_PATTERN: string; - FORMAT_BYTES_DEFAULT_PATTERN: string; - FORMAT_CURRENCY_DEFAULT_PATTERN: string; - FORMAT_NUMBER_DEFAULT_LOCALE: string; - TIMEPICKER_REFRESH_INTERVAL_DEFAULTS: string; - TIMEPICKER_QUICK_RANGES: string; - INDEXPATTERN_PLACEHOLDER: string; - FILTERS_PINNED_BY_DEFAULT: string; - FILTERS_EDITOR_SUGGEST_VALUES: string; + readonly META_FIELDS: "metaFields"; + readonly DOC_HIGHLIGHT: "doc_table:highlight"; + readonly QUERY_STRING_OPTIONS: "query:queryString:options"; + readonly QUERY_ALLOW_LEADING_WILDCARDS: "query:allowLeadingWildcards"; + readonly SEARCH_QUERY_LANGUAGE: "search:queryLanguage"; + readonly SORT_OPTIONS: "sort:options"; + readonly COURIER_IGNORE_FILTER_IF_FIELD_NOT_IN_INDEX: "courier:ignoreFilterIfFieldNotInIndex"; + readonly COURIER_SET_REQUEST_PREFERENCE: "courier:setRequestPreference"; + readonly COURIER_CUSTOM_REQUEST_PREFERENCE: "courier:customRequestPreference"; + readonly COURIER_MAX_CONCURRENT_SHARD_REQUESTS: "courier:maxConcurrentShardRequests"; + readonly COURIER_BATCH_SEARCHES: "courier:batchSearches"; + readonly SEARCH_INCLUDE_FROZEN: "search:includeFrozen"; + readonly HISTOGRAM_BAR_TARGET: "histogram:barTarget"; + readonly HISTOGRAM_MAX_BARS: "histogram:maxBars"; + readonly HISTORY_LIMIT: "history:limit"; + readonly SHORT_DOTS_ENABLE: "shortDots:enable"; + readonly FORMAT_DEFAULT_TYPE_MAP: "format:defaultTypeMap"; + readonly FORMAT_NUMBER_DEFAULT_PATTERN: "format:number:defaultPattern"; + readonly FORMAT_PERCENT_DEFAULT_PATTERN: "format:percent:defaultPattern"; + readonly FORMAT_BYTES_DEFAULT_PATTERN: "format:bytes:defaultPattern"; + readonly FORMAT_CURRENCY_DEFAULT_PATTERN: "format:currency:defaultPattern"; + readonly FORMAT_NUMBER_DEFAULT_LOCALE: "format:number:defaultLocale"; + readonly TIMEPICKER_REFRESH_INTERVAL_DEFAULTS: "timepicker:refreshIntervalDefaults"; + readonly TIMEPICKER_QUICK_RANGES: "timepicker:quickRanges"; + readonly TIMEPICKER_TIME_DEFAULTS: "timepicker:timeDefaults"; + readonly INDEXPATTERN_PLACEHOLDER: "indexPattern:placeholder"; + readonly FILTERS_PINNED_BY_DEFAULT: "filters:pinnedByDefault"; + readonly FILTERS_EDITOR_SUGGEST_VALUES: "filterEditor:suggestValues"; } ``` diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.esaggsexpressionfunctiondefinition.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.esaggsexpressionfunctiondefinition.md new file mode 100644 index 0000000000000..572c4e0c1eb2f --- /dev/null +++ b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.esaggsexpressionfunctiondefinition.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-server](./kibana-plugin-plugins-data-server.md) > [EsaggsExpressionFunctionDefinition](./kibana-plugin-plugins-data-server.esaggsexpressionfunctiondefinition.md) + +## EsaggsExpressionFunctionDefinition type + +Signature: + +```typescript +export declare type EsaggsExpressionFunctionDefinition = ExpressionFunctionDefinition<'esaggs', Input, Arguments, Output>; +``` diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.fieldformats.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.fieldformats.md index 45fc1a608e8ca..0dddc65f4db92 100644 --- a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.fieldformats.md +++ b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.fieldformats.md @@ -13,7 +13,6 @@ fieldFormats: { BoolFormat: typeof BoolFormat; BytesFormat: typeof BytesFormat; ColorFormat: typeof ColorFormat; - DateNanosFormat: typeof DateNanosFormat; DurationFormat: typeof DurationFormat; IpFormat: typeof IpFormat; NumberFormat: typeof NumberFormat; diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.irequesttypesmap.es.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.irequesttypesmap.es.md deleted file mode 100644 index 9cebff05dc9db..0000000000000 --- a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.irequesttypesmap.es.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-server](./kibana-plugin-plugins-data-server.md) > [IRequestTypesMap](./kibana-plugin-plugins-data-server.irequesttypesmap.md) > [es](./kibana-plugin-plugins-data-server.irequesttypesmap.es.md) - -## IRequestTypesMap.es property - -Signature: - -```typescript -[ES_SEARCH_STRATEGY]: IEsSearchRequest; -``` diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.irequesttypesmap.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.irequesttypesmap.md deleted file mode 100644 index 3f5e4ba0f7799..0000000000000 --- a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.irequesttypesmap.md +++ /dev/null @@ -1,20 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-server](./kibana-plugin-plugins-data-server.md) > [IRequestTypesMap](./kibana-plugin-plugins-data-server.irequesttypesmap.md) - -## IRequestTypesMap interface - -The map of search strategy IDs to the corresponding request type definitions. - -Signature: - -```typescript -export interface IRequestTypesMap -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [es](./kibana-plugin-plugins-data-server.irequesttypesmap.es.md) | IEsSearchRequest | | - diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.iresponsetypesmap.es.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.iresponsetypesmap.es.md deleted file mode 100644 index 1154fc141d6c7..0000000000000 --- a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.iresponsetypesmap.es.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-server](./kibana-plugin-plugins-data-server.md) > [IResponseTypesMap](./kibana-plugin-plugins-data-server.iresponsetypesmap.md) > [es](./kibana-plugin-plugins-data-server.iresponsetypesmap.es.md) - -## IResponseTypesMap.es property - -Signature: - -```typescript -[ES_SEARCH_STRATEGY]: IEsSearchResponse; -``` diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.iresponsetypesmap.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.iresponsetypesmap.md deleted file mode 100644 index 629ab4347eda8..0000000000000 --- a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.iresponsetypesmap.md +++ /dev/null @@ -1,20 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-server](./kibana-plugin-plugins-data-server.md) > [IResponseTypesMap](./kibana-plugin-plugins-data-server.iresponsetypesmap.md) - -## IResponseTypesMap interface - -The map of search strategy IDs to the corresponding response type definitions. - -Signature: - -```typescript -export interface IResponseTypesMap -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [es](./kibana-plugin-plugins-data-server.iresponsetypesmap.es.md) | IEsSearchResponse | | - diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearch.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearch.md deleted file mode 100644 index 96991579c1716..0000000000000 --- a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearch.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-server](./kibana-plugin-plugins-data-server.md) > [ISearch](./kibana-plugin-plugins-data-server.isearch.md) - -## ISearch type - -Signature: - -```typescript -export declare type ISearch = (context: RequestHandlerContext, request: IRequestTypesMap[T], options?: ISearchOptions) => Promise; -``` diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchcancel.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchcancel.md deleted file mode 100644 index b5a687d1b19d8..0000000000000 --- a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchcancel.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-server](./kibana-plugin-plugins-data-server.md) > [ISearchCancel](./kibana-plugin-plugins-data-server.isearchcancel.md) - -## ISearchCancel type - -Signature: - -```typescript -export declare type ISearchCancel = (context: RequestHandlerContext, id: string) => Promise; -``` diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchoptions.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchoptions.md index 49412fc42d3b5..002ce864a1aa4 100644 --- a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchoptions.md +++ b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchoptions.md @@ -15,4 +15,5 @@ export interface ISearchOptions | Property | Type | Description | | --- | --- | --- | | [signal](./kibana-plugin-plugins-data-server.isearchoptions.signal.md) | AbortSignal | An AbortSignal that allows the caller of search to abort a search request. | +| [strategy](./kibana-plugin-plugins-data-server.isearchoptions.strategy.md) | string | | diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchoptions.strategy.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchoptions.strategy.md new file mode 100644 index 0000000000000..6df72d023e2c0 --- /dev/null +++ b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchoptions.strategy.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-server](./kibana-plugin-plugins-data-server.md) > [ISearchOptions](./kibana-plugin-plugins-data-server.isearchoptions.md) > [strategy](./kibana-plugin-plugins-data-server.isearchoptions.strategy.md) + +## ISearchOptions.strategy property + +Signature: + +```typescript +strategy?: string; +``` diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchsetup.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchsetup.md index 93e253b2e98a3..3afba80064f08 100644 --- a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchsetup.md +++ b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchsetup.md @@ -15,4 +15,5 @@ export interface ISearchSetup | Property | Type | Description | | --- | --- | --- | | [registerSearchStrategy](./kibana-plugin-plugins-data-server.isearchsetup.registersearchstrategy.md) | TRegisterSearchStrategy | Extension point exposed for other plugins to register their own search strategies. | +| [usage](./kibana-plugin-plugins-data-server.isearchsetup.usage.md) | SearchUsage | Used internally for telemetry | diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchsetup.registersearchstrategy.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchsetup.registersearchstrategy.md index c06b8b00806bf..73c575e7095ed 100644 --- a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchsetup.registersearchstrategy.md +++ b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchsetup.registersearchstrategy.md @@ -9,5 +9,5 @@ Extension point exposed for other plugins to register their own search strategie Signature: ```typescript -registerSearchStrategy: TRegisterSearchStrategy; +registerSearchStrategy: (name: string, strategy: ISearchStrategy) => void; ``` diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchsetup.usage.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchsetup.usage.md new file mode 100644 index 0000000000000..85abd9d9dba98 --- /dev/null +++ b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchsetup.usage.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-server](./kibana-plugin-plugins-data-server.md) > [ISearchSetup](./kibana-plugin-plugins-data-server.isearchsetup.md) > [usage](./kibana-plugin-plugins-data-server.isearchsetup.usage.md) + +## ISearchSetup.usage property + +Used internally for telemetry + +Signature: + +```typescript +usage: SearchUsage; +``` diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstart.getsearchstrategy.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstart.getsearchstrategy.md index 0ba4bf578d6cc..970b2811a574b 100644 --- a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstart.getsearchstrategy.md +++ b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstart.getsearchstrategy.md @@ -9,5 +9,5 @@ Get other registered search strategies. For example, if a new strategy needs to Signature: ```typescript -getSearchStrategy: TGetSearchStrategy; +getSearchStrategy: (name: string) => ISearchStrategy; ``` diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstart.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstart.md index abe72396f61e1..308ce3cb568bc 100644 --- a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstart.md +++ b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstart.md @@ -14,5 +14,6 @@ export interface ISearchStart | Property | Type | Description | | --- | --- | --- | -| [getSearchStrategy](./kibana-plugin-plugins-data-server.isearchstart.getsearchstrategy.md) | TGetSearchStrategy | Get other registered search strategies. For example, if a new strategy needs to use the already-registered ES search strategy, it can use this function to accomplish that. | +| [getSearchStrategy](./kibana-plugin-plugins-data-server.isearchstart.getsearchstrategy.md) | (name: string) => ISearchStrategy | Get other registered search strategies. For example, if a new strategy needs to use the already-registered ES search strategy, it can use this function to accomplish that. | +| [search](./kibana-plugin-plugins-data-server.isearchstart.search.md) | (context: RequestHandlerContext, request: IKibanaSearchRequest, options: ISearchOptions) => Promise<IKibanaSearchResponse> | | diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstart.search.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstart.search.md new file mode 100644 index 0000000000000..1c2ae91699559 --- /dev/null +++ b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstart.search.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-plugins-data-server](./kibana-plugin-plugins-data-server.md) > [ISearchStart](./kibana-plugin-plugins-data-server.isearchstart.md) > [search](./kibana-plugin-plugins-data-server.isearchstart.search.md) + +## ISearchStart.search property + +Signature: + +```typescript +search: (context: RequestHandlerContext, request: IKibanaSearchRequest, options: ISearchOptions) => Promise; +``` diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstrategy.cancel.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstrategy.cancel.md index c1e0c3d9f2330..34903697090ea 100644 --- a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstrategy.cancel.md +++ b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstrategy.cancel.md @@ -7,5 +7,5 @@ Signature: ```typescript -cancel?: ISearchCancel; +cancel?: (context: RequestHandlerContext, id: string) => Promise; ``` diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstrategy.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstrategy.md index 167c6ab6e5a16..d54e027c4b847 100644 --- a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstrategy.md +++ b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstrategy.md @@ -9,13 +9,13 @@ Search strategy interface contains a search method that takes in a request and r Signature: ```typescript -export interface ISearchStrategy +export interface ISearchStrategy ``` ## Properties | Property | Type | Description | | --- | --- | --- | -| [cancel](./kibana-plugin-plugins-data-server.isearchstrategy.cancel.md) | ISearchCancel<T> | | -| [search](./kibana-plugin-plugins-data-server.isearchstrategy.search.md) | ISearch<T> | | +| [cancel](./kibana-plugin-plugins-data-server.isearchstrategy.cancel.md) | (context: RequestHandlerContext, id: string) => Promise<void> | | +| [search](./kibana-plugin-plugins-data-server.isearchstrategy.search.md) | (context: RequestHandlerContext, request: IEsSearchRequest, options?: ISearchOptions) => Promise<IEsSearchResponse> | | diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstrategy.search.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstrategy.search.md index 34a17ca87807a..1a225d0c9aeab 100644 --- a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstrategy.search.md +++ b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchstrategy.search.md @@ -7,5 +7,5 @@ Signature: ```typescript -search: ISearch; +search: (context: RequestHandlerContext, request: IEsSearchRequest, options?: ISearchOptions) => Promise; ``` diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.md index c80112fb17dde..6bf481841f334 100644 --- a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.md +++ b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.md @@ -40,8 +40,6 @@ | [IIndexPattern](./kibana-plugin-plugins-data-server.iindexpattern.md) | | | [IndexPatternAttributes](./kibana-plugin-plugins-data-server.indexpatternattributes.md) | Use data plugin interface instead | | [IndexPatternFieldDescriptor](./kibana-plugin-plugins-data-server.indexpatternfielddescriptor.md) | | -| [IRequestTypesMap](./kibana-plugin-plugins-data-server.irequesttypesmap.md) | The map of search strategy IDs to the corresponding request type definitions. | -| [IResponseTypesMap](./kibana-plugin-plugins-data-server.iresponsetypesmap.md) | The map of search strategy IDs to the corresponding response type definitions. | | [ISearchOptions](./kibana-plugin-plugins-data-server.isearchoptions.md) | | | [ISearchSetup](./kibana-plugin-plugins-data-server.isearchsetup.md) | | | [ISearchStart](./kibana-plugin-plugins-data-server.isearchstart.md) | | @@ -71,10 +69,8 @@ | Type Alias | Description | | --- | --- | +| [EsaggsExpressionFunctionDefinition](./kibana-plugin-plugins-data-server.esaggsexpressionfunctiondefinition.md) | | | [FieldFormatsGetConfigFn](./kibana-plugin-plugins-data-server.fieldformatsgetconfigfn.md) | | | [IFieldFormatsRegistry](./kibana-plugin-plugins-data-server.ifieldformatsregistry.md) | | -| [ISearch](./kibana-plugin-plugins-data-server.isearch.md) | | -| [ISearchCancel](./kibana-plugin-plugins-data-server.isearchcancel.md) | | | [ParsedInterval](./kibana-plugin-plugins-data-server.parsedinterval.md) | | -| [TStrategyTypes](./kibana-plugin-plugins-data-server.tstrategytypes.md) | Contains all known strategy type identifiers that will be used to map to request and response shapes. Plugins that wish to add their own custom search strategies should extend this type via:const MY\_STRATEGY = 'MY\_STRATEGY';declare module 'src/plugins/search/server' { export interface IRequestTypesMap { \[MY\_STRATEGY\]: IMySearchRequest; }export interface IResponseTypesMap { \[MY\_STRATEGY\]: IMySearchResponse } } | diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.search.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.search.md index 6020498fdcb6d..09563358100b3 100644 --- a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.search.md +++ b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.search.md @@ -12,6 +12,7 @@ search: { dateHistogramInterval: typeof dateHistogramInterval; InvalidEsCalendarIntervalError: typeof InvalidEsCalendarIntervalError; InvalidEsIntervalFormatError: typeof InvalidEsIntervalFormatError; + Ipv4Address: typeof Ipv4Address; isValidEsInterval: typeof isValidEsInterval; isValidInterval: typeof isValidInterval; parseEsInterval: typeof parseEsInterval; diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.tstrategytypes.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.tstrategytypes.md deleted file mode 100644 index 443d8d1b424d0..0000000000000 --- a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.tstrategytypes.md +++ /dev/null @@ -1,19 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-plugins-data-server](./kibana-plugin-plugins-data-server.md) > [TStrategyTypes](./kibana-plugin-plugins-data-server.tstrategytypes.md) - -## TStrategyTypes type - -Contains all known strategy type identifiers that will be used to map to request and response shapes. Plugins that wish to add their own custom search strategies should extend this type via: - -const MY\_STRATEGY = 'MY\_STRATEGY'; - -declare module 'src/plugins/search/server' { export interface IRequestTypesMap { \[MY\_STRATEGY\]: IMySearchRequest; } - -export interface IResponseTypesMap { \[MY\_STRATEGY\]: IMySearchResponse } } - -Signature: - -```typescript -export declare type TStrategyTypes = typeof ES_SEARCH_STRATEGY | string; -``` diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.ui_settings.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.ui_settings.md index 855cfd11d00ea..e419b64cd43aa 100644 --- a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.ui_settings.md +++ b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.ui_settings.md @@ -8,32 +8,33 @@ ```typescript UI_SETTINGS: { - META_FIELDS: string; - DOC_HIGHLIGHT: string; - QUERY_STRING_OPTIONS: string; - QUERY_ALLOW_LEADING_WILDCARDS: string; - SEARCH_QUERY_LANGUAGE: string; - SORT_OPTIONS: string; - COURIER_IGNORE_FILTER_IF_FIELD_NOT_IN_INDEX: string; - COURIER_SET_REQUEST_PREFERENCE: string; - COURIER_CUSTOM_REQUEST_PREFERENCE: string; - COURIER_MAX_CONCURRENT_SHARD_REQUESTS: string; - COURIER_BATCH_SEARCHES: string; - SEARCH_INCLUDE_FROZEN: string; - HISTOGRAM_BAR_TARGET: string; - HISTOGRAM_MAX_BARS: string; - HISTORY_LIMIT: string; - SHORT_DOTS_ENABLE: string; - FORMAT_DEFAULT_TYPE_MAP: string; - FORMAT_NUMBER_DEFAULT_PATTERN: string; - FORMAT_PERCENT_DEFAULT_PATTERN: string; - FORMAT_BYTES_DEFAULT_PATTERN: string; - FORMAT_CURRENCY_DEFAULT_PATTERN: string; - FORMAT_NUMBER_DEFAULT_LOCALE: string; - TIMEPICKER_REFRESH_INTERVAL_DEFAULTS: string; - TIMEPICKER_QUICK_RANGES: string; - INDEXPATTERN_PLACEHOLDER: string; - FILTERS_PINNED_BY_DEFAULT: string; - FILTERS_EDITOR_SUGGEST_VALUES: string; + readonly META_FIELDS: "metaFields"; + readonly DOC_HIGHLIGHT: "doc_table:highlight"; + readonly QUERY_STRING_OPTIONS: "query:queryString:options"; + readonly QUERY_ALLOW_LEADING_WILDCARDS: "query:allowLeadingWildcards"; + readonly SEARCH_QUERY_LANGUAGE: "search:queryLanguage"; + readonly SORT_OPTIONS: "sort:options"; + readonly COURIER_IGNORE_FILTER_IF_FIELD_NOT_IN_INDEX: "courier:ignoreFilterIfFieldNotInIndex"; + readonly COURIER_SET_REQUEST_PREFERENCE: "courier:setRequestPreference"; + readonly COURIER_CUSTOM_REQUEST_PREFERENCE: "courier:customRequestPreference"; + readonly COURIER_MAX_CONCURRENT_SHARD_REQUESTS: "courier:maxConcurrentShardRequests"; + readonly COURIER_BATCH_SEARCHES: "courier:batchSearches"; + readonly SEARCH_INCLUDE_FROZEN: "search:includeFrozen"; + readonly HISTOGRAM_BAR_TARGET: "histogram:barTarget"; + readonly HISTOGRAM_MAX_BARS: "histogram:maxBars"; + readonly HISTORY_LIMIT: "history:limit"; + readonly SHORT_DOTS_ENABLE: "shortDots:enable"; + readonly FORMAT_DEFAULT_TYPE_MAP: "format:defaultTypeMap"; + readonly FORMAT_NUMBER_DEFAULT_PATTERN: "format:number:defaultPattern"; + readonly FORMAT_PERCENT_DEFAULT_PATTERN: "format:percent:defaultPattern"; + readonly FORMAT_BYTES_DEFAULT_PATTERN: "format:bytes:defaultPattern"; + readonly FORMAT_CURRENCY_DEFAULT_PATTERN: "format:currency:defaultPattern"; + readonly FORMAT_NUMBER_DEFAULT_LOCALE: "format:number:defaultLocale"; + readonly TIMEPICKER_REFRESH_INTERVAL_DEFAULTS: "timepicker:refreshIntervalDefaults"; + readonly TIMEPICKER_QUICK_RANGES: "timepicker:quickRanges"; + readonly TIMEPICKER_TIME_DEFAULTS: "timepicker:timeDefaults"; + readonly INDEXPATTERN_PLACEHOLDER: "indexPattern:placeholder"; + readonly FILTERS_PINNED_BY_DEFAULT: "filters:pinnedByDefault"; + readonly FILTERS_EDITOR_SUGGEST_VALUES: "filterEditor:suggestValues"; } ``` diff --git a/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.comparator.md b/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.comparator.md index 12af33756fb19..f429866848aa4 100644 --- a/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.comparator.md +++ b/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.comparator.md @@ -4,7 +4,7 @@ ## Comparator type -Used to compare state. see [useContainerSelector](./kibana-plugin-plugins-kibana_utils-common-state_containers.usecontainerselector.md) +Used to compare state, see [useContainerSelector](./kibana-plugin-plugins-kibana_utils-common-state_containers.usecontainerselector.md). Signature: diff --git a/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.connect.md b/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.connect.md index e05f1fb392fe6..ca68c47ddaa7e 100644 --- a/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.connect.md +++ b/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.connect.md @@ -4,7 +4,7 @@ ## Connect type -Similar to `connect` from react-redux, allows to map state from state container to component's props +Similar to `connect` from react-redux, allows to map state from state container to component's props. Signature: diff --git a/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_1.md b/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_1.md index 794bf63588312..8aadd0a234a8a 100644 --- a/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_1.md +++ b/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_1.md @@ -4,7 +4,7 @@ ## createStateContainer() function -Creates a state container with transitions, but without selectors +Creates a state container with transitions, but without selectors. Signature: diff --git a/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_2.md b/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_2.md index 1946baae202f1..bb06ca18e808a 100644 --- a/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_2.md +++ b/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_2.md @@ -4,7 +4,7 @@ ## createStateContainer() function -Creates a state container with transitions and selectors +Creates a state container with transitions and selectors. Signature: diff --git a/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontaineroptions.freeze.md b/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontaineroptions.freeze.md index 4f772c7c54d08..0b05775ad1458 100644 --- a/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontaineroptions.freeze.md +++ b/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontaineroptions.freeze.md @@ -4,7 +4,7 @@ ## CreateStateContainerOptions.freeze property -Function to use when freezing state. Supply identity function. If not provided, default deepFreeze is use. +Function to use when freezing state. Supply identity function. If not provided, default `deepFreeze` is used. Signature: diff --git a/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontaineroptions.md b/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontaineroptions.md index d328d306e93e1..8dba1b647edf4 100644 --- a/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontaineroptions.md +++ b/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontaineroptions.md @@ -16,5 +16,5 @@ export interface CreateStateContainerOptions | Property | Type | Description | | --- | --- | --- | -| [freeze](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontaineroptions.freeze.md) | <T>(state: T) => T | Function to use when freezing state. Supply identity function. If not provided, default deepFreeze is use. | +| [freeze](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontaineroptions.freeze.md) | <T>(state: T) => T | Function to use when freezing state. Supply identity function. If not provided, default deepFreeze is used. | diff --git a/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.md b/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.md index e74ff2c6885be..7cabb72cecb31 100644 --- a/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.md +++ b/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.md @@ -11,8 +11,8 @@ State containers are Redux-store-like objects meant to help you manage state in | Function | Description | | --- | --- | | [createStateContainer(defaultState)](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer.md) | Creates a state container without transitions and without selectors. | -| [createStateContainer(defaultState, pureTransitions)](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_1.md) | Creates a state container with transitions, but without selectors | -| [createStateContainer(defaultState, pureTransitions, pureSelectors, options)](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_2.md) | Creates a state container with transitions and selectors | +| [createStateContainer(defaultState, pureTransitions)](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_1.md) | Creates a state container with transitions, but without selectors. | +| [createStateContainer(defaultState, pureTransitions, pureSelectors, options)](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_2.md) | Creates a state container with transitions and selectors. | ## Interfaces @@ -20,8 +20,8 @@ State containers are Redux-store-like objects meant to help you manage state in | --- | --- | | [BaseStateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.md) | Base state container shape without transitions or selectors | | [CreateStateContainerOptions](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontaineroptions.md) | State container options | -| [ReduxLikeStateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.reduxlikestatecontainer.md) | Fully featured state container which matches Redux store interface. Extends [StateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.statecontainer.md) Allows to use state container with redux libraries | -| [StateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.statecontainer.md) | Fully featured state container with [Selectors](./kibana-plugin-plugins-kibana_utils-common-state_containers.selector.md) and . Extends [BaseStateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.md) | +| [ReduxLikeStateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.reduxlikestatecontainer.md) | Fully featured state container which matches Redux store interface. Extends [StateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.statecontainer.md). Allows to use state container with redux libraries. | +| [StateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.statecontainer.md) | Fully featured state container with [Selectors](./kibana-plugin-plugins-kibana_utils-common-state_containers.selector.md) and . Extends [BaseStateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.md). | ## Variables @@ -36,8 +36,8 @@ State containers are Redux-store-like objects meant to help you manage state in | Type Alias | Description | | --- | --- | | [BaseState](./kibana-plugin-plugins-kibana_utils-common-state_containers.basestate.md) | Base [StateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.statecontainer.md) state shape | -| [Comparator](./kibana-plugin-plugins-kibana_utils-common-state_containers.comparator.md) | Used to compare state. see [useContainerSelector](./kibana-plugin-plugins-kibana_utils-common-state_containers.usecontainerselector.md) | -| [Connect](./kibana-plugin-plugins-kibana_utils-common-state_containers.connect.md) | Similar to connect from react-redux, allows to map state from state container to component's props | +| [Comparator](./kibana-plugin-plugins-kibana_utils-common-state_containers.comparator.md) | Used to compare state, see [useContainerSelector](./kibana-plugin-plugins-kibana_utils-common-state_containers.usecontainerselector.md). | +| [Connect](./kibana-plugin-plugins-kibana_utils-common-state_containers.connect.md) | Similar to connect from react-redux, allows to map state from state container to component's props. | | [Dispatch](./kibana-plugin-plugins-kibana_utils-common-state_containers.dispatch.md) | Redux like dispatch | | [EnsurePureSelector](./kibana-plugin-plugins-kibana_utils-common-state_containers.ensurepureselector.md) | | | [EnsurePureTransition](./kibana-plugin-plugins-kibana_utils-common-state_containers.ensurepuretransition.md) | | diff --git a/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.reduxlikestatecontainer.md b/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.reduxlikestatecontainer.md index 0e08119c1eae4..1229f4c2998f8 100644 --- a/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.reduxlikestatecontainer.md +++ b/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.reduxlikestatecontainer.md @@ -4,7 +4,7 @@ ## ReduxLikeStateContainer interface -Fully featured state container which matches Redux store interface. Extends [StateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.statecontainer.md) Allows to use state container with redux libraries +Fully featured state container which matches Redux store interface. Extends [StateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.statecontainer.md). Allows to use state container with redux libraries. Signature: diff --git a/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.statecontainer.md b/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.statecontainer.md index 23ec1c8e5be01..5d47540c824b0 100644 --- a/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.statecontainer.md +++ b/docs/development/plugins/kibana_utils/common/state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.statecontainer.md @@ -4,7 +4,7 @@ ## StateContainer interface -Fully featured state container with [Selectors](./kibana-plugin-plugins-kibana_utils-common-state_containers.selector.md) and . Extends [BaseStateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.md) +Fully featured state container with [Selectors](./kibana-plugin-plugins-kibana_utils-common-state_containers.selector.md) and . Extends [BaseStateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.md). Signature: diff --git a/docs/development/plugins/kibana_utils/public/state_sync/index.md b/docs/development/plugins/kibana_utils/public/state_sync/index.md index 4b345d9130bd5..5625e4a4b5eb8 100644 --- a/docs/development/plugins/kibana_utils/public/state_sync/index.md +++ b/docs/development/plugins/kibana_utils/public/state_sync/index.md @@ -8,5 +8,5 @@ | Package | Description | | --- | --- | -| [kibana-plugin-plugins-kibana\_utils-public-state\_sync](./kibana-plugin-plugins-kibana_utils-public-state_sync.md) | State syncing utilities are a set of helpers for syncing your application state with URL or browser storage.They are designed to work together with state containers (). But state containers are not required.State syncing utilities include:- util which: - Subscribes to state changes and pushes them to state storage. - Optionally subscribes to state storage changes and pushes them to state. - Two types of storage compatible with syncState: - - Serializes state and persists it to URL's query param in rison or hashed format. Listens for state updates in the URL and pushes them back to state. - - Serializes state and persists it to browser storage.Refer [here](https://github.com/elastic/kibana/tree/master/src/plugins/kibana_utils/docs/state_sync) for a complete guide and examples | +| [kibana-plugin-plugins-kibana\_utils-public-state\_sync](./kibana-plugin-plugins-kibana_utils-public-state_sync.md) | State syncing utilities are a set of helpers for syncing your application state with browser URL or browser storage.They are designed to work together with [state containers](https://github.com/elastic/kibana/tree/master/src/plugins/kibana_utils/docs/state_containers). But state containers are not required.State syncing utilities include:\* util which: \* Subscribes to state changes and pushes them to state storage. \* Optionally subscribes to state storage changes and pushes them to state. \* Two types of storages compatible with syncState: \* - Serializes state and persists it to URL's query param in rison or hashed format. Listens for state updates in the URL and pushes them back to state. \* - Serializes state and persists it to browser storage.Refer [here](https://github.com/elastic/kibana/tree/master/src/plugins/kibana_utils/docs/state_sync) for a complete guide and examples. | diff --git a/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.ikbnurlstatestorage.flush.md b/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.ikbnurlstatestorage.flush.md index e0e6aa9be4368..dfeef1cdce22c 100644 --- a/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.ikbnurlstatestorage.flush.md +++ b/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.ikbnurlstatestorage.flush.md @@ -4,7 +4,7 @@ ## IKbnUrlStateStorage.flush property -synchronously runs any pending url updates returned boolean indicates if change occurred +Synchronously runs any pending url updates, returned boolean indicates if change occurred. Signature: diff --git a/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.ikbnurlstatestorage.md b/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.ikbnurlstatestorage.md index 56cefebd2acfe..371f7b7c15362 100644 --- a/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.ikbnurlstatestorage.md +++ b/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.ikbnurlstatestorage.md @@ -4,7 +4,11 @@ ## IKbnUrlStateStorage interface -KbnUrlStateStorage is a state storage for [syncState()](./kibana-plugin-plugins-kibana_utils-public-state_sync.syncstate.md) utility which: 1. Keeps state in sync with the URL. 2. Serializes data and stores it in the URL in one of the supported formats: \* Rison encoded. \* Hashed URL: In URL we store only the hash from the serialized state, but the state itself is stored in sessionStorage. See kibana's advanced option for more context state:storeInSessionStorage 3. Takes care of listening to the URL updates and notifies state about the updates. 4. Takes care of batching URL updates to prevent redundant browser history records. [GUIDE](https://github.com/elastic/kibana/blob/master/src/plugins/kibana_utils/docs/state_sync/storages/kbn_url_storage.md) +KbnUrlStateStorage is a state storage for [syncState()](./kibana-plugin-plugins-kibana_utils-public-state_sync.syncstate.md) utility which: + +1. Keeps state in sync with the URL. 2. Serializes data and stores it in the URL in one of the supported formats: \* Rison encoded. \* Hashed URL: In URL we store only the hash from the serialized state, but the state itself is stored in sessionStorage. See Kibana's `state:storeInSessionStorage` advanced option for more context. 3. Takes care of listening to the URL updates and notifies state about the updates. 4. Takes care of batching URL updates to prevent redundant browser history records. + +[Refer to this guide for more info](https://github.com/elastic/kibana/blob/master/src/plugins/kibana_utils/docs/state_sync/storages/kbn_url_storage.md) Signature: @@ -18,7 +22,7 @@ export interface IKbnUrlStateStorage extends IStateStorage | --- | --- | --- | | [cancel](./kibana-plugin-plugins-kibana_utils-public-state_sync.ikbnurlstatestorage.cancel.md) | () => void | cancels any pending url updates | | [change$](./kibana-plugin-plugins-kibana_utils-public-state_sync.ikbnurlstatestorage.change_.md) | <State = unknown>(key: string) => Observable<State | null> | | -| [flush](./kibana-plugin-plugins-kibana_utils-public-state_sync.ikbnurlstatestorage.flush.md) | (opts?: {
replace?: boolean;
}) => boolean | synchronously runs any pending url updates returned boolean indicates if change occurred | +| [flush](./kibana-plugin-plugins-kibana_utils-public-state_sync.ikbnurlstatestorage.flush.md) | (opts?: {
replace?: boolean;
}) => boolean | Synchronously runs any pending url updates, returned boolean indicates if change occurred. | | [get](./kibana-plugin-plugins-kibana_utils-public-state_sync.ikbnurlstatestorage.get.md) | <State = unknown>(key: string) => State | null | | | [set](./kibana-plugin-plugins-kibana_utils-public-state_sync.ikbnurlstatestorage.set.md) | <State>(key: string, state: State, opts?: {
replace: boolean;
}) => Promise<string | undefined> | | diff --git a/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.inullablebasestatecontainer.md b/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.inullablebasestatecontainer.md index ca69609936405..d81694484c3c0 100644 --- a/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.inullablebasestatecontainer.md +++ b/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.inullablebasestatecontainer.md @@ -14,7 +14,7 @@ export interface INullableBaseStateContainer extends Ba ## Remarks -State container for stateSync() have to accept "null" for example, set() implementation could handle null and fallback to some default state this is required to handle edge case, when state in storage becomes empty and syncing is in progress. state container will be notified about about storage becoming empty with null passed in +State container for `stateSync()` have to accept `null` for example, `set()` implementation could handle null and fallback to some default state this is required to handle edge case, when state in storage becomes empty and syncing is in progress. State container will be notified about about storage becoming empty with null passed in. ## Properties diff --git a/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.istatestorage.cancel.md b/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.istatestorage.cancel.md index ce771d52a6e60..13bacfae9ef56 100644 --- a/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.istatestorage.cancel.md +++ b/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.istatestorage.cancel.md @@ -4,7 +4,7 @@ ## IStateStorage.cancel property -Optional method to cancel any pending activity syncState() will call it, if it is provided by IStateStorage +Optional method to cancel any pending activity [syncState()](./kibana-plugin-plugins-kibana_utils-public-state_sync.syncstate.md) will call it during destroy, if it is provided by IStateStorage Signature: diff --git a/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.istatestorage.md b/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.istatestorage.md index 2c34a185fb7b1..82f7949dfdc03 100644 --- a/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.istatestorage.md +++ b/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.istatestorage.md @@ -18,7 +18,7 @@ export interface IStateStorage | Property | Type | Description | | --- | --- | --- | -| [cancel](./kibana-plugin-plugins-kibana_utils-public-state_sync.istatestorage.cancel.md) | () => void | Optional method to cancel any pending activity syncState() will call it, if it is provided by IStateStorage | +| [cancel](./kibana-plugin-plugins-kibana_utils-public-state_sync.istatestorage.cancel.md) | () => void | Optional method to cancel any pending activity [syncState()](./kibana-plugin-plugins-kibana_utils-public-state_sync.syncstate.md) will call it during destroy, if it is provided by IStateStorage | | [change$](./kibana-plugin-plugins-kibana_utils-public-state_sync.istatestorage.change_.md) | <State = unknown>(key: string) => Observable<State | null> | Should notify when the stored state has changed | | [get](./kibana-plugin-plugins-kibana_utils-public-state_sync.istatestorage.get.md) | <State = unknown>(key: string) => State | null | Should retrieve state from the storage and deserialize it | | [set](./kibana-plugin-plugins-kibana_utils-public-state_sync.istatestorage.set.md) | <State>(key: string, state: State) => any | Take in a state object, should serialise and persist | diff --git a/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.md b/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.md index 2b02c98e0d605..52919f78a035c 100644 --- a/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.md +++ b/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.md @@ -4,28 +4,28 @@ ## kibana-plugin-plugins-kibana\_utils-public-state\_sync package -State syncing utilities are a set of helpers for syncing your application state with URL or browser storage. +State syncing utilities are a set of helpers for syncing your application state with browser URL or browser storage. -They are designed to work together with state containers (). But state containers are not required. +They are designed to work together with [state containers](https://github.com/elastic/kibana/tree/master/src/plugins/kibana_utils/docs/state_containers). But state containers are not required. State syncing utilities include: -- [syncState()](./kibana-plugin-plugins-kibana_utils-public-state_sync.syncstate.md) util which: - Subscribes to state changes and pushes them to state storage. - Optionally subscribes to state storage changes and pushes them to state. - Two types of storage compatible with `syncState`: - [IKbnUrlStateStorage](./kibana-plugin-plugins-kibana_utils-public-state_sync.ikbnurlstatestorage.md) - Serializes state and persists it to URL's query param in rison or hashed format. Listens for state updates in the URL and pushes them back to state. - [ISessionStorageStateStorage](./kibana-plugin-plugins-kibana_utils-public-state_sync.isessionstoragestatestorage.md) - Serializes state and persists it to browser storage. +\*[syncState()](./kibana-plugin-plugins-kibana_utils-public-state_sync.syncstate.md) util which: \* Subscribes to state changes and pushes them to state storage. \* Optionally subscribes to state storage changes and pushes them to state. \* Two types of storages compatible with `syncState`: \* [IKbnUrlStateStorage](./kibana-plugin-plugins-kibana_utils-public-state_sync.ikbnurlstatestorage.md) - Serializes state and persists it to URL's query param in rison or hashed format. Listens for state updates in the URL and pushes them back to state. \* [ISessionStorageStateStorage](./kibana-plugin-plugins-kibana_utils-public-state_sync.isessionstoragestatestorage.md) - Serializes state and persists it to browser storage. -Refer [here](https://github.com/elastic/kibana/tree/master/src/plugins/kibana_utils/docs/state_sync) for a complete guide and examples +Refer [here](https://github.com/elastic/kibana/tree/master/src/plugins/kibana_utils/docs/state_sync) for a complete guide and examples. ## Functions | Function | Description | | --- | --- | -| [syncState({ storageKey, stateStorage, stateContainer, })](./kibana-plugin-plugins-kibana_utils-public-state_sync.syncstate.md) | Utility for syncing application state wrapped in state container with some kind of storage (e.g. URL) Refer [here](https://github.com/elastic/kibana/tree/master/src/plugins/kibana_utils/docs/state_sync) for a complete guide and examples | +| [syncState({ storageKey, stateStorage, stateContainer, })](./kibana-plugin-plugins-kibana_utils-public-state_sync.syncstate.md) | Utility for syncing application state wrapped in state container with some kind of storage (e.g. URL)Go [here](https://github.com/elastic/kibana/tree/master/src/plugins/kibana_utils/docs/state_sync) for a complete guide and examples. | | [syncStates(stateSyncConfigs)](./kibana-plugin-plugins-kibana_utils-public-state_sync.syncstates.md) | | ## Interfaces | Interface | Description | | --- | --- | -| [IKbnUrlStateStorage](./kibana-plugin-plugins-kibana_utils-public-state_sync.ikbnurlstatestorage.md) | KbnUrlStateStorage is a state storage for [syncState()](./kibana-plugin-plugins-kibana_utils-public-state_sync.syncstate.md) utility which: 1. Keeps state in sync with the URL. 2. Serializes data and stores it in the URL in one of the supported formats: \* Rison encoded. \* Hashed URL: In URL we store only the hash from the serialized state, but the state itself is stored in sessionStorage. See kibana's advanced option for more context state:storeInSessionStorage 3. Takes care of listening to the URL updates and notifies state about the updates. 4. Takes care of batching URL updates to prevent redundant browser history records. [GUIDE](https://github.com/elastic/kibana/blob/master/src/plugins/kibana_utils/docs/state_sync/storages/kbn_url_storage.md) | +| [IKbnUrlStateStorage](./kibana-plugin-plugins-kibana_utils-public-state_sync.ikbnurlstatestorage.md) | KbnUrlStateStorage is a state storage for [syncState()](./kibana-plugin-plugins-kibana_utils-public-state_sync.syncstate.md) utility which:1. Keeps state in sync with the URL. 2. Serializes data and stores it in the URL in one of the supported formats: \* Rison encoded. \* Hashed URL: In URL we store only the hash from the serialized state, but the state itself is stored in sessionStorage. See Kibana's state:storeInSessionStorage advanced option for more context. 3. Takes care of listening to the URL updates and notifies state about the updates. 4. Takes care of batching URL updates to prevent redundant browser history records.[Refer to this guide for more info](https://github.com/elastic/kibana/blob/master/src/plugins/kibana_utils/docs/state_sync/storages/kbn_url_storage.md) | | [INullableBaseStateContainer](./kibana-plugin-plugins-kibana_utils-public-state_sync.inullablebasestatecontainer.md) | Extension of with one constraint: set state should handle null as incoming state | | [ISessionStorageStateStorage](./kibana-plugin-plugins-kibana_utils-public-state_sync.isessionstoragestatestorage.md) | [IStateStorage](./kibana-plugin-plugins-kibana_utils-public-state_sync.istatestorage.md) for storing state in browser [guide](https://github.com/elastic/kibana/blob/master/src/plugins/kibana_utils/docs/state_sync/storages/session_storage.md) | | [IStateStorage](./kibana-plugin-plugins-kibana_utils-public-state_sync.istatestorage.md) | Any StateStorage have to implement IStateStorage interface StateStorage is responsible for: \* state serialisation / deserialization \* persisting to and retrieving from storageFor an example take a look at already implemented [IKbnUrlStateStorage](./kibana-plugin-plugins-kibana_utils-public-state_sync.ikbnurlstatestorage.md) and [ISessionStorageStateStorage](./kibana-plugin-plugins-kibana_utils-public-state_sync.isessionstoragestatestorage.md) state storages | diff --git a/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.syncstate.md b/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.syncstate.md index d095c3fffc512..10dc4d0e18746 100644 --- a/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.syncstate.md +++ b/docs/development/plugins/kibana_utils/public/state_sync/kibana-plugin-plugins-kibana_utils-public-state_sync.syncstate.md @@ -4,7 +4,9 @@ ## syncState() function -Utility for syncing application state wrapped in state container with some kind of storage (e.g. URL) Refer [here](https://github.com/elastic/kibana/tree/master/src/plugins/kibana_utils/docs/state_sync) for a complete guide and examples +Utility for syncing application state wrapped in state container with some kind of storage (e.g. URL) + +Go [here](https://github.com/elastic/kibana/tree/master/src/plugins/kibana_utils/docs/state_sync) for a complete guide and examples. Signature: @@ -24,13 +26,9 @@ export declare function syncState ({ tab: s.tab }); diff --git a/docs/images/Discover-ContextView.png b/docs/discover/images/Discover-ContextView.png similarity index 100% rename from docs/images/Discover-ContextView.png rename to docs/discover/images/Discover-ContextView.png diff --git a/docs/images/Discover-Start.png b/docs/discover/images/Discover-Start.png similarity index 100% rename from docs/images/Discover-Start.png rename to docs/discover/images/Discover-Start.png diff --git a/docs/images/Expanded-Document.png b/docs/discover/images/Expanded-Document.png similarity index 100% rename from docs/images/Expanded-Document.png rename to docs/discover/images/Expanded-Document.png diff --git a/docs/images/Histogram-Time.png b/docs/discover/images/Histogram-Time.png similarity index 100% rename from docs/images/Histogram-Time.png rename to docs/discover/images/Histogram-Time.png diff --git a/docs/images/NegativeFilter.jpg b/docs/discover/images/NegativeFilter.jpg similarity index 100% rename from docs/images/NegativeFilter.jpg rename to docs/discover/images/NegativeFilter.jpg diff --git a/docs/images/PositiveFilter.jpg b/docs/discover/images/PositiveFilter.jpg similarity index 100% rename from docs/images/PositiveFilter.jpg rename to docs/discover/images/PositiveFilter.jpg diff --git a/docs/images/Timepicker-View.png b/docs/discover/images/Timepicker-View.png similarity index 100% rename from docs/images/Timepicker-View.png rename to docs/discover/images/Timepicker-View.png diff --git a/docs/images/edit_filter_query_json.png b/docs/discover/images/edit_filter_query_json.png similarity index 100% rename from docs/images/edit_filter_query_json.png rename to docs/discover/images/edit_filter_query_json.png diff --git a/docs/images/filter-field.png b/docs/discover/images/filter-field.png similarity index 100% rename from docs/images/filter-field.png rename to docs/discover/images/filter-field.png diff --git a/docs/images/time-filter-bar.png b/docs/discover/images/time-filter-bar.png similarity index 100% rename from docs/images/time-filter-bar.png rename to docs/discover/images/time-filter-bar.png diff --git a/docs/images/time-filter-calendar.png b/docs/discover/images/time-filter-calendar.png similarity index 100% rename from docs/images/time-filter-calendar.png rename to docs/discover/images/time-filter-calendar.png diff --git a/docs/images/tutorial-dashboard.png b/docs/getting-started/images/tutorial-dashboard.png similarity index 100% rename from docs/images/tutorial-dashboard.png rename to docs/getting-started/images/tutorial-dashboard.png diff --git a/docs/images/tutorial-discover-2.png b/docs/getting-started/images/tutorial-discover-2.png similarity index 100% rename from docs/images/tutorial-discover-2.png rename to docs/getting-started/images/tutorial-discover-2.png diff --git a/docs/images/tutorial-discover-3.png b/docs/getting-started/images/tutorial-discover-3.png similarity index 100% rename from docs/images/tutorial-discover-3.png rename to docs/getting-started/images/tutorial-discover-3.png diff --git a/docs/images/tutorial-full-inspect1.png b/docs/getting-started/images/tutorial-full-inspect1.png similarity index 100% rename from docs/images/tutorial-full-inspect1.png rename to docs/getting-started/images/tutorial-full-inspect1.png diff --git a/docs/images/tutorial-pattern-1.png b/docs/getting-started/images/tutorial-pattern-1.png similarity index 100% rename from docs/images/tutorial-pattern-1.png rename to docs/getting-started/images/tutorial-pattern-1.png diff --git a/docs/images/tutorial-visualize-bar-1.5.png b/docs/getting-started/images/tutorial-visualize-bar-1.5.png similarity index 100% rename from docs/images/tutorial-visualize-bar-1.5.png rename to docs/getting-started/images/tutorial-visualize-bar-1.5.png diff --git a/docs/images/tutorial-visualize-map-2.png b/docs/getting-started/images/tutorial-visualize-map-2.png similarity index 100% rename from docs/images/tutorial-visualize-map-2.png rename to docs/getting-started/images/tutorial-visualize-map-2.png diff --git a/docs/images/tutorial-visualize-md-2.png b/docs/getting-started/images/tutorial-visualize-md-2.png similarity index 100% rename from docs/images/tutorial-visualize-md-2.png rename to docs/getting-started/images/tutorial-visualize-md-2.png diff --git a/docs/images/tutorial-visualize-pie-2.png b/docs/getting-started/images/tutorial-visualize-pie-2.png similarity index 100% rename from docs/images/tutorial-visualize-pie-2.png rename to docs/getting-started/images/tutorial-visualize-pie-2.png diff --git a/docs/images/tutorial-visualize-pie-3.png b/docs/getting-started/images/tutorial-visualize-pie-3.png similarity index 100% rename from docs/images/tutorial-visualize-pie-3.png rename to docs/getting-started/images/tutorial-visualize-pie-3.png diff --git a/docs/images/tutorial-visualize-wizard-step-1.png b/docs/getting-started/images/tutorial-visualize-wizard-step-1.png similarity index 100% rename from docs/images/tutorial-visualize-wizard-step-1.png rename to docs/getting-started/images/tutorial-visualize-wizard-step-1.png diff --git a/docs/images/AddFieldButton.jpg b/docs/images/AddFieldButton.jpg deleted file mode 100644 index efd4f50e34a0b..0000000000000 Binary files a/docs/images/AddFieldButton.jpg and /dev/null differ diff --git a/docs/images/CollapseButton.jpg b/docs/images/CollapseButton.jpg deleted file mode 100644 index 38bb350d49746..0000000000000 Binary files a/docs/images/CollapseButton.jpg and /dev/null differ diff --git a/docs/images/Dashboard_Resize_Menu.png b/docs/images/Dashboard_Resize_Menu.png deleted file mode 100644 index 835d23afe40e9..0000000000000 Binary files a/docs/images/Dashboard_Resize_Menu.png and /dev/null differ diff --git a/docs/images/Dashboard_visualization_data.png b/docs/images/Dashboard_visualization_data.png deleted file mode 100644 index 9792fedf1a51a..0000000000000 Binary files a/docs/images/Dashboard_visualization_data.png and /dev/null differ diff --git a/docs/images/Discover-ContextView-FilterMontage.png b/docs/images/Discover-ContextView-FilterMontage.png deleted file mode 100644 index c990d314a6ba1..0000000000000 Binary files a/docs/images/Discover-ContextView-FilterMontage.png and /dev/null differ diff --git a/docs/images/Discover-FieldStats.jpg b/docs/images/Discover-FieldStats.jpg deleted file mode 100644 index 4092b0d7caafd..0000000000000 Binary files a/docs/images/Discover-FieldStats.jpg and /dev/null differ diff --git a/docs/images/Discover-MoveColumn.jpg b/docs/images/Discover-MoveColumn.jpg deleted file mode 100644 index 630f2a0f18dbe..0000000000000 Binary files a/docs/images/Discover-MoveColumn.jpg and /dev/null differ diff --git a/docs/images/EditVis.png b/docs/images/EditVis.png deleted file mode 100644 index 3013168200860..0000000000000 Binary files a/docs/images/EditVis.png and /dev/null differ diff --git a/docs/images/ExistsButton.jpg b/docs/images/ExistsButton.jpg deleted file mode 100644 index 0d4ede0101e73..0000000000000 Binary files a/docs/images/ExistsButton.jpg and /dev/null differ diff --git a/docs/images/ExpandButton.jpg b/docs/images/ExpandButton.jpg deleted file mode 100644 index 1ed389a25dd36..0000000000000 Binary files a/docs/images/ExpandButton.jpg and /dev/null differ diff --git a/docs/images/NYCTA-Table.jpg b/docs/images/NYCTA-Table.jpg deleted file mode 100644 index 6b4987ef4b437..0000000000000 Binary files a/docs/images/NYCTA-Table.jpg and /dev/null differ diff --git a/docs/images/NewDashboard.png b/docs/images/NewDashboard.png deleted file mode 100644 index 08e5159250134..0000000000000 Binary files a/docs/images/NewDashboard.png and /dev/null differ diff --git a/docs/images/RemoveFieldButton.jpg b/docs/images/RemoveFieldButton.jpg deleted file mode 100644 index a260dc3cff62e..0000000000000 Binary files a/docs/images/RemoveFieldButton.jpg and /dev/null differ diff --git a/docs/images/Start-Page.png b/docs/images/Start-Page.png deleted file mode 100644 index 706d4aafd75e2..0000000000000 Binary files a/docs/images/Start-Page.png and /dev/null differ diff --git a/docs/images/TimeFilter.jpg b/docs/images/TimeFilter.jpg deleted file mode 100644 index 1c8700bc05616..0000000000000 Binary files a/docs/images/TimeFilter.jpg and /dev/null differ diff --git a/docs/images/VizEditor.jpg b/docs/images/VizEditor.jpg deleted file mode 100644 index 8aabfe544a0cd..0000000000000 Binary files a/docs/images/VizEditor.jpg and /dev/null differ diff --git a/docs/images/add-column-button.png b/docs/images/add-column-button.png deleted file mode 100644 index 6f44d0facf41f..0000000000000 Binary files a/docs/images/add-column-button.png and /dev/null differ diff --git a/docs/images/add_filter_field.png b/docs/images/add_filter_field.png deleted file mode 100644 index 2052559cf5273..0000000000000 Binary files a/docs/images/add_filter_field.png and /dev/null differ diff --git a/docs/images/add_filter_operator.png b/docs/images/add_filter_operator.png deleted file mode 100644 index fd7d42a9d1b98..0000000000000 Binary files a/docs/images/add_filter_operator.png and /dev/null differ diff --git a/docs/images/add_filter_value.png b/docs/images/add_filter_value.png deleted file mode 100644 index d357c6e5a3013..0000000000000 Binary files a/docs/images/add_filter_value.png and /dev/null differ diff --git a/docs/images/auto_format_after.png b/docs/images/auto_format_after.png deleted file mode 100644 index 018e82951b64f..0000000000000 Binary files a/docs/images/auto_format_after.png and /dev/null differ diff --git a/docs/images/auto_format_before.png b/docs/images/auto_format_before.png deleted file mode 100644 index 2535aa1af5240..0000000000000 Binary files a/docs/images/auto_format_before.png and /dev/null differ diff --git a/docs/images/auto_format_bulk.png b/docs/images/auto_format_bulk.png deleted file mode 100644 index 92cb688473ab7..0000000000000 Binary files a/docs/images/auto_format_bulk.png and /dev/null differ diff --git a/docs/images/autorefresh-intervals.png b/docs/images/autorefresh-intervals.png deleted file mode 100644 index 49be46fefd4aa..0000000000000 Binary files a/docs/images/autorefresh-intervals.png and /dev/null differ diff --git a/docs/images/autorefresh-pause.png b/docs/images/autorefresh-pause.png deleted file mode 100644 index 5a83c4587c961..0000000000000 Binary files a/docs/images/autorefresh-pause.png and /dev/null differ diff --git a/docs/images/autorefresh.png b/docs/images/autorefresh.png deleted file mode 100644 index 9a6225b9007bd..0000000000000 Binary files a/docs/images/autorefresh.png and /dev/null differ diff --git a/docs/images/bar-terms-agg.png b/docs/images/bar-terms-agg.png deleted file mode 100644 index b0b62b9e53213..0000000000000 Binary files a/docs/images/bar-terms-agg.png and /dev/null differ diff --git a/docs/images/bar-terms-subagg.png b/docs/images/bar-terms-subagg.png deleted file mode 100644 index 37cf5486eff1e..0000000000000 Binary files a/docs/images/bar-terms-subagg.png and /dev/null differ diff --git a/docs/images/canvas-align-elements.gif b/docs/images/canvas-align-elements.gif deleted file mode 100644 index 0081308d68795..0000000000000 Binary files a/docs/images/canvas-align-elements.gif and /dev/null differ diff --git a/docs/images/canvas-background-color-picker.gif b/docs/images/canvas-background-color-picker.gif deleted file mode 100644 index bd22941b35f5d..0000000000000 Binary files a/docs/images/canvas-background-color-picker.gif and /dev/null differ diff --git a/docs/images/canvas-click-drag-element.gif b/docs/images/canvas-click-drag-element.gif deleted file mode 100644 index 34f4268caf6f5..0000000000000 Binary files a/docs/images/canvas-click-drag-element.gif and /dev/null differ diff --git a/docs/images/canvas-distribute-elements.gif b/docs/images/canvas-distribute-elements.gif deleted file mode 100644 index 685d76ba22e40..0000000000000 Binary files a/docs/images/canvas-distribute-elements.gif and /dev/null differ diff --git a/docs/images/canvas-download-json.gif b/docs/images/canvas-download-json.gif deleted file mode 100644 index c0c0025e508c1..0000000000000 Binary files a/docs/images/canvas-download-json.gif and /dev/null differ diff --git a/docs/images/canvas-ecommerce.png b/docs/images/canvas-ecommerce.png deleted file mode 100644 index 58c0612881341..0000000000000 Binary files a/docs/images/canvas-ecommerce.png and /dev/null differ diff --git a/docs/images/canvas-element-order.gif b/docs/images/canvas-element-order.gif deleted file mode 100644 index e2911367e7dfa..0000000000000 Binary files a/docs/images/canvas-element-order.gif and /dev/null differ diff --git a/docs/images/canvas-embed_workpad.gif b/docs/images/canvas-embed_workpad.gif deleted file mode 100644 index 97a79d775fe36..0000000000000 Binary files a/docs/images/canvas-embed_workpad.gif and /dev/null differ diff --git a/docs/images/canvas-fullscreen.gif b/docs/images/canvas-fullscreen.gif deleted file mode 100644 index 2eebd3b511000..0000000000000 Binary files a/docs/images/canvas-fullscreen.gif and /dev/null differ diff --git a/docs/images/canvas-move-pixel.gif b/docs/images/canvas-move-pixel.gif deleted file mode 100644 index 228f0f7b7e18c..0000000000000 Binary files a/docs/images/canvas-move-pixel.gif and /dev/null differ diff --git a/docs/images/canvas-resize-element.gif b/docs/images/canvas-resize-element.gif deleted file mode 100644 index d2d2ab06bbb42..0000000000000 Binary files a/docs/images/canvas-resize-element.gif and /dev/null differ diff --git a/docs/images/canvas-zoom.gif b/docs/images/canvas-zoom.gif deleted file mode 100644 index 584118d75a43f..0000000000000 Binary files a/docs/images/canvas-zoom.gif and /dev/null differ diff --git a/docs/images/canvas_create_image.png b/docs/images/canvas_create_image.png deleted file mode 100644 index 7b7c38102e4c9..0000000000000 Binary files a/docs/images/canvas_create_image.png and /dev/null differ diff --git a/docs/images/canvas_map-time-filter.gif b/docs/images/canvas_map-time-filter.gif deleted file mode 100644 index 301d7f4b44158..0000000000000 Binary files a/docs/images/canvas_map-time-filter.gif and /dev/null differ diff --git a/docs/images/canvas_share_autoplay_480.gif b/docs/images/canvas_share_autoplay_480.gif deleted file mode 100644 index 84a108e58d3dc..0000000000000 Binary files a/docs/images/canvas_share_autoplay_480.gif and /dev/null differ diff --git a/docs/images/canvas_share_hidetoolbar_480.gif b/docs/images/canvas_share_hidetoolbar_480.gif deleted file mode 100644 index 282783057776a..0000000000000 Binary files a/docs/images/canvas_share_hidetoolbar_480.gif and /dev/null differ diff --git a/docs/images/canvas_workpad_3_page.png b/docs/images/canvas_workpad_3_page.png deleted file mode 100644 index 9a60ed3d00f60..0000000000000 Binary files a/docs/images/canvas_workpad_3_page.png and /dev/null differ diff --git a/docs/images/canvas_workpad_edit_style.png b/docs/images/canvas_workpad_edit_style.png deleted file mode 100644 index d12ae2cd81b8f..0000000000000 Binary files a/docs/images/canvas_workpad_edit_style.png and /dev/null differ diff --git a/docs/images/canvas_workpad_weblog.png b/docs/images/canvas_workpad_weblog.png deleted file mode 100755 index 7b6ebee5c9554..0000000000000 Binary files a/docs/images/canvas_workpad_weblog.png and /dev/null differ diff --git a/docs/images/controls/controls_options.png b/docs/images/controls/controls_options.png deleted file mode 100644 index aab93d5cd4be0..0000000000000 Binary files a/docs/images/controls/controls_options.png and /dev/null differ diff --git a/docs/images/controls/dropdown_control_editor.png b/docs/images/controls/dropdown_control_editor.png deleted file mode 100644 index 36a360dcd275e..0000000000000 Binary files a/docs/images/controls/dropdown_control_editor.png and /dev/null differ diff --git a/docs/images/controls/range_slider_editor.png b/docs/images/controls/range_slider_editor.png deleted file mode 100644 index 8d6c5a68d1d24..0000000000000 Binary files a/docs/images/controls/range_slider_editor.png and /dev/null differ diff --git a/docs/images/discover-compass.png b/docs/images/discover-compass.png deleted file mode 100644 index 0e3c80ff75a74..0000000000000 Binary files a/docs/images/discover-compass.png and /dev/null differ diff --git a/docs/images/edit_filter_query.png b/docs/images/edit_filter_query.png deleted file mode 100644 index 367a2a8578b8b..0000000000000 Binary files a/docs/images/edit_filter_query.png and /dev/null differ diff --git a/docs/images/filter-actions.png b/docs/images/filter-actions.png deleted file mode 100644 index 92feef2f0dbbb..0000000000000 Binary files a/docs/images/filter-actions.png and /dev/null differ diff --git a/docs/images/filter-allbuttons.png b/docs/images/filter-allbuttons.png deleted file mode 100644 index 3d6951812daa7..0000000000000 Binary files a/docs/images/filter-allbuttons.png and /dev/null differ diff --git a/docs/images/filter-sample.png b/docs/images/filter-sample.png deleted file mode 100644 index 9d2540720a5a2..0000000000000 Binary files a/docs/images/filter-sample.png and /dev/null differ diff --git a/docs/images/goal.png b/docs/images/goal.png deleted file mode 100644 index 04f16e8cd3e74..0000000000000 Binary files a/docs/images/goal.png and /dev/null differ diff --git a/docs/images/history.png b/docs/images/history.png deleted file mode 100644 index 8e6674e1f2c69..0000000000000 Binary files a/docs/images/history.png and /dev/null differ diff --git a/docs/images/labelbutton.png b/docs/images/labelbutton.png deleted file mode 100644 index 287a588802384..0000000000000 Binary files a/docs/images/labelbutton.png and /dev/null differ diff --git a/docs/images/lens_remove_layer.png b/docs/images/lens_remove_layer.png deleted file mode 100644 index 4184e5b846870..0000000000000 Binary files a/docs/images/lens_remove_layer.png and /dev/null differ diff --git a/docs/images/management-index-management.png b/docs/images/management-index-management.png deleted file mode 100644 index 1b1ff9226147c..0000000000000 Binary files a/docs/images/management-index-management.png and /dev/null differ diff --git a/docs/images/management-license.png b/docs/images/management-license.png deleted file mode 100644 index 3347aec8632e4..0000000000000 Binary files a/docs/images/management-license.png and /dev/null differ diff --git a/docs/images/management-upgrade-assistant-8.0.png b/docs/images/management-upgrade-assistant-8.0.png deleted file mode 100644 index 4b37262414039..0000000000000 Binary files a/docs/images/management-upgrade-assistant-8.0.png and /dev/null differ diff --git a/docs/images/management-watcher-buttons.png b/docs/images/management-watcher-buttons.png deleted file mode 100644 index ce114ccf1bac9..0000000000000 Binary files a/docs/images/management-watcher-buttons.png and /dev/null differ diff --git a/docs/images/management_rolled_dashboard.png b/docs/images/management_rolled_dashboard.png deleted file mode 100755 index db731420fb96a..0000000000000 Binary files a/docs/images/management_rolled_dashboard.png and /dev/null differ diff --git a/docs/images/management_rollups_visualization.png b/docs/images/management_rollups_visualization.png deleted file mode 100755 index bba3b6e91a953..0000000000000 Binary files a/docs/images/management_rollups_visualization.png and /dev/null differ diff --git a/docs/images/markdown-example.png b/docs/images/markdown-example.png deleted file mode 100644 index 79daa1298883d..0000000000000 Binary files a/docs/images/markdown-example.png and /dev/null differ diff --git a/docs/images/multiple_requests.png b/docs/images/multiple_requests.png deleted file mode 100644 index e4fd010d54b4b..0000000000000 Binary files a/docs/images/multiple_requests.png and /dev/null differ diff --git a/docs/images/regionmap.png b/docs/images/regionmap.png deleted file mode 100644 index 97f2594e8bee6..0000000000000 Binary files a/docs/images/regionmap.png and /dev/null differ diff --git a/docs/images/search-button.jpg b/docs/images/search-button.jpg deleted file mode 100644 index b7787cac4bf6a..0000000000000 Binary files a/docs/images/search-button.jpg and /dev/null differ diff --git a/docs/images/security_base_all.png b/docs/images/security_base_all.png deleted file mode 100644 index 2aef42132ef21..0000000000000 Binary files a/docs/images/security_base_all.png and /dev/null differ diff --git a/docs/images/share-short-link.png b/docs/images/share-short-link.png deleted file mode 100644 index bf7f7782c4e2a..0000000000000 Binary files a/docs/images/share-short-link.png and /dev/null differ diff --git a/docs/images/time-filter-absolute.jpg b/docs/images/time-filter-absolute.jpg deleted file mode 100644 index bc54d57f0f737..0000000000000 Binary files a/docs/images/time-filter-absolute.jpg and /dev/null differ diff --git a/docs/images/time-filter-relative.jpg b/docs/images/time-filter-relative.jpg deleted file mode 100644 index 77beca3a3fd46..0000000000000 Binary files a/docs/images/time-filter-relative.jpg and /dev/null differ diff --git a/docs/images/time-filter.jpg b/docs/images/time-filter.jpg deleted file mode 100644 index e437f314d849d..0000000000000 Binary files a/docs/images/time-filter.jpg and /dev/null differ diff --git a/docs/images/time-picker-step.jpg b/docs/images/time-picker-step.jpg deleted file mode 100644 index 90c749776bb5d..0000000000000 Binary files a/docs/images/time-picker-step.jpg and /dev/null differ diff --git a/docs/images/time-picker.jpg b/docs/images/time-picker.jpg deleted file mode 100644 index 25830082d5919..0000000000000 Binary files a/docs/images/time-picker.jpg and /dev/null differ diff --git a/docs/images/timelion-arg-help.jpg b/docs/images/timelion-arg-help.jpg deleted file mode 100644 index 3e471c861d46b..0000000000000 Binary files a/docs/images/timelion-arg-help.jpg and /dev/null differ diff --git a/docs/images/timelion-read-only-badge.png b/docs/images/timelion-read-only-badge.png deleted file mode 100644 index 19ffbfed6335a..0000000000000 Binary files a/docs/images/timelion-read-only-badge.png and /dev/null differ diff --git a/docs/images/timelion-save01.png b/docs/images/timelion-save01.png deleted file mode 100644 index 47a33c2d36d43..0000000000000 Binary files a/docs/images/timelion-save01.png and /dev/null differ diff --git a/docs/images/timelion-save02.png b/docs/images/timelion-save02.png deleted file mode 100644 index 348b084ee5259..0000000000000 Binary files a/docs/images/timelion-save02.png and /dev/null differ diff --git a/docs/images/tsvb-annotations.png b/docs/images/tsvb-annotations.png deleted file mode 100644 index 22238db7e9e91..0000000000000 Binary files a/docs/images/tsvb-annotations.png and /dev/null differ diff --git a/docs/images/tsvb-data-tab-derivative-example.png b/docs/images/tsvb-data-tab-derivative-example.png deleted file mode 100644 index 66368baf1e16a..0000000000000 Binary files a/docs/images/tsvb-data-tab-derivative-example.png and /dev/null differ diff --git a/docs/images/tsvb-data-tab-label.png b/docs/images/tsvb-data-tab-label.png deleted file mode 100644 index 43d1fc64f4446..0000000000000 Binary files a/docs/images/tsvb-data-tab-label.png and /dev/null differ diff --git a/docs/images/tsvb-data-tab-series-options-time-series.png b/docs/images/tsvb-data-tab-series-options-time-series.png deleted file mode 100644 index 4c7ddadd38d95..0000000000000 Binary files a/docs/images/tsvb-data-tab-series-options-time-series.png and /dev/null differ diff --git a/docs/images/tsvb-data-tab-series-options.png b/docs/images/tsvb-data-tab-series-options.png deleted file mode 100644 index afadc3349bfe4..0000000000000 Binary files a/docs/images/tsvb-data-tab-series-options.png and /dev/null differ diff --git a/docs/images/tutorial-full-inspect2.png b/docs/images/tutorial-full-inspect2.png deleted file mode 100644 index 23c840f545ec3..0000000000000 Binary files a/docs/images/tutorial-full-inspect2.png and /dev/null differ diff --git a/docs/images/tutorial-sample-discover-2.png b/docs/images/tutorial-sample-discover-2.png deleted file mode 100644 index 4f4b2dc920ccb..0000000000000 Binary files a/docs/images/tutorial-sample-discover-2.png and /dev/null differ diff --git a/docs/images/tutorial-sample-inspect2.png b/docs/images/tutorial-sample-inspect2.png deleted file mode 100644 index b487d21e5cc02..0000000000000 Binary files a/docs/images/tutorial-sample-inspect2.png and /dev/null differ diff --git a/docs/images/tutorial-visualize-pie-1.png b/docs/images/tutorial-visualize-pie-1.png deleted file mode 100644 index 109829c01f28c..0000000000000 Binary files a/docs/images/tutorial-visualize-pie-1.png and /dev/null differ diff --git a/docs/images/visualize-flow.png b/docs/images/visualize-flow.png deleted file mode 100644 index bc00ff52a8d6e..0000000000000 Binary files a/docs/images/visualize-flow.png and /dev/null differ diff --git a/docs/images/visualize-icon.png b/docs/images/visualize-icon.png deleted file mode 100644 index af7ad18e9bf79..0000000000000 Binary files a/docs/images/visualize-icon.png and /dev/null differ diff --git a/docs/images/visualize_coordinate_map_example.png b/docs/images/visualize_coordinate_map_example.png deleted file mode 100644 index 24f03376adade..0000000000000 Binary files a/docs/images/visualize_coordinate_map_example.png and /dev/null differ diff --git a/docs/images/visualize_region_map_example.png b/docs/images/visualize_region_map_example.png deleted file mode 100644 index cf89e92625ece..0000000000000 Binary files a/docs/images/visualize_region_map_example.png and /dev/null differ diff --git a/docs/images/viz-fit-bounds.png b/docs/images/viz-fit-bounds.png deleted file mode 100644 index 9c0ddb89d7ddd..0000000000000 Binary files a/docs/images/viz-fit-bounds.png and /dev/null differ diff --git a/docs/images/viz-lat-long-filter.png b/docs/images/viz-lat-long-filter.png deleted file mode 100644 index 30c139b224565..0000000000000 Binary files a/docs/images/viz-lat-long-filter.png and /dev/null differ diff --git a/docs/images/viz-zoom.png b/docs/images/viz-zoom.png deleted file mode 100644 index 661e053130882..0000000000000 Binary files a/docs/images/viz-zoom.png and /dev/null differ diff --git a/docs/management/advanced-options.asciidoc b/docs/management/advanced-options.asciidoc index 561919738786e..9a94c25bcdf6e 100644 --- a/docs/management/advanced-options.asciidoc +++ b/docs/management/advanced-options.asciidoc @@ -247,7 +247,7 @@ retrieved. `timelion:es.timefield`:: The default field containing a timestamp when using the `.es()` query. `timelion:graphite.url`:: [experimental] Used with graphite queries, this is the URL of your graphite host in the form https://www.hostedgraphite.com/UID/ACCESS_KEY/graphite. This URL can be -selected from a whitelist configured in the `kibana.yml` under `timelion.graphiteUrls`. +selected from an allow-list configured in the `kibana.yml` under `timelion.graphiteUrls`. `timelion:max_buckets`:: The maximum number of buckets a single data source can return. This value is used for calculating automatic intervals in visualizations. `timelion:min_interval`:: The smallest interval to calculate when using "auto". diff --git a/docs/images/follower_indices.png b/docs/management/alerting/images/follower_indices.png similarity index 100% rename from docs/images/follower_indices.png rename to docs/management/alerting/images/follower_indices.png diff --git a/docs/images/actions_icon.png b/docs/management/images/actions_icon.png similarity index 100% rename from docs/images/actions_icon.png rename to docs/management/images/actions_icon.png diff --git a/docs/images/add_remote_cluster.png b/docs/management/images/add_remote_cluster.png similarity index 100% rename from docs/images/add_remote_cluster.png rename to docs/management/images/add_remote_cluster.png diff --git a/docs/images/auto_follow_pattern.png b/docs/management/images/auto_follow_pattern.png similarity index 100% rename from docs/images/auto_follow_pattern.png rename to docs/management/images/auto_follow_pattern.png diff --git a/docs/images/colorformatter.png b/docs/management/images/colorformatter.png similarity index 100% rename from docs/images/colorformatter.png rename to docs/management/images/colorformatter.png diff --git a/docs/images/cross-cluster-replication-list-view.png b/docs/management/images/cross-cluster-replication-list-view.png similarity index 100% rename from docs/images/cross-cluster-replication-list-view.png rename to docs/management/images/cross-cluster-replication-list-view.png diff --git a/docs/images/index-lifecycle-policies-create.png b/docs/management/images/index-lifecycle-policies-create.png similarity index 100% rename from docs/images/index-lifecycle-policies-create.png rename to docs/management/images/index-lifecycle-policies-create.png diff --git a/docs/images/index_lifecycle_policies_options.png b/docs/management/images/index_lifecycle_policies_options.png similarity index 100% rename from docs/images/index_lifecycle_policies_options.png rename to docs/management/images/index_lifecycle_policies_options.png diff --git a/docs/images/index_management_add_policy.png b/docs/management/images/index_management_add_policy.png similarity index 100% rename from docs/images/index_management_add_policy.png rename to docs/management/images/index_management_add_policy.png diff --git a/docs/images/management-create-rollup-bar-chart.png b/docs/management/images/management-create-rollup-bar-chart.png similarity index 100% rename from docs/images/management-create-rollup-bar-chart.png rename to docs/management/images/management-create-rollup-bar-chart.png diff --git a/docs/images/management-index-patterns.png b/docs/management/images/management-index-patterns.png similarity index 100% rename from docs/images/management-index-patterns.png rename to docs/management/images/management-index-patterns.png diff --git a/docs/images/management-index-read-only-badge.png b/docs/management/images/management-index-read-only-badge.png similarity index 100% rename from docs/images/management-index-read-only-badge.png rename to docs/management/images/management-index-read-only-badge.png diff --git a/docs/images/management-index-templates-mappings.png b/docs/management/images/management-index-templates-mappings.png similarity index 100% rename from docs/images/management-index-templates-mappings.png rename to docs/management/images/management-index-templates-mappings.png diff --git a/docs/images/management-index-templates.png b/docs/management/images/management-index-templates.png similarity index 100% rename from docs/images/management-index-templates.png rename to docs/management/images/management-index-templates.png diff --git a/docs/management/images/management-license.png b/docs/management/images/management-license.png new file mode 100644 index 0000000000000..8df9402939b2e Binary files /dev/null and b/docs/management/images/management-license.png differ diff --git a/docs/images/management-rollup-index-pattern.png b/docs/management/images/management-rollup-index-pattern.png similarity index 100% rename from docs/images/management-rollup-index-pattern.png rename to docs/management/images/management-rollup-index-pattern.png diff --git a/docs/images/management-saved-objects.png b/docs/management/images/management-saved-objects.png similarity index 100% rename from docs/images/management-saved-objects.png rename to docs/management/images/management-saved-objects.png diff --git a/docs/images/management-upgrade-assistant-9.0.png b/docs/management/images/management-upgrade-assistant-9.0.png similarity index 100% rename from docs/images/management-upgrade-assistant-9.0.png rename to docs/management/images/management-upgrade-assistant-9.0.png diff --git a/docs/images/management_create_rollup_job.png b/docs/management/images/management_create_rollup_job.png similarity index 100% rename from docs/images/management_create_rollup_job.png rename to docs/management/images/management_create_rollup_job.png diff --git a/docs/images/management_create_rollup_menu.png b/docs/management/images/management_create_rollup_menu.png similarity index 100% rename from docs/images/management_create_rollup_menu.png rename to docs/management/images/management_create_rollup_menu.png diff --git a/docs/images/management_index_create_wizard.png b/docs/management/images/management_index_create_wizard.png similarity index 100% rename from docs/images/management_index_create_wizard.png rename to docs/management/images/management_index_create_wizard.png diff --git a/docs/images/management_index_details.png b/docs/management/images/management_index_details.png similarity index 100% rename from docs/images/management_index_details.png rename to docs/management/images/management_index_details.png diff --git a/docs/images/management_index_labels.png b/docs/management/images/management_index_labels.png similarity index 100% rename from docs/images/management_index_labels.png rename to docs/management/images/management_index_labels.png diff --git a/docs/images/management_rollup_job_dashboard.png b/docs/management/images/management_rollup_job_dashboard.png similarity index 100% rename from docs/images/management_rollup_job_dashboard.png rename to docs/management/images/management_rollup_job_dashboard.png diff --git a/docs/images/management_rollup_job_details.png b/docs/management/images/management_rollup_job_details.png similarity index 100% rename from docs/images/management_rollup_job_details.png rename to docs/management/images/management_rollup_job_details.png diff --git a/docs/images/management_rollup_job_vis.png b/docs/management/images/management_rollup_job_vis.png similarity index 100% rename from docs/images/management_rollup_job_vis.png rename to docs/management/images/management_rollup_job_vis.png diff --git a/docs/images/management_rollup_list.png b/docs/management/images/management_rollup_list.png similarity index 100% rename from docs/images/management_rollup_list.png rename to docs/management/images/management_rollup_list.png diff --git a/docs/images/remote-clusters-list-view.png b/docs/management/images/remote-clusters-list-view.png similarity index 100% rename from docs/images/remote-clusters-list-view.png rename to docs/management/images/remote-clusters-list-view.png diff --git a/docs/images/settings-read-only-badge.png b/docs/management/images/settings-read-only-badge.png similarity index 100% rename from docs/images/settings-read-only-badge.png rename to docs/management/images/settings-read-only-badge.png diff --git a/docs/images/tutorial-ilm-custom-policy.png b/docs/management/images/tutorial-ilm-custom-policy.png similarity index 100% rename from docs/images/tutorial-ilm-custom-policy.png rename to docs/management/images/tutorial-ilm-custom-policy.png diff --git a/docs/images/tutorial-ilm-delete-phase-creation.png b/docs/management/images/tutorial-ilm-delete-phase-creation.png similarity index 100% rename from docs/images/tutorial-ilm-delete-phase-creation.png rename to docs/management/images/tutorial-ilm-delete-phase-creation.png diff --git a/docs/images/tutorial-ilm-delete-rollover.png b/docs/management/images/tutorial-ilm-delete-rollover.png similarity index 100% rename from docs/images/tutorial-ilm-delete-rollover.png rename to docs/management/images/tutorial-ilm-delete-rollover.png diff --git a/docs/images/tutorial-ilm-hotphaserollover-default.png b/docs/management/images/tutorial-ilm-hotphaserollover-default.png similarity index 100% rename from docs/images/tutorial-ilm-hotphaserollover-default.png rename to docs/management/images/tutorial-ilm-hotphaserollover-default.png diff --git a/docs/images/tutorial-ilm-modify-default-warm-phase-rollover.png b/docs/management/images/tutorial-ilm-modify-default-warm-phase-rollover.png similarity index 100% rename from docs/images/tutorial-ilm-modify-default-warm-phase-rollover.png rename to docs/management/images/tutorial-ilm-modify-default-warm-phase-rollover.png diff --git a/docs/management/managing-licenses.asciidoc b/docs/management/managing-licenses.asciidoc index 6cd6657a0aaeb..99cfd12eeade9 100644 --- a/docs/management/managing-licenses.asciidoc +++ b/docs/management/managing-licenses.asciidoc @@ -1,28 +1,27 @@ [[managing-licenses]] == License Management -When you install the default distribution of {kib}, you receive a basic license -with no expiration date. For the full list of free features that are included in -the basic license, refer to https://www.elastic.co/subscriptions[the subscription page]. +When you install the default distribution of {kib}, you receive free features +with no expiration date. For the full list of features, refer to +{subscriptions}. -If you want to try out the full set of platinum features, you can activate a -30-day trial license. To view the -status of your license, start a trial, or install a new license, open the menu, then go to *Stack Management > {es} > License Management*. +If you want to try out the full set of features, you can activate a free 30-day +trial. To view the status of your license, start a trial, or install a new +license, open the menu, then go to *Stack Management > {es} > License Management*. NOTE: You can start a trial only if your cluster has not already activated a trial license for the current major product version. For example, if you have already activated a trial for 6.0, you cannot start a new trial until -7.0. You can, however, contact `info@elastic.co` to request an extended trial -license. +7.0. You can, however, request an extended trial at {extendtrial}. When you activate a new license level, new features appear in *Stack Management*. [role="screenshot"] image::images/management-license.png[] -At the end of the trial period, the platinum features operate in a -<>. You can revert to a basic license, -extend the trial, or purchase a subscription. +At the end of the trial period, some features operate in a +<>. You can revert to Basic, extend the trial, +or purchase a subscription. TIP: If {security-features} are enabled, unless you have a trial license, you must configure Transport Layer Security (TLS) in {es}. diff --git a/docs/maps/connect-to-ems.asciidoc b/docs/maps/connect-to-ems.asciidoc index 2b88ffe2e2dda..45ced2e64aa73 100644 --- a/docs/maps/connect-to-ems.asciidoc +++ b/docs/maps/connect-to-ems.asciidoc @@ -19,7 +19,7 @@ Maps makes requests directly from the browser to EMS. To connect to EMS when your Kibana server and browser are in an internal network: . Set `map.proxyElasticMapsServiceInMaps` to `true` in your <> file to proxy EMS requests through the Kibana server. -. Update your firewall rules to whitelist connections from your Kibana server to the EMS domains. +. Update your firewall rules to allow connections from your Kibana server to the EMS domains. NOTE: Coordinate map and region map visualizations do not support `map.proxyElasticMapsServiceInMaps` and will not proxy EMS requests through the Kibana server. diff --git a/docs/migration/migrate_8_0.asciidoc b/docs/migration/migrate_8_0.asciidoc index 82798e948822a..b80503750a26e 100644 --- a/docs/migration/migrate_8_0.asciidoc +++ b/docs/migration/migrate_8_0.asciidoc @@ -115,12 +115,17 @@ URL that it derived from the actual server address and `xpack.security.public` s *Impact:* Any workflow that involved manually clearing generated bundles will have to be updated with the new path. +[float]] +=== kibana.keystore has moved from the `data` folder to the `config` folder +*Details:* By default, kibana.keystore has moved from the configured `path.data` folder to `/config` for archive distributions +and `/etc/kibana` for package distributions. If a pre-existing keystore exists in the data directory that path will continue to be used. + [float] [[breaking_80_user_role_changes]] === User role changes [float] -==== `kibana_user` role has been removed and `kibana_admin` has been added. +=== `kibana_user` role has been removed and `kibana_admin` has been added. *Details:* The `kibana_user` role has been removed and `kibana_admin` has been added to better reflect its intended use. This role continues to grant all access to every diff --git a/docs/settings/apm-settings.asciidoc b/docs/settings/apm-settings.asciidoc index f78b0642f7fa3..b396c40aa21f9 100644 --- a/docs/settings/apm-settings.asciidoc +++ b/docs/settings/apm-settings.asciidoc @@ -47,7 +47,7 @@ Changing these settings may disable features of the APM App. | Set to `false` to hide the APM app from the menu. Defaults to `true`. | `xpack.apm.ui.transactionGroupBucketSize` - | Number of top transaction groups displayed in the APM app. Defaults to `100`. + | Number of top transaction groups displayed in the APM app. Defaults to `1000`. | `xpack.apm.ui.maxTraceItems` {ess-icon} | Maximum number of child items displayed when viewing trace details. Defaults to `1000`. diff --git a/docs/settings/ingest-manager-settings.asciidoc b/docs/settings/ingest-manager-settings.asciidoc index f46c769079040..30e11f726c26b 100644 --- a/docs/settings/ingest-manager-settings.asciidoc +++ b/docs/settings/ingest-manager-settings.asciidoc @@ -8,8 +8,7 @@ experimental[] You can configure `xpack.ingestManager` settings in your `kibana.yml`. -By default, {ingest-manager} is not enabled. You need to -enable it. To use {fleet}, you also need to configure {kib} and {es} hosts. +By default, {ingest-manager} is enabled. To use {fleet}, you also need to configure {kib} and {es} hosts. See the {ingest-guide}/index.html[Ingest Management] docs for more information. @@ -19,9 +18,7 @@ See the {ingest-guide}/index.html[Ingest Management] docs for more information. [cols="2*<"] |=== | `xpack.ingestManager.enabled` {ess-icon} - | Set to `true` to enable {ingest-manager}. -| `xpack.ingestManager.epm.enabled` {ess-icon} - | Set to `true` (default) to enable {package-manager}. + | Set to `true` (default) to enable {ingest-manager}. | `xpack.ingestManager.fleet.enabled` {ess-icon} | Set to `true` (default) to enable {fleet}. |=== @@ -32,7 +29,7 @@ See the {ingest-guide}/index.html[Ingest Management] docs for more information. [cols="2*<"] |=== -| `xpack.ingestManager.epm.registryUrl` +| `xpack.ingestManager.registryUrl` | The address to use to reach {package-manager} registry. |=== diff --git a/docs/images/add-data-fv.png b/docs/setup/images/add-data-fv.png similarity index 100% rename from docs/images/add-data-fv.png rename to docs/setup/images/add-data-fv.png diff --git a/docs/images/add-data-tutorials.png b/docs/setup/images/add-data-tutorials.png similarity index 100% rename from docs/images/add-data-tutorials.png rename to docs/setup/images/add-data-tutorials.png diff --git a/docs/images/data-viz-homepage.jpg b/docs/setup/images/data-viz-homepage.jpg similarity index 100% rename from docs/images/data-viz-homepage.jpg rename to docs/setup/images/data-viz-homepage.jpg diff --git a/docs/images/kibana-status-page-7_5_0.png b/docs/setup/images/kibana-status-page-7_5_0.png similarity index 100% rename from docs/images/kibana-status-page-7_5_0.png rename to docs/setup/images/kibana-status-page-7_5_0.png diff --git a/docs/setup/production.asciidoc b/docs/setup/production.asciidoc index 72f275e237490..afb4b37df6a28 100644 --- a/docs/setup/production.asciidoc +++ b/docs/setup/production.asciidoc @@ -167,9 +167,9 @@ These can be used to automatically update the list of hosts as a cluster is resi Kibana has a default maximum memory limit of 1.4 GB, and in most cases, we recommend leaving this unconfigured. In some scenarios, such as large reporting jobs, it may make sense to tweak limits to meet more specific requirements. -You can modify this limit by setting `--max-old-space-size` in the `NODE_OPTIONS` environment variable. For deb and rpm, packages this is passed in via `/etc/default/kibana` and can be appended to the bottom of the file. +You can modify this limit by setting `--max-old-space-size` in the `node.options` config file that can be found inside `kibana/config` folder or any other configured with the environment variable `KIBANA_PATH_CONF` (for example in debian based system would be `/etc/kibana`). The option accepts a limit in MB: -------- -NODE_OPTIONS="--max-old-space-size=2048" bin/kibana +--max-old-space-size=2048 -------- diff --git a/docs/uptime-guide/alerting.asciidoc b/docs/uptime-guide/alerting.asciidoc deleted file mode 100644 index bf9e7693fc7a5..0000000000000 --- a/docs/uptime-guide/alerting.asciidoc +++ /dev/null @@ -1,33 +0,0 @@ -[role="xpack"] -[[uptime-alerting]] - -=== Uptime alerting - -The Uptime app integrates with Kibana's {kibana-ref}/alerting-getting-started.html[alerting and actions] -feature. It provides a set of built-in actions and Uptime specific threshold alerts for you to use -and enables central management of all alerts from {kibana-ref}/management.html[Kibana Management]. - -[role="screenshot"] -image::images/create-alert.png[Create alert] - -[float] -==== Monitor status alerts - -To receive alerts when a monitor goes down, use the alerting menu at the top of the -overview page. Use a query in the alert flyout to determine which monitors to check -with your alert. If you already have a query in the overview page search bar it will -be carried over into this box. - -[role="screenshot"] -image::images/monitor-status-alert.png[Create monitor status alert flyout] - -[float] -==== TLS alerts - -Uptime also provides the ability to create an alert that will notify you when one or -more of your monitors have a TLS certificate that will expire within some threshold, -or when its age exceeds a limit. The values for these thresholds are configurable on -the <>. - -[role="screenshot"] -image::images/tls-alert.png[Create TLS alert flyout] diff --git a/docs/uptime-guide/app-overview.asciidoc b/docs/uptime-guide/app-overview.asciidoc deleted file mode 100644 index 692489a7ad311..0000000000000 --- a/docs/uptime-guide/app-overview.asciidoc +++ /dev/null @@ -1,70 +0,0 @@ -[role="xpack"] -[[uptime-app]] -== Uptime app - -The Uptime app in {kib} enables you to monitor the status of network endpoints via HTTP/S, TCP, and ICMP. -You can explore endpoint status over time, drill down into specific monitors, -and view a high-level snapshot of your environment at any point in time. - -[role="screenshot"] -image::images/uptime-overview.png[Uptime app overview] - -[role="xpack"] -[[uptime-app-overview]] -=== Overview - -The Uptime overview helps you quickly identify and diagnose outages and -other connectivity issues within your network or environment. You can use the date range -selection that is global to the Uptime app, to highlight -an absolute date range, or a relative one, similar to other areas of {kib}. - -[float] -=== Filter bar - -The Filter bar enables you to quickly view specific groups of monitors, or even -an individual monitor if you have defined many. - -This control allows you to use automated filter options, as well as input custom filter -text to select specific monitors by field, URL, ID, and other attributes. - -[role="screenshot"] -image::images/filter-bar.png[Filter bar] - -[float] -=== Snapshot panel - -The Snapshot panel displays the overall -status of the environment you're monitoring or a subset of those monitors. -You can see the total number of detected monitors within the selected -Uptime date range, along with the number of monitors -in an `up` or `down` state, which is based on the last check reported by Heartbeat -for each monitor. - -Next to the counts, there is a histogram displaying the change over time throughout the -selected date range. - -[role="screenshot"] -image::images/snapshot-view.png[Snapshot view] - -[float] -=== Monitor list - -Information about individual monitors is displayed in the monitor list and provides a quick -way to navigate to a more in-depth visualization for interesting hosts or endpoints. - -The information displayed includes the recent status of a host or endpoint, when the monitor was last checked, its -ID and URL, and its IP address. There is also sparkline showing its check status over time. - -[role="screenshot"] -image::images/monitor-list.png[Monitor list] - -[float] -=== Observability integrations - -The Monitor list also contains a menu of available integrations. When Uptime detects Kubernetes or -Docker related host information, it provides links to open the Metrics app or Logs app pre-filtered -for this host. Additionally, to help you quickly determine if these solutions contain data relevant to you, -this feature contains links to filter the other views on the host's IP address. - -[role="screenshot"] -image::images/observability_integrations.png[Observability integrations] diff --git a/docs/uptime-guide/certificates.asciidoc b/docs/uptime-guide/certificates.asciidoc deleted file mode 100644 index 58db91aa080eb..0000000000000 --- a/docs/uptime-guide/certificates.asciidoc +++ /dev/null @@ -1,15 +0,0 @@ -[role="xpack"] -[[uptime-certificates]] - -=== Certificates - -The certificates page enables you to visualize TLS certificate data in your indices. In addition to the -common name, associated monitors, issuer information, and SHA fingerprints, Uptime also assigns a status -derived from the threshold values in the <>. - -Several of the columns on this page are sortable. You can use the search bar at the top of the view -to find values in most of the TLS-related fields in your Uptime indices. Additionally, using the `Alerts` -dropdown at the top of the page you can create a TLS alert. - -[role="screenshot"] -image::images/certificates-page.png[Certificates] diff --git a/docs/uptime-guide/deployment-arch.asciidoc b/docs/uptime-guide/deployment-arch.asciidoc deleted file mode 100644 index c1b2f596c6665..0000000000000 --- a/docs/uptime-guide/deployment-arch.asciidoc +++ /dev/null @@ -1,27 +0,0 @@ -[role="xpack"] -[[uptime-deployment-arch]] -== Deployment Architecture - -There are multiple ways to deploy Uptime and Heartbeat. -Use the information in this section to determine the best deployment for you. -A guiding principle is that when an outage takes down the service being monitored it should not also take down Heartbeat. -You want Heartbeat to be functioning even when your service is not, so the guidelines here help you maximize this possibility. - -Heartbeat is commonly run as a centralized service within a data center. -While it is possible to run it as a separate "sidecar" process paired with each process/container, we recommend against it. -Running Heartbeat centrally ensures you will still be able to see monitoring data in the event of an overloaded, disconnected, or otherwise malfunctioning server. - -For further redundancy, you may want to deploy multiple Heartbeats across geographic and network boundaries to provide more data. -To do so, specify Heartbeat's observer {heartbeat-ref}/configuration-observer-options.html[geo options]. - -Some examples might be: - -* **A site served from a content delivery network (CDN) with points of presence (POPs) around the globe:** -To check if your site is reachable via CDN POPS, you may want to have multiple Heartbeat instances at different data centers around the world. -* **A service within a single data center that is accessed across multiple VPNs:** -Set up one Heartbeat instance within the VPN the service operates from, and another within an additional VPN that users access the service from. -Having both instances helps pinpoint network errors in the event of an outage. -* **A single service running primarily in a US east coast data center, with a hot failover located in a US west coast data center:** -In each data center, run a Heartbeat instance that checks both the local copy of the service and its counterpart across the country. -Set up two monitors in each region, one for the local service and one for the remote service. -In the event of a data center failure it will be immediately apparent if the service had a connectivity issue to the outside world or if the failure was only internal. diff --git a/docs/uptime-guide/images/cert-exp.png b/docs/uptime-guide/images/cert-exp.png deleted file mode 100644 index cd87668db96dd..0000000000000 Binary files a/docs/uptime-guide/images/cert-exp.png and /dev/null differ diff --git a/docs/uptime-guide/images/certificates-page.png b/docs/uptime-guide/images/certificates-page.png deleted file mode 100644 index 598aae982cd6a..0000000000000 Binary files a/docs/uptime-guide/images/certificates-page.png and /dev/null differ diff --git a/docs/uptime-guide/images/check-history.png b/docs/uptime-guide/images/check-history.png deleted file mode 100644 index aac5efd9b91d3..0000000000000 Binary files a/docs/uptime-guide/images/check-history.png and /dev/null differ diff --git a/docs/uptime-guide/images/create-alert.png b/docs/uptime-guide/images/create-alert.png deleted file mode 100644 index 54a0c400cad4c..0000000000000 Binary files a/docs/uptime-guide/images/create-alert.png and /dev/null differ diff --git a/docs/uptime-guide/images/crosshair-example.png b/docs/uptime-guide/images/crosshair-example.png deleted file mode 100644 index f9e89c4f622e0..0000000000000 Binary files a/docs/uptime-guide/images/crosshair-example.png and /dev/null differ diff --git a/docs/uptime-guide/images/filter-bar.png b/docs/uptime-guide/images/filter-bar.png deleted file mode 100644 index b7c424d3d0d91..0000000000000 Binary files a/docs/uptime-guide/images/filter-bar.png and /dev/null differ diff --git a/docs/uptime-guide/images/indices.png b/docs/uptime-guide/images/indices.png deleted file mode 100644 index 4090747b6726c..0000000000000 Binary files a/docs/uptime-guide/images/indices.png and /dev/null differ diff --git a/docs/uptime-guide/images/monitor-charts.png b/docs/uptime-guide/images/monitor-charts.png deleted file mode 100644 index 522f34662657e..0000000000000 Binary files a/docs/uptime-guide/images/monitor-charts.png and /dev/null differ diff --git a/docs/uptime-guide/images/monitor-list.png b/docs/uptime-guide/images/monitor-list.png deleted file mode 100644 index c9a8eccf01f6e..0000000000000 Binary files a/docs/uptime-guide/images/monitor-list.png and /dev/null differ diff --git a/docs/uptime-guide/images/monitor-status-alert.png b/docs/uptime-guide/images/monitor-status-alert.png deleted file mode 100644 index 847a0f58f02ce..0000000000000 Binary files a/docs/uptime-guide/images/monitor-status-alert.png and /dev/null differ diff --git a/docs/uptime-guide/images/observability_integrations.png b/docs/uptime-guide/images/observability_integrations.png deleted file mode 100644 index 3b23aa2dbd2a5..0000000000000 Binary files a/docs/uptime-guide/images/observability_integrations.png and /dev/null differ diff --git a/docs/uptime-guide/images/settings.png b/docs/uptime-guide/images/settings.png deleted file mode 100644 index d19b7f842ea68..0000000000000 Binary files a/docs/uptime-guide/images/settings.png and /dev/null differ diff --git a/docs/uptime-guide/images/snapshot-view.png b/docs/uptime-guide/images/snapshot-view.png deleted file mode 100644 index b6f07fb0721aa..0000000000000 Binary files a/docs/uptime-guide/images/snapshot-view.png and /dev/null differ diff --git a/docs/uptime-guide/images/status-bar.png b/docs/uptime-guide/images/status-bar.png deleted file mode 100644 index fd72e2b78c2a0..0000000000000 Binary files a/docs/uptime-guide/images/status-bar.png and /dev/null differ diff --git a/docs/uptime-guide/images/tls-alert.png b/docs/uptime-guide/images/tls-alert.png deleted file mode 100644 index 19efe07838903..0000000000000 Binary files a/docs/uptime-guide/images/tls-alert.png and /dev/null differ diff --git a/docs/uptime-guide/images/uptime-multi-deployment.png b/docs/uptime-guide/images/uptime-multi-deployment.png deleted file mode 100644 index 5440d91e48e23..0000000000000 Binary files a/docs/uptime-guide/images/uptime-multi-deployment.png and /dev/null differ diff --git a/docs/uptime-guide/images/uptime-overview.png b/docs/uptime-guide/images/uptime-overview.png deleted file mode 100644 index 25c88b2d14287..0000000000000 Binary files a/docs/uptime-guide/images/uptime-overview.png and /dev/null differ diff --git a/docs/uptime-guide/images/uptime-setup.png b/docs/uptime-guide/images/uptime-setup.png deleted file mode 100644 index 398125202fc4a..0000000000000 Binary files a/docs/uptime-guide/images/uptime-setup.png and /dev/null differ diff --git a/docs/uptime-guide/images/uptime-simple-deployment.png b/docs/uptime-guide/images/uptime-simple-deployment.png deleted file mode 100644 index f46dfdb2b8b86..0000000000000 Binary files a/docs/uptime-guide/images/uptime-simple-deployment.png and /dev/null differ diff --git a/docs/uptime-guide/index.asciidoc b/docs/uptime-guide/index.asciidoc deleted file mode 100644 index 01a93cb454ea9..0000000000000 --- a/docs/uptime-guide/index.asciidoc +++ /dev/null @@ -1,22 +0,0 @@ - -include::{asciidoc-dir}/../../shared/versions/stack/{source_branch}.asciidoc[] -include::{asciidoc-dir}/../../shared/attributes.asciidoc[] - -= Uptime monitoring guide - -include::overview.asciidoc[] - -include::install.asciidoc[] - -include::deployment-arch.asciidoc[] - -include::app-overview.asciidoc[] - -include::monitor.asciidoc[] - -include::settings.asciidoc[] - -include::certificates.asciidoc[] - -include::alerting.asciidoc[] - diff --git a/docs/uptime-guide/install.asciidoc b/docs/uptime-guide/install.asciidoc deleted file mode 100644 index 05b9c6665562f..0000000000000 --- a/docs/uptime-guide/install.asciidoc +++ /dev/null @@ -1,74 +0,0 @@ -[[install-uptime]] -== Install Uptime - -The easiest way to get started with Elastic Uptime is by using our hosted {es} Service on Elastic Cloud. -The {es} Service is available on both AWS and GCP, -and automatically configures {es} and {kib}. - -[float] -=== Hosted Elasticsearch Service - -Skip managing your own {es} and {kib} instance by using our -https://www.elastic.co/cloud/elasticsearch-service[hosted {es} Service] on -Elastic Cloud. - -{ess-trial}[Try out the {es} Service for free], -then jump straight to <>. - -[float] -[[before-installation]] -=== Install the stack yourself - -If you'd rather install the stack yourself, -first see the https://www.elastic.co/support/matrix[Elastic Support Matrix] for information about supported operating systems and product compatibility. - -* <> -* <> -* <> - -[[install-elasticsearch]] -=== Step 1: Install Elasticsearch - -Install an {es} cluster, start it up, and make sure it's running. - -. Verify that your system meets the -https://www.elastic.co/support/matrix#matrix_jvm[minimum JVM requirements] for {es}. -. {stack-gs}/get-started-elastic-stack.html#install-elasticsearch[Install Elasticsearch]. -. {stack-gs}/get-started-elastic-stack.html#_make_sure_elasticsearch_is_up_and_running[Make sure elasticsearch is up and running]. - -[[install-kibana]] -=== Step 2: Install Kibana - -Install {kib}, start it up, and open up the web interface: - -. {stack-gs}/get-started-elastic-stack.html#install-kibana[Install Kibana]. -. {stack-gs}/get-started-elastic-stack.html#_launch_the_kibana_web_interface[Launch the Kibana Web Interface]. - -[[install-heartbeat]] -=== Step 3: Install and configure Heartbeat - -Uptime requires the setup of monitors in Heartbeat. -These monitors provide the data you'll be visualizing in the {kibana-ref}/xpack-uptime.html[Uptime app]. - -For instructions on installing and configuring Heartbeat, see the *Setup Instructions* in {kib}. -Additional information is available in {heartbeat-ref}/heartbeat-configuration.html[Configure Heartbeat]. - -[role="screenshot"] -image::images/uptime-setup.png[Installation instructions on the Uptime page in Kibana] - -[[setup-security]] -=== Step 4: Set up Security - -Secure your installation by following the {heartbeat-ref}/securing-heartbeat.html[Secure Heartbeat] documentation. - -[float] -==== Important considerations - -* Make sure you're using the same major versions of Heartbeat and {kib}. - -* Index patterns tell {kib} which {es} indices you want to explore. -The Uptime app requires a +heartbeat-{major-version-only}*+ index pattern. -If you have configured a different index pattern, you can use {ref}/indices-aliases.html[index aliases] to ensure data is recognized by the Uptime app. - -After you install and configure Heartbeat, -the {kibana-ref}/xpack-uptime.html[Uptime app] is automatically populated with the Heartbeat monitors. diff --git a/docs/uptime-guide/monitor.asciidoc b/docs/uptime-guide/monitor.asciidoc deleted file mode 100644 index bb5d315cf63eb..0000000000000 --- a/docs/uptime-guide/monitor.asciidoc +++ /dev/null @@ -1,59 +0,0 @@ -[role="xpack"] -[[uptime-monitor]] -=== Monitor - -The Monitor page helps you gain insights into the performance -of a specific network endpoint. A detailed visualization of -the monitor's request duration over time, as well as the `up`/`down` -status over time, is displayed. By configuring Machine Learning jobs -on this page, you can also also detect anomalies in response time data. - - -==== Status panel - -The Status panel displays a quick summary of the latest information -regarding your monitor. You can view its latest status, click a link to -visit the targeted URL, see its most recent request duration, and determine the -amount of time that has elapsed since the last check. - -When two Heartbeat instances are configured in different geographic locations -the map will show each location as a pinpoint on the map, along with the -amount of time elapsed since data was last received from that location. - -[role="screenshot"] -image::images/status-bar.png[Status bar] - - -[float] -==== Monitor charts - -The Monitor charts visualize information over the time specified in the -date range. These charts help you gain insights into how quickly requests are being resolved -by the targeted endpoint, and give you a sense of how frequently a host or endpoint -was down in your selected timespan. - -[role="screenshot"] -image::images/monitor-charts.png[Monitor charts] - -The Monitor duration chart displays request duration information for your monitor. -The area surrounding the line is the range of request time for the corresponding -bucket. The line is the average time. In the upper right hand of this panel -you can enable Anomaly detection using Machine Learning. When response times change -in an unexpected way the time range in which they occurred are highlighted with a color. - -The pings over time chart is a graphical representation of the check statuses over time. -Hover over the charts to display crosshairs with specific numeric data. - -[role="screenshot"] -image::images/crosshair-example.png[Chart crosshair] - -[float] -==== Check history - -The Check history table lists the total count of this monitor's checks for the selected -date range. To help find recent problems on a per-check basis, you can filter the checks -by status and location. This table can help you gain some insight into more granular details -about recent individual data points that Heartbeat is logging about your host or endpoint. - -[role="screenshot"] -image::images/check-history.png[Check history view] diff --git a/docs/uptime-guide/overview.asciidoc b/docs/uptime-guide/overview.asciidoc deleted file mode 100644 index ab230b27f8cda..0000000000000 --- a/docs/uptime-guide/overview.asciidoc +++ /dev/null @@ -1,57 +0,0 @@ -[role="xpack"] -[[uptime-overview]] -== Elastic Uptime overview - -++++ -Overview -++++ - -Elastic Uptime enables you to monitor the availability and response times of applications and services in real time and to detect problems before they affect users. - -Elastic Uptime helps you to understand uptime and response time characteristics for your services and applications. -It can be deployed both inside and outside your organization's network, so that you can analyze problems from multiple vantage points. - -Elastic Uptime uses these components: *Heartbeat*, *Elasticsearch* and *Kibana*. - -[float] -=== Heartbeat - -{heartbeat-ref}/index.html[Heartbeat] is an open source data shipper that performs uptime monitoring. -Elastic Uptime uses Heartbeat to collect monitoring data from your target applications and services, and ship it to Elasticsearch. - -[float] -=== Elasticsearch - -{ref}/index.html[Elasticsearch] is a highly scalable, open source, search and analytics engine. -Elasticsearch can store, search, and analyze large volumes of data in near real-time. -Elastic Uptime uses Elasticsearch to store monitoring data from Heartbeat in Elasticsearch documents. - -[float] -=== Kibana - -{kibana-ref}/index.html[Kibana] is an open source analytics and visualization platform designed to work with Elasticsearch. -You can use Kibana to search, view, and interact with data stored in Elasticsearch. -You can easily perform advanced data analysis and visualize your data in a variety of charts, tables, and maps. - -The {kibana-ref}/xpack-uptime.html[Elasticsearch Uptime app] in Kibana provides a dedicated user interface for viewing uptime data and identifying problem areas. - -[float] -=== Example deployments -// ++ I like the Infra/logging diagram which shows Metrics and Logging apps as separate components inside Kibana -// ++ In diagram, should be Uptime app, not Uptime UI, possibly even Elastic Uptime? Also applies to Metrics/Logging/APM. -// ++ Need more whitespace around components. - -In this simple deployment, a single instance of Heartbeat is deployed at a single monitoring location to monitor a single service. -The Heartbeat instance sends the monitoring data to Elasticsearch. -Then you can use the Uptime app in Kibana to view the data from Heartbeat and determine the status of the service. - -image::images/uptime-simple-deployment.png[Uptime simple deployment] - -In this deployment, two instances of Heartbeat are deployed at two different monitoring locations. -Both instances monitor the same service. -The Heartbeat instances send the monitoring data to Elasticsearch. -As before, you can use the Uptime app in Kibana to view the Heartbeat data and determine the status of the service. -When a failure occurs, the multiple monitoring locations enable you to pinpoint the area in which the failure has occurred. - -image::images/uptime-multi-deployment.png[Uptime multiple server deployment] - diff --git a/docs/uptime-guide/settings.asciidoc b/docs/uptime-guide/settings.asciidoc deleted file mode 100644 index 59f9af631bfa7..0000000000000 --- a/docs/uptime-guide/settings.asciidoc +++ /dev/null @@ -1,51 +0,0 @@ -[role="xpack"] -[[uptime-settings]] - -=== Settings - -The Uptime settings page lets you change which Heartbeat indices are displayed -by the uptime app. Users must have the 'all' permission to modify items on this page. -Uptime settings apply to the current space only. Use different settings in different -spaces to segment different uptime use cases and domains. - -==== Indices - -Imagine your organization has one team for internal IT services, and another -for public services. Each team operates independently and is only responsible for its -own services. In this scenario, you might set up separate Heartbeat instances for each team, -writing out to index patterns named `it-heartbeat-\*`, and `external-heartbeat-\*`. You would -create separate roles and users for each in Elasticsearch, each with access to their own spaces, -named `it` and `external` respectively. Within each space you would navigate to the settings page -and set the correct index pattern to match only the indices that space is allowed to access. - -Note: The pattern set here only restricts what the Uptime app shows. Users may still be able -to manually query Elasticsearch for data outside this pattern. - -[role="screenshot"] -image::images/indices.png[Heartbeat indices] - -See the {kibana-ref}/uptime-security.html[Uptime security] and {heartbeat-ref}/securing-heartbeat.html[Heartbeat security] -docs for more information. - -==== Certificate thresholds - -You can modify settings in this section to control how Uptime will visualize your TLS values in -the <>. These settings also determine which certificates will be -selected by any TLS alert you define. - -There are two fields, `age` and `expiration`. Use the `age` threshold to specify when Uptime should warn -you about certificates that have been valid for too long. Use the `expiration` threshold to specify when Uptime should warn you -about certificates that have approaching expiration dates. - -For example, a common security requirement is to make sure that none of your organization's TLS certificates have been -valid for longer than one year. Modifying the `Age limit` field's value to 365 days will help you keep track of which -certificates you may want to refresh. - -Likewise, to see which of your TLS certificates are close to expiring ahead of time, specify -an `Expiration threshold` on this page. When the count of a certificate's remaining valid days falls -below this threshold, Uptime will consider it in a warning state. When you define a TLS alert, you receive a -notification from Uptime about the certificate. - -[role="screenshot"] -image::images/cert-exp.png[Certification expiration thresholds] - diff --git a/docs/user/alerting/action-types.asciidoc b/docs/user/alerting/action-types.asciidoc index e8dcf689df8e4..1743edb10f92b 100644 --- a/docs/user/alerting/action-types.asciidoc +++ b/docs/user/alerting/action-types.asciidoc @@ -23,6 +23,10 @@ a| <> | Add a message to a Kibana log. +a| <> + +| Push or update data to a new incident in ServiceNow. + a| <> | Send a message to a Slack channel or user. @@ -55,3 +59,4 @@ include::action-types/server-log.asciidoc[] include::action-types/slack.asciidoc[] include::action-types/webhook.asciidoc[] include::action-types/pre-configured-connectors.asciidoc[] +include::action-types/servicenow.asciidoc[] diff --git a/docs/user/alerting/action-types/email.asciidoc b/docs/user/alerting/action-types/email.asciidoc index 4fb8a816d1ec9..f6a02b9038c02 100644 --- a/docs/user/alerting/action-types/email.asciidoc +++ b/docs/user/alerting/action-types/email.asciidoc @@ -77,3 +77,122 @@ Email actions have the following configuration properties: To, CC, BCC:: Each is a list of addresses. Addresses can be specified in `user@host-name` format, or in `name ` format. One of To, CC, or BCC must contain an entry. Subject:: The subject line of the email. Message:: The message text of the email. Markdown format is supported. + +[[configuring-email]] +==== Configuring email accounts + +The email action can send email using many popular SMTP email services. + +You configure the email action to send emails using the connector form. +For more information about configuring the email connector to work with different email +systems, refer to: + +* <> +* <> +* <> +* <> + +[float] +[[gmail]] +===== Sending email from Gmail + +Use the following email account settings to send email from the +https://mail.google.com[Gmail] SMTP service: + +[source,text] +-------------------------------------------------- + config: + host: smtp.gmail.com + port: 465 + secure: true + secrets: + user: + password: +-------------------------------------------------- +// CONSOLE + +If you get an authentication error that indicates that you need to continue the +sign-in process from a web browser when the action attempts to send email, you need +to configure Gmail to https://support.google.com/accounts/answer/6010255?hl=en[allow +less secure apps to access your account]. + +If two-step verification is enabled for your account, you must generate and use +a unique App Password to send email from {watcher}. See +https://support.google.com/accounts/answer/185833?hl=en[Sign in using App Passwords] +for more information. + +[float] +[[outlook]] +===== Sending email from Outlook.com + +Use the following email account settings to send email action from the +https://www.outlook.com/[Outlook.com] SMTP service: + +[source,text] +-------------------------------------------------- +config: + host: smtp-mail.outlook.com + port: 465 + secure: true +secrets: + user: + password: +-------------------------------------------------- + +When sending emails, you must provide a from address, either as the default +in your account configuration or as part of the email action in the watch. + +NOTE: You must use a unique App Password if two-step verification is enabled. + See http://windows.microsoft.com/en-us/windows/app-passwords-two-step-verification[App + passwords and two-step verification] for more information. + +[float] +[[amazon-ses]] +===== Sending email from Amazon SES (Simple Email Service) + +Use the following email account settings to send email from the +http://aws.amazon.com/ses[Amazon Simple Email Service] (SES) SMTP service: + +[source,text] +-------------------------------------------------- +config: + host: email-smtp.us-east-1.amazonaws.com <1> + port: 465 + secure: true +secrets: + user: + password: +-------------------------------------------------- +<1> `smtp.host` varies depending on the region + +NOTE: You must use your Amazon SES SMTP credentials to send email through + Amazon SES. For more information, see + http://docs.aws.amazon.com/ses/latest/DeveloperGuide/smtp-credentials.html[Obtaining + Your Amazon SES SMTP Credentials]. You might also need to verify + https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-email-addresses.html[your email address] + or https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-domains.html[your whole domain] + at AWS. + +[float] +[[exchange]] +===== Sending email from Microsoft Exchange + +Use the following email account settings to send email action from Microsoft +Exchange: + +[source,text] +-------------------------------------------------- +config: + host: + port: 465 + secure: true + from: <1> +secrets: + user: <2> + password: +-------------------------------------------------- +<1> Some organizations configure Exchange to validate that the `from` field is a + valid local email account. +<2> Many organizations support use of your email address as your username. + Check with your system administrator if you receive + authentication-related failures. diff --git a/docs/user/alerting/action-types/index.asciidoc b/docs/user/alerting/action-types/index.asciidoc index 115423086bae3..3a57c44494394 100644 --- a/docs/user/alerting/action-types/index.asciidoc +++ b/docs/user/alerting/action-types/index.asciidoc @@ -2,7 +2,7 @@ [[index-action-type]] === Index action -The index action type will index a document into {es}. +The index action type will index a document into {es}. See also the {ref}/indices-create-index.html[create index API]. [float] [[index-connector-configuration]] @@ -53,4 +53,38 @@ Execution time field:: This field will be automatically set to the time the ale Index actions have the following properties: -Document:: The document to index in json format. +Document:: The document to index in JSON format. + +Example of the index document for Index Threshold alert: + +[source,text] +-------------------------------------------------- +{ + "alert_id": "{{alertId}}", + "alert_name": "{{alertName}}", + "alert_instance_id": "{{alertInstanceId}}", + "context_message": "{{context.message}}" +} +-------------------------------------------------- + +Example of create test index using the API. + +[source,text] +-------------------------------------------------- +PUT test +{ + "settings" : { + "number_of_shards" : 1 + }, + "mappings" : { + "_doc" : { + "properties" : { + "alert_id" : { "type" : "text" }, + "alert_name" : { "type" : "text" }, + "alert_instance_id" : { "type" : "text" }, + "context_message": { "type" : "text" } + } + } + } +} +-------------------------------------------------- diff --git a/docs/user/alerting/action-types/pagerduty.asciidoc b/docs/user/alerting/action-types/pagerduty.asciidoc index 0468ab042e57e..5fd85a1045265 100644 --- a/docs/user/alerting/action-types/pagerduty.asciidoc +++ b/docs/user/alerting/action-types/pagerduty.asciidoc @@ -68,11 +68,11 @@ Then, select the *Integrations* tab and click the *New Integration* button. * If you are creating a new service for your integration, go to https://support.pagerduty.com/docs/services-and-integrations#section-configuring-services-and-integrations[Configuring Services and Integrations] -and follow the steps outlined in the *Create a New Service* section, selecting *Elastic* as the *Integration Type* in step 4. +and follow the steps outlined in the *Create a New Service* section, selecting *Elastic Alerts* as the *Integration Type* in step 4. Continue with the <> section once you have finished these steps. . Enter an *Integration Name* in the format Elastic-service-name (for example, Elastic-Alerting or Kibana-APM-Alerting) -and select Elastic from the *Integration Type* menu. +and select *Elastic Alerts* from the *Integration Type* menu. . Click *Add Integration* to save your new integration. + You will be redirected to the *Integrations* tab for your service. An Integration Key is generated on this screen. diff --git a/docs/user/alerting/action-types/pre-configured-connectors.asciidoc b/docs/user/alerting/action-types/pre-configured-connectors.asciidoc index b1cf2d650e576..e3f1703f08e88 100644 --- a/docs/user/alerting/action-types/pre-configured-connectors.asciidoc +++ b/docs/user/alerting/action-types/pre-configured-connectors.asciidoc @@ -28,12 +28,12 @@ two out-of-the box connectors: <> and < actionTypeId: .slack <2> name: 'Slack #xyz' <3> - secrets: <4> + secrets: webhookUrl: 'https://hooks.slack.com/services/abcd/efgh/ijklmnopqrstuvwxyz' webhook-service: actionTypeId: .webhook name: 'Email service' - config: + config: <4> url: 'https://email-alert-service.elastic.co' method: post headers: diff --git a/docs/user/alerting/action-types/servicenow.asciidoc b/docs/user/alerting/action-types/servicenow.asciidoc new file mode 100644 index 0000000000000..32f828aea2357 --- /dev/null +++ b/docs/user/alerting/action-types/servicenow.asciidoc @@ -0,0 +1,72 @@ +[role="xpack"] +[[servicenow-action-type]] +=== ServiceNow action + +The ServiceNow action type uses the https://developer.servicenow.com/app.do#!/rest_api_doc?v=orlando&id=c_TableAPI[V2 Table API] to create ServiceNow incidents. + +[float] +[[servicenow-connector-configuration]] +==== Connector configuration + +ServiceNow connectors have the following configuration properties: + +Name:: The name of the connector. The name is used to identify a connector in the management UI connector listing, or in the connector list when configuring an action. +URL:: ServiceNow instance URL. +Username:: Username for HTTP Basic authentication. +Password:: Password for HTTP Basic authentication. + +[float] +[[Preconfigured-servicenow-configuration]] +==== Preconfigured action type + +[source,text] +-- + my-servicenow: + name: preconfigured-servicenow-action-type + actionTypeId: .servicenow + config: + apiUrl: https://dev94428.service-now.com/ + secrets: + username: testuser + password: passwordkeystorevalue +-- + +`config` defines the action type specific to the configuration and contains the following properties: + +[cols="2*<"] +|=== + +| `apiUrl` +| An address that corresponds to *Sender*. + +|=== + +`secrets` defines sensitive information for the action type: + +[cols="2*<"] +|=== + +| `username` +| A string that corresponds to *User*. + +| `password` +| A string that corresponds to *Password*. Should be stored in the <>. + +|=== + +[[servicenow-action-configuration]] +==== Action configuration + +ServiceNow actions have the following configuration properties: + +Urgency:: The extent to which the incident resolution can delay. +Severity:: The severity of the incident. +Impact:: The effect an incident has on business. Can be measured by the number of affected users or by how critical it is to the business in question. +Short description:: A short description of the incident, used for searching the contents of the knowledge base. +Description:: The details about the incident. +Additional comments:: Additional information for the client, such as how to troubleshoot the issue. + +[[configuring-servicenow]] +==== Configuring and testing ServiceNow + +ServiceNow offers free https://developer.servicenow.com/dev.do#!/guides/madrid/now-platform/pdi-guide/obtaining-a-pdi[Personal Developer Instances], which you can use to test incidents. diff --git a/docs/user/alerting/action-types/slack.asciidoc b/docs/user/alerting/action-types/slack.asciidoc index 5bad8a53f898c..99bf73c0f5597 100644 --- a/docs/user/alerting/action-types/slack.asciidoc +++ b/docs/user/alerting/action-types/slack.asciidoc @@ -38,3 +38,23 @@ Webhook URL:: The URL of the incoming webhook. See https://api.slack.com/messa Slack actions have the following properties: Message:: The message text, converted to the `text` field in the Webhook JSON payload. Currently only the text field is supported. Markdown, images, and other advanced formatting are not yet supported. + +[[configuring-slack]] +==== Configuring Slack Accounts + +You configure the accounts Slack action type can use to communicate with Slack in the +connector form. + +You need a https://api.slack.com/incoming-webhooks[Slack webhook URL] to +configure a Slack account. To create a webhook +URL, set up an an **Incoming Webhook Integration** through the Slack console: + +. Log in to http://slack.com[slack.com] as a team administrator. +. Go to https://my.slack.com/services/new/incoming-webhook. +. Select a default channel for the integration. ++ +image::images/slack-add-webhook-integration.png[] +. Click *Add Incoming Webhook Integration*. +. Copy the generated webhook URL so you can paste it into your Slack connector form. ++ +image::images/slack-copy-webhook-url.png[] diff --git a/docs/user/alerting/images/slack-add-webhook-integration.png b/docs/user/alerting/images/slack-add-webhook-integration.png new file mode 100644 index 0000000000000..347822ddd9fac Binary files /dev/null and b/docs/user/alerting/images/slack-add-webhook-integration.png differ diff --git a/docs/user/alerting/images/slack-copy-webhook-url.png b/docs/user/alerting/images/slack-copy-webhook-url.png new file mode 100644 index 0000000000000..0acc9488e22a3 Binary files /dev/null and b/docs/user/alerting/images/slack-copy-webhook-url.png differ diff --git a/docs/images/Dashboard_add_new_visualization.png b/docs/user/dashboard/images/Dashboard_add_new_visualization.png similarity index 100% rename from docs/images/Dashboard_add_new_visualization.png rename to docs/user/dashboard/images/Dashboard_add_new_visualization.png diff --git a/docs/images/Dashboard_add_visualization.png b/docs/user/dashboard/images/Dashboard_add_visualization.png similarity index 100% rename from docs/images/Dashboard_add_visualization.png rename to docs/user/dashboard/images/Dashboard_add_visualization.png diff --git a/docs/images/Dashboard_example.png b/docs/user/dashboard/images/Dashboard_example.png similarity index 100% rename from docs/images/Dashboard_example.png rename to docs/user/dashboard/images/Dashboard_example.png diff --git a/docs/images/Dashboard_inspect.png b/docs/user/dashboard/images/Dashboard_inspect.png similarity index 100% rename from docs/images/Dashboard_inspect.png rename to docs/user/dashboard/images/Dashboard_inspect.png diff --git a/docs/images/clone_panel.gif b/docs/user/dashboard/images/clone_panel.gif similarity index 100% rename from docs/images/clone_panel.gif rename to docs/user/dashboard/images/clone_panel.gif diff --git a/docs/images/dashboard-read-only-badge.png b/docs/user/dashboard/images/dashboard-read-only-badge.png similarity index 100% rename from docs/images/dashboard-read-only-badge.png rename to docs/user/dashboard/images/dashboard-read-only-badge.png diff --git a/docs/images/time_range_per_panel.gif b/docs/user/dashboard/images/time_range_per_panel.gif similarity index 100% rename from docs/images/time_range_per_panel.gif rename to docs/user/dashboard/images/time_range_per_panel.gif diff --git a/docs/images/intro-dashboard.png b/docs/user/introduction/images/intro-dashboard.png similarity index 100% rename from docs/images/intro-dashboard.png rename to docs/user/introduction/images/intro-dashboard.png diff --git a/docs/images/intro-data-tutorial.png b/docs/user/introduction/images/intro-data-tutorial.png similarity index 100% rename from docs/images/intro-data-tutorial.png rename to docs/user/introduction/images/intro-data-tutorial.png diff --git a/docs/images/intro-discover.png b/docs/user/introduction/images/intro-discover.png similarity index 100% rename from docs/images/intro-discover.png rename to docs/user/introduction/images/intro-discover.png diff --git a/docs/images/intro-kibana.png b/docs/user/introduction/images/intro-kibana.png similarity index 100% rename from docs/images/intro-kibana.png rename to docs/user/introduction/images/intro-kibana.png diff --git a/docs/images/intro-management.png b/docs/user/introduction/images/intro-management.png similarity index 100% rename from docs/images/intro-management.png rename to docs/user/introduction/images/intro-management.png diff --git a/docs/images/intro-spaces.jpg b/docs/user/introduction/images/intro-spaces.jpg similarity index 100% rename from docs/images/intro-spaces.jpg rename to docs/user/introduction/images/intro-spaces.jpg diff --git a/docs/user/ml/images/ml-annotations-list.jpg b/docs/user/ml/images/ml-annotations-list.jpg deleted file mode 100644 index 8b1194dd20c0f..0000000000000 Binary files a/docs/user/ml/images/ml-annotations-list.jpg and /dev/null differ diff --git a/docs/user/ml/images/ml-annotations-list.png b/docs/user/ml/images/ml-annotations-list.png new file mode 100644 index 0000000000000..f1a0b66241126 Binary files /dev/null and b/docs/user/ml/images/ml-annotations-list.png differ diff --git a/docs/user/ml/images/ml-job-management.jpg b/docs/user/ml/images/ml-job-management.jpg deleted file mode 100644 index efdf7923c0faa..0000000000000 Binary files a/docs/user/ml/images/ml-job-management.jpg and /dev/null differ diff --git a/docs/user/ml/images/ml-job-management.png b/docs/user/ml/images/ml-job-management.png new file mode 100644 index 0000000000000..4589c7093a7cf Binary files /dev/null and b/docs/user/ml/images/ml-job-management.png differ diff --git a/docs/user/ml/images/ml-settings.jpg b/docs/user/ml/images/ml-settings.jpg deleted file mode 100644 index 3713be005924d..0000000000000 Binary files a/docs/user/ml/images/ml-settings.jpg and /dev/null differ diff --git a/docs/user/ml/images/ml-settings.png b/docs/user/ml/images/ml-settings.png new file mode 100644 index 0000000000000..f5c9fca647389 Binary files /dev/null and b/docs/user/ml/images/ml-settings.png differ diff --git a/docs/user/ml/images/ml-single-metric-viewer.jpg b/docs/user/ml/images/ml-single-metric-viewer.jpg deleted file mode 100644 index 2fbb9387d1e29..0000000000000 Binary files a/docs/user/ml/images/ml-single-metric-viewer.jpg and /dev/null differ diff --git a/docs/user/ml/images/ml-single-metric-viewer.png b/docs/user/ml/images/ml-single-metric-viewer.png new file mode 100644 index 0000000000000..04c21d9bc533a Binary files /dev/null and b/docs/user/ml/images/ml-single-metric-viewer.png differ diff --git a/docs/user/ml/images/outliers.png b/docs/user/ml/images/outliers.png index 3f4c5f6c6bbf0..874ebbc79201c 100644 Binary files a/docs/user/ml/images/outliers.png and b/docs/user/ml/images/outliers.png differ diff --git a/docs/user/ml/index.asciidoc b/docs/user/ml/index.asciidoc index 1bc74ce87de08..214dae2b96e04 100644 --- a/docs/user/ml/index.asciidoc +++ b/docs/user/ml/index.asciidoc @@ -47,20 +47,20 @@ create {anomaly-jobs} and manage jobs and {dfeeds} from the *Job Management* pane: [role="screenshot"] -image::user/ml/images/ml-job-management.jpg[Job Management] +image::user/ml/images/ml-job-management.png[Job Management] You can use the *Settings* pane to create and edit {ml-docs}/ml-calendars.html[calendars] and the filters that are used in {ml-docs}/ml-rules.html[custom rules]: [role="screenshot"] -image::user/ml/images/ml-settings.jpg[Calendar Management] +image::user/ml/images/ml-settings.png[Calendar Management] The *Anomaly Explorer* and *Single Metric Viewer* display the results of your {anomaly-jobs}. For example: [role="screenshot"] -image::user/ml/images/ml-single-metric-viewer.jpg[Single Metric Viewer] +image::user/ml/images/ml-single-metric-viewer.png[Single Metric Viewer] You can optionally add annotations by drag-selecting a period of time in the *Single Metric Viewer* and adding a description. For example, you can add an @@ -68,7 +68,7 @@ explanation for anomalies in that time period or provide notes about what is occurring in your operational environment at that time: [role="screenshot"] -image::user/ml/images/ml-annotations-list.jpg[Single Metric Viewer with annotations] +image::user/ml/images/ml-annotations-list.png[Single Metric Viewer with annotations] In some circumstances, annotations are also added automatically. For example, if the {anomaly-job} detects that there is missing data, it annotates the affected @@ -94,8 +94,8 @@ The Elastic {ml} {dfanalytics} feature enables you to analyze your data using indices that contain the results alongside your source data. If you have a license that includes the {ml-features}, you can create -{dfanalytics-jobs} and view their results on the *Analytics* page -in {kib}. For example: +{dfanalytics-jobs} and view their results on the *Data Frame Analytics* page in +{kib}. For example: [role="screenshot"] image::user/ml/images/outliers.png[{oldetection-cap} results in {kib}] diff --git a/docs/images/monitoring-dashboard.png b/docs/user/monitoring/images/monitoring-dashboard.png similarity index 100% rename from docs/images/monitoring-dashboard.png rename to docs/user/monitoring/images/monitoring-dashboard.png diff --git a/docs/images/report-automate-csv.png b/docs/user/reporting/images/report-automate-csv.png similarity index 100% rename from docs/images/report-automate-csv.png rename to docs/user/reporting/images/report-automate-csv.png diff --git a/docs/images/report-automate-pdf.png b/docs/user/reporting/images/report-automate-pdf.png similarity index 100% rename from docs/images/report-automate-pdf.png rename to docs/user/reporting/images/report-automate-pdf.png diff --git a/docs/user/reporting/index.asciidoc b/docs/user/reporting/index.asciidoc index 4123912b79237..6acdbbe3f0a99 100644 --- a/docs/user/reporting/index.asciidoc +++ b/docs/user/reporting/index.asciidoc @@ -19,7 +19,7 @@ image::user/reporting/images/share-button.png["Share"] [float] == Setup -{reporting} is automatically enabled in {kib}. The first time {kib} runs, it extracts a custom build for the Chromium web browser, which +{reporting} is automatically enabled in {kib}. It runs a custom build of the Chromium web browser, which runs on the server in headless mode to load {kib} and capture the rendered {kib} charts as images. Chromium is an open-source project not related to Elastic, but the Chromium binary for {kib} has been custom-built by Elastic to ensure it diff --git a/docs/images/add-bucket.png b/docs/visualize/images/add-bucket.png similarity index 100% rename from docs/images/add-bucket.png rename to docs/visualize/images/add-bucket.png diff --git a/docs/images/apply-changes-button.png b/docs/visualize/images/apply-changes-button.png similarity index 100% rename from docs/images/apply-changes-button.png rename to docs/visualize/images/apply-changes-button.png diff --git a/docs/images/color-picker.png b/docs/visualize/images/color-picker.png similarity index 100% rename from docs/images/color-picker.png rename to docs/visualize/images/color-picker.png diff --git a/docs/images/dashboard-controls.png b/docs/visualize/images/dashboard-controls.png similarity index 100% rename from docs/images/dashboard-controls.png rename to docs/visualize/images/dashboard-controls.png diff --git a/docs/images/gauge.png b/docs/visualize/images/gauge.png similarity index 100% rename from docs/images/gauge.png rename to docs/visualize/images/gauge.png diff --git a/docs/images/lens_data_info.png b/docs/visualize/images/lens_data_info.png similarity index 100% rename from docs/images/lens_data_info.png rename to docs/visualize/images/lens_data_info.png diff --git a/docs/images/lens_drag_drop.gif b/docs/visualize/images/lens_drag_drop.gif similarity index 100% rename from docs/images/lens_drag_drop.gif rename to docs/visualize/images/lens_drag_drop.gif diff --git a/docs/images/lens_suggestions.gif b/docs/visualize/images/lens_suggestions.gif similarity index 100% rename from docs/images/lens_suggestions.gif rename to docs/visualize/images/lens_suggestions.gif diff --git a/docs/images/lens_tutorial_1.png b/docs/visualize/images/lens_tutorial_1.png similarity index 100% rename from docs/images/lens_tutorial_1.png rename to docs/visualize/images/lens_tutorial_1.png diff --git a/docs/images/lens_tutorial_2.png b/docs/visualize/images/lens_tutorial_2.png similarity index 100% rename from docs/images/lens_tutorial_2.png rename to docs/visualize/images/lens_tutorial_2.png diff --git a/docs/images/lens_tutorial_3.png b/docs/visualize/images/lens_tutorial_3.png similarity index 100% rename from docs/images/lens_tutorial_3.png rename to docs/visualize/images/lens_tutorial_3.png diff --git a/docs/images/lens_viz_types.png b/docs/visualize/images/lens_viz_types.png similarity index 100% rename from docs/images/lens_viz_types.png rename to docs/visualize/images/lens_viz_types.png diff --git a/docs/images/markdown_example_1.png b/docs/visualize/images/markdown_example_1.png similarity index 100% rename from docs/images/markdown_example_1.png rename to docs/visualize/images/markdown_example_1.png diff --git a/docs/images/markdown_example_2.png b/docs/visualize/images/markdown_example_2.png similarity index 100% rename from docs/images/markdown_example_2.png rename to docs/visualize/images/markdown_example_2.png diff --git a/docs/images/markdown_example_3.png b/docs/visualize/images/markdown_example_3.png similarity index 100% rename from docs/images/markdown_example_3.png rename to docs/visualize/images/markdown_example_3.png diff --git a/docs/images/markdown_example_4.png b/docs/visualize/images/markdown_example_4.png similarity index 100% rename from docs/images/markdown_example_4.png rename to docs/visualize/images/markdown_example_4.png diff --git a/docs/images/timelion-conditional01.png b/docs/visualize/images/timelion-conditional01.png similarity index 100% rename from docs/images/timelion-conditional01.png rename to docs/visualize/images/timelion-conditional01.png diff --git a/docs/images/timelion-conditional02.png b/docs/visualize/images/timelion-conditional02.png similarity index 100% rename from docs/images/timelion-conditional02.png rename to docs/visualize/images/timelion-conditional02.png diff --git a/docs/images/timelion-conditional03.png b/docs/visualize/images/timelion-conditional03.png similarity index 100% rename from docs/images/timelion-conditional03.png rename to docs/visualize/images/timelion-conditional03.png diff --git a/docs/images/timelion-conditional04.png b/docs/visualize/images/timelion-conditional04.png similarity index 100% rename from docs/images/timelion-conditional04.png rename to docs/visualize/images/timelion-conditional04.png diff --git a/docs/images/timelion-create01.png b/docs/visualize/images/timelion-create01.png similarity index 100% rename from docs/images/timelion-create01.png rename to docs/visualize/images/timelion-create01.png diff --git a/docs/images/timelion-create02.png b/docs/visualize/images/timelion-create02.png similarity index 100% rename from docs/images/timelion-create02.png rename to docs/visualize/images/timelion-create02.png diff --git a/docs/images/timelion-create03.png b/docs/visualize/images/timelion-create03.png similarity index 100% rename from docs/images/timelion-create03.png rename to docs/visualize/images/timelion-create03.png diff --git a/docs/images/timelion-customize01.png b/docs/visualize/images/timelion-customize01.png similarity index 100% rename from docs/images/timelion-customize01.png rename to docs/visualize/images/timelion-customize01.png diff --git a/docs/images/timelion-customize02.png b/docs/visualize/images/timelion-customize02.png similarity index 100% rename from docs/images/timelion-customize02.png rename to docs/visualize/images/timelion-customize02.png diff --git a/docs/images/timelion-customize03.png b/docs/visualize/images/timelion-customize03.png similarity index 100% rename from docs/images/timelion-customize03.png rename to docs/visualize/images/timelion-customize03.png diff --git a/docs/images/timelion-customize04.png b/docs/visualize/images/timelion-customize04.png similarity index 100% rename from docs/images/timelion-customize04.png rename to docs/visualize/images/timelion-customize04.png diff --git a/docs/images/timelion-math01.png b/docs/visualize/images/timelion-math01.png similarity index 100% rename from docs/images/timelion-math01.png rename to docs/visualize/images/timelion-math01.png diff --git a/docs/images/timelion-math02.png b/docs/visualize/images/timelion-math02.png similarity index 100% rename from docs/images/timelion-math02.png rename to docs/visualize/images/timelion-math02.png diff --git a/docs/images/timelion-math03.png b/docs/visualize/images/timelion-math03.png similarity index 100% rename from docs/images/timelion-math03.png rename to docs/visualize/images/timelion-math03.png diff --git a/docs/images/timelion-math04.png b/docs/visualize/images/timelion-math04.png similarity index 100% rename from docs/images/timelion-math04.png rename to docs/visualize/images/timelion-math04.png diff --git a/docs/images/timelion-math05.png b/docs/visualize/images/timelion-math05.png similarity index 100% rename from docs/images/timelion-math05.png rename to docs/visualize/images/timelion-math05.png diff --git a/docs/images/tsvb-gauge.png b/docs/visualize/images/tsvb-gauge.png similarity index 100% rename from docs/images/tsvb-gauge.png rename to docs/visualize/images/tsvb-gauge.png diff --git a/docs/images/tsvb-markdown.png b/docs/visualize/images/tsvb-markdown.png similarity index 100% rename from docs/images/tsvb-markdown.png rename to docs/visualize/images/tsvb-markdown.png diff --git a/docs/images/tsvb-metric.png b/docs/visualize/images/tsvb-metric.png similarity index 100% rename from docs/images/tsvb-metric.png rename to docs/visualize/images/tsvb-metric.png diff --git a/docs/images/tsvb-screenshot.png b/docs/visualize/images/tsvb-screenshot.png similarity index 100% rename from docs/images/tsvb-screenshot.png rename to docs/visualize/images/tsvb-screenshot.png diff --git a/docs/images/tsvb-table.png b/docs/visualize/images/tsvb-table.png similarity index 100% rename from docs/images/tsvb-table.png rename to docs/visualize/images/tsvb-table.png diff --git a/docs/images/tsvb-top-n.png b/docs/visualize/images/tsvb-top-n.png similarity index 100% rename from docs/images/tsvb-top-n.png rename to docs/visualize/images/tsvb-top-n.png diff --git a/docs/images/vega_lite_default.png b/docs/visualize/images/vega_lite_default.png similarity index 100% rename from docs/images/vega_lite_default.png rename to docs/visualize/images/vega_lite_default.png diff --git a/docs/visualize/images/vega_lite_tutorial_1.png b/docs/visualize/images/vega_lite_tutorial_1.png new file mode 100644 index 0000000000000..4e8d0aba3635b Binary files /dev/null and b/docs/visualize/images/vega_lite_tutorial_1.png differ diff --git a/docs/visualize/images/vega_lite_tutorial_2.png b/docs/visualize/images/vega_lite_tutorial_2.png new file mode 100644 index 0000000000000..523ae91514a11 Binary files /dev/null and b/docs/visualize/images/vega_lite_tutorial_2.png differ diff --git a/docs/visualize/images/vega_tutorial_3.png b/docs/visualize/images/vega_tutorial_3.png new file mode 100644 index 0000000000000..e025ecc585807 Binary files /dev/null and b/docs/visualize/images/vega_tutorial_3.png differ diff --git a/docs/visualize/images/vega_tutorial_4.png b/docs/visualize/images/vega_tutorial_4.png new file mode 100644 index 0000000000000..c8ee311e9bf5e Binary files /dev/null and b/docs/visualize/images/vega_tutorial_4.png differ diff --git a/docs/images/visualize-date-histogram-split-1.png b/docs/visualize/images/visualize-date-histogram-split-1.png similarity index 100% rename from docs/images/visualize-date-histogram-split-1.png rename to docs/visualize/images/visualize-date-histogram-split-1.png diff --git a/docs/images/visualize-date-histogram-split-2.png b/docs/visualize/images/visualize-date-histogram-split-2.png similarity index 100% rename from docs/images/visualize-date-histogram-split-2.png rename to docs/visualize/images/visualize-date-histogram-split-2.png diff --git a/docs/images/visualize-date-histogram.png b/docs/visualize/images/visualize-date-histogram.png similarity index 100% rename from docs/images/visualize-date-histogram.png rename to docs/visualize/images/visualize-date-histogram.png diff --git a/docs/images/visualize-drag-reorder.png b/docs/visualize/images/visualize-drag-reorder.png similarity index 100% rename from docs/images/visualize-drag-reorder.png rename to docs/visualize/images/visualize-drag-reorder.png diff --git a/docs/images/visualize_heat_map_example.png b/docs/visualize/images/visualize_heat_map_example.png similarity index 100% rename from docs/images/visualize_heat_map_example.png rename to docs/visualize/images/visualize_heat_map_example.png diff --git a/docs/visualize/vega.asciidoc b/docs/visualize/vega.asciidoc index 24bd3a44bebba..3a1c57da93f07 100644 --- a/docs/visualize/vega.asciidoc +++ b/docs/visualize/vega.asciidoc @@ -3,71 +3,1287 @@ experimental[] -Build custom visualizations from multiple data sources using Vega -and Vega-Lite. +Build custom visualizations using Vega and Vega-Lite, backed by one or more +data sources including {es}, Elastic Map Service, URL, +or static data. Use the {kib} extensions to Vega to embed Vega into +your dashboard, and to add interactivity to the visualizations. -* *Vega* — A declarative format to create visualizations using JSON. - Generate interactive displays using D3. +Vega and Vega-Lite are both declarative formats to create visualizations +using JSON. Both use a different syntax for declaring visualizations, +and are not fully interchangeable. -* *Vega-Lite* — An easier format to use than Vega that enables more rapid - data analysis. Compiles into Vega. +[float] +[[when-to-vega]] +=== When to use Vega -For more information about Vega and Vega-Lite, refer to -<>. +Vega and Vega-Lite are capable of building most of the visualizations +that {kib} provides, but with higher complexity. The most common reason +to use Vega in {kib} is that {kib} is missing support for the query or +visualization, for example: -[float] -[[create-vega-viz]] -=== Create Vega visualizations +* Aggregations using the `nested` or `parent/child` mapping +* Aggregations without a {kib} index pattern +* Queries using custom time filters +* Complex calculations +* Extracting data from _source instead of aggregation +* Scatter charts +* Sankey charts +* Custom maps +* Using a visual theme that {kib} does not provide + +[[vega-lite-tutorial]] +=== Tutorial: First visualization in Vega-Lite -You create Vega visualizations by using the text editor, which is -preconfigured with the options you need. +In this tutorial, you will learn about how to edit Vega-Lite in {kib} to create +a stacked area chart from an {es} search query. It will give you a starting point +for a more comprehensive +https://vega.github.io/vega-lite/tutorials/getting_started.html[introduction to Vega-Lite], +while only covering the basics. + +In this tutorial, you will build a stacked area chart from one of the {kib} sample data +sets. [role="screenshot"] -image::images/vega_lite_default.png[] +image::visualize/images/vega_lite_tutorial_1.png[] -[float] -[[vega-schema]] -==== Change the Vega version +Before beginning this tutorial, install the <> +set. + +When you first open the Vega editor in {kib}, you will see a pre-populated +line chart which shows the total number of documents across all your indices +within the time range. -The default visualization uses Vega-Lite version 2. To use Vega version 4, edit -the `schema`. +[role="screenshot"] +image::visualize/images/vega_lite_default.png[] + +The text editor contains a Vega-Lite spec written in https://hjson.github.io/[HJSON], +which is similar to JSON but optimized for human editing. HJSON supports: -Go to `$schema`, enter `https://vega.github.io/schema/vega/v5.json`, then click -*Update*. +* Comments using // or /* syntax +* Object keys without quotes +* String values without quotes +* Optional commas +* Double or single quotes +* Multiline strings [float] -[[vega-type]] -==== Change the visualization type +==== Small steps -The default visualization is a line chart. To change the visualization type, -change the `mark` value. The supported visualization types are listed in the -text editor. +Always work on Vega in the smallest steps possible, and save your work frequently. +Small changes will cause unexpected results. Click the "Save" button now. -Go to `mark`, change the value to a different visualization type, then click -*Update*. +The first step is to change the index to one of the <> +sets. Change + +```yaml +index: _all +``` + +to: + +```yaml +index: kibana_sample_data_ecommerce +``` + +Click "Update". The result is probably not what you expect. You should see a flat +line with 0 results. + +You've only changed the index, so the difference must be the query is returning +no results. You can try the <>, +but intuition may be faster for this particular problem. + +In this case, the problem is that you are querying the field `@timestamp`, +which does not exist in the `kibana_sample_data_ecommerce` data. Find and replace +`@timestamp` with `order_date`. This fixes the problem, leaving you with this spec: + +.Expand Vega-Lite spec +[%collapsible%closed] +==== +[source,yaml] +---- +{ + $schema: https://vega.github.io/schema/vega-lite/v4.json + title: Event counts from ecommerce + data: { + url: { + %context%: true + %timefield%: order_date + index: kibana_sample_data_ecommerce + body: { + aggs: { + time_buckets: { + date_histogram: { + field: order_date + interval: {%autointerval%: true} + extended_bounds: { + min: {%timefilter%: "min"} + max: {%timefilter%: "max"} + } + min_doc_count: 0 + } + } + } + size: 0 + } + } + format: {property: "aggregations.time_buckets.buckets" } + } + + mark: line + + encoding: { + x: { + field: key + type: temporal + axis: { title: null } + } + y: { + field: doc_count + type: quantitative + axis: { title: "Document count" } + } + } +} +---- + +==== + +Now, let's make the visualization more interesting by adding another aggregation +to create a stacked area chart. To verify that you have constructed the right +query, it is easiest to use the {kib} Dev Tools in a separate tab from the +Vega editor. Open the Dev Tools from the Management section of the navigation. + +This query is roughly equivalent to the one that is used in the default +Vega-Lite spec. Copy it into the Dev Tools: + +```js +POST kibana_sample_data_ecommerce/_search +{ + "query": { + "range": { + "order_date": { + "gte": "now-7d" + } + } + }, + "aggs": { + "time_buckets": { + "date_histogram": { + "field": "order_date", + "fixed_interval": "1d", + "extended_bounds": { + "min": "now-7d" + }, + "min_doc_count": 0 + } + } + }, + "size": 0 +} +``` + +There's not enough data to create a stacked bar in the original query, so we +will add a new +{ref}/search-aggregations-bucket-terms-aggregation.html[terms aggregation]: + +```js +POST kibana_sample_data_ecommerce/_search +{ + "query": { + "range": { + "order_date": { + "gte": "now-7d" + } + } + }, + "aggs": { + "categories": { + "terms": { "field": "category.keyword" }, + "aggs": { + "time_buckets": { + "date_histogram": { + "field": "order_date", + "fixed_interval": "1d", + "extended_bounds": { + "min": "now-7d" + }, + "min_doc_count": 0 + } + } + } + } + }, + "size": 0 +} +``` + +You'll see that the response format looks different from the previous query: + +```json +{ + "aggregations" : { + "categories" : { + "doc_count_error_upper_bound" : 0, + "sum_other_doc_count" : 0, + "buckets" : [{ + "key" : "Men's Clothing", + "doc_count" : 1661, + "time_buckets" : { + "buckets" : [{ + "key_as_string" : "2020-06-30T00:00:00.000Z", + "key" : 1593475200000, + "doc_count" : 19 + }, { + "key_as_string" : "2020-07-01T00:00:00.000Z", + "key" : 1593561600000, + "doc_count" : 71 + }] + } + }] + } + } +} +``` + +Now that we have data that we're happy with, it's time to convert from an +isolated {es} query into a query with {kib} integration. Looking at the +<>, you will +see the full list of special tokens that are used in this query, such +as `%context: true`. This query has also replaced `"fixed_interval": "1d"` +with `interval: {%autointerval%: true}`. Copy the final query into +your spec: + +```yaml + data: { + url: { + %context%: true + %timefield%: order_date + index: kibana_sample_data_ecommerce + body: { + aggs: { + categories: { + terms: { field: "category.keyword" } + aggs: { + time_buckets: { + date_histogram: { + field: order_date + interval: {%autointerval%: true} + extended_bounds: { + min: {%timefilter%: "min"} + max: {%timefilter%: "max"} + } + min_doc_count: 0 + } + } + } + } + } + size: 0 + } + } + format: {property: "aggregations.categories.buckets" } + } +``` + +If you copy and paste that into your Vega-Lite spec, and click "Update", +you will see a warning saying `Infinite extent for field "key": [Infinity, -Infinity]`. +Let's use our <> to understand why. + +Vega-Lite generates data using the names `source_0` and `data_0`. `source_0` contains +the results from the {es} query, and `data_0` contains the visually encoded results +which are shown in the chart. To debug this problem, you need to compare both. + +To look at the source, open the browser dev tools console and type +`VEGA_DEBUG.view.data('source_0')`. You will see: + +```js +[{ + doc_count: 454 + key: "Men's Clothing" + time_buckets: {buckets: Array(57)} + Symbol(vega_id): 12822 +}, ...] +``` + +To compare to the visually encoded data, open the browser dev tools console and type +`VEGA_DEBUG.view.data('data_0')`. You will see: + +```js +[{ + doc_count: 454 + key: NaN + time_buckets: {buckets: Array(57)} + Symbol(vega_id): 13879 +}] +``` + +The issue seems to be that the `key` property is not being converted the right way, +which makes sense because the `key` is now `Men's Clothing` instead of a timestamp. + +To fix this, try updating the `encoding` of your Vega-Lite spec to: + +```yaml + encoding: { + x: { + field: time_buckets.buckets.key + type: temporal + axis: { title: null } + } + y: { + field: time_buckets.buckets.doc_count + type: quantitative + axis: { title: "Document count" } + } + } +``` + +This will show more errors, and you can inspect `VEGA_DEBUG.view.data('data_0')` to +understand why. This now shows: + +```js +[{ + doc_count: 454 + key: "Men's Clothing" + time_buckets: {buckets: Array(57)} + time_buckets.buckets.doc_count: undefined + time_buckets.buckets.key: null + Symbol(vega_id): 14094 +}] +``` + +It looks like the problem is that the `time_buckets` inner array is not being +extracted by Vega. The solution is to use a Vega-lite +https://vega.github.io/vega-lite/docs/flatten.html[flatten transformation], available in {kib} 7.9 and later. +If using an older version of Kibana, the flatten transformation is available in Vega +but not Vega-Lite. + +Add this section in between the `data` and `encoding` section: + +```yaml + transform: [{ + flatten: ["time_buckets.buckets"] + }] +``` + +This does not yet produce the results you expect. Inspect the transformed data +by typing `VEGA_DEBUG.view.data('data_0')` into the console again: + +```js +[{ + doc_count: 453 + key: "Men's Clothing" + time_bucket.buckets.doc_count: undefined + time_buckets: {buckets: Array(57)} + time_buckets.buckets: { + key_as_string: "2020-06-30T15:00:00.000Z", + key: 1593529200000, + doc_count: 2 + } + time_buckets.buckets.key: null + Symbol(vega_id): 21564 +}] +``` + +The debug view shows `undefined` values where you would expect to see numbers, and +the cause is that there are duplicate names which are confusing Vega-Lite. This can +be fixed by making this change to the `transform` and `encoding` blocks: + +```yaml + transform: [{ + flatten: ["time_buckets.buckets"], + as: ["buckets"] + }] + + mark: area + + encoding: { + x: { + field: buckets.key + type: temporal + axis: { title: null } + } + y: { + field: buckets.doc_count + type: quantitative + axis: { title: "Document count" } + } + color: { + field: key + type: nominal + } + } +``` + +At this point, you have a stacked area chart that shows the top categories, +but the chart is still missing some common features that we expect from a {kib} +visualization. Let's add hover states and tooltips next. + +Hover states are handled differently in Vega-Lite and Vega. In Vega-Lite this is +done using a concept called `selection`, which has many permutations that are not +covered in this tutorial. We will be adding a simple tooltip and hover state. + +Because {kib} has enabled the https://vega.github.io/vega-lite/docs/tooltip.html[Vega tooltip plugin], +tooltips can be defined in several ways: + +* Automatic tooltip based on the data, via `{ content: "data" }` +* Array of fields, like `[{ field: "key", type: "nominal" }]` +* Defining a custom Javascript object using the `calculate` transform + +For the simple tooltip, add this to your encoding: + +```yaml + encoding: { + tooltip: [{ + field: buckets.key + type: temporal + title: "Date" + }, { + field: key + type: nominal + title: "Category" + }, { + field: buckets.doc_count + type: quantitative + title: "Count" + }] + } +``` + +As you hover over the area series in your chart, a multi-line tooltip will +appear, but it won't indicate the nearest point that it's pointing to. To +indicate the nearest point, we need to add a second layer. + +The first step is to remove the `mark: area` from your visualization. +Once you've removed the previous mark, add a composite mark at the end of +the Vega-Lite spec: + +```yaml + layer: [{ + mark: area + }, { + mark: point + }] +``` + +You'll see that the points are not appearing to line up with the area chart, +and the reason is that the points are not being stacked. Change your Y encoding +to this: + +```yaml + y: { + field: buckets.doc_count + type: quantitative + axis: { title: "Document count" } + stack: true + } +``` + +Now, we will add a `selection` block inside the point mark: + +```yaml + layer: [{ + mark: area + }, { + mark: point + + selection: { + pointhover: { + type: single + on: mouseover + clear: mouseout + empty: none + fields: ["buckets.key", "key"] + nearest: true + } + } + + encoding: { + size: { + condition: { + selection: pointhover + value: 100 + } + value: 5 + } + fill: { + condition: { + selection: pointhover + value: white + } + } + } + }] +``` + +Now that you've enabled a selection, try moving the mouse around the visualization +and seeing the points respond to the nearest position: + +[role="screenshot"] +image::visualize/images/vega_lite_tutorial_2.png[] + +The final result of this tutorial is this spec: + +.Expand final Vega-Lite spec +[%collapsible%closed] +==== +[source,yaml] +---- +{ + $schema: https://vega.github.io/schema/vega-lite/v4.json + title: Event counts from ecommerce + data: { + url: { + %context%: true + %timefield%: order_date + index: kibana_sample_data_ecommerce + body: { + aggs: { + categories: { + terms: { field: "category.keyword" } + aggs: { + time_buckets: { + date_histogram: { + field: order_date + interval: {%autointerval%: true} + extended_bounds: { + min: {%timefilter%: "min"} + max: {%timefilter%: "max"} + } + min_doc_count: 0 + } + } + } + } + } + size: 0 + } + } + format: {property: "aggregations.categories.buckets" } + } + + transform: [{ + flatten: ["time_buckets.buckets"] + as: ["buckets"] + }] + + encoding: { + x: { + field: buckets.key + type: temporal + axis: { title: null } + } + y: { + field: buckets.doc_count + type: quantitative + axis: { title: "Document count" } + stack: true + } + color: { + field: key + type: nominal + title: "Category" + } + tooltip: [{ + field: buckets.key + type: temporal + title: "Date" + }, { + field: key + type: nominal + title: "Category" + }, { + field: buckets.doc_count + type: quantitative + title: "Count" + }] + } + + layer: [{ + mark: area + }, { + mark: point + + selection: { + pointhover: { + type: single + on: mouseover + clear: mouseout + empty: none + fields: ["buckets.key", "key"] + nearest: true + } + } + + encoding: { + size: { + condition: { + selection: pointhover + value: 100 + } + value: 5 + } + fill: { + condition: { + selection: pointhover + value: white + } + } + } + }] +} +---- + +==== + +[[vega-tutorial]] +=== Tutorial: Updating {kib} filters from Vega + +In this tutorial you will build an area chart in Vega using an {es} search query, +and add a click handler and drag handler to update {kib} filters. +This tutorial is not a full https://vega.github.io/vega/tutorials/[Vega tutorial], +but will cover the basics of creating Vega visualizations into {kib}. + +First, create an almost-blank Vega chart by pasting this into the editor: + +```yaml +{ + $schema: "https://vega.github.io/schema/vega/v5.json" + data: [{ + name: source_0 + }] + + scales: [{ + name: x + type: time + range: width + }, { + name: y + type: linear + range: height + }] + + axes: [{ + orient: bottom + scale: x + }, { + orient: left + scale: y + }] + + marks: [ + { + type: area + from: { + data: source_0 + } + encode: { + update: { + } + } + } + ] +} +``` + +Despite being almost blank, this Vega spec still contains the minimum requirements: + +* Data +* Scales +* Marks +* (optional) Axes + +Next, add a valid {es} search query in the `data` block: + +```yaml + data: [ + { + name: source_0 + url: { + %context%: true + %timefield%: order_date + index: kibana_sample_data_ecommerce + body: { + aggs: { + time_buckets: { + date_histogram: { + field: order_date + fixed_interval: "3h" + extended_bounds: { + min: {%timefilter%: "min"} + max: {%timefilter%: "max"} + } + min_doc_count: 0 + } + } + } + size: 0 + } + } + format: { property: "aggregations.time_buckets.buckets" } + } + ] +``` + +Click "Update", and nothing will change in the visualization. The first step +is to change the X and Y scales based on the data: + +```yaml + scales: [{ + name: x + type: time + range: width + domain: { + data: source_0 + field: key + } + }, { + name: y + type: linear + range: height + domain: { + data: source_0 + field: doc_count + } + }] +``` + +Click "Update", and you will see that the X and Y axes are now showing labels based +on the real data. + +Next, encode the fields `key` and `doc_count` as the X and Y values: + +```yaml + marks: [ + { + type: area + from: { + data: source_0 + } + encode: { + update: { + x: { + scale: x + field: key + } + y: { + scale: y + value: 0 + } + y2: { + scale: y + field: doc_count + } + } + } + } + ] +``` + +Click "Update" and you will get a basic area chart: + +[role="screenshot"] +image::visualize/images/vega_tutorial_3.png[] + +Next, add a new block to the `marks` section. This will show clickable points to filter for a specific +date: + +```yaml + { + name: point + type: symbol + style: ["point"] + from: { + data: source_0 + } + encode: { + update: { + x: { + scale: x + field: key + } + y: { + scale: y + field: doc_count + } + size: { + value: 100 + } + fill: { + value: black + } + } + } + } +``` + +Next, we will create a Vega signal to make the points clickable. You can access +the clicked `datum` in the expression used to update. In this case, you want +clicks on points to add a time filter with the 3-hour interval defined above. + +```yaml + signals: [ + { + name: point_click + on: [{ + events: { + source: scope + type: click + markname: point + } + update: '''kibanaSetTimeFilter(datum.key, datum.key + 3 * 60 * 60 * 1000)''' + }] + } + ] +``` + +This event is using the {kib} custom function `kibanaSetTimeFilter` to generate a filter that +gets applied to the entire dashboard on click. + +The mouse cursor does not currently indicate that the chart is interactive. Find the `marks` section, +and update the mark named `point` by adding `cursor: { value: "pointer" }` to +the `encoding` section like this: + +```yaml + { + name: point + type: symbol + style: ["point"] + from: { + data: source_0 + } + encode: { + update: { + ... + cursor: { value: "pointer" } + } + } + } +``` + +Next, we will add a drag interaction which will allow the user to narrow into +a specific time range in the visualization. This will require adding more signals, and +adding a rectangle overlay: + +[role="screenshot"] +image::visualize/images/vega_tutorial_4.png[] + +The first step is to add a new `signal` to track the X position of the cursor: + +```yaml + { + name: currentX + value: -1 + on: [{ + events: { + type: mousemove + source: view + }, + update: "clamp(x(), 0, width)" + }, { + events: { + type: mouseout + source: view + } + update: "-1" + }] + } +``` + +Now add a new `mark` to indicate the current cursor position: + +```yaml + { + type: rule + interactive: false + encode: { + update: { + y: {value: 0} + y2: {signal: "height"} + stroke: {value: "gray"} + strokeDash: { + value: [2, 1] + } + x: {signal: "max(currentX,0)"} + defined: {signal: "currentX > 0"} + } + } + } +``` + +Next, add a signal to track the current selected range, which will update +until the user releases the mouse button or uses the escape key: + + +```yaml + { + name: selected + value: [0, 0] + on: [{ + events: { + type: mousedown + source: view + } + update: "[clamp(x(), 0, width), clamp(x(), 0, width)]" + }, { + events: { + type: mousemove + source: window + consume: true + between: [{ + type: mousedown + source: view + }, { + merge: [{ + type: mouseup + source: window + }, { + type: keydown + source: window + filter: "event.key === 'Escape'" + }] + }] + } + update: "[selected[0], clamp(x(), 0, width)]" + }, { + events: { + type: keydown + source: window + filter: "event.key === 'Escape'" + } + update: "[0, 0]" + }] + } +``` + +Now that there is a signal which tracks the time range from the user, we need to indicate +the range visually by adding a new mark which only appears conditionally: + +```yaml + { + type: rect + name: selectedRect + encode: { + update: { + height: {signal: "height"} + fill: {value: "#333"} + fillOpacity: {value: 0.2} + x: {signal: "selected[0]"} + x2: {signal: "selected[1]"} + defined: {signal: "selected[0] !== selected[1]"} + } + } + } +``` + +Finally, add a new signal which will update the {kib} time filter when the mouse is released while +dragging: + +```yaml + { + name: applyTimeFilter + value: null + on: [{ + events: { + type: mouseup + source: view + } + update: '''selected[0] !== selected[1] ? kibanaSetTimeFilter( + invert('x',selected[0]), + invert('x',selected[1])) : null''' + }] + } +``` + +Putting this all together, your visualization now supports the main features of +standard visualizations in {kib}, but with the potential to add even more control. +The final Vega spec for this tutorial is here: + +.Expand final Vega spec +[%collapsible%closed] +==== +[source,yaml] +---- +{ + $schema: "https://vega.github.io/schema/vega/v5.json" + data: [ + { + name: source_0 + url: { + %context%: true + %timefield%: order_date + index: kibana_sample_data_ecommerce + body: { + aggs: { + time_buckets: { + date_histogram: { + field: order_date + fixed_interval: "3h" + extended_bounds: { + min: {%timefilter%: "min"} + max: {%timefilter%: "max"} + } + min_doc_count: 0 + } + } + } + size: 0 + } + } + format: { property: "aggregations.time_buckets.buckets" } + } + ] + + scales: [{ + name: x + type: time + range: width + domain: { + data: source_0 + field: key + } + }, { + name: y + type: linear + range: height + domain: { + data: source_0 + field: doc_count + } + }] + + axes: [{ + orient: bottom + scale: x + }, { + orient: left + scale: y + }] + + marks: [ + { + type: area + from: { + data: source_0 + } + encode: { + update: { + x: { + scale: x + field: key + } + y: { + scale: y + value: 0 + } + y2: { + scale: y + field: doc_count + } + } + } + }, + { + name: point + type: symbol + style: ["point"] + from: { + data: source_0 + } + encode: { + update: { + x: { + scale: x + field: key + } + y: { + scale: y + field: doc_count + } + size: { + value: 100 + } + fill: { + value: black + } + cursor: { value: "pointer" } + } + } + }, + { + type: rule + interactive: false + encode: { + update: { + y: {value: 0} + y2: {signal: "height"} + stroke: {value: "gray"} + strokeDash: { + value: [2, 1] + } + x: {signal: "max(currentX,0)"} + defined: {signal: "currentX > 0"} + } + } + }, + { + type: rect + name: selectedRect + encode: { + update: { + height: {signal: "height"} + fill: {value: "#333"} + fillOpacity: {value: 0.2} + x: {signal: "selected[0]"} + x2: {signal: "selected[1]"} + defined: {signal: "selected[0] !== selected[1]"} + } + } + } + ] + + signals: [ + { + name: point_click + on: [{ + events: { + source: scope + type: click + markname: point + } + update: '''kibanaSetTimeFilter(datum.key, datum.key + 3 * 60 * 60 * 1000)''' + }] + } + { + name: currentX + value: -1 + on: [{ + events: { + type: mousemove + source: view + }, + update: "clamp(x(), 0, width)" + }, { + events: { + type: mouseout + source: view + } + update: "-1" + }] + } + { + name: selected + value: [0, 0] + on: [{ + events: { + type: mousedown + source: view + } + update: "[clamp(x(), 0, width), clamp(x(), 0, width)]" + }, { + events: { + type: mousemove + source: window + consume: true + between: [{ + type: mousedown + source: view + }, { + merge: [{ + type: mouseup + source: window + }, { + type: keydown + source: window + filter: "event.key === 'Escape'" + }] + }] + } + update: "[selected[0], clamp(x(), 0, width)]" + }, { + events: { + type: keydown + source: window + filter: "event.key === 'Escape'" + } + update: "[0, 0]" + }] + } + { + name: applyTimeFilter + value: null + on: [{ + events: { + type: mouseup + source: view + } + update: '''selected[0] !== selected[1] ? kibanaSetTimeFilter( + invert('x',selected[0]), + invert('x',selected[1])) : null''' + }] + } + ] +} + +---- +==== + +[[vega-reference]] +=== Reference for {kib} extensions + +{kib} has extended Vega and Vega-Lite with extensions that support: + +* Default height and width +* Default theme to match {kib} +* Writing {es} queries using the time range and filters from dashboards +* Using the Elastic Map Service in Vega maps +* Additional tooltip styling +* Advanced setting to enable URL loading from any domain +* Limited debugging support using the browser dev tools +* (Vega only) Expression functions which can update the time range and dashboard filters -[float] [[vega-sizing-and-positioning]] -==== Change the layout +==== Default height and width By default, Vega visualizations use the `autosize = { type: 'fit', contains: 'padding' }` layout. `fit` uses all available space, ignores `width` and `height` values, and respects the padding values. To override this behavior, change the `autosize` value. -[[vega-querying-elasticsearch]] -=== Query {es} +[[vega-theme]] +==== Default theme to match {kib} + +{kib} registers a default https://vega.github.io/vega/docs/schemes/[Vega color scheme] +with the id `elastic`, and sets a default color for each `mark` type. +Override it by providing a different `stroke`, `fill`, or `color` (Vega-Lite) value. + +[[vega-queries]] +==== Writing {es} queries in Vega + +experimental[] {kib} extends the Vega https://vega.github.io/vega/docs/data/[data] elements +with support for direct {es} queries specified as a `url`. -experimental[] Vega https://vega.github.io/vega/docs/data/[data] elements -use embedded and external data with a `"url"` parameter. {kib} adds support for -direct {es} queries by overloading -the `"url"` value. +Because of this, {kib} is **unable to support dynamically loaded data**, +which would otherwise work in Vega. All data is fetched before it's passed to +the Vega renderer. -NOTE: With Vega, you dynamically load your data by setting signals as data URLs. -Since {kib} is unable to support dynamically loaded data, all data is fetched -before it's passed to the Vega renderer. +To define an {es} query in Vega, set the `url` to an object. {kib} will parse +the object looking for special tokens that allow your query to integrate with {kib}. +These tokens are: -For example, count the number of documents in all indices: +* `%context%: true`: Set at the top level, and replaces the `query` section with filters from dashboard +* `%timefield%: `: Set at the top level, integrates the query with the dashboard time filter +* `{%timefilter%: true}`: Replaced by an {es} range query with upper and lower bounds +* `{%timefilter%: "min" | "max"}`: Replaced only by the upper or lower bounds +* `{%timefilter: true, shift: -1, unit: 'hour'}`: Generates a time range query one hour in the past +* `{%autointerval%: true}`: Replaced by the string which contains the automatic {kib} time interval, such as `1h` +* `{%autointerval%: 10}`: Replaced by a string which is approximately dividing the time into 10 ranges, allowing + you to influence the automatic interval +* `"%dashboard_context-must_clause%"`: String replaced by object containing filters +* `"%dashboard_context-filter_clause%"`: String replaced by an object containing filters +* `"%dashboard_context-must_not_clause%"`: String replaced by an object containing filters + +Putting this together, an example query that counts the number of documents in +a specific index: [source,yaml] ---- @@ -80,8 +1296,8 @@ url: { %context%: true // Which indexes to search - index: _all - // The body element may contain "aggs" and "query" subfields + index: kibana_sample_data_logs + // The body element may contain "aggs" and "query" keys body: { aggs: { time_buckets: { @@ -183,7 +1399,7 @@ except that the time range is shifted back by 10 minutes: } ---- -NOTE: When using `"%context%": true` or defining a value for "%timefield%"` the body cannot contain a query. To customize the query within the VEGA specification (e.g. add an additional filter, or shift the timefilter), define your query and use the placeholders as in the example above. The placeholders will be replaced by the actual context of the dashboard or visualization once parsed. +NOTE: When using `"%context%": true` or defining a value for `"%timefield%"` the body cannot contain a query. To customize the query within the VEGA specification (e.g. add an additional filter, or shift the timefilter), define your query and use the placeholders as in the example above. The placeholders will be replaced by the actual context of the dashboard or visualization once parsed. The `"%timefilter%"` can also be used to specify a single min or max value. The date_histogram's `extended_bounds` can be set @@ -194,6 +1410,7 @@ also supported. The `"interval"` can also be set dynamically, depending on the currently picked range: `"interval": {"%autointerval%": 10}` will try to get about 10-15 data points (buckets). +[float] [[vega-esmfiles]] === Access Elastic Map Service files @@ -260,21 +1477,44 @@ Additionally, you can use `latitude`, `longitude`, and `zoom` signals. These signals can be used in the graph, or can be updated to modify the position of the map. -Vega visualization ignore the `autosize`, `width`, `height`, and `padding` -values, using `fit` model with zero padding. +[float] +[[vega-tooltip]] +==== Additional tooltip styling + +{kib} has installed the https://vega.github.io/vega-lite/docs/tooltip.html[Vega tooltip plugin], +so tooltips can be defined in the ways documented there. Beyond that, {kib} also supports +a configuration option for changing the tooltip position and padding: + +```js +{ + config: { + kibana: { + tooltips: { + position: 'top', + padding: 15 + } + } + } +} +``` + +[[vega-url-loading]] +==== Advanced setting to enable URL loading from any domain -[[vega-debugging]] -=== Debugging Vega +Vega can load data from any URL, but this is disabled by default in {kib}. +To change this, set `vis_type_vega.enableExternalUrls: true` in `kibana.yml`, +then restart {kib}. [[vega-browser-debugging-console]] ==== Browser debugging console experimental[] Use browser debugging tools (for example, F12 or Ctrl+Shift+J in Chrome) to inspect the `VEGA_DEBUG` variable: -+ + * `view` — Access to the Vega View object. See https://vega.github.io/vega/docs/api/debugging/[Vega Debugging Guide] -on how to inspect data and signals at runtime. For Vega-Lite, `VEGA_DEBUG.view.data('source_0')` gets the main data set. -For Vega, it uses the data name as defined in your Vega spec. +on how to inspect data and signals at runtime. For Vega-Lite, +`VEGA_DEBUG.view.data('source_0')` gets the pre-transformed data, and `VEGA_DEBUG.view.data('data_0')` +gets the encoded data. For Vega, it uses the data name as defined in your Vega spec. * `vega_spec` — Vega JSON graph specification after some modifications by {kib}. In case of Vega-Lite, this is the output of the Vega-Lite compiler. @@ -283,7 +1523,7 @@ of Vega-Lite, this is the output of the Vega-Lite compiler. Vega-Lite compilation. [[vega-data]] -==== Data +==== Debugging data experimental[] If you are using an {es} query, make sure your resulting data is what you expected. The easiest way to view it is by using the "networking" @@ -294,45 +1534,52 @@ https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Dev Tools]. P `GET /_search`, then add your query as the following lines (just the value of the `"query"` field). -If you need to share your graph with someone, copy the -raw data response to https://gist.github.com/[gist.github.com], possibly -with a `.json` extension, use the `[raw]` button, and use that url -directly in your graph. +[[vega-getting-help]] +==== Asking for help with a Vega spec -To restrict Vega from using non-ES data sources, add `vega.enableExternalUrls: false` -to your kibana.yml file. +Because of the dynamic nature of the data in {es}, it is hard to help you with +Vega specs unless you can share a dataset. To do this, use the browser developer +tools and type: -[[vega-notes]] -[[vega-useful-links]] -=== Resources and examples +`JSON.stringify(VEGA_DEBUG.vegalite_spec, null, 2)` -experimental[] To learn more about Vega and Vega-List, refer to the resources and examples. +Copy the response to https://gist.github.com/[gist.github.com], possibly +with a `.json` extension, use the `[raw]` button, and share that when +asking for help. -==== Vega editor -The https://vega.github.io/editor/[Vega Editor] includes examples for Vega & Vega-Lite, but does not support any -{kib}-specific features like {es} requests and interactive base maps. +[float] +[[vega-expression-functions]] +==== (Vega only) Expression functions which can update the time range and dashboard filters -==== Vega-Lite resources -* https://vega.github.io/vega-lite/tutorials/getting_started.html[Tutorials] -* https://vega.github.io/vega-lite/docs/[Docs] -* https://vega.github.io/vega-lite/examples/[Examples] +{kib} has extended the Vega expression language with these functions: -==== Vega resources -* https://vega.github.io/vega/tutorials/[Tutorials] -* https://vega.github.io/vega/docs/[Docs] -* https://vega.github.io/vega/examples/[Examples] +```js +/** + * @param {object} query Elastic Query DSL snippet, as used in the query DSL editor + * @param {string} [index] as defined in Kibana, or default if missing + */ +kibanaAddFilter(query, index) -TIP: When you use the examples, you may -need to modify the "data" section to use absolute URL. For example, -replace `"url": "data/world-110m.json"` with -`"url": "https://vega.github.io/editor/data/world-110m.json"`. +/** + * @param {object} query Elastic Query DSL snippet, as used in the query DSL editor + * @param {string} [index] as defined in Kibana, or default if missing + */ +kibanaRemoveFilter(query, index) + +kibanaRemoveAllFilters() +/** + * Update dashboard time filter to the new values + * @param {number|string|Date} start + * @param {number|string|Date} end + */ +kibanaSetTimeFilter(start, end) +``` + +[float] [[vega-additional-configuration-options]] ==== Additional configuration options -These options are specific to the {kib}. link:#vega-with-a-map[Map support] has -additional configuration options. - [source,yaml] ---- { @@ -343,12 +1590,37 @@ additional configuration options. controlsLocation: top // Can be `vertical` or `horizontal` (default). controlsDirection: vertical - // If true, hides most of Vega and VegaLite warnings + // If true, hides most of Vega and Vega-Lite warnings hideWarnings: true // Vega renderer to use: `svg` or `canvas` (default) renderer: canvas } } - /* the rest of Vega code */ } ---- + + +[[vega-notes]] +[[vega-useful-links]] +=== Resources and examples + +experimental[] To learn more about Vega and Vega-Lite, refer to the resources and examples. + +==== Vega editor +The https://vega.github.io/editor/[Vega Editor] includes examples for Vega & Vega-Lite, but does not support any +{kib}-specific features like {es} requests and interactive base maps. + +==== Vega-Lite resources +* https://vega.github.io/vega-lite/tutorials/getting_started.html[Tutorials] +* https://vega.github.io/vega-lite/docs/[Docs] +* https://vega.github.io/vega-lite/examples/[Examples] + +==== Vega resources +* https://vega.github.io/vega/tutorials/[Tutorials] +* https://vega.github.io/vega/docs/[Docs] +* https://vega.github.io/vega/examples/[Examples] + +TIP: When you use the examples in {kib}, you may +need to modify the "data" section to use absolute URL. For example, +replace `"url": "data/world-110m.json"` with +`"url": "https://vega.github.io/editor/data/world-110m.json"`. diff --git a/examples/alerting_example/public/components/view_alert.tsx b/examples/alerting_example/public/components/view_alert.tsx index 75a515bfa1b25..0f7fc70648a9e 100644 --- a/examples/alerting_example/public/components/view_alert.tsx +++ b/examples/alerting_example/public/components/view_alert.tsx @@ -49,10 +49,10 @@ export const ViewAlertPage = withRouter(({ http, id }: Props) => { useEffect(() => { if (!alert) { - http.get(`${BASE_ALERT_API_PATH}/${id}`).then(setAlert); + http.get(`${BASE_ALERT_API_PATH}/alert/${id}`).then(setAlert); } if (!alertState) { - http.get(`${BASE_ALERT_API_PATH}/${id}/state`).then(setAlertState); + http.get(`${BASE_ALERT_API_PATH}/alert/${id}/state`).then(setAlertState); } }, [alert, alertState, http, id]); diff --git a/examples/alerting_example/server/plugin.ts b/examples/alerting_example/server/plugin.ts index 2bd742fc58bcc..1d7ad37a46551 100644 --- a/examples/alerting_example/server/plugin.ts +++ b/examples/alerting_example/server/plugin.ts @@ -53,7 +53,7 @@ export class AlertingExamplePlugin implements Plugin = (request, options) => { - return from(core.getStartServices()).pipe( - flatMap((startServices) => { - const asyncStrategy = (startServices[1] as DemoDataSearchStartDependencies).data.search.getSearchStrategy( - ASYNC_SEARCH_STRATEGY - ); - return asyncStrategy.search( - { ...request, serverStrategy: ASYNC_DEMO_SEARCH_STRATEGY }, - options - ) as Observable; - }) - ); - }; - return { search }; -} diff --git a/examples/demo_search/public/demo_search_strategy.ts b/examples/demo_search/public/demo_search_strategy.ts deleted file mode 100644 index d56d827a5c0f8..0000000000000 --- a/examples/demo_search/public/demo_search_strategy.ts +++ /dev/null @@ -1,65 +0,0 @@ -/* - * Licensed to Elasticsearch B.V. under one or more contributor - * license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright - * ownership. Elasticsearch B.V. licenses this file to you under - * the Apache License, Version 2.0 (the "License"); you may - * not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. - */ - -import { Observable, from } from 'rxjs'; -import { flatMap } from 'rxjs/operators'; -import { CoreSetup } from 'kibana/public'; -import { ISearch, SYNC_SEARCH_STRATEGY } from '../../../src/plugins/data/public'; -import { DEMO_SEARCH_STRATEGY, IDemoResponse } from '../common'; -import { DemoDataSearchStartDependencies } from './types'; - -/** - * This demo search strategy provider simply provides a shortcut for calling the DEMO_SEARCH_STRATEGY - * on the server side, without users having to pass it in explicitly, and it takes advantage of the - * already registered SYNC_SEARCH_STRATEGY that exists on the client. - * - * so instead of callers having to do: - * - * ``` - * data.search.search( - * { ...request, serverStrategy: DEMO_SEARCH_STRATEGY }, - * options, - * SYNC_SEARCH_STRATEGY - * ) as Observable, - *``` - - * They can instead just do - * - * ``` - * data.search.search(request, options, DEMO_SEARCH_STRATEGY); - * ``` - * - * and are ensured type safety in regard to the request and response objects. - */ -export function demoClientSearchStrategyProvider(core: CoreSetup) { - const search: ISearch = (request, options) => { - return from(core.getStartServices()).pipe( - flatMap((startServices) => { - const syncStrategy = (startServices[1] as DemoDataSearchStartDependencies).data.search.getSearchStrategy( - SYNC_SEARCH_STRATEGY - ); - return syncStrategy.search( - { ...request, serverStrategy: DEMO_SEARCH_STRATEGY }, - options - ) as Observable; - }) - ); - }; - return { search }; -} diff --git a/examples/demo_search/public/index.ts b/examples/demo_search/public/index.ts deleted file mode 100644 index 0a97ac6b72ea7..0000000000000 --- a/examples/demo_search/public/index.ts +++ /dev/null @@ -1,26 +0,0 @@ -/* - * Licensed to Elasticsearch B.V. under one or more contributor - * license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright - * ownership. Elasticsearch B.V. licenses this file to you under - * the Apache License, Version 2.0 (the "License"); you may - * not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. - */ - -import { PluginInitializer } from 'kibana/public'; - -import { DemoDataPlugin } from './plugin'; - -export { DEMO_SEARCH_STRATEGY } from '../common'; - -export const plugin: PluginInitializer = () => new DemoDataPlugin(); diff --git a/examples/demo_search/public/plugin.ts b/examples/demo_search/public/plugin.ts deleted file mode 100644 index 5d074c19903e2..0000000000000 --- a/examples/demo_search/public/plugin.ts +++ /dev/null @@ -1,65 +0,0 @@ -/* - * Licensed to Elasticsearch B.V. under one or more contributor - * license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright - * ownership. Elasticsearch B.V. licenses this file to you under - * the Apache License, Version 2.0 (the "License"); you may - * not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. - */ - -import { Plugin, CoreSetup } from '../../../src/core/public'; -import { - DEMO_SEARCH_STRATEGY, - IDemoRequest, - IDemoResponse, - ASYNC_DEMO_SEARCH_STRATEGY, - IAsyncDemoRequest, - IAsyncDemoResponse, -} from '../common'; -import { demoClientSearchStrategyProvider } from './demo_search_strategy'; -import { asyncDemoClientSearchStrategyProvider } from './async_demo_search_strategy'; -import { DemoDataSearchSetupDependencies, DemoDataSearchStartDependencies } from './types'; - -/** - * Add the typescript mappings for our search strategy to the request and - * response types. This allows typescript to require the right shapes if - * making the call: - * const response = context.search.search(request, {}, DEMO_SEARCH_STRATEGY); - * - * If the caller does not pass in the right `request` shape, typescript will - * complain. The caller will also get a typed response. - */ -declare module '../../../src/plugins/data/public' { - export interface IRequestTypesMap { - [DEMO_SEARCH_STRATEGY]: IDemoRequest; - [ASYNC_DEMO_SEARCH_STRATEGY]: IAsyncDemoRequest; - } - - export interface IResponseTypesMap { - [DEMO_SEARCH_STRATEGY]: IDemoResponse; - [ASYNC_DEMO_SEARCH_STRATEGY]: IAsyncDemoResponse; - } -} - -export class DemoDataPlugin - implements Plugin { - public setup(core: CoreSetup, { data }: DemoDataSearchSetupDependencies) { - const demoClientSearchStrategy = demoClientSearchStrategyProvider(core); - const asyncDemoClientSearchStrategy = asyncDemoClientSearchStrategyProvider(core); - data.search.registerSearchStrategy(DEMO_SEARCH_STRATEGY, demoClientSearchStrategy); - data.search.registerSearchStrategy(ASYNC_DEMO_SEARCH_STRATEGY, asyncDemoClientSearchStrategy); - } - - public start() {} - public stop() {} -} diff --git a/examples/demo_search/public/types.ts b/examples/demo_search/public/types.ts deleted file mode 100644 index 64725da7df870..0000000000000 --- a/examples/demo_search/public/types.ts +++ /dev/null @@ -1,28 +0,0 @@ -/* - * Licensed to Elasticsearch B.V. under one or more contributor - * license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright - * ownership. Elasticsearch B.V. licenses this file to you under - * the Apache License, Version 2.0 (the "License"); you may - * not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. - */ - -import { DataPublicPluginStart, DataPublicPluginSetup } from '../../../src/plugins/data/public'; - -export interface DemoDataSearchSetupDependencies { - data: DataPublicPluginSetup; -} - -export interface DemoDataSearchStartDependencies { - data: DataPublicPluginStart; -} diff --git a/examples/demo_search/server/async_demo_search_strategy.ts b/examples/demo_search/server/async_demo_search_strategy.ts deleted file mode 100644 index 2eda0f4d09e11..0000000000000 --- a/examples/demo_search/server/async_demo_search_strategy.ts +++ /dev/null @@ -1,62 +0,0 @@ -/* - * Licensed to Elasticsearch B.V. under one or more contributor - * license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright - * ownership. Elasticsearch B.V. licenses this file to you under - * the Apache License, Version 2.0 (the "License"); you may - * not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. - */ - -import { ISearchStrategy } from '../../../src/plugins/data/server'; -import { ASYNC_DEMO_SEARCH_STRATEGY, IAsyncDemoRequest } from '../common'; - -export const asyncDemoSearchStrategyProvider = (): ISearchStrategy< - typeof ASYNC_DEMO_SEARCH_STRATEGY -> => { - function getFibonacciSequence(n = 0) { - const beginning = [0, 1].slice(0, n); - return Array(Math.max(0, n)) - .fill(null) - .reduce((sequence, value, i) => { - if (i < 2) return sequence; - return [...sequence, sequence[i - 1] + sequence[i - 2]]; - }, beginning); - } - - const generateId = (() => { - let id = 0; - return () => `${id++}`; - })(); - - const loadedMap = new Map(); - const totalMap = new Map(); - - return { - search: async (context, request: IAsyncDemoRequest) => { - const id = request.id ?? generateId(); - - const loaded = (loadedMap.get(id) ?? 0) + 1; - loadedMap.set(id, loaded); - - const total = request.fibonacciNumbers ?? totalMap.get(id); - totalMap.set(id, total); - - const fibonacciSequence = getFibonacciSequence(loaded); - return { id, total, loaded, fibonacciSequence }; - }, - cancel: async (context, id) => { - loadedMap.delete(id); - totalMap.delete(id); - }, - }; -}; diff --git a/examples/demo_search/server/demo_search_strategy.ts b/examples/demo_search/server/demo_search_strategy.ts deleted file mode 100644 index 36280ad22e83c..0000000000000 --- a/examples/demo_search/server/demo_search_strategy.ts +++ /dev/null @@ -1,34 +0,0 @@ -/* - * Licensed to Elasticsearch B.V. under one or more contributor - * license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright - * ownership. Elasticsearch B.V. licenses this file to you under - * the Apache License, Version 2.0 (the "License"); you may - * not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. - */ - -import { ISearchStrategy } from '../../../src/plugins/data/server'; -import { DEMO_SEARCH_STRATEGY, IDemoRequest } from '../common'; - -export const demoSearchStrategyProvider = (): ISearchStrategy => { - return { - search: (context, request: IDemoRequest) => { - return Promise.resolve({ - greeting: - request.mood === 'happy' - ? `Lovely to meet you, ${request.name}` - : `Hope you feel better, ${request.name}`, - }); - }, - }; -}; diff --git a/examples/demo_search/server/index.ts b/examples/demo_search/server/index.ts deleted file mode 100644 index 368575b705c90..0000000000000 --- a/examples/demo_search/server/index.ts +++ /dev/null @@ -1,22 +0,0 @@ -/* - * Licensed to Elasticsearch B.V. under one or more contributor - * license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright - * ownership. Elasticsearch B.V. licenses this file to you under - * the Apache License, Version 2.0 (the "License"); you may - * not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. - */ - -import { DemoDataPlugin } from './plugin'; - -export const plugin = () => new DemoDataPlugin(); diff --git a/examples/demo_search/server/plugin.ts b/examples/demo_search/server/plugin.ts deleted file mode 100644 index 8a72b5007f988..0000000000000 --- a/examples/demo_search/server/plugin.ts +++ /dev/null @@ -1,71 +0,0 @@ -/* - * Licensed to Elasticsearch B.V. under one or more contributor - * license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright - * ownership. Elasticsearch B.V. licenses this file to you under - * the Apache License, Version 2.0 (the "License"); you may - * not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. - */ - -import { Plugin, CoreSetup } from 'kibana/server'; -import { PluginSetup as DataPluginSetup } from 'src/plugins/data/server'; -import { demoSearchStrategyProvider } from './demo_search_strategy'; -import { - DEMO_SEARCH_STRATEGY, - IDemoRequest, - IDemoResponse, - ASYNC_DEMO_SEARCH_STRATEGY, - IAsyncDemoRequest, - IAsyncDemoResponse, -} from '../common'; -import { asyncDemoSearchStrategyProvider } from './async_demo_search_strategy'; - -interface IDemoSearchExplorerDeps { - data: DataPluginSetup; -} - -/** - * Add the typescript mappings for our search strategy to the request and - * response types. This allows typescript to require the right shapes if - * making the call: - * const response = context.search.search(request, DEMO_SEARCH_STRATEGY); - * - * If the caller does not pass in the right `request` shape, typescript will - * complain. The caller will also get a typed response. - */ -declare module '../../../src/plugins/data/server' { - export interface IRequestTypesMap { - [DEMO_SEARCH_STRATEGY]: IDemoRequest; - [ASYNC_DEMO_SEARCH_STRATEGY]: IAsyncDemoRequest; - } - - export interface IResponseTypesMap { - [DEMO_SEARCH_STRATEGY]: IDemoResponse; - [ASYNC_DEMO_SEARCH_STRATEGY]: IAsyncDemoResponse; - } -} - -export class DemoDataPlugin implements Plugin { - constructor() {} - - public setup(core: CoreSetup, deps: IDemoSearchExplorerDeps) { - deps.data.search.registerSearchStrategy(DEMO_SEARCH_STRATEGY, demoSearchStrategyProvider()); - deps.data.search.registerSearchStrategy( - ASYNC_DEMO_SEARCH_STRATEGY, - asyncDemoSearchStrategyProvider() - ); - } - - public start() {} - public stop() {} -} diff --git a/examples/demo_search/tsconfig.json b/examples/demo_search/tsconfig.json deleted file mode 100644 index 7fa03739119b4..0000000000000 --- a/examples/demo_search/tsconfig.json +++ /dev/null @@ -1,16 +0,0 @@ -{ - "extends": "../../tsconfig.json", - "compilerOptions": { - "outDir": "./target", - "skipLibCheck": true - }, - "include": [ - "index.ts", - "common/**/*.ts", - "public/**/*.ts", - "public/**/*.tsx", - "server/**/*.ts", - "../../typings/**/*" - ], - "exclude": [] -} diff --git a/examples/embeddable_examples/common/book_saved_object_attributes.ts b/examples/embeddable_examples/common/book_saved_object_attributes.ts new file mode 100644 index 0000000000000..62c08b7b81362 --- /dev/null +++ b/examples/embeddable_examples/common/book_saved_object_attributes.ts @@ -0,0 +1,28 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { SavedObjectAttributes } from '../../../src/core/types'; + +export const BOOK_SAVED_OBJECT = 'book'; + +export interface BookSavedObjectAttributes extends SavedObjectAttributes { + title: string; + author?: string; + readIt?: boolean; +} diff --git a/examples/embeddable_examples/common/index.ts b/examples/embeddable_examples/common/index.ts index 726420fb9bdc3..55715113a12a2 100644 --- a/examples/embeddable_examples/common/index.ts +++ b/examples/embeddable_examples/common/index.ts @@ -18,3 +18,4 @@ */ export { TodoSavedObjectAttributes } from './todo_saved_object_attributes'; +export { BookSavedObjectAttributes, BOOK_SAVED_OBJECT } from './book_saved_object_attributes'; diff --git a/examples/embeddable_examples/kibana.json b/examples/embeddable_examples/kibana.json index 486c6322fad93..771c19cfdbd3d 100644 --- a/examples/embeddable_examples/kibana.json +++ b/examples/embeddable_examples/kibana.json @@ -4,7 +4,8 @@ "kibanaVersion": "kibana", "server": true, "ui": true, - "requiredPlugins": ["embeddable"], + "requiredPlugins": ["embeddable", "uiActions"], "optionalPlugins": [], - "extraPublicDirs": ["public/todo", "public/hello_world", "public/todo/todo_ref_embeddable"] + "extraPublicDirs": ["public/todo", "public/hello_world", "public/todo/todo_ref_embeddable"], + "requiredBundles": ["kibanaReact"] } diff --git a/examples/embeddable_examples/public/book/book_component.tsx b/examples/embeddable_examples/public/book/book_component.tsx new file mode 100644 index 0000000000000..064e13c131a0a --- /dev/null +++ b/examples/embeddable_examples/public/book/book_component.tsx @@ -0,0 +1,90 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +import React from 'react'; +import { EuiFlexItem, EuiFlexGroup, EuiIcon } from '@elastic/eui'; + +import { EuiText } from '@elastic/eui'; +import { EuiFlexGrid } from '@elastic/eui'; +import { withEmbeddableSubscription } from '../../../../src/plugins/embeddable/public'; +import { BookEmbeddableInput, BookEmbeddableOutput, BookEmbeddable } from './book_embeddable'; + +interface Props { + input: BookEmbeddableInput; + output: BookEmbeddableOutput; + embeddable: BookEmbeddable; +} + +function wrapSearchTerms(task?: string, search?: string) { + if (!search || !task) return task; + const parts = task.split(new RegExp(`(${search})`, 'g')); + return parts.map((part, i) => + part === search ? ( + + {part} + + ) : ( + part + ) + ); +} + +export function BookEmbeddableComponentInner({ input: { search }, output: { attributes } }: Props) { + const title = attributes?.title; + const author = attributes?.author; + const readIt = attributes?.readIt; + + return ( + + + + {title ? ( + + +

{wrapSearchTerms(title, search)},

+ + + ) : null} + {author ? ( + + +
-{wrapSearchTerms(author, search)}
+ + + ) : null} + {readIt ? ( + + + + ) : ( + + + + )} + + + + ); +} + +export const BookEmbeddableComponent = withEmbeddableSubscription< + BookEmbeddableInput, + BookEmbeddableOutput, + BookEmbeddable, + {} +>(BookEmbeddableComponentInner); diff --git a/examples/embeddable_examples/public/book/book_embeddable.tsx b/examples/embeddable_examples/public/book/book_embeddable.tsx new file mode 100644 index 0000000000000..d49bd3280d97d --- /dev/null +++ b/examples/embeddable_examples/public/book/book_embeddable.tsx @@ -0,0 +1,123 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +import React from 'react'; +import ReactDOM from 'react-dom'; +import { Subscription } from 'rxjs'; +import { + Embeddable, + EmbeddableInput, + IContainer, + EmbeddableOutput, + SavedObjectEmbeddableInput, + AttributeService, +} from '../../../../src/plugins/embeddable/public'; +import { BookSavedObjectAttributes } from '../../common'; +import { BookEmbeddableComponent } from './book_component'; + +export const BOOK_EMBEDDABLE = 'book'; +export type BookEmbeddableInput = BookByValueInput | BookByReferenceInput; +export interface BookEmbeddableOutput extends EmbeddableOutput { + hasMatch: boolean; + attributes: BookSavedObjectAttributes; +} + +interface BookInheritedInput extends EmbeddableInput { + search?: string; +} + +export type BookByValueInput = { attributes: BookSavedObjectAttributes } & BookInheritedInput; +export type BookByReferenceInput = SavedObjectEmbeddableInput & BookInheritedInput; + +/** + * Returns whether any attributes contain the search string. If search is empty, true is returned. If + * there are no savedAttributes, false is returned. + * @param search - the search string + * @param savedAttributes - the saved object attributes for the saved object with id `input.savedObjectId` + */ +function getHasMatch(search?: string, savedAttributes?: BookSavedObjectAttributes): boolean { + if (!search) return true; + if (!savedAttributes) return false; + return Boolean( + (savedAttributes.author && savedAttributes.author.match(search)) || + (savedAttributes.title && savedAttributes.title.match(search)) + ); +} + +export class BookEmbeddable extends Embeddable { + public readonly type = BOOK_EMBEDDABLE; + private subscription: Subscription; + private node?: HTMLElement; + private savedObjectId?: string; + private attributes?: BookSavedObjectAttributes; + + constructor( + initialInput: BookEmbeddableInput, + private attributeService: AttributeService< + BookSavedObjectAttributes, + BookByValueInput, + BookByReferenceInput + >, + { + parent, + }: { + parent?: IContainer; + } + ) { + super(initialInput, {} as BookEmbeddableOutput, parent); + + this.subscription = this.getInput$().subscribe(async () => { + const savedObjectId = (this.getInput() as BookByReferenceInput).savedObjectId; + const attributes = (this.getInput() as BookByValueInput).attributes; + if (this.attributes !== attributes || this.savedObjectId !== savedObjectId) { + this.savedObjectId = savedObjectId; + this.reload(); + } else { + this.updateOutput({ + attributes: this.attributes, + hasMatch: getHasMatch(this.input.search, this.attributes), + }); + } + }); + } + + public render(node: HTMLElement) { + if (this.node) { + ReactDOM.unmountComponentAtNode(this.node); + } + this.node = node; + ReactDOM.render(, node); + } + + public async reload() { + this.attributes = await this.attributeService.unwrapAttributes(this.input); + + this.updateOutput({ + attributes: this.attributes, + hasMatch: getHasMatch(this.input.search, this.attributes), + }); + } + + public destroy() { + super.destroy(); + this.subscription.unsubscribe(); + if (this.node) { + ReactDOM.unmountComponentAtNode(this.node); + } + } +} diff --git a/examples/embeddable_examples/public/book/book_embeddable_factory.tsx b/examples/embeddable_examples/public/book/book_embeddable_factory.tsx new file mode 100644 index 0000000000000..f4a32fb498a2d --- /dev/null +++ b/examples/embeddable_examples/public/book/book_embeddable_factory.tsx @@ -0,0 +1,127 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import React from 'react'; +import { i18n } from '@kbn/i18n'; +import { BookSavedObjectAttributes, BOOK_SAVED_OBJECT } from '../../common'; +import { toMountPoint } from '../../../../src/plugins/kibana_react/public'; +import { + EmbeddableFactoryDefinition, + EmbeddableStart, + IContainer, + AttributeService, + EmbeddableFactory, +} from '../../../../src/plugins/embeddable/public'; +import { + BookEmbeddable, + BOOK_EMBEDDABLE, + BookEmbeddableInput, + BookEmbeddableOutput, + BookByValueInput, + BookByReferenceInput, +} from './book_embeddable'; +import { CreateEditBookComponent } from './create_edit_book_component'; +import { OverlayStart } from '../../../../src/core/public'; + +interface StartServices { + getAttributeService: EmbeddableStart['getAttributeService']; + openModal: OverlayStart['openModal']; +} + +export type BookEmbeddableFactory = EmbeddableFactory< + BookEmbeddableInput, + BookEmbeddableOutput, + BookEmbeddable, + BookSavedObjectAttributes +>; + +export class BookEmbeddableFactoryDefinition + implements + EmbeddableFactoryDefinition< + BookEmbeddableInput, + BookEmbeddableOutput, + BookEmbeddable, + BookSavedObjectAttributes + > { + public readonly type = BOOK_EMBEDDABLE; + public savedObjectMetaData = { + name: 'Book', + includeFields: ['title', 'author', 'readIt'], + type: BOOK_SAVED_OBJECT, + getIconForSavedObject: () => 'pencil', + }; + + private attributeService?: AttributeService< + BookSavedObjectAttributes, + BookByValueInput, + BookByReferenceInput + >; + + constructor(private getStartServices: () => Promise) {} + + public async isEditable() { + return true; + } + + public async create(input: BookEmbeddableInput, parent?: IContainer) { + return new BookEmbeddable(input, await this.getAttributeService(), { + parent, + }); + } + + public getDisplayName() { + return i18n.translate('embeddableExamples.book.displayName', { + defaultMessage: 'Book', + }); + } + + public async getExplicitInput(): Promise> { + const { openModal } = await this.getStartServices(); + return new Promise>((resolve) => { + const onSave = async (attributes: BookSavedObjectAttributes, useRefType: boolean) => { + const wrappedAttributes = (await this.getAttributeService()).wrapAttributes( + attributes, + useRefType + ); + resolve(wrappedAttributes); + }; + const overlay = openModal( + toMountPoint( + { + onSave(attributes, useRefType); + overlay.close(); + }} + /> + ) + ); + }); + } + + private async getAttributeService() { + if (!this.attributeService) { + this.attributeService = await (await this.getStartServices()).getAttributeService< + BookSavedObjectAttributes, + BookByValueInput, + BookByReferenceInput + >(this.type); + } + return this.attributeService; + } +} diff --git a/examples/embeddable_examples/public/book/create_edit_book_component.tsx b/examples/embeddable_examples/public/book/create_edit_book_component.tsx new file mode 100644 index 0000000000000..7e2d3cb9d88ab --- /dev/null +++ b/examples/embeddable_examples/public/book/create_edit_book_component.tsx @@ -0,0 +1,88 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +import React, { useState } from 'react'; +import { EuiModalBody, EuiCheckbox } from '@elastic/eui'; +import { EuiFieldText } from '@elastic/eui'; +import { EuiButton } from '@elastic/eui'; +import { EuiModalFooter } from '@elastic/eui'; +import { EuiModalHeader } from '@elastic/eui'; +import { EuiFormRow } from '@elastic/eui'; +import { BookSavedObjectAttributes } from '../../common'; + +export function CreateEditBookComponent({ + savedObjectId, + attributes, + onSave, +}: { + savedObjectId?: string; + attributes?: BookSavedObjectAttributes; + onSave: (attributes: BookSavedObjectAttributes, useRefType: boolean) => void; +}) { + const [title, setTitle] = useState(attributes?.title ?? ''); + const [author, setAuthor] = useState(attributes?.author ?? ''); + const [readIt, setReadIt] = useState(attributes?.readIt ?? false); + return ( + + +

{`${savedObjectId ? 'Create new ' : 'Edit '}`}

+ + + + setTitle(e.target.value)} + /> + + + setAuthor(e.target.value)} + /> + + + setReadIt(event.target.checked)} + /> + + + + onSave({ title, author, readIt }, false)} + > + {savedObjectId ? 'Unlink from library item' : 'Save and Return'} + + onSave({ title, author, readIt }, true)} + > + {savedObjectId ? 'Update library item' : 'Save to library'} + + + + ); +} diff --git a/examples/embeddable_examples/public/book/edit_book_action.tsx b/examples/embeddable_examples/public/book/edit_book_action.tsx new file mode 100644 index 0000000000000..222f70e0be60f --- /dev/null +++ b/examples/embeddable_examples/public/book/edit_book_action.tsx @@ -0,0 +1,93 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +import React from 'react'; +import { OverlayStart } from 'kibana/public'; +import { i18n } from '@kbn/i18n'; +import { BookSavedObjectAttributes, BOOK_SAVED_OBJECT } from '../../common'; +import { createAction } from '../../../../src/plugins/ui_actions/public'; +import { toMountPoint } from '../../../../src/plugins/kibana_react/public'; +import { + ViewMode, + EmbeddableStart, + SavedObjectEmbeddableInput, +} from '../../../../src/plugins/embeddable/public'; +import { + BookEmbeddable, + BOOK_EMBEDDABLE, + BookByReferenceInput, + BookByValueInput, +} from './book_embeddable'; +import { CreateEditBookComponent } from './create_edit_book_component'; + +interface StartServices { + openModal: OverlayStart['openModal']; + getAttributeService: EmbeddableStart['getAttributeService']; +} + +interface ActionContext { + embeddable: BookEmbeddable; +} + +export const ACTION_EDIT_BOOK = 'ACTION_EDIT_BOOK'; + +export const createEditBookAction = (getStartServices: () => Promise) => + createAction({ + getDisplayName: () => + i18n.translate('embeddableExamples.book.edit', { defaultMessage: 'Edit Book' }), + type: ACTION_EDIT_BOOK, + order: 100, + getIconType: () => 'documents', + isCompatible: async ({ embeddable }: ActionContext) => { + return ( + embeddable.type === BOOK_EMBEDDABLE && embeddable.getInput().viewMode === ViewMode.EDIT + ); + }, + execute: async ({ embeddable }: ActionContext) => { + const { openModal, getAttributeService } = await getStartServices(); + const attributeService = getAttributeService< + BookSavedObjectAttributes, + BookByValueInput, + BookByReferenceInput + >(BOOK_SAVED_OBJECT); + const onSave = async (attributes: BookSavedObjectAttributes, useRefType: boolean) => { + const newInput = await attributeService.wrapAttributes(attributes, useRefType, embeddable); + if (!useRefType && (embeddable.getInput() as SavedObjectEmbeddableInput).savedObjectId) { + // Remove the savedObejctId when un-linking + newInput.savedObjectId = null; + } + embeddable.updateInput(newInput); + if (useRefType) { + // Ensures that any duplicate embeddables also register the changes. This mirrors the behavior of going back and forth between apps + embeddable.getRoot().reload(); + } + }; + const overlay = openModal( + toMountPoint( + { + overlay.close(); + onSave(attributes, useRefType); + }} + /> + ) + ); + }, + }); diff --git a/examples/embeddable_examples/public/book/index.ts b/examples/embeddable_examples/public/book/index.ts new file mode 100644 index 0000000000000..46f44926e2152 --- /dev/null +++ b/examples/embeddable_examples/public/book/index.ts @@ -0,0 +1,21 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +export * from './book_embeddable'; +export * from './book_embeddable_factory'; diff --git a/examples/embeddable_examples/public/create_sample_data.ts b/examples/embeddable_examples/public/create_sample_data.ts index bd5ade18aa91e..d598c32a182fe 100644 --- a/examples/embeddable_examples/public/create_sample_data.ts +++ b/examples/embeddable_examples/public/create_sample_data.ts @@ -18,9 +18,9 @@ */ import { SavedObjectsClientContract } from 'kibana/public'; -import { TodoSavedObjectAttributes } from '../common'; +import { TodoSavedObjectAttributes, BookSavedObjectAttributes, BOOK_SAVED_OBJECT } from '../common'; -export async function createSampleData(client: SavedObjectsClientContract) { +export async function createSampleData(client: SavedObjectsClientContract, overwrite = true) { await client.create( 'todo', { @@ -30,7 +30,20 @@ export async function createSampleData(client: SavedObjectsClientContract) { }, { id: 'sample-todo-saved-object', - overwrite: true, + overwrite, + } + ); + + await client.create( + BOOK_SAVED_OBJECT, + { + title: 'Pillars of the Earth', + author: 'Ken Follett', + readIt: true, + }, + { + id: 'sample-book-saved-object', + overwrite, } ); } diff --git a/examples/embeddable_examples/public/index.ts b/examples/embeddable_examples/public/index.ts index ec007f7c626f0..86f50f2b6e114 100644 --- a/examples/embeddable_examples/public/index.ts +++ b/examples/embeddable_examples/public/index.ts @@ -26,6 +26,8 @@ export { export { ListContainer, LIST_CONTAINER, ListContainerFactory } from './list_container'; export { TODO_EMBEDDABLE, TodoEmbeddableFactory } from './todo'; +export { BOOK_EMBEDDABLE } from './book'; + import { EmbeddableExamplesPlugin } from './plugin'; export { diff --git a/examples/embeddable_examples/public/plugin.ts b/examples/embeddable_examples/public/plugin.ts index d65ca1e8e7e8d..95f4f5b41e198 100644 --- a/examples/embeddable_examples/public/plugin.ts +++ b/examples/embeddable_examples/public/plugin.ts @@ -17,14 +17,19 @@ * under the License. */ -import { EmbeddableSetup, EmbeddableStart } from '../../../src/plugins/embeddable/public'; -import { CoreSetup, CoreStart, Plugin } from '../../../src/core/public'; import { + EmbeddableSetup, + EmbeddableStart, + CONTEXT_MENU_TRIGGER, +} from '../../../src/plugins/embeddable/public'; +import { Plugin, CoreSetup, CoreStart } from '../../../src/core/public'; +import { + HelloWorldEmbeddableFactory, HELLO_WORLD_EMBEDDABLE, HelloWorldEmbeddableFactoryDefinition, - HelloWorldEmbeddableFactory, } from './hello_world'; import { TODO_EMBEDDABLE, TodoEmbeddableFactory, TodoEmbeddableFactoryDefinition } from './todo'; + import { MULTI_TASK_TODO_EMBEDDABLE, MultiTaskTodoEmbeddableFactory, @@ -46,9 +51,17 @@ import { TodoRefEmbeddableFactory, TodoRefEmbeddableFactoryDefinition, } from './todo/todo_ref_embeddable_factory'; +import { ACTION_EDIT_BOOK, createEditBookAction } from './book/edit_book_action'; +import { BookEmbeddable, BOOK_EMBEDDABLE } from './book/book_embeddable'; +import { + BookEmbeddableFactory, + BookEmbeddableFactoryDefinition, +} from './book/book_embeddable_factory'; +import { UiActionsStart } from '../../../src/plugins/ui_actions/public'; export interface EmbeddableExamplesSetupDependencies { embeddable: EmbeddableSetup; + uiActions: UiActionsStart; } export interface EmbeddableExamplesStartDependencies { @@ -62,6 +75,7 @@ interface ExampleEmbeddableFactories { getListContainerEmbeddableFactory: () => ListContainerFactory; getTodoEmbeddableFactory: () => TodoEmbeddableFactory; getTodoRefEmbeddableFactory: () => TodoRefEmbeddableFactory; + getBookEmbeddableFactory: () => BookEmbeddableFactory; } export interface EmbeddableExamplesStart { @@ -69,6 +83,12 @@ export interface EmbeddableExamplesStart { factories: ExampleEmbeddableFactories; } +declare module '../../../src/plugins/ui_actions/public' { + export interface ActionContextMapping { + [ACTION_EDIT_BOOK]: { embeddable: BookEmbeddable }; + } +} + export class EmbeddableExamplesPlugin implements Plugin< @@ -121,6 +141,20 @@ export class EmbeddableExamplesPlugin getEmbeddableFactory: (await core.getStartServices())[1].embeddable.getEmbeddableFactory, })) ); + this.exampleEmbeddableFactories.getBookEmbeddableFactory = deps.embeddable.registerEmbeddableFactory( + BOOK_EMBEDDABLE, + new BookEmbeddableFactoryDefinition(async () => ({ + getAttributeService: (await core.getStartServices())[1].embeddable.getAttributeService, + openModal: (await core.getStartServices())[0].overlays.openModal, + })) + ); + + const editBookAction = createEditBookAction(async () => ({ + getAttributeService: (await core.getStartServices())[1].embeddable.getAttributeService, + openModal: (await core.getStartServices())[0].overlays.openModal, + })); + deps.uiActions.registerAction(editBookAction); + deps.uiActions.attachAction(CONTEXT_MENU_TRIGGER, editBookAction.id); } public start( diff --git a/examples/embeddable_examples/server/book_saved_object.ts b/examples/embeddable_examples/server/book_saved_object.ts new file mode 100644 index 0000000000000..f0aca57f7925f --- /dev/null +++ b/examples/embeddable_examples/server/book_saved_object.ts @@ -0,0 +1,40 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { SavedObjectsType } from 'kibana/server'; + +export const bookSavedObject: SavedObjectsType = { + name: 'book', + hidden: false, + namespaceType: 'agnostic', + mappings: { + properties: { + title: { + type: 'keyword', + }, + author: { + type: 'keyword', + }, + readIt: { + type: 'boolean', + }, + }, + }, + migrations: {}, +}; diff --git a/examples/embeddable_examples/server/plugin.ts b/examples/embeddable_examples/server/plugin.ts index d956b834d0d3c..1308ac9e0fc5e 100644 --- a/examples/embeddable_examples/server/plugin.ts +++ b/examples/embeddable_examples/server/plugin.ts @@ -19,10 +19,12 @@ import { Plugin, CoreSetup, CoreStart } from 'kibana/server'; import { todoSavedObject } from './todo_saved_object'; +import { bookSavedObject } from './book_saved_object'; export class EmbeddableExamplesPlugin implements Plugin { public setup(core: CoreSetup) { core.savedObjects.registerType(todoSavedObject); + core.savedObjects.registerType(bookSavedObject); } public start(core: CoreStart) {} diff --git a/examples/embeddable_explorer/public/embeddable_panel_example.tsx b/examples/embeddable_explorer/public/embeddable_panel_example.tsx index b2807f9a4c346..ca9675bb7f5a1 100644 --- a/examples/embeddable_explorer/public/embeddable_panel_example.tsx +++ b/examples/embeddable_explorer/public/embeddable_panel_example.tsx @@ -33,6 +33,7 @@ import { EmbeddableStart, IEmbeddable } from '../../../src/plugins/embeddable/pu import { HELLO_WORLD_EMBEDDABLE, TODO_EMBEDDABLE, + BOOK_EMBEDDABLE, MULTI_TASK_TODO_EMBEDDABLE, SearchableListContainerFactory, } from '../../embeddable_examples/public'; @@ -72,6 +73,35 @@ export function EmbeddablePanelExample({ embeddableServices, searchListContainer tasks: ['Go to school', 'Watch planet earth', 'Read the encyclopedia'], }, }, + '4': { + type: BOOK_EMBEDDABLE, + explicitInput: { + id: '4', + savedObjectId: 'sample-book-saved-object', + }, + }, + '5': { + type: BOOK_EMBEDDABLE, + explicitInput: { + id: '5', + attributes: { + title: 'The Sympathizer', + author: 'Viet Thanh Nguyen', + readIt: true, + }, + }, + }, + '6': { + type: BOOK_EMBEDDABLE, + explicitInput: { + id: '6', + attributes: { + title: 'The Hobbit', + author: 'J.R.R. Tolkien', + readIt: false, + }, + }, + }, }, }; diff --git a/examples/routing_example/README.md b/examples/routing_example/README.md new file mode 100644 index 0000000000000..0a88707bf70bb --- /dev/null +++ b/examples/routing_example/README.md @@ -0,0 +1,9 @@ +Team owner: Platform + +A working example of a plugin that registers and uses multiple custom routes. + +Read more: + +- [IRouter API Docs](../../docs/development/core/server/kibana-plugin-core-server.irouter.md) +- [HttpHandler (core.http.fetch) API Docs](../../docs/development/core/public/kibana-plugin-core-public.httphandler.md) +- [Routing Conventions](../../STYLEGUIDE.md#api-endpoints) \ No newline at end of file diff --git a/examples/routing_example/common/index.ts b/examples/routing_example/common/index.ts new file mode 100644 index 0000000000000..5aa47b1f69cdf --- /dev/null +++ b/examples/routing_example/common/index.ts @@ -0,0 +1,27 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +export const RANDOM_NUMBER_ROUTE_PATH = '/api/random_number'; + +export const RANDOM_NUMBER_BETWEEN_ROUTE_PATH = '/api/random_number_between'; + +export const POST_MESSAGE_ROUTE_PATH = '/api/post_message'; + +// Internal APIs should use the `internal` prefix, instead of the `api` prefix. +export const INTERNAL_GET_MESSAGE_BY_ID_ROUTE = '/internal/get_message'; diff --git a/examples/routing_example/kibana.json b/examples/routing_example/kibana.json new file mode 100644 index 0000000000000..37851a0da5a85 --- /dev/null +++ b/examples/routing_example/kibana.json @@ -0,0 +1,9 @@ +{ + "id": "routingExample", + "version": "0.0.1", + "kibanaVersion": "kibana", + "server": true, + "ui": true, + "requiredPlugins": ["developerExamples"], + "optionalPlugins": [] +} diff --git a/examples/routing_example/public/app.tsx b/examples/routing_example/public/app.tsx new file mode 100644 index 0000000000000..3b33cb33ccb01 --- /dev/null +++ b/examples/routing_example/public/app.tsx @@ -0,0 +1,105 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import React from 'react'; +import ReactDOM from 'react-dom'; +import { AppMountParameters } from 'kibana/public'; +import { + EuiPage, + EuiPageBody, + EuiPageContent, + EuiText, + EuiHorizontalRule, + EuiPageContentHeader, + EuiListGroup, +} from '@elastic/eui'; +import { RandomNumberRouteExample } from './random_number_example'; +import { RandomNumberBetweenRouteExample } from './random_number_between_example'; +import { Services } from './services'; +import { PostMessageRouteExample } from './post_message_example'; +import { GetMessageRouteExample } from './get_message_example'; + +type Props = Services; + +function RoutingExplorer({ + fetchRandomNumber, + fetchRandomNumberBetween, + addSuccessToast, + postMessage, + getMessageById, +}: Props) { + return ( + + + + + +

Routing examples

+ + + + + + + + + + + + + + + + + + + ); +} + +export const renderApp = (props: Props, element: AppMountParameters['element']) => { + ReactDOM.render(, element); + + return () => ReactDOM.unmountComponentAtNode(element); +}; diff --git a/examples/routing_example/public/get_message_example.tsx b/examples/routing_example/public/get_message_example.tsx new file mode 100644 index 0000000000000..3c34326564d2b --- /dev/null +++ b/examples/routing_example/public/get_message_example.tsx @@ -0,0 +1,96 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +import React, { useCallback } from 'react'; +import { useState } from 'react'; +import { + EuiText, + EuiButton, + EuiLoadingSpinner, + EuiFieldText, + EuiCallOut, + EuiFormRow, +} from '@elastic/eui'; +import { HttpFetchError } from '../../../src/core/public'; +import { isError } from './is_error'; +import { Services } from './services'; + +interface Props { + getMessageById: Services['getMessageById']; +} + +export function GetMessageRouteExample({ getMessageById }: Props) { + const [error, setError] = useState(); + const [isFetching, setIsFetching] = useState(false); + const [message, setMessage] = useState(''); + const [id, setId] = useState(''); + + const doFetch = useCallback(async () => { + if (isFetching) return; + setIsFetching(true); + const response = await getMessageById(id); + + if (isError(response)) { + setError(response); + setMessage(''); + } else { + setError(undefined); + setMessage(response); + } + + setIsFetching(false); + }, [isFetching, getMessageById, setMessage, id]); + + return ( + + +

GET example with param

+ +

This examples uses a simple GET route that takes an id as a param in the route path.

+ + setId(e.target.value)} + data-test-subj="routingExampleGetMessageId" + /> + + + + doFetch()} + > + {isFetching ? : 'Get message'} + + + + {error !== undefined ? ( + + {error.message} + + ) : null} + {message !== '' ? ( +

+ Message is: 

{message}
+

+ ) : null} + + + ); +} diff --git a/examples/routing_example/public/index.ts b/examples/routing_example/public/index.ts new file mode 100644 index 0000000000000..2bb703e71cbef --- /dev/null +++ b/examples/routing_example/public/index.ts @@ -0,0 +1,23 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { PluginInitializer } from 'kibana/public'; +import { RoutingExamplePlugin } from './plugin'; + +export const plugin: PluginInitializer<{}, {}> = () => new RoutingExamplePlugin(); diff --git a/examples/routing_example/public/is_error.ts b/examples/routing_example/public/is_error.ts new file mode 100644 index 0000000000000..528cca5b50d5d --- /dev/null +++ b/examples/routing_example/public/is_error.ts @@ -0,0 +1,24 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { HttpFetchError } from '../../../src/core/public'; + +export function isError(error: T | HttpFetchError): error is HttpFetchError { + return error instanceof HttpFetchError; +} diff --git a/examples/routing_example/public/plugin.tsx b/examples/routing_example/public/plugin.tsx new file mode 100644 index 0000000000000..eabdd2ade05b2 --- /dev/null +++ b/examples/routing_example/public/plugin.tsx @@ -0,0 +1,78 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +import { + CoreStart, + Plugin, + CoreSetup, + AppMountParameters, + AppNavLinkStatus, +} from '../../../src/core/public'; +import { DeveloperExamplesSetup } from '../../developer_examples/public'; +import { getServices } from './services'; + +interface SetupDeps { + developerExamples: DeveloperExamplesSetup; +} + +export class RoutingExamplePlugin implements Plugin<{}, {}, SetupDeps, {}> { + public setup(core: CoreSetup, { developerExamples }: SetupDeps) { + core.application.register({ + id: 'routingExample', + title: 'Routing', + navLinkStatus: AppNavLinkStatus.hidden, + async mount(params: AppMountParameters) { + const [coreStart] = await core.getStartServices(); + const startServices = getServices(coreStart); + const { renderApp } = await import('./app'); + return renderApp(startServices, params.element); + }, + }); + + developerExamples.register({ + appId: 'routingExample', + title: 'Routing', + description: `Examples show how to use core routing and fetch services to register and query your own custom routes.`, + links: [ + { + label: 'IRouter', + href: + 'https://github.com/elastic/kibana/blob/master/docs/development/core/server/kibana-plugin-core-server.irouter.md', + iconType: 'logoGithub', + target: '_blank', + size: 's', + }, + { + label: 'HttpHandler (core.http.fetch)', + href: + 'https://github.com/elastic/kibana/blob/master/docs/development/core/public/kibana-plugin-core-public.httphandler.md', + iconType: 'logoGithub', + target: '_blank', + size: 's', + }, + ], + }); + return {}; + } + + public start(core: CoreStart) { + return {}; + } + + public stop() {} +} diff --git a/examples/routing_example/public/post_message_example.tsx b/examples/routing_example/public/post_message_example.tsx new file mode 100644 index 0000000000000..3004d66c4aa97 --- /dev/null +++ b/examples/routing_example/public/post_message_example.tsx @@ -0,0 +1,103 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +import React, { useCallback } from 'react'; +import { useState } from 'react'; +import { + EuiText, + EuiButton, + EuiLoadingSpinner, + EuiFieldText, + EuiCallOut, + EuiFormRow, + EuiTextArea, +} from '@elastic/eui'; +import { HttpFetchError } from '../../../src/core/public'; +import { isError } from './is_error'; +import { Services } from './services'; + +interface Props { + postMessage: Services['postMessage']; + addSuccessToast: Services['addSuccessToast']; +} + +export function PostMessageRouteExample({ postMessage, addSuccessToast }: Props) { + const [error, setError] = useState(); + const [isPosting, setIsPosting] = useState(false); + const [message, setMessage] = useState(''); + const [id, setId] = useState(''); + + const doFetch = useCallback(async () => { + if (isPosting) return; + setIsPosting(true); + const response = await postMessage(message, id); + + if (response && isError(response)) { + setError(response); + } else { + setError(undefined); + addSuccessToast('Message was added!'); + setMessage(''); + setId(''); + } + + setIsPosting(false); + }, [isPosting, postMessage, addSuccessToast, setMessage, message, id]); + + return ( + + +

POST example with body

+

+ This examples uses a simple POST route that takes a body parameter and an id as a param in + the route path. +

+ + setId(e.target.value)} + data-test-subj="routingExampleSetMessageId" + /> + + + setMessage(e.target.value)} + /> + + + + doFetch()} + > + {isPosting ? : 'Post message'} + + + + {error !== undefined ? ( + + {error.message} + + ) : null} + + + ); +} diff --git a/examples/routing_example/public/random_number_between_example.tsx b/examples/routing_example/public/random_number_between_example.tsx new file mode 100644 index 0000000000000..9f75060193114 --- /dev/null +++ b/examples/routing_example/public/random_number_between_example.tsx @@ -0,0 +1,98 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +import React, { useCallback } from 'react'; +import { useState } from 'react'; +import { + EuiText, + EuiButton, + EuiLoadingSpinner, + EuiFieldText, + EuiCallOut, + EuiFormRow, +} from '@elastic/eui'; +import { HttpFetchError } from '../../../src/core/public'; +import { isError } from './is_error'; +import { Services } from './services'; + +interface Props { + fetchRandomNumberBetween: Services['fetchRandomNumberBetween']; +} + +export function RandomNumberBetweenRouteExample({ fetchRandomNumberBetween }: Props) { + const [error, setError] = useState(); + const [randomNumber, setRandomNumber] = useState(0); + const [isFetching, setIsFetching] = useState(false); + const [maxInput, setMaxInput] = useState('10'); + + const doFetch = useCallback(async () => { + if (isFetching) return; + setIsFetching(true); + const response = await fetchRandomNumberBetween(Number.parseInt(maxInput, 10)); + + if (isError(response)) { + setError(response); + } else { + setRandomNumber(response); + } + + setIsFetching(false); + }, [isFetching, maxInput, fetchRandomNumberBetween]); + + return ( + + +

GET example with query

+

+ This examples uses a simple GET route that takes a query parameter in the request and + returns a single number. +

+ + setMaxInput(e.target.value)} + isInvalid={isNaN(Number(maxInput))} + /> + + + + doFetch()} + > + {isFetching ? : 'Generate random number'} + + + + {error !== undefined ? ( + + {error.message} + + ) : null} + {randomNumber > -1 ? ( +

+ Random number is +
{randomNumber}
+

+ ) : null} + + + ); +} diff --git a/examples/routing_example/public/random_number_example.tsx b/examples/routing_example/public/random_number_example.tsx new file mode 100644 index 0000000000000..6b073826c854f --- /dev/null +++ b/examples/routing_example/public/random_number_example.tsx @@ -0,0 +1,78 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +import React, { useCallback } from 'react'; +import { useState } from 'react'; +import { EuiText, EuiButton, EuiLoadingSpinner, EuiCallOut } from '@elastic/eui'; +import { HttpFetchError } from '../../../src/core/public'; +import { Services } from './services'; +import { isError } from './is_error'; + +interface Props { + fetchRandomNumber: Services['fetchRandomNumber']; +} + +export function RandomNumberRouteExample({ fetchRandomNumber }: Props) { + const [error, setError] = useState(undefined); + const [randomNumber, setRandomNumber] = useState(0); + const [isFetching, setIsFetching] = useState(false); + + const doFetch = useCallback(async () => { + if (isFetching) return; + setIsFetching(true); + const response = await fetchRandomNumber(); + + if (isError(response)) { + setError(response); + } else { + setRandomNumber(response); + } + + setIsFetching(false); + }, [isFetching, fetchRandomNumber]); + + return ( + + +

GET example

+

+ This examples uses a simple GET route that takes no parameters or body in the request and + returns a single number. +

+ doFetch()} + > + {isFetching ? : 'Generate a random number'} + + + {error !== undefined ? ( + + {error} + + ) : null} + {randomNumber > -1 ? ( +

+ Random number is
{randomNumber}
+

+ ) : null} + + + ); +} diff --git a/examples/routing_example/public/services.ts b/examples/routing_example/public/services.ts new file mode 100644 index 0000000000000..08a79270372fd --- /dev/null +++ b/examples/routing_example/public/services.ts @@ -0,0 +1,78 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { CoreStart, HttpFetchError } from 'kibana/public'; +import { + RANDOM_NUMBER_ROUTE_PATH, + RANDOM_NUMBER_BETWEEN_ROUTE_PATH, + POST_MESSAGE_ROUTE_PATH, + INTERNAL_GET_MESSAGE_BY_ID_ROUTE, +} from '../common'; + +export interface Services { + fetchRandomNumber: () => Promise; + fetchRandomNumberBetween: (max: number) => Promise; + postMessage: (message: string, id: string) => Promise; + getMessageById: (id: string) => Promise; + addSuccessToast: (message: string) => void; +} + +export function getServices(core: CoreStart): Services { + return { + addSuccessToast: (message: string) => core.notifications.toasts.addSuccess(message), + fetchRandomNumber: async () => { + try { + const response = await core.http.fetch<{ randomNumber: number }>(RANDOM_NUMBER_ROUTE_PATH); + return response.randomNumber; + } catch (e) { + return e; + } + }, + fetchRandomNumberBetween: async (max: number) => { + try { + const response = await core.http.fetch<{ randomNumber: number }>( + RANDOM_NUMBER_BETWEEN_ROUTE_PATH, + { query: { max } } + ); + return response.randomNumber; + } catch (e) { + return e; + } + }, + postMessage: async (message: string, id: string) => { + try { + await core.http.post(`${POST_MESSAGE_ROUTE_PATH}/${id}`, { + body: JSON.stringify({ message }), + }); + } catch (e) { + return e; + } + }, + getMessageById: async (id: string) => { + try { + const response = await core.http.get<{ message: string }>( + `${INTERNAL_GET_MESSAGE_BY_ID_ROUTE}/${id}` + ); + return response.message; + } catch (e) { + return e; + } + }, + }; +} diff --git a/examples/routing_example/server/index.ts b/examples/routing_example/server/index.ts new file mode 100644 index 0000000000000..77a0d9bb95549 --- /dev/null +++ b/examples/routing_example/server/index.ts @@ -0,0 +1,24 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { PluginInitializer } from 'kibana/server'; + +import { RoutingExamplePlugin } from './plugin'; + +export const plugin: PluginInitializer<{}, {}> = () => new RoutingExamplePlugin(); diff --git a/examples/routing_example/server/plugin.ts b/examples/routing_example/server/plugin.ts new file mode 100644 index 0000000000000..8e92fafc7b30c --- /dev/null +++ b/examples/routing_example/server/plugin.ts @@ -0,0 +1,37 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { Plugin, CoreSetup, CoreStart } from 'kibana/server'; +import { registerRoutes } from './routes'; + +export class RoutingExamplePlugin implements Plugin<{}, {}> { + public setup(core: CoreSetup) { + const router = core.http.createRouter(); + + registerRoutes(router); + + return {}; + } + + public start(core: CoreStart) { + return {}; + } + + public stop() {} +} diff --git a/examples/routing_example/server/routes/index.ts b/examples/routing_example/server/routes/index.ts new file mode 100644 index 0000000000000..ea575cf371bb7 --- /dev/null +++ b/examples/routing_example/server/routes/index.ts @@ -0,0 +1,19 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +export { registerRoutes } from './register_routes'; diff --git a/examples/routing_example/server/routes/message_routes.ts b/examples/routing_example/server/routes/message_routes.ts new file mode 100644 index 0000000000000..2b4ec5e11fb4a --- /dev/null +++ b/examples/routing_example/server/routes/message_routes.ts @@ -0,0 +1,90 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { schema } from '@kbn/config-schema'; +import { POST_MESSAGE_ROUTE_PATH, INTERNAL_GET_MESSAGE_BY_ID_ROUTE } from '../../common'; + +import { IRouter } from '../../../../src/core/server'; + +/** + * + * NOTE: DON'T USE IN MEMORY DATA STRUCTURES TO STORE DATA! + * + * That won't work in a system with multiple Kibanas, which is a setup we recommend for + * load balancing. I'm only doing so here to simplify the routing example. In real life, + * Elasticsearch should be used to persist data that can be shared across multiple Kibana + * instances. + */ + +const messages: { [key: string]: string } = {}; + +/** + * @param router Pushes a message with an id onto an in memory map. + */ +export function registerPostMessageRoute(router: IRouter) { + router.post( + { + path: `${POST_MESSAGE_ROUTE_PATH}/{id}`, + validate: { + params: schema.object({ + // This parameter name matches the one in POST_MESSAGE_ROUTE_PATH: `api/post_message/{id}`. + // Params are often used for ids like this. + id: schema.string(), + }), + body: schema.object({ + message: schema.string({ maxLength: 100 }), + }), + }, + }, + async (context, request, response) => { + if (messages[request.params.id]) { + return response.badRequest({ + body: `Message with id ${request.params.id} already exists`, + }); + } + + // See note above. NEVER DO THIS IN REAL CODE! Data should only be persisted in Elasticsearch. + messages[request.params.id] = request.body.message; + + return response.ok(); + } + ); +} + +/** + * @param router Returns the message with the given id from an in memory array. + */ +export function registerGetMessageByIdRoute(router: IRouter) { + router.get( + { + path: `${INTERNAL_GET_MESSAGE_BY_ID_ROUTE}/{id}`, + validate: { + params: schema.object({ + id: schema.string(), + }), + }, + }, + async (context, request, response) => { + if (!messages[request.params.id]) { + return response.notFound(); + } + return response.ok({ body: { message: messages[request.params.id] } }); + } + ); +} diff --git a/examples/routing_example/server/routes/random_number_between_generator.ts b/examples/routing_example/server/routes/random_number_between_generator.ts new file mode 100644 index 0000000000000..9481578e540fe --- /dev/null +++ b/examples/routing_example/server/routes/random_number_between_generator.ts @@ -0,0 +1,47 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { schema } from '@kbn/config-schema'; +import { RANDOM_NUMBER_BETWEEN_ROUTE_PATH } from '../../common'; + +import { IRouter } from '../../../../src/core/server'; + +/** + * + * @param router Registers a get route that returns a random number between one and another number suplied by the user. + */ +export function registerGetRandomNumberBetweenRoute(router: IRouter) { + router.get( + { + path: RANDOM_NUMBER_BETWEEN_ROUTE_PATH, + validate: { + query: schema.object({ + max: schema.number({ defaultValue: 10 }), + }), + }, + }, + async (context, request, response) => { + return response.ok({ + body: { + randomNumber: Math.random() * request.query.max, + }, + }); + } + ); +} diff --git a/examples/routing_example/server/routes/random_number_generator.ts b/examples/routing_example/server/routes/random_number_generator.ts new file mode 100644 index 0000000000000..2cfce45b957ae --- /dev/null +++ b/examples/routing_example/server/routes/random_number_generator.ts @@ -0,0 +1,43 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { RANDOM_NUMBER_ROUTE_PATH } from '../../common'; + +import { IRouter } from '../../../../src/core/server'; + +/** + * + * @param router Registers a get route that returns a random number between one and ten. It has no input + * parameters, and returns a random number in the body. + */ +export function registerGetRandomNumberRoute(router: IRouter) { + router.get( + { + path: RANDOM_NUMBER_ROUTE_PATH, + validate: {}, + }, + async (context, request, response) => { + return response.ok({ + body: { + randomNumber: Math.random() * 10, + }, + }); + } + ); +} diff --git a/examples/routing_example/server/routes/register_routes.ts b/examples/routing_example/server/routes/register_routes.ts new file mode 100644 index 0000000000000..f556c0ed2c2fd --- /dev/null +++ b/examples/routing_example/server/routes/register_routes.ts @@ -0,0 +1,30 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { IRouter } from 'kibana/server'; +import { registerGetRandomNumberRoute } from './random_number_generator'; +import { registerGetRandomNumberBetweenRoute } from './random_number_between_generator'; +import { registerGetMessageByIdRoute, registerPostMessageRoute } from './message_routes'; + +export function registerRoutes(router: IRouter) { + registerGetRandomNumberRoute(router); + registerGetRandomNumberBetweenRoute(router); + registerGetMessageByIdRoute(router); + registerPostMessageRoute(router); +} diff --git a/examples/routing_example/tsconfig.json b/examples/routing_example/tsconfig.json new file mode 100644 index 0000000000000..9bbd9021b2e0a --- /dev/null +++ b/examples/routing_example/tsconfig.json @@ -0,0 +1,16 @@ +{ + "extends": "../../tsconfig.json", + "compilerOptions": { + "outDir": "./target", + "skipLibCheck": true + }, + "include": [ + "index.ts", + "public/**/*.ts", + "public/**/*.tsx", + "server/**/*.ts", + "common/**/*.ts", + "../../typings/**/*", + ], + "exclude": [] +} diff --git a/examples/search_explorer/README.md b/examples/search_explorer/README.md deleted file mode 100644 index 0e5a48cf22dc1..0000000000000 --- a/examples/search_explorer/README.md +++ /dev/null @@ -1,8 +0,0 @@ -## Search explorer - -This example search explorer app shows how to use different search strategies in order to retrieve data. - -One demo uses the built in elasticsearch search strategy, and runs a search against data in elasticsearch. The -other demo uses the custom demo search strategy, a custom search strategy registerd inside the [demo_search plugin](../demo_search). - -To run this example, use the command `yarn start --run-examples`. \ No newline at end of file diff --git a/examples/search_explorer/kibana.json b/examples/search_explorer/kibana.json deleted file mode 100644 index e22d4e2756d11..0000000000000 --- a/examples/search_explorer/kibana.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "id": "searchExplorer", - "version": "0.0.1", - "kibanaVersion": "kibana", - "server": false, - "ui": true, - "requiredPlugins": ["data", "demoSearch", "developerExamples"], - "optionalPlugins": [] -} diff --git a/examples/search_explorer/public/application.tsx b/examples/search_explorer/public/application.tsx deleted file mode 100644 index a7072936f268d..0000000000000 --- a/examples/search_explorer/public/application.tsx +++ /dev/null @@ -1,133 +0,0 @@ -/* - * Licensed to Elasticsearch B.V. under one or more contributor - * license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright - * ownership. Elasticsearch B.V. licenses this file to you under - * the Apache License, Version 2.0 (the "License"); you may - * not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. - */ - -import React from 'react'; -import ReactDOM from 'react-dom'; -import { BrowserRouter as Router, Route, withRouter, RouteComponentProps } from 'react-router-dom'; - -import { - EuiPage, - EuiPageSideBar, - // @ts-ignore - EuiSideNav, -} from '@elastic/eui'; - -import { AppMountParameters, CoreStart } from '../../../src/core/public'; -import { EsSearchTest } from './es_strategy'; -import { Page } from './page'; -import { DemoStrategy } from './demo_strategy'; -import { AsyncDemoStrategy } from './async_demo_strategy'; -import { DocumentationPage } from './documentation'; -import { SearchApiPage } from './search_api'; -import { AppPluginStartDependencies, SearchBarComponentParams } from './types'; - -const Home = () => ; - -interface PageDef { - title: string; - id: string; - component: React.ReactNode; -} - -type NavProps = RouteComponentProps & { - navigateToApp: CoreStart['application']['navigateToApp']; - pages: PageDef[]; -}; - -const Nav = withRouter(({ history, navigateToApp, pages }: NavProps) => { - const navItems = pages.map((page) => ({ - id: page.id, - name: page.title, - onClick: () => history.push(`/${page.id}`), - 'data-test-subj': page.id, - })); - - return ( - - ); -}); - -const buildPage = (page: PageDef) => {page.component}; - -const SearchApp = ({ basename, data, application }: SearchBarComponentParams) => { - const pages: PageDef[] = [ - { - id: 'home', - title: 'Home', - component: , - }, - { - title: 'Search API', - id: 'searchAPI', - component: , - }, - { - title: 'ES search strategy', - id: 'esSearch', - component: , - }, - { - title: 'Demo search strategy', - id: 'demoSearch', - component: , - }, - { - title: 'Async demo search strategy', - id: 'asyncDemoSearch', - component: , - }, - ]; - - const routes = pages.map((page, i) => ( - buildPage(page)} /> - )); - - return ( - - - -