diff --git a/.ci/es-snapshots/Jenkinsfile_build_es b/.ci/es-snapshots/Jenkinsfile_build_es new file mode 100644 index 0000000000000..ad0ad54275e12 --- /dev/null +++ b/.ci/es-snapshots/Jenkinsfile_build_es @@ -0,0 +1,162 @@ +#!/bin/groovy + +// This job effectively has two SCM configurations: +// one for kibana, used to check out this Jenkinsfile (which means it's the job's main SCM configuration), as well as kick-off the downstream verification job +// one for elasticsearch, used to check out the elasticsearch source before building it + +// There are two parameters that drive which branch is checked out for each of these, but they will typically be the same +// 'branch_specifier' is for kibana / the job itself +// ES_BRANCH is for elasticsearch + +library 'kibana-pipeline-library' +kibanaLibrary.load() + +def ES_BRANCH = params.ES_BRANCH + +if (!ES_BRANCH) { + error "Parameter 'ES_BRANCH' must be specified." +} + +currentBuild.displayName += " - ${ES_BRANCH}" +currentBuild.description = "ES: ${ES_BRANCH}
Kibana: ${params.branch_specifier}" + +def PROMOTE_WITHOUT_VERIFY = !!params.PROMOTE_WITHOUT_VERIFICATION + +timeout(time: 120, unit: 'MINUTES') { + timestamps { + ansiColor('xterm') { + node('linux && immutable') { + catchError { + def VERSION + def SNAPSHOT_ID + def DESTINATION + + def scmVars = checkoutEs(ES_BRANCH) + def GIT_COMMIT = scmVars.GIT_COMMIT + def GIT_COMMIT_SHORT = sh(script: "git rev-parse --short ${GIT_COMMIT}", returnStdout: true).trim() + + buildArchives('to-archive') + + dir('to-archive') { + def now = new Date() + def date = now.format("yyyyMMdd-HHmmss") + + def filesRaw = sh(script: "ls -1", returnStdout: true).trim() + def files = filesRaw + .split("\n") + .collect { filename -> + // Filename examples + // elasticsearch-oss-8.0.0-SNAPSHOT-linux-x86_64.tar.gz + // elasticsearch-8.0.0-SNAPSHOT-linux-x86_64.tar.gz + def parts = filename.replace("elasticsearch-oss", "oss").split("-") + + VERSION = VERSION ?: parts[1] + SNAPSHOT_ID = SNAPSHOT_ID ?: "${date}_${GIT_COMMIT_SHORT}" + DESTINATION = DESTINATION ?: "${VERSION}/archives/${SNAPSHOT_ID}" + + return [ + filename: filename, + checksum: filename + '.sha512', + url: "https://storage.googleapis.com/kibana-ci-es-snapshots-daily/${DESTINATION}/${filename}".toString(), + version: parts[1], + platform: parts[3], + architecture: parts[4].split('\\.')[0], + license: parts[0] == 'oss' ? 'oss' : 'default', + ] + } + + sh 'find * -exec bash -c "shasum -a 512 {} > {}.sha512" \\;' + + def manifest = [ + bucket: "kibana-ci-es-snapshots-daily/${DESTINATION}".toString(), + branch: ES_BRANCH, + sha: GIT_COMMIT, + sha_short: GIT_COMMIT_SHORT, + version: VERSION, + generated: now.format("yyyy-MM-dd'T'HH:mm:ss'Z'", TimeZone.getTimeZone("UTC")), + archives: files, + ] + def manifestJson = toJSON(manifest).toString() + writeFile file: 'manifest.json', text: manifestJson + + upload(DESTINATION, '*.*') + + sh "cp manifest.json manifest-latest.json" + upload(VERSION, 'manifest-latest.json') + } + + if (PROMOTE_WITHOUT_VERIFY) { + esSnapshots.promote(VERSION, SNAPSHOT_ID) + + emailext( + to: 'build-kibana@elastic.co', + subject: "ES snapshot promoted without verification: ${params.ES_BRANCH}", + body: '${SCRIPT,template="groovy-html.template"}', + mimeType: 'text/html', + ) + } else { + build( + propagate: false, + wait: false, + job: 'elasticsearch+snapshots+verify', + parameters: [ + string(name: 'branch_specifier', value: branch_specifier), + string(name: 'SNAPSHOT_VERSION', value: VERSION), + string(name: 'SNAPSHOT_ID', value: SNAPSHOT_ID), + ] + ) + } + } + + kibanaPipeline.sendMail() + } + } + } +} + +def checkoutEs(branch) { + retryWithDelay(8, 15) { + return checkout([ + $class: 'GitSCM', + branches: [[name: branch]], + doGenerateSubmoduleConfigurations: false, + extensions: [], + submoduleCfg: [], + userRemoteConfigs: [[ + credentialsId: 'f6c7695a-671e-4f4f-a331-acdce44ff9ba', + url: 'git@github.com:elastic/elasticsearch', + ]], + ]) + } +} + +def upload(destination, pattern) { + return googleStorageUpload( + credentialsId: 'kibana-ci-gcs-plugin', + bucket: "gs://kibana-ci-es-snapshots-daily/${destination}", + pattern: pattern, + sharedPublicly: false, + showInline: false, + ) +} + +def buildArchives(destination) { + def props = readProperties file: '.ci/java-versions.properties' + withEnv([ + // Select the correct JDK for this branch + "PATH=/var/lib/jenkins/.java/${props.ES_BUILD_JAVA}/bin:${env.PATH}", + + // These Jenkins env vars trigger some automation in the elasticsearch repo that we don't want + "BUILD_NUMBER=", + "JENKINS_URL=", + "BUILD_URL=", + "JOB_NAME=", + "NODE_NAME=", + ]) { + sh """ + ./gradlew -p distribution/archives assemble --parallel + mkdir -p ${destination} + find distribution/archives -type f \\( -name 'elasticsearch-*-*-*-*.tar.gz' -o -name 'elasticsearch-*-*-*-*.zip' \\) -not -path *no-jdk* -exec cp {} ${destination} \\; + """ + } +} diff --git a/.ci/es-snapshots/Jenkinsfile_trigger_build_es b/.ci/es-snapshots/Jenkinsfile_trigger_build_es new file mode 100644 index 0000000000000..186917e967824 --- /dev/null +++ b/.ci/es-snapshots/Jenkinsfile_trigger_build_es @@ -0,0 +1,19 @@ +#!/bin/groovy + +if (!params.branches_yaml) { + error "'branches_yaml' parameter must be specified" +} + +def branches = readYaml text: params.branches_yaml + +branches.each { branch -> + build( + propagate: false, + wait: false, + job: 'elasticsearch+snapshots+build', + parameters: [ + string(name: 'branch_specifier', value: branch), + string(name: 'ES_BRANCH', value: branch), + ] + ) +} diff --git a/.ci/es-snapshots/Jenkinsfile_verify_es b/.ci/es-snapshots/Jenkinsfile_verify_es new file mode 100644 index 0000000000000..3d5ec75fa0e72 --- /dev/null +++ b/.ci/es-snapshots/Jenkinsfile_verify_es @@ -0,0 +1,72 @@ +#!/bin/groovy + +library 'kibana-pipeline-library' +kibanaLibrary.load() + +def SNAPSHOT_VERSION = params.SNAPSHOT_VERSION +def SNAPSHOT_ID = params.SNAPSHOT_ID + +if (!SNAPSHOT_VERSION) { + error "Parameter SNAPSHOT_VERSION must be specified" +} + +if (!SNAPSHOT_ID) { + error "Parameter SNAPSHOT_ID must be specified" +} + +currentBuild.displayName += " - ${SNAPSHOT_VERSION}" +currentBuild.description = "ES: ${SNAPSHOT_VERSION}
Kibana: ${params.branch_specifier}" + +def SNAPSHOT_MANIFEST = "https://storage.googleapis.com/kibana-ci-es-snapshots-daily/${SNAPSHOT_VERSION}/archives/${SNAPSHOT_ID}/manifest.json" + +timeout(time: 120, unit: 'MINUTES') { + timestamps { + ansiColor('xterm') { + catchError { + withEnv(["ES_SNAPSHOT_MANIFEST=${SNAPSHOT_MANIFEST}"]) { + parallel([ + // TODO we just need to run integration tests from intake? + 'kibana-intake-agent': kibanaPipeline.legacyJobRunner('kibana-intake'), + 'x-pack-intake-agent': kibanaPipeline.legacyJobRunner('x-pack-intake'), + 'kibana-oss-agent': kibanaPipeline.withWorkers('kibana-oss-tests', { kibanaPipeline.buildOss() }, [ + 'oss-ciGroup1': kibanaPipeline.getOssCiGroupWorker(1), + 'oss-ciGroup2': kibanaPipeline.getOssCiGroupWorker(2), + 'oss-ciGroup3': kibanaPipeline.getOssCiGroupWorker(3), + 'oss-ciGroup4': kibanaPipeline.getOssCiGroupWorker(4), + 'oss-ciGroup5': kibanaPipeline.getOssCiGroupWorker(5), + 'oss-ciGroup6': kibanaPipeline.getOssCiGroupWorker(6), + 'oss-ciGroup7': kibanaPipeline.getOssCiGroupWorker(7), + 'oss-ciGroup8': kibanaPipeline.getOssCiGroupWorker(8), + 'oss-ciGroup9': kibanaPipeline.getOssCiGroupWorker(9), + 'oss-ciGroup10': kibanaPipeline.getOssCiGroupWorker(10), + 'oss-ciGroup11': kibanaPipeline.getOssCiGroupWorker(11), + 'oss-ciGroup12': kibanaPipeline.getOssCiGroupWorker(12), + ]), + 'kibana-xpack-agent': kibanaPipeline.withWorkers('kibana-xpack-tests', { kibanaPipeline.buildXpack() }, [ + 'xpack-ciGroup1': kibanaPipeline.getXpackCiGroupWorker(1), + 'xpack-ciGroup2': kibanaPipeline.getXpackCiGroupWorker(2), + 'xpack-ciGroup3': kibanaPipeline.getXpackCiGroupWorker(3), + 'xpack-ciGroup4': kibanaPipeline.getXpackCiGroupWorker(4), + 'xpack-ciGroup5': kibanaPipeline.getXpackCiGroupWorker(5), + 'xpack-ciGroup6': kibanaPipeline.getXpackCiGroupWorker(6), + 'xpack-ciGroup7': kibanaPipeline.getXpackCiGroupWorker(7), + 'xpack-ciGroup8': kibanaPipeline.getXpackCiGroupWorker(8), + 'xpack-ciGroup9': kibanaPipeline.getXpackCiGroupWorker(9), + 'xpack-ciGroup10': kibanaPipeline.getXpackCiGroupWorker(10), + ]), + ]) + } + + promoteSnapshot(SNAPSHOT_VERSION, SNAPSHOT_ID) + } + + kibanaPipeline.sendMail() + } + } +} + +def promoteSnapshot(snapshotVersion, snapshotId) { + node('linux && immutable') { + esSnapshots.promote(snapshotVersion, snapshotId) + } +} diff --git a/.eslintrc.js b/.eslintrc.js index 7dd0860aac04e..8a9d4da6178e9 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -177,25 +177,12 @@ module.exports = { 'react-hooks/exhaustive-deps': 'off', }, }, - { - files: ['x-pack/legacy/plugins/monitoring/**/*.{js,ts,tsx}'], - rules: { - 'jsx-a11y/click-events-have-key-events': 'off', - }, - }, { files: ['x-pack/legacy/plugins/snapshot_restore/**/*.{js,ts,tsx}'], rules: { 'react-hooks/exhaustive-deps': 'off', }, }, - { - files: ['x-pack/legacy/plugins/uptime/**/*.{js,ts,tsx}'], - rules: { - 'react-hooks/exhaustive-deps': 'off', - 'react-hooks/rules-of-hooks': 'off', - }, - }, /** * Files that require Apache 2.0 headers, settings @@ -736,15 +723,13 @@ module.exports = { 'no-unreachable': 'error', 'no-unsafe-finally': 'error', 'no-useless-call': 'error', - // This will be turned on after bug fixes are mostly complete - // 'no-useless-catch': 'warn', + 'no-useless-catch': 'error', 'no-useless-concat': 'error', 'no-useless-computed-key': 'error', // This will be turned on after bug fixes are mostly complete // 'no-useless-escape': 'warn', 'no-useless-rename': 'error', - // This will be turned on after bug fixes are mostly complete - // 'no-useless-return': 'warn', + 'no-useless-return': 'error', // This will be turned on after bug fixers are mostly complete // 'no-void': 'warn', 'one-var-declaration-per-line': 'error', @@ -752,14 +737,13 @@ module.exports = { 'prefer-promise-reject-errors': 'error', 'prefer-rest-params': 'error', 'prefer-spread': 'error', - // This style will be turned on after most bugs are fixed - // 'prefer-template': 'warn', + 'prefer-template': 'error', 'react/boolean-prop-naming': 'error', 'react/button-has-type': 'error', + 'react/display-name': 'error', 'react/forbid-dom-props': 'error', 'react/no-access-state-in-setstate': 'error', - // This style will be turned on after most bugs are fixed - // 'react/no-children-prop': 'warn', + 'react/no-children-prop': 'error', 'react/no-danger-with-children': 'error', 'react/no-deprecated': 'error', 'react/no-did-mount-set-state': 'error', @@ -821,21 +805,6 @@ module.exports = { }, }, - /** - * Monitoring overrides - */ - { - files: ['x-pack/legacy/plugins/monitoring/**/*.js'], - rules: { - 'no-unused-vars': ['error', { args: 'all', argsIgnorePattern: '^_' }], - 'no-else-return': 'error', - }, - }, - { - files: ['x-pack/legacy/plugins/monitoring/public/**/*.js'], - env: { browser: true }, - }, - /** * Canvas overrides */ diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 3142e0ff97749..18d60bce4b95e 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -8,6 +8,16 @@ /src/plugins/share/ @elastic/kibana-app /src/legacy/server/url_shortening/ @elastic/kibana-app /src/legacy/server/sample_data/ @elastic/kibana-app +/src/legacy/core_plugins/kibana/public/dashboard/ @elastic/kibana-app +/src/legacy/core_plugins/kibana/public/discover/ @elastic/kibana-app +/src/legacy/core_plugins/kibana/public/visualize/ @elastic/kibana-app +/src/legacy/core_plugins/kibana/public/local_application_service/ @elastic/kibana-app +/src/legacy/core_plugins/kibana/public/home/ @elastic/kibana-app +/src/legacy/core_plugins/kibana/public/dev_tools/ @elastic/kibana-app +/src/plugins/home/ @elastic/kibana-app +/src/plugins/kibana_legacy/ @elastic/kibana-app +/src/plugins/timelion/ @elastic/kibana-app +/src/plugins/dev_tools/ @elastic/kibana-app # App Architecture /src/plugins/data/ @elastic/kibana-app-arch @@ -20,6 +30,7 @@ /src/plugins/visualizations/ @elastic/kibana-app-arch /x-pack/plugins/advanced_ui_actions/ @elastic/kibana-app-arch /src/legacy/core_plugins/data/ @elastic/kibana-app-arch +/src/legacy/core_plugins/elasticsearch/lib/create_proxy.js @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 @@ -57,6 +68,13 @@ /x-pack/test/functional/services/transform_ui/ @elastic/ml-ui /x-pack/test/functional/services/transform.ts @elastic/ml-ui +# Maps +/x-pack/legacy/plugins/maps/ @elastic/kibana-gis +/x-pack/test/api_integration/apis/maps/ @elastic/kibana-gis +/x-pack/test/functional/apps/maps/ @elastic/kibana-gis +/x-pack/test/functional/es_archives/maps/ @elastic/kibana-gis +/x-pack/test/visual_regression/tests/maps/index.js @elastic/kibana-gis + # Operations /src/dev/ @elastic/kibana-operations /src/setup_node_env/ @elastic/kibana-operations @@ -109,6 +127,9 @@ /x-pack/legacy/plugins/alerting @elastic/kibana-alerting-services /x-pack/legacy/plugins/actions @elastic/kibana-alerting-services /x-pack/legacy/plugins/task_manager @elastic/kibana-alerting-services +/x-pack/test/alerting_api_integration @elastic/kibana-alerting-services +/x-pack/test/plugin_api_integration/plugins/task_manager @elastic/kibana-alerting-services +/x-pack/test/plugin_api_integration/test_suites/task_manager @elastic/kibana-alerting-services # Design **/*.scss @elastic/kibana-design diff --git a/.github/workflows/pr-project-assigner.yml b/.github/workflows/pr-project-assigner.yml index aea8a9cad6b1f..59123731dce66 100644 --- a/.github/workflows/pr-project-assigner.yml +++ b/.github/workflows/pr-project-assigner.yml @@ -11,5 +11,11 @@ jobs: uses: elastic/github-actions/project-assigner@v1.0.0 id: project_assigner with: - issue-mappings: '[{"label": "Team:AppAch", "projectName": "kibana-app-arch", "columnId": 6173897}]' - ghToken: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file + issue-mappings: | + [ + { "label": "Team:AppArch", "projectName": "kibana-app-arch", "columnId": 6173897 }, + { "label": "Feature:Lens", "projectName": "Lens", "columnId": 6219362 }, + { "label": "Team:Platform", "projectName": "kibana-platform", "columnId": 5514360 }, + {"label": "Team:Canvas", "projectName": "canvas", "columnId": 6187580} + ] + ghToken: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/project-assigner.yml b/.github/workflows/project-assigner.yml index c7f17993249eb..aec3bf88f0ee2 100644 --- a/.github/workflows/project-assigner.yml +++ b/.github/workflows/project-assigner.yml @@ -11,7 +11,7 @@ jobs: uses: elastic/github-actions/project-assigner@v1.0.0 id: project_assigner with: - issue-mappings: '[{"label": "Team:AppArch", "projectName": "kibana-app-arch", "columnId": 6173895}]' + issue-mappings: '[{"label": "Team:AppArch", "projectName": "kibana-app-arch", "columnId": 6173895}, {"label": "Feature:Lens", "projectName": "Lens", "columnId": 6219363}, {"label": "Team:Canvas", "projectName": "canvas", "columnId": 6187593}]' ghToken: ${{ secrets.GITHUB_TOKEN }} - + diff --git a/.gitignore b/.gitignore index e7391a5c292d0..02b20da297fc6 100644 --- a/.gitignore +++ b/.gitignore @@ -29,7 +29,6 @@ disabledPlugins webpackstats.json /config/* !/config/kibana.yml -!/config/apm.js coverage selenium .babel_register_cache.json diff --git a/.i18nrc.json b/.i18nrc.json index 9a37ce1310a32..4bc0f773ee8b5 100644 --- a/.i18nrc.json +++ b/.i18nrc.json @@ -9,7 +9,9 @@ "src/plugins/data" ], "embeddableApi": "src/plugins/embeddable", + "embeddableExamples": "examples/embeddable_examples", "share": "src/plugins/share", + "home": "src/plugins/home", "esUi": "src/plugins/es_ui_shared", "devTools": "src/plugins/dev_tools", "expressions": "src/plugins/expressions", @@ -20,7 +22,7 @@ "kbn": "src/legacy/core_plugins/kibana", "kbnDocViews": "src/legacy/core_plugins/kbn_doc_views", "kbnVislibVisTypes": "src/legacy/core_plugins/kbn_vislib_vis_types", - "management": "src/legacy/core_plugins/management", + "management": ["src/legacy/core_plugins/management", "src/plugins/management"], "kibana_react": "src/legacy/core_plugins/kibana_react", "kibana-react": "src/plugins/kibana_react", "kibana_utils": "src/plugins/kibana_utils", diff --git a/.node-version b/.node-version index 95abd2ac49910..06c9b9d306348 100644 --- a/.node-version +++ b/.node-version @@ -1 +1 @@ -10.15.2 +10.18.0 diff --git a/.nvmrc b/.nvmrc index 95abd2ac49910..06c9b9d306348 100644 --- a/.nvmrc +++ b/.nvmrc @@ -1 +1 @@ -10.15.2 +10.18.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 06e08c85dafec..6ae3db559b61b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -190,6 +190,19 @@ These snapshots are built on a nightly basis which expire after a couple weeks. 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` diff --git a/NOTICE.txt b/NOTICE.txt index 230e511746022..955c3127fa955 100644 --- a/NOTICE.txt +++ b/NOTICE.txt @@ -1,5 +1,5 @@ Kibana source code with Kibana X-Pack source code -Copyright 2012-2019 Elasticsearch B.V. +Copyright 2012-2020 Elasticsearch B.V. --- Pretty handling of logarithmic axes. diff --git a/config/apm.js b/config/apm.js deleted file mode 100644 index 0cfcd759f163b..0000000000000 --- a/config/apm.js +++ /dev/null @@ -1,87 +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. - */ - -/** - * DO NOT EDIT THIS FILE! - * - * This file contains the configuration for the Elastic APM instrumentaion of - * Kibana itself and is only intented to be used during development of Kibana. - * - * Instrumentation is turned off by default. Once activated it will send APM - * data to an Elasticsearch cluster accessible by Elastic employees. - * - * To modify the configuration, either use environment variables, or create a - * file named `config/apm.dev.js`, which exports a config object as described - * in the docs. - * - * For an overview over the available configuration files, see: - * https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html - * - * For general information about Elastic APM, see: - * https://www.elastic.co/guide/en/apm/get-started/current/index.html - */ - -const { readFileSync } = require('fs'); -const { join } = require('path'); -const { execSync } = require('child_process'); -const merge = require('lodash.merge'); - -module.exports = merge( - { - active: false, - serverUrl: 'https://f1542b814f674090afd914960583265f.apm.us-central1.gcp.cloud.es.io:443', - // The secretToken below is intended to be hardcoded in this file even though - // it makes it public. This is not a security/privacy issue. Normally we'd - // instead disable the need for a secretToken in the APM Server config where - // the data is transmitted to, but due to how it's being hosted, it's easier, - // for now, to simply leave it in. - secretToken: 'R0Gjg46pE9K9wGestd', - globalLabels: {}, - centralConfig: false, - logUncaughtExceptions: true, - }, - devConfig() -); - -const rev = gitRev(); -if (rev !== null) module.exports.globalLabels.git_rev = rev; - -try { - const filename = join(__dirname, '..', 'data', 'uuid'); - module.exports.globalLabels.kibana_uuid = readFileSync(filename, 'utf-8'); -} catch (e) {} // eslint-disable-line no-empty - -function gitRev() { - try { - return execSync('git rev-parse --short HEAD', { - encoding: 'utf-8', - stdio: ['ignore', 'pipe', 'ignore'], - }).trim(); - } catch (e) { - return null; - } -} - -function devConfig() { - try { - return require('./apm.dev'); // eslint-disable-line import/no-unresolved - } catch (e) { - return {}; - } -} diff --git a/docs/api/spaces-management/post.asciidoc b/docs/api/spaces-management/post.asciidoc index d8c194d8dc2b5..4d4627e98899e 100644 --- a/docs/api/spaces-management/post.asciidoc +++ b/docs/api/spaces-management/post.asciidoc @@ -16,28 +16,28 @@ experimental["The underlying Spaces concepts are stable, but the APIs for managi [[spaces-api-post-request-body]] ==== Request body -`id`:: +`id`:: (Required, string) The space ID that is part of the Kibana URL when inside the space. You are unable to change the ID with the update operation. -`name`:: +`name`:: (Required, string) The display name for the space. -`description`:: +`description`:: (Optional, string) The description for the space. -`disabledFeatures`:: +`disabledFeatures`:: (Optional, string array) The list of disabled features for the space. To get a list of available feature IDs, use the <>. -`initials`:: +`initials`:: (Optional, string) Specifies the initials shown in the space avatar. By default, the initials are automatically generated from the space name. Initials must be 1 or 2 characters. -`color`:: +`color`:: (Optional, string) Specifies the hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name. -`imageUrl`:: +`imageUrl`:: (Optional, string) Specifies the data-url encoded image to display in the space avatar. If specified, `initials` will not be displayed, and the `color` will be visible as the background color for transparent images. For best results, your image should be 64x64. Images will not be optimized by this API call, so care should be taken when using custom images. - + [[spaces-api-post-response-codes]] ==== Response codes diff --git a/docs/api/using-api.asciidoc b/docs/api/using-api.asciidoc index 82071af463636..37c5315025dc4 100644 --- a/docs/api/using-api.asciidoc +++ b/docs/api/using-api.asciidoc @@ -1,7 +1,7 @@ [[using-api]] == Using the APIs -Interact with the {kib} APIs through the `curl` command and HTTP and HTTPs protocols. +Interact with the {kib} APIs through the `curl` command and HTTP and HTTPs protocols. It is recommended that you use HTTPs on port 5601 because it is more secure. @@ -34,13 +34,37 @@ For example, the following `curl` command exports a dashboard: curl -X POST -u $USER:$PASSWORD "localhost:5601/api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c" -- -The following {kib} APIs are available: +[float] +[[api-request-headers]] +=== Request headers + +For all APIs, you must use a request header. The {kib} APIs support the `kbn-xsrf` and `Content-Type` headers. + +`kbn-xsrf: true`:: + By default, you must use `kbn-xsrf` for all API calls, except in the following scenarios: + +* The API endpoint uses the `GET` or `HEAD` methods + +* The path is whitelisted using the <> setting + +* 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. + +Request header example: + +[source,sh] +-- +curl -X POST \ + http://localhost:5601/api/spaces/space \ + -H 'Content-Type: application/json' \ + -H 'kbn-xsrf: true' \ + -d '{ + "id": "sales", + "name": "Sales", + "description": "This is your Sales Space!", + "disabledFeatures": [] +} +' +-- diff --git a/docs/apm/advanced-queries.asciidoc b/docs/apm/advanced-queries.asciidoc index 1f064c1cad3fd..942882f8c4dfb 100644 --- a/docs/apm/advanced-queries.asciidoc +++ b/docs/apm/advanced-queries.asciidoc @@ -1,9 +1,7 @@ [[advanced-queries]] === Advanced queries -When querying, you're simply searching and selecting data from fields in Elasticsearch documents. -It may be helpful to view some of your documents in {kibana-ref}/discover.html[Discover] to better understand how APM data is stored in Elasticsearch. - +When querying in the APM app, you're simply searching and selecting data from fields in Elasticsearch documents. Queries entered into the query bar are also added as parameters to the URL, so it's easy to share a specific query or view with others. @@ -13,11 +11,48 @@ In the screenshot below, you can begin to see some of the transaction fields ava image::apm/images/apm-query-bar.png[Example of the Kibana Query bar in APM app in Kibana] [float] -==== Example queries +==== Example APM app queries * Exclude response times slower than 2000 ms: `transaction.duration.us > 2000000` * Filter by response status code: `context.response.status_code >= 400` * Filter by single user ID: `context.user.id : 12` -* View _all_ transactions for an endpoint, instead of just a sample - `processor.event: "transaction" AND transaction.name: ""` TIP: Read the {kibana-ref}/kuery-query.html[Kibana Query Language Enhancements] documentation to learn more about the capabilities of the {kib} query language. + +[float] +[[discover-advanced-queries]] +=== Querying in the Discover app + +It may also be helpful to view your APM data in the {kibana-ref}/discover.html[Discover app]. +Querying documents in Discover works the same way as querying in the APM app, +and all of the example queries listed above can also be used in the Discover app. + +[float] +==== Example Discover app query + +One example where you may want to make use of the Discover app, +is for viewing _all_ transactions for an endpoint, instead of just a sample. + +TIP: Starting in v7.6, you can view 10 samples per bucket in the APM app, instead of just one. + +Use the APM app to find a transaction name and time bucket that you're interested in learning more about. +Then, switch to the Discover app and make a search: + +["source","sh"] +----- +processor.event: "transaction" AND transaction.name: "" and transaction.duration.us > 13000 and transaction.duration.us < 14000` +----- + +In this example, we're interested in viewing all of the `APIRestController#customers` transactions +that took between 13 and 14 milliseconds. Here's what Discover returns: + +[role="screenshot"] +image::apm/images/advanced-discover.png[View all transactions in bucket] + +You can now explore the data until you find a specific transaction that you're interested in. +Copy that transaction's `transaction.id`, and paste it into the APM app to view the data in the context of the APM app: + +[role="screenshot"] +image::apm/images/specific-transaction-search.png[View specific transaction in apm app] +[role="screenshot"] +image::apm/images/specific-transaction.png[View specific transaction in apm app] diff --git a/docs/apm/images/advanced-discover.png b/docs/apm/images/advanced-discover.png new file mode 100644 index 0000000000000..56ba58b2c1d41 Binary files /dev/null and b/docs/apm/images/advanced-discover.png differ diff --git a/docs/apm/images/specific-transaction-search.png b/docs/apm/images/specific-transaction-search.png new file mode 100644 index 0000000000000..4ed548f015713 Binary files /dev/null and b/docs/apm/images/specific-transaction-search.png differ diff --git a/docs/apm/images/specific-transaction.png b/docs/apm/images/specific-transaction.png new file mode 100644 index 0000000000000..9911dbd879f41 Binary files /dev/null and b/docs/apm/images/specific-transaction.png differ diff --git a/docs/apm/settings.asciidoc b/docs/apm/settings.asciidoc new file mode 100644 index 0000000000000..2fc8748f13b09 --- /dev/null +++ b/docs/apm/settings.asciidoc @@ -0,0 +1,10 @@ +// Do not link directly to this page. +// Link to the anchor in `/docs/settings/apm-settings.asciidoc` instead. +[[apm-settings-in-kibana]] +=== APM settings in Kibana + +You do not need to configure any settings to use APM. It is enabled by default. +If you'd like to change any of the default values, +copy and paste the relevant settings below into your `kibana.yml` configuration file. + +include::./../settings/apm-settings.asciidoc[tag=general-apm-settings] diff --git a/docs/apm/using-the-apm-ui.asciidoc b/docs/apm/using-the-apm-ui.asciidoc index 818e4429d25af..95ec41cf8a403 100644 --- a/docs/apm/using-the-apm-ui.asciidoc +++ b/docs/apm/using-the-apm-ui.asciidoc @@ -8,15 +8,18 @@ Not to worry, we've created this guide to help you get the most out of Elastic A APM is available via the navigation sidebar in {Kib}. -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> include::filters.asciidoc[] @@ -36,4 +39,6 @@ include::agent-configuration.asciidoc[] include::advanced-queries.asciidoc[] +include::settings.asciidoc[] + include::troubleshooting.asciidoc[] diff --git a/docs/canvas/canvas-elements.asciidoc b/docs/canvas/canvas-elements.asciidoc index c5c6f116ee34e..dc605a47de383 100644 --- a/docs/canvas/canvas-elements.asciidoc +++ b/docs/canvas/canvas-elements.asciidoc @@ -20,24 +20,24 @@ When you add elements to your workpad, you can: [[add-canvas-element]] === Add elements to your workpad -Choose the elements to display on your workpad, then familiarize yourself with the element using the preconfigured demo data. +Choose the elements to display on your workpad, then familiarize yourself with the element using the preconfigured demo data. By default, every element you add to a workpad uses demo data until you change the data source. The demo data includes a small sample data set that you can use to experiment with your element. . Click *Add element*. -. In the *Elements* window, select the element you want to use. +. In the *Elements* window, select the element you want to use. + [role="screenshot"] image::images/canvas-element-select.gif[Canvas elements] -. Play around with the default settings and see what the element can do. +. Play around with the default settings and see what the element can do. -TIP: Want to use a different element? You can delete the element by selecting it, clicking the *Element options* icon in the top right corner, then selecting *Delete*. +TIP: Want to use a different element? You can delete the element by selecting it, clicking the *Element options* icon in the top right, then selecting *Delete*. [float] [[connect-element-data]] === Connect the element to your data -When you are ready to move on from the demo data, connect the element to your own data. +When you have finished using the demo data, connect the element to a data source. . Make sure that the element is selected, then select *Data*. @@ -45,55 +45,51 @@ When you are ready to move on from the demo data, connect the element to your ow [float] [[elasticsearch-sql-data-source]] -==== Connect to Elasticsearch SQL +==== Connect to {es} SQL -Access your data in Elasticsearch using the Elasticsearch SQL syntax. +Access your data in {es} using SQL syntax. For information about SQL syntax, refer to {ref}/sql-spec.html[SQL language]. -Unfamiliar with writing Elasticsearch SQL queries? For more information, refer to {ref}/sql-spec.html[SQL language]. +. Click *{es} SQL*. -. Click *Elasticsearch SQL*. +. In the *{es} SQL query* box, enter your query, then *Preview* it. -. In the *Elasticearch SQL query* box, enter your query, then *Preview* it. - -. If everything looks correct, *Save* it. +. If everything looks correct, *Save* it. [float] [[elasticsearch-raw-doc-data-source]] -==== Connect to Elasticsearch raw data +==== Connect to {es} raw data -Use the Lucene query syntax to use your raw data in Elasticsearch. +Access your raw data in {es} without the use of aggregations. Use {es} raw data when you have low volume datasets, or to plot exact, non-aggregated values. -For for more information about the Lucene query string sytax, refer to <>. +To use targeted queries, you can enter a query using the <>. -. Click *Elasticsearch raw documents*. +. Click *{es} raw documents*. -. In the *Index* field, enter the index pattern that you want to display. +. In the *Index* field, enter the index pattern that you want to display. . From the *Fields* dropdown, select the associated fields you want to display. . To sort the data, select an option from the *Sort Field* and *Sort Order* dropdowns. -. For more targeted queries, enter a *Query* using the Lucene query string syntax. +. For more targeted queries, enter a *Query* using the Lucene query string syntax. -. *Preview* the query. +. *Preview* the query. -. If your query looks correct, *Save* it. +. If your query looks correct, *Save* it. [float] [[timelion-data-source]] ==== Connect to Timelion -Use <> queries to use your time series data. +Access your time series data using <> queries. To use Timelion queries, you can enter a query using the <>. . Click *Timelion*. -. Enter a *Query* using the Lucene query string syntax. -+ -For for more information about the Lucene query string syntax, refer to <>. +. Enter a *Query* using the Lucene query string syntax. . Enter the *Interval*, then *Preview* the query. -. If your query looks correct, *Save* it. +. If your query looks correct, *Save* it. [float] [[configure-display-options]] @@ -109,7 +105,7 @@ When you connect your element to a data source, the element often appears as a w . Click *Display* -. Change the display options for the element. +. Change the display options for the element. [float] [[element-display-container]] @@ -122,7 +118,7 @@ Further define the appearance of the element container and border. . Expand *Container style*. . Change the *Appearance* and *Border* options. - + [float] [[apply-element-styles]] ==== Apply a set of styles @@ -155,7 +151,7 @@ Increase or decrease how often your data refreshes on your workpad. [role="screenshot"] image::images/canvas-refresh-interval.png[Element data refresh interval] -TIP: To manually refresh the data, click the *Refresh data* icon. +TIP: To manually refresh the data, click the *Refresh data* icon. [float] [[organize-element]] @@ -223,7 +219,7 @@ Change the order of how the elements are displayed on your workpad. . Select an element. -. In the top right corder, click the *Element options* icon. +. In the top right corder, click the *Element options* icon. . Select *Order*, then select the order that you want the element to appear. @@ -262,7 +258,7 @@ When you have run out of room on your workpad page, add more pages. . Click *Page 1*, then click *+*. -. On the *Page* editor panel on the right, select the page transition from the *Transition* dropdown. +. On the *Page* editor panel on the right, select the page transition from the *Transition* dropdown. + [role="screenshot"] image::images/canvas-add-pages.gif[Add pages] diff --git a/docs/canvas/canvas-expression-lifecycle.asciidoc b/docs/canvas/canvas-expression-lifecycle.asciidoc new file mode 100644 index 0000000000000..895c1382c4d36 --- /dev/null +++ b/docs/canvas/canvas-expression-lifecycle.asciidoc @@ -0,0 +1,261 @@ +[role="xpack"] +[[canvas-expression-lifecycle]] +== Canvas expression lifecycle + +Elements in Canvas are all created using an *expression language* that defines how to retrieve, manipulate, and ultimately visualize data. The goal is to allow you to do most of what you need without understanding the *expression language*, but learning how it works unlocks a lot of Canvas's power. + + +[[canvas-expressions-always-start-with-a-function]] +=== Expressions always start with a function + +Expressions simply execute <> in a specific order, which produce some output value. That output can then be inserted into another function, and another after that, until it produces the output you need. + +To use demo dataset available in Canvas to produce a table, run the following expression: + +[source,text] +---- +filters +| demodata +| table +| render +---- + +This expression starts out with the <> function, which provides the value of any time filters or dropdown filters in the workpad. This is then inserted into <>, a function that returns exactly what you expect, demo data. Because the <> function receives the filter information from the <> function before it, it applies those filters to reduce the set of data it returns. We call the output from the previous function _context_. + +The filtered <> becomes the _context_ of the next function, <>, which creates a table visualization from this data set. The <> function isn’t strictly required, but by being explicit, you have the option of providing arguments to control things like the font used in the table. The output of the <> function becomes the _context_ of the <> function. Like the <>, the <> function isn’t required either, but it allows access to other arguments, such as styling the border of the element or injecting custom CSS. + + +[[canvas-function-arguments]] +=== Function arguments + +Let’s look at another expression, which uses the same <> function, but instead produces a pie chart. + +image::images/canvas-functions-can-take-arguments-pie-chart.png[Pie Chart, height=400] +[source,text] +---- +filters +| demodata +| pointseries color="state" size="max(price)" +| pie +| render +---- + +To produce a filtered set of random data, the expression uses the <> and <> functions. This time, however, the output becomes the context for the <> function, which is a way to aggregate your data, similar to how Elasticsearch works, but more generalized. In this case, the data is split up using the `color` and `size` dimensions, using arguments on the <> function. Each unique value in the state column will have an associated size value, which in this case, will be the maximum value of the price column. + +If the expression stopped there, it would produce a `pointseries` data type as the output of this expression. But instead of looking at the raw values, the result is inserted into the <> function, which will produce an output that will render a pie visualization. And just like before, this is inserted into the <> function, which is useful for its arguments. + +The end result is a simple pie chart that uses the default color palette, but the <> function can take additional arguments that control how it gets rendered. For example, you can provide a `hole` argument to turn your pie chart into a donut chart by changing the expression to: + + +image::images/canvas-functions-can-take-arguments-donut-chart.png[Donut Chart, height=400] +[source,text] +---- +filters +| demodata +| pointseries color="state" size="max(price)" +| pie hole=50 +| render +---- + + +[[canvas-aliases-and-unnamed-arguments]] +=== Aliases and unnamed arguments + +Argument definitions have one canonical name, which is always provided in the underlying code. When argument definitions are used in an expression, they often include aliases that make them easier or faster to type. + +For example, the <> function has 2 arguments: + +* `expression` - Produces a calculated value. +* `name` - The name of column. + +The `expression` argument includes some aliases, namely `exp`, `fn`, and `function`. That means that you can use any of those four options to provide that argument’s value. + +So `mapColumn name=newColumn fn={string example}` is equal to `mapColumn name=newColumn expression={string example}`. + +There’s also a special type of alias which allows you to leave off the argument’s name entirely. The alias for this is an underscore, which indicates that the argument is an _unnamed_ argument and can be provided without explicitly naming it in the expression. The `name` argument here uses the _unnamed_ alias, which means that you can further simplify our example to `mapColumn newColumn fn={string example}`. + +NOTE: There can only be one _unnamed_ argument for each function. + + +[[canvas-change-your-expression-change-your-output]] +=== Change your expression, change your output +You can substitute one function for another to change the output. For example, you could change the visualization by swapping out the <> function for another renderer, a function that returns a `render` data type. + +Let’s change that last pie chart into a bubble chart by replacing the <> function with the <> function. This is possible because both functions can accept a `pointseries` data type as their _context_. Switching the functions will work, but it won’t produce a useful visualization on its own since you don’t have the x-axis and y-axis defined. You will also need to modify the <> function to change its output. In this case, you can change the `size` argument to `y`, so the maximum price values are plotted on the y-axis, and add an `x` argument using the `@timestamp` field in the data to plot those values over time. This leaves you with the following expression and produces a bubble chart showing the max price of each state over time: + +image::images/canvas-change-your-expression-chart.png[Bubble Chart, height=400] +[source,text] +---- +filters +| demodata +| pointseries color="state" y="max(price)" x="@timestamp" +| plot +| render +---- + +Similar to the <> function, the <> function takes arguments that control the design elements of the visualization. As one example, passing a `legend` argument with a value of `false` to the function will hide the legend on the chart. + +image::images/canvas-change-your-expression-chart-no-legend.png[Bubble Chart Without Legend, height=400] +[source,text,subs=+quotes] +---- +filters +| demodata +| pointseries color="state" y="max(price)" x="@timestamp" +| plot *legend=false* +| render +---- + + +[[canvas-fetch-and-manipulate-data]] +=== Fetch and manipulate data +So far, you have only seen expressions as a way to produce visualizations, but that’s not really what’s happening. Expressions only produce data, which is then used to create something, which in the case of Canvas, means rendering an element. An element can be a visualization, driven by data, but it can also be something much simpler, like a static image. Either way, an expression is used to produce an output that is used to render the desired result. For example, here’s an expression that shows an image: + +[source,text] +---- +image dataurl=https://placekitten.com/160/160 mode="cover" +---- + +But as mentioned, this doesn’t actually _render that image_, but instead it _produces some output that can be used to render that image_. That’s an important distinction, and you can see the actual output by adding in the render function and telling it to produce debug output. For example: + +[source,text] +---- +image dataurl=https://placekitten.com/160/160 mode="cover" +| render as=debug +---- + +The follow appears as JSON output: + +[source,JSON] +---- +{ + "type": "image", + "mode": "cover", + "dataurl": "https://placekitten.com/160/160" +} +---- + +NOTE: You may need to expand the element’s size to see the whole output. + +Canvas uses this output’s data type to map to a specific renderer and passes the entire output into it. It’s up to the image render function to produce an image on the workpad’s page. In this case, the expression produces some JSON output, but expressions can also produce other, simpler data, like a string or a number. Typically, useful results use JSON. + +Canvas uses the output to render an element, but other applications can use expressions to do pretty much anything. As stated previously, expressions simply execute functions, and the functions are all written in Javascript. That means if you can do something in Javascript, you can do it with an expression. + +This can include: + +* Sending emails +* Sending notifications +* Reading from a file +* Writing to a file +* Controlling devices with WebUSB or Web Bluetooth +* Consuming external APIs + +If your Javascript works in the environment where the code will run, such as in Node.js or in a browser, you can do it with an expression. + +[[canvas-expressions-compose-functions-with-subexpressions]] +=== Compose functions with sub-expressions + +You may have noticed another syntax in examples from other sections, namely expressions inside of curly brackets. These are called sub-expressions, and they can be used to provide a calculated value to another expression, instead of just a static one. + +A simple example of this is when you upload your own images to a Canvas workpad. That upload becomes an asset, and that asset can be retrieved using the `asset` function. Usually you’ll just do this from the UI, adding an image element to the page and uploading your image from the control in the sidebar, or picking an existing asset from there as well. In both cases, the system will consume that asset via the `asset` function, and you’ll end up with an expression similar to this: + +[source,text] +---- +image dataurl={asset 3cb3ec3a-84d7-48fa-8709-274ad5cc9e0b} +---- + +Sub-expressions are executed before the function that uses them is executed. In this case, `asset` will be run first, it will produce a value, the base64-encoded value of the image and that value will be used as the value for the `dataurl` argument in the <> function. After the asset function executes, you will get the following output: + +[source,text] +---- +image dataurl="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0" +---- + +Since all of the sub-expressions are now resolved into actual values, the <> function can be executed to produce its JSON output, just as it’s explained previously. In the case of images, the ability to nest sub-expressions is particularly useful to show one of several images conditionally. For example, you could swap between two images based on some calculated value by mixing in the <> function, like in this example expression: + +[source,text] +---- +demodata +| image dataurl={ + if condition={getCell price | gte 100} + then={asset 3cb3ec3a-84d7-48fa-8709-274ad5cc9e0b} + else={asset cbc11a1f-8f25-4163-94b4-2c3a060192e7} +} +---- + +NOTE: The examples in this section can’t be copy and pasted directly, since the values used throughout will not exist in your workpad. + +Here, the expression to use for the value of the `condition` argument, `getCell price | gte 100`, runs first since it is nested deeper. + +The expression does the following: + +* Retrieves the value from the *price* column in the first row of the `demodata` data table +* Inputs the value to the `gte` function +* Compares the value to `100` +* Returns `true` if the value is 100 or greater, and `false` if the value is 100 or less + +That boolean value becomes the value for the `condition` argument. The output from the `then` expression is used as the output when `condition` is `true`. The output from the `else` expression is used when `condition` is false. In both cases, a base64-encoded image will be returned, and one of the two images will be displayed. + +You might be wondering how the <> function in the sub-expression accessed the data from the <> function, even though <> was not being directly inserted into <>. The answer is simple, but important to understand. When nested sub-expressions are executed, they automatically receive the same _context_, or output of the previous function that its parent function receives. In this specific expression, demodata’s data table is automatically provided to the nested expression’s `getCell` function, which allows that expression to pull out a value and compare it to another value. + +The passing of the _context_ is automatic, and it happens no matter how deeply you nest your sub-expressions. To demonstrate this, let’s modify the expression slightly to compare the value of the price against multiple conditions using the <> function. + +[source,text] +---- +demodata +| image dataurl={ + if condition={getCell price | all {gte 100} {neq 105}} + then={asset 3cb3ec3a-84d7-48fa-8709-274ad5cc9e0b} + else={asset cbc11a1f-8f25-4163-94b4-2c3a060192e7} +} +---- + +This time, `getCell price` is run, and the result is passed into the next function as the context. Then, each sub-expression of the <> function is run, with the context given to their parent, which in this case is the result of `getCell price`. If `all` of these sub-expressions evaluate to `true`, then the `if` condition argument will be true. + +Sub-expressions can seem a little foreign, especially if you aren’t a developer, but they’re worth getting familiar with, since they provide a ton of power and flexibility. Since you can nest any expression you want, you can also use this behavior to mix data from multiple indices, or even data from multiple sources. As an example, you could query an API for a value to use as part of the query provided to <>. + +This whole section is really just scratching the surface, but hopefully after reading it, you at least understand how to read expressions and make sense of what they are doing. With a little practice, you’ll get the hang of mixing _context_ and sub-expressions together to turn any input into your desired output. + +[[canvas-handling-context-and-argument-types]] +=== Handling context and argument types +If you look through the <>, you may notice that all of them define what a function accepts and what it returns. Additionally, every argument includes a type property that specifies the kind of data that can be used. These two types of values are actually the same, and can be used as a guide for how to deal with piping to other functions and using subexpressions for argument values. + +To explain how this works, consider the following expression from the previous section: + +[source,text] +---- +image dataurl={asset 3cb3ec3a-84d7-48fa-8709-274ad5cc9e0b} +---- + +If you <> for the `image` function, you’ll see that it accepts the `null` data type and returns an `image` data type. Accepting `null` effectively means that it does not use context at all, so if you insert anything to `image`, the value that was produced previously will be ignored. When the function executes, it will produce an `image` output, which is simply an object of type `image` that contains the information required to render an image. + +NOTE: The function does not render an image itself. + +As explained in the "<>" section, the output of an expression is just data. So the `image` type here is just a specific shape of data, not an actual image. + +Next, let’s take a look at the `asset` function. Like `image`, it accepts `null`, but it returns something different, a `string` in this case. Because `asset` will produce a string, its output can be used as the input for any function or argument that accepts a string. + +<> for the `dataurl` argument, its type is `string`, meaning it will accept any kind of string. There are some rules about the value of the string that the function itself enforces, but as far as the interpreter is concerned, that expression is valid because the argument accepts a string and the output of `asset` is a string. + +The interpreter also attempts to cast some input types into others, which allows you to use a string input even when the function or argument calls for a number. Keep in mind that it’s not able to convert any string value, but if the string is a number, it can easily be cast into a `number` type. Take the following expression for example: + +[source,text] +---- +string "0.4" +| revealImage image={asset asset-06511b39-ec44-408a-a5f3-abe2da44a426} +---- + +If you <> for the `revealImage` function, you’ll see that it accepts a `number` but the `string` function returns a `string` type. In this case, because the string value is a number, it can be converted into a `number` type and used without you having to do anything else. + +Most `primitive` types can be converted automatically, as you might expect. You just saw that a `string` can be cast into a `number`, but you can also pretty easily cast things into `boolean` too, and you can cast anything to `null`. + +There are other useful type casting options available. For example, something of type `datatable` can be cast to a type `pointseries` simply by only preserving specific columns from the data (namely x, y, size, color, and text). This allows you to treat your source data, which is generally of type `datatable`, like a `pointseries` type simply by convention. + +You can fetch data from Elasticsearch using `essql`, which allows you to aggregate the data, provide a custom name for the value, and insert that data directly to another function that only accepts `pointseries` even though `essql` will output a `datatable` type. This makes the following example expression valid: + +[source,text] +---- +essql "SELECT user AS x, sum(cost) AS y FROM index GROUP BY user" +| plot +---- + +In the docs you can see that `essql` returns a `datatable` type, but `plot` expects a `pointseries` context. This works because the `datatable` output will have the columns `x` and `y` as a result of using `AS` in the sql statement to name them. Because the data follows the convention of the `pointseries` data type, casting it into `pointseries` is possible, and it can be passed directly to `plot` as a result. diff --git a/docs/developer/plugin/development-uiexports.asciidoc b/docs/developer/plugin/development-uiexports.asciidoc index 6368446f7fb43..18d326cbfb9c0 100644 --- a/docs/developer/plugin/development-uiexports.asciidoc +++ b/docs/developer/plugin/development-uiexports.asciidoc @@ -9,8 +9,8 @@ An aggregate list of available UiExport types: | hacks | Any module that should be included in every application | visTypes | Modules that register providers with the `ui/registry/vis_types` registry. | inspectorViews | Modules that register custom inspector views via the `viewRegistry` in `ui/inspector`. -| chromeNavControls | Modules that register providers with the `ui/registry/chrome_nav_controls` registry. -| navbarExtensions | Modules that register providers with the `ui/registry/navbar_extensions` registry. -| docViews | Modules that register providers with the `ui/registry/doc_views` registry. +| chromeNavControls | Modules that register providers with the `ui/registry/chrome_header_nav_controls` registry. +| navbarExtensions | Modules that register providers with the setup contract of the `navigation` plugin. +| docViews | Modules that register providers with the setup contract method `addDocView` of the `discover` plugin. | app | Adds an application to the system. This uiExport type is defined as an object of metadata rather than just a module id. |======================================================================= diff --git a/docs/development/core/public/kibana-plugin-public.app.approute.md b/docs/development/core/public/kibana-plugin-public.app.approute.md new file mode 100644 index 0000000000000..7f35f4346b6b3 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.app.approute.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [App](./kibana-plugin-public.app.md) > [appRoute](./kibana-plugin-public.app.approute.md) + +## App.appRoute property + +Override the application's routing path from `/app/${id}`. Must be unique across registered applications. Should not include the base path from HTTP. + +Signature: + +```typescript +appRoute?: string; +``` diff --git a/docs/development/core/public/kibana-plugin-public.app.md b/docs/development/core/public/kibana-plugin-public.app.md index edab4f88497f6..acf07cbf62e91 100644 --- a/docs/development/core/public/kibana-plugin-public.app.md +++ b/docs/development/core/public/kibana-plugin-public.app.md @@ -16,6 +16,7 @@ export interface App extends AppBase | Property | Type | Description | | --- | --- | --- | +| [appRoute](./kibana-plugin-public.app.approute.md) | string | Override the application's routing path from /app/${id}. Must be unique across registered applications. Should not include the base path from HTTP. | | [chromeless](./kibana-plugin-public.app.chromeless.md) | boolean | Hide the UI chrome when the application is mounted. Defaults to false. Takes precedence over chrome service visibility settings. | | [mount](./kibana-plugin-public.app.mount.md) | AppMount | AppMountDeprecated | A mount function called when the user navigates to this app's route. May have signature of [AppMount](./kibana-plugin-public.appmount.md) or [AppMountDeprecated](./kibana-plugin-public.appmountdeprecated.md). | diff --git a/docs/development/core/public/kibana-plugin-public.appmountparameters.appbasepath.md b/docs/development/core/public/kibana-plugin-public.appmountparameters.appbasepath.md index a1544373ee698..7cd709d615729 100644 --- a/docs/development/core/public/kibana-plugin-public.appmountparameters.appbasepath.md +++ b/docs/development/core/public/kibana-plugin-public.appmountparameters.appbasepath.md @@ -4,7 +4,7 @@ ## AppMountParameters.appBasePath property -The base path for configuring the application's router. +The route path for configuring navigation to the application. This string should not include the base path from HTTP. Signature: @@ -22,6 +22,7 @@ export class MyPlugin implements Plugin { setup({ application }) { application.register({ id: 'my-app', + appRoute: '/my-app', async mount(params) { const { renderApp } = await import('./application'); return renderApp(params); diff --git a/docs/development/core/public/kibana-plugin-public.appmountparameters.md b/docs/development/core/public/kibana-plugin-public.appmountparameters.md index 8733f9cd4915d..aa5ca93ed8ff0 100644 --- a/docs/development/core/public/kibana-plugin-public.appmountparameters.md +++ b/docs/development/core/public/kibana-plugin-public.appmountparameters.md @@ -15,6 +15,6 @@ export interface AppMountParameters | Property | Type | Description | | --- | --- | --- | -| [appBasePath](./kibana-plugin-public.appmountparameters.appbasepath.md) | string | The base path for configuring the application's router. | +| [appBasePath](./kibana-plugin-public.appmountparameters.appbasepath.md) | string | The route path for configuring navigation to the application. This string should not include the base path from HTTP. | | [element](./kibana-plugin-public.appmountparameters.element.md) | HTMLElement | The container element to render the application into. | diff --git a/docs/development/core/public/kibana-plugin-public.chromedoctitle.md b/docs/development/core/public/kibana-plugin-public.chromedoctitle.md index 3c6cfab486288..feb3b3ab966ef 100644 --- a/docs/development/core/public/kibana-plugin-public.chromedoctitle.md +++ b/docs/development/core/public/kibana-plugin-public.chromedoctitle.md @@ -12,13 +12,6 @@ APIs for accessing and updating the document title. export interface ChromeDocTitle ``` -## Methods - -| Method | Description | -| --- | --- | -| [change(newTitle)](./kibana-plugin-public.chromedoctitle.change.md) | Changes the current document title. | -| [reset()](./kibana-plugin-public.chromedoctitle.reset.md) | Resets the document title to it's initial value. (meaning the one present in the title meta at application load.) | - ## Example 1 How to change the title of the document @@ -37,3 +30,10 @@ chrome.docTitle.reset() ``` +## Methods + +| Method | Description | +| --- | --- | +| [change(newTitle)](./kibana-plugin-public.chromedoctitle.change.md) | Changes the current document title. | +| [reset()](./kibana-plugin-public.chromedoctitle.reset.md) | Resets the document title to it's initial value. (meaning the one present in the title meta at application load.) | + diff --git a/docs/development/core/public/kibana-plugin-public.chromenavcontrols.md b/docs/development/core/public/kibana-plugin-public.chromenavcontrols.md index a34db9bb33d9d..30b9a6869d1ff 100644 --- a/docs/development/core/public/kibana-plugin-public.chromenavcontrols.md +++ b/docs/development/core/public/kibana-plugin-public.chromenavcontrols.md @@ -12,13 +12,6 @@ export interface ChromeNavControls ``` -## Methods - -| Method | Description | -| --- | --- | -| [registerLeft(navControl)](./kibana-plugin-public.chromenavcontrols.registerleft.md) | Register a nav control to be presented on the left side of the chrome header. | -| [registerRight(navControl)](./kibana-plugin-public.chromenavcontrols.registerright.md) | Register a nav control to be presented on the right side of the chrome header. | - ## Example Register a left-side nav control rendered with React. @@ -33,3 +26,10 @@ chrome.navControls.registerLeft({ ``` +## Methods + +| Method | Description | +| --- | --- | +| [registerLeft(navControl)](./kibana-plugin-public.chromenavcontrols.registerleft.md) | Register a nav control to be presented on the left side of the chrome header. | +| [registerRight(navControl)](./kibana-plugin-public.chromenavcontrols.registerright.md) | Register a nav control to be presented on the right side of the chrome header. | + diff --git a/docs/development/core/public/kibana-plugin-public.chromestart.md b/docs/development/core/public/kibana-plugin-public.chromestart.md index d5d99f3d5be65..4e44e5bf05074 100644 --- a/docs/development/core/public/kibana-plugin-public.chromestart.md +++ b/docs/development/core/public/kibana-plugin-public.chromestart.md @@ -12,6 +12,31 @@ ChromeStart allows plugins to customize the global chrome header UI and enrich t export interface ChromeStart ``` +## Remarks + +While ChromeStart exposes many APIs, they should be used sparingly and the developer should understand how they affect other plugins and applications. + +## Example 1 + +How to add a recently accessed item to the sidebar: + +```ts +core.chrome.recentlyAccessed.add('/app/map/1234', 'Map 1234', '1234'); + +``` + +## Example 2 + +How to set the help dropdown extension: + +```tsx +core.chrome.setHelpExtension(elem => { + ReactDOM.render(, elem); + return () => ReactDOM.unmountComponentAtNode(elem); +}); + +``` + ## Properties | Property | Type | Description | @@ -43,28 +68,3 @@ export interface ChromeStart | [setIsCollapsed(isCollapsed)](./kibana-plugin-public.chromestart.setiscollapsed.md) | Set the collapsed state of the chrome navigation. | | [setIsVisible(isVisible)](./kibana-plugin-public.chromestart.setisvisible.md) | Set the temporary visibility for the chrome. This does nothing if the chrome is hidden by default and should be used to hide the chrome for things like full-screen modes with an exit button. | -## Remarks - -While ChromeStart exposes many APIs, they should be used sparingly and the developer should understand how they affect other plugins and applications. - -## Example 1 - -How to add a recently accessed item to the sidebar: - -```ts -core.chrome.recentlyAccessed.add('/app/map/1234', 'Map 1234', '1234'); - -``` - -## Example 2 - -How to set the help dropdown extension: - -```tsx -core.chrome.setHelpExtension(elem => { - ReactDOM.render(, elem); - return () => ReactDOM.unmountComponentAtNode(elem); -}); - -``` - diff --git a/docs/development/core/public/kibana-plugin-public.contextsetup.md b/docs/development/core/public/kibana-plugin-public.contextsetup.md index a006fa7205ca6..d4399b6ba70c4 100644 --- a/docs/development/core/public/kibana-plugin-public.contextsetup.md +++ b/docs/development/core/public/kibana-plugin-public.contextsetup.md @@ -12,12 +12,6 @@ An object that handles registration of context providers and configuring handler export interface ContextSetup ``` -## Methods - -| Method | Description | -| --- | --- | -| [createContextContainer()](./kibana-plugin-public.contextsetup.createcontextcontainer.md) | Creates a new [IContextContainer](./kibana-plugin-public.icontextcontainer.md) for a service owner. | - ## Remarks A [IContextContainer](./kibana-plugin-public.icontextcontainer.md) can be used by any Core service or plugin (known as the "service owner") which wishes to expose APIs in a handler function. The container object will manage registering context providers and configuring a handler with all of the contexts that should be exposed to the handler's plugin. This is dependent on the dependencies that the handler's plugin declares. @@ -136,3 +130,9 @@ class VizRenderingPlugin { ``` +## Methods + +| Method | Description | +| --- | --- | +| [createContextContainer()](./kibana-plugin-public.contextsetup.createcontextcontainer.md) | Creates a new [IContextContainer](./kibana-plugin-public.icontextcontainer.md) for a service owner. | + diff --git a/docs/development/core/public/kibana-plugin-public.httpservicebase.addloadingcount.md b/docs/development/core/public/kibana-plugin-public.httpservicebase.addloadingcount.md deleted file mode 100644 index e984fea48625d..0000000000000 --- a/docs/development/core/public/kibana-plugin-public.httpservicebase.addloadingcount.md +++ /dev/null @@ -1,24 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) > [addLoadingCount](./kibana-plugin-public.httpservicebase.addloadingcount.md) - -## HttpServiceBase.addLoadingCount() method - -Adds a new source of loading counts. Used to show the global loading indicator when sum of all observed counts are more than 0. - -Signature: - -```typescript -addLoadingCount(countSource$: Observable): void; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| countSource$ | Observable<number> | | - -Returns: - -`void` - diff --git a/docs/development/core/public/kibana-plugin-public.httpservicebase.anonymouspaths.md b/docs/development/core/public/kibana-plugin-public.httpservicebase.anonymouspaths.md deleted file mode 100644 index e94757c5eb031..0000000000000 --- a/docs/development/core/public/kibana-plugin-public.httpservicebase.anonymouspaths.md +++ /dev/null @@ -1,13 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) > [anonymousPaths](./kibana-plugin-public.httpservicebase.anonymouspaths.md) - -## HttpServiceBase.anonymousPaths property - -APIs for denoting certain paths for not requiring authentication - -Signature: - -```typescript -anonymousPaths: IAnonymousPaths; -``` diff --git a/docs/development/core/public/kibana-plugin-public.httpservicebase.basepath.md b/docs/development/core/public/kibana-plugin-public.httpservicebase.basepath.md deleted file mode 100644 index 6c5f690a5c607..0000000000000 --- a/docs/development/core/public/kibana-plugin-public.httpservicebase.basepath.md +++ /dev/null @@ -1,13 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) > [basePath](./kibana-plugin-public.httpservicebase.basepath.md) - -## HttpServiceBase.basePath property - -APIs for manipulating the basePath on URL segments. - -Signature: - -```typescript -basePath: IBasePath; -``` diff --git a/docs/development/core/public/kibana-plugin-public.httpservicebase.delete.md b/docs/development/core/public/kibana-plugin-public.httpservicebase.delete.md deleted file mode 100644 index 73022ef4f2946..0000000000000 --- a/docs/development/core/public/kibana-plugin-public.httpservicebase.delete.md +++ /dev/null @@ -1,13 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) > [delete](./kibana-plugin-public.httpservicebase.delete.md) - -## HttpServiceBase.delete property - -Makes an HTTP request with the DELETE method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. - -Signature: - -```typescript -delete: HttpHandler; -``` diff --git a/docs/development/core/public/kibana-plugin-public.httpservicebase.fetch.md b/docs/development/core/public/kibana-plugin-public.httpservicebase.fetch.md deleted file mode 100644 index 3a1ae4892a3dd..0000000000000 --- a/docs/development/core/public/kibana-plugin-public.httpservicebase.fetch.md +++ /dev/null @@ -1,13 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) > [fetch](./kibana-plugin-public.httpservicebase.fetch.md) - -## HttpServiceBase.fetch property - -Makes an HTTP request. Defaults to a GET request unless overriden. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. - -Signature: - -```typescript -fetch: HttpHandler; -``` diff --git a/docs/development/core/public/kibana-plugin-public.httpservicebase.get.md b/docs/development/core/public/kibana-plugin-public.httpservicebase.get.md deleted file mode 100644 index a61b3dd140e50..0000000000000 --- a/docs/development/core/public/kibana-plugin-public.httpservicebase.get.md +++ /dev/null @@ -1,13 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) > [get](./kibana-plugin-public.httpservicebase.get.md) - -## HttpServiceBase.get property - -Makes an HTTP request with the GET method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. - -Signature: - -```typescript -get: HttpHandler; -``` diff --git a/docs/development/core/public/kibana-plugin-public.httpservicebase.getloadingcount_.md b/docs/development/core/public/kibana-plugin-public.httpservicebase.getloadingcount_.md deleted file mode 100644 index 0b2129330cd01..0000000000000 --- a/docs/development/core/public/kibana-plugin-public.httpservicebase.getloadingcount_.md +++ /dev/null @@ -1,17 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) > [getLoadingCount$](./kibana-plugin-public.httpservicebase.getloadingcount_.md) - -## HttpServiceBase.getLoadingCount$() method - -Get the sum of all loading count sources as a single Observable. - -Signature: - -```typescript -getLoadingCount$(): Observable; -``` -Returns: - -`Observable` - diff --git a/docs/development/core/public/kibana-plugin-public.httpservicebase.head.md b/docs/development/core/public/kibana-plugin-public.httpservicebase.head.md deleted file mode 100644 index 4624d95f03bf3..0000000000000 --- a/docs/development/core/public/kibana-plugin-public.httpservicebase.head.md +++ /dev/null @@ -1,13 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) > [head](./kibana-plugin-public.httpservicebase.head.md) - -## HttpServiceBase.head property - -Makes an HTTP request with the HEAD method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. - -Signature: - -```typescript -head: HttpHandler; -``` diff --git a/docs/development/core/public/kibana-plugin-public.httpservicebase.intercept.md b/docs/development/core/public/kibana-plugin-public.httpservicebase.intercept.md deleted file mode 100644 index 8cf5bf813df09..0000000000000 --- a/docs/development/core/public/kibana-plugin-public.httpservicebase.intercept.md +++ /dev/null @@ -1,26 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) > [intercept](./kibana-plugin-public.httpservicebase.intercept.md) - -## HttpServiceBase.intercept() method - -Adds a new [HttpInterceptor](./kibana-plugin-public.httpinterceptor.md) to the global HTTP client. - -Signature: - -```typescript -intercept(interceptor: HttpInterceptor): () => void; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| interceptor | HttpInterceptor | | - -Returns: - -`() => void` - -a function for removing the attached interceptor. - diff --git a/docs/development/core/public/kibana-plugin-public.httpservicebase.md b/docs/development/core/public/kibana-plugin-public.httpservicebase.md deleted file mode 100644 index 9ea77c95b343e..0000000000000 --- a/docs/development/core/public/kibana-plugin-public.httpservicebase.md +++ /dev/null @@ -1,37 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) - -## HttpServiceBase interface - - -Signature: - -```typescript -export interface HttpServiceBase -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [anonymousPaths](./kibana-plugin-public.httpservicebase.anonymouspaths.md) | IAnonymousPaths | APIs for denoting certain paths for not requiring authentication | -| [basePath](./kibana-plugin-public.httpservicebase.basepath.md) | IBasePath | APIs for manipulating the basePath on URL segments. | -| [delete](./kibana-plugin-public.httpservicebase.delete.md) | HttpHandler | Makes an HTTP request with the DELETE method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. | -| [fetch](./kibana-plugin-public.httpservicebase.fetch.md) | HttpHandler | Makes an HTTP request. Defaults to a GET request unless overriden. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. | -| [get](./kibana-plugin-public.httpservicebase.get.md) | HttpHandler | Makes an HTTP request with the GET method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. | -| [head](./kibana-plugin-public.httpservicebase.head.md) | HttpHandler | Makes an HTTP request with the HEAD method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. | -| [options](./kibana-plugin-public.httpservicebase.options.md) | HttpHandler | Makes an HTTP request with the OPTIONS method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. | -| [patch](./kibana-plugin-public.httpservicebase.patch.md) | HttpHandler | Makes an HTTP request with the PATCH method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. | -| [post](./kibana-plugin-public.httpservicebase.post.md) | HttpHandler | Makes an HTTP request with the POST method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. | -| [put](./kibana-plugin-public.httpservicebase.put.md) | HttpHandler | Makes an HTTP request with the PUT method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. | - -## Methods - -| Method | Description | -| --- | --- | -| [addLoadingCount(countSource$)](./kibana-plugin-public.httpservicebase.addloadingcount.md) | Adds a new source of loading counts. Used to show the global loading indicator when sum of all observed counts are more than 0. | -| [getLoadingCount$()](./kibana-plugin-public.httpservicebase.getloadingcount_.md) | Get the sum of all loading count sources as a single Observable. | -| [intercept(interceptor)](./kibana-plugin-public.httpservicebase.intercept.md) | Adds a new [HttpInterceptor](./kibana-plugin-public.httpinterceptor.md) to the global HTTP client. | -| [removeAllInterceptors()](./kibana-plugin-public.httpservicebase.removeallinterceptors.md) | Removes all configured interceptors. | - diff --git a/docs/development/core/public/kibana-plugin-public.httpservicebase.options.md b/docs/development/core/public/kibana-plugin-public.httpservicebase.options.md deleted file mode 100644 index 0820beb2752f2..0000000000000 --- a/docs/development/core/public/kibana-plugin-public.httpservicebase.options.md +++ /dev/null @@ -1,13 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) > [options](./kibana-plugin-public.httpservicebase.options.md) - -## HttpServiceBase.options property - -Makes an HTTP request with the OPTIONS method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. - -Signature: - -```typescript -options: HttpHandler; -``` diff --git a/docs/development/core/public/kibana-plugin-public.httpservicebase.patch.md b/docs/development/core/public/kibana-plugin-public.httpservicebase.patch.md deleted file mode 100644 index 00e1ffc0e16bf..0000000000000 --- a/docs/development/core/public/kibana-plugin-public.httpservicebase.patch.md +++ /dev/null @@ -1,13 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) > [patch](./kibana-plugin-public.httpservicebase.patch.md) - -## HttpServiceBase.patch property - -Makes an HTTP request with the PATCH method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. - -Signature: - -```typescript -patch: HttpHandler; -``` diff --git a/docs/development/core/public/kibana-plugin-public.httpservicebase.post.md b/docs/development/core/public/kibana-plugin-public.httpservicebase.post.md deleted file mode 100644 index 3771a7c910895..0000000000000 --- a/docs/development/core/public/kibana-plugin-public.httpservicebase.post.md +++ /dev/null @@ -1,13 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) > [post](./kibana-plugin-public.httpservicebase.post.md) - -## HttpServiceBase.post property - -Makes an HTTP request with the POST method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. - -Signature: - -```typescript -post: HttpHandler; -``` diff --git a/docs/development/core/public/kibana-plugin-public.httpservicebase.put.md b/docs/development/core/public/kibana-plugin-public.httpservicebase.put.md deleted file mode 100644 index 6e43aafa916bc..0000000000000 --- a/docs/development/core/public/kibana-plugin-public.httpservicebase.put.md +++ /dev/null @@ -1,13 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) > [put](./kibana-plugin-public.httpservicebase.put.md) - -## HttpServiceBase.put property - -Makes an HTTP request with the PUT method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. - -Signature: - -```typescript -put: HttpHandler; -``` diff --git a/docs/development/core/public/kibana-plugin-public.httpservicebase.removeallinterceptors.md b/docs/development/core/public/kibana-plugin-public.httpservicebase.removeallinterceptors.md deleted file mode 100644 index 0432ec29a22b6..0000000000000 --- a/docs/development/core/public/kibana-plugin-public.httpservicebase.removeallinterceptors.md +++ /dev/null @@ -1,17 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) > [removeAllInterceptors](./kibana-plugin-public.httpservicebase.removeallinterceptors.md) - -## HttpServiceBase.removeAllInterceptors() method - -Removes all configured interceptors. - -Signature: - -```typescript -removeAllInterceptors(): void; -``` -Returns: - -`void` - diff --git a/docs/development/core/public/kibana-plugin-public.httpsetup.addloadingcountsource.md b/docs/development/core/public/kibana-plugin-public.httpsetup.addloadingcountsource.md new file mode 100644 index 0000000000000..a2fe66bb55c77 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.httpsetup.addloadingcountsource.md @@ -0,0 +1,24 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpSetup](./kibana-plugin-public.httpsetup.md) > [addLoadingCountSource](./kibana-plugin-public.httpsetup.addloadingcountsource.md) + +## HttpSetup.addLoadingCountSource() method + +Adds a new source of loading counts. Used to show the global loading indicator when sum of all observed counts are more than 0. + +Signature: + +```typescript +addLoadingCountSource(countSource$: Observable): void; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| countSource$ | Observable<number> | | + +Returns: + +`void` + diff --git a/docs/development/core/public/kibana-plugin-public.httpsetup.anonymouspaths.md b/docs/development/core/public/kibana-plugin-public.httpsetup.anonymouspaths.md new file mode 100644 index 0000000000000..a9268ca1d8ed6 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.httpsetup.anonymouspaths.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpSetup](./kibana-plugin-public.httpsetup.md) > [anonymousPaths](./kibana-plugin-public.httpsetup.anonymouspaths.md) + +## HttpSetup.anonymousPaths property + +APIs for denoting certain paths for not requiring authentication + +Signature: + +```typescript +anonymousPaths: IAnonymousPaths; +``` diff --git a/docs/development/core/public/kibana-plugin-public.httpsetup.basepath.md b/docs/development/core/public/kibana-plugin-public.httpsetup.basepath.md new file mode 100644 index 0000000000000..6b0726dc8ef2b --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.httpsetup.basepath.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpSetup](./kibana-plugin-public.httpsetup.md) > [basePath](./kibana-plugin-public.httpsetup.basepath.md) + +## HttpSetup.basePath property + +APIs for manipulating the basePath on URL segments. + +Signature: + +```typescript +basePath: IBasePath; +``` diff --git a/docs/development/core/public/kibana-plugin-public.httpsetup.delete.md b/docs/development/core/public/kibana-plugin-public.httpsetup.delete.md new file mode 100644 index 0000000000000..565f0eb336d4f --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.httpsetup.delete.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpSetup](./kibana-plugin-public.httpsetup.md) > [delete](./kibana-plugin-public.httpsetup.delete.md) + +## HttpSetup.delete property + +Makes an HTTP request with the DELETE method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. + +Signature: + +```typescript +delete: HttpHandler; +``` diff --git a/docs/development/core/public/kibana-plugin-public.httpsetup.fetch.md b/docs/development/core/public/kibana-plugin-public.httpsetup.fetch.md new file mode 100644 index 0000000000000..2d6447363fa9b --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.httpsetup.fetch.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpSetup](./kibana-plugin-public.httpsetup.md) > [fetch](./kibana-plugin-public.httpsetup.fetch.md) + +## HttpSetup.fetch property + +Makes an HTTP request. Defaults to a GET request unless overriden. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. + +Signature: + +```typescript +fetch: HttpHandler; +``` diff --git a/docs/development/core/public/kibana-plugin-public.httpsetup.get.md b/docs/development/core/public/kibana-plugin-public.httpsetup.get.md new file mode 100644 index 0000000000000..0c484e33e9b58 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.httpsetup.get.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpSetup](./kibana-plugin-public.httpsetup.md) > [get](./kibana-plugin-public.httpsetup.get.md) + +## HttpSetup.get property + +Makes an HTTP request with the GET method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. + +Signature: + +```typescript +get: HttpHandler; +``` diff --git a/docs/development/core/public/kibana-plugin-public.httpsetup.getloadingcount_.md b/docs/development/core/public/kibana-plugin-public.httpsetup.getloadingcount_.md new file mode 100644 index 0000000000000..628b62b2ffc27 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.httpsetup.getloadingcount_.md @@ -0,0 +1,17 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpSetup](./kibana-plugin-public.httpsetup.md) > [getLoadingCount$](./kibana-plugin-public.httpsetup.getloadingcount_.md) + +## HttpSetup.getLoadingCount$() method + +Get the sum of all loading count sources as a single Observable. + +Signature: + +```typescript +getLoadingCount$(): Observable; +``` +Returns: + +`Observable` + diff --git a/docs/development/core/public/kibana-plugin-public.httpsetup.head.md b/docs/development/core/public/kibana-plugin-public.httpsetup.head.md new file mode 100644 index 0000000000000..e4d49c843e572 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.httpsetup.head.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpSetup](./kibana-plugin-public.httpsetup.md) > [head](./kibana-plugin-public.httpsetup.head.md) + +## HttpSetup.head property + +Makes an HTTP request with the HEAD method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. + +Signature: + +```typescript +head: HttpHandler; +``` diff --git a/docs/development/core/public/kibana-plugin-public.httpsetup.intercept.md b/docs/development/core/public/kibana-plugin-public.httpsetup.intercept.md new file mode 100644 index 0000000000000..1bda0c6166e65 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.httpsetup.intercept.md @@ -0,0 +1,26 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpSetup](./kibana-plugin-public.httpsetup.md) > [intercept](./kibana-plugin-public.httpsetup.intercept.md) + +## HttpSetup.intercept() method + +Adds a new [HttpInterceptor](./kibana-plugin-public.httpinterceptor.md) to the global HTTP client. + +Signature: + +```typescript +intercept(interceptor: HttpInterceptor): () => void; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| interceptor | HttpInterceptor | | + +Returns: + +`() => void` + +a function for removing the attached interceptor. + diff --git a/docs/development/core/public/kibana-plugin-public.httpsetup.md b/docs/development/core/public/kibana-plugin-public.httpsetup.md index 7ef037ea7abd1..8a14d26c57ca3 100644 --- a/docs/development/core/public/kibana-plugin-public.httpsetup.md +++ b/docs/development/core/public/kibana-plugin-public.httpsetup.md @@ -2,12 +2,35 @@ [Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpSetup](./kibana-plugin-public.httpsetup.md) -## HttpSetup type +## HttpSetup interface -See [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) Signature: ```typescript -export declare type HttpSetup = HttpServiceBase; +export interface HttpSetup ``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [anonymousPaths](./kibana-plugin-public.httpsetup.anonymouspaths.md) | IAnonymousPaths | APIs for denoting certain paths for not requiring authentication | +| [basePath](./kibana-plugin-public.httpsetup.basepath.md) | IBasePath | APIs for manipulating the basePath on URL segments. | +| [delete](./kibana-plugin-public.httpsetup.delete.md) | HttpHandler | Makes an HTTP request with the DELETE method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. | +| [fetch](./kibana-plugin-public.httpsetup.fetch.md) | HttpHandler | Makes an HTTP request. Defaults to a GET request unless overriden. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. | +| [get](./kibana-plugin-public.httpsetup.get.md) | HttpHandler | Makes an HTTP request with the GET method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. | +| [head](./kibana-plugin-public.httpsetup.head.md) | HttpHandler | Makes an HTTP request with the HEAD method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. | +| [options](./kibana-plugin-public.httpsetup.options.md) | HttpHandler | Makes an HTTP request with the OPTIONS method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. | +| [patch](./kibana-plugin-public.httpsetup.patch.md) | HttpHandler | Makes an HTTP request with the PATCH method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. | +| [post](./kibana-plugin-public.httpsetup.post.md) | HttpHandler | Makes an HTTP request with the POST method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. | +| [put](./kibana-plugin-public.httpsetup.put.md) | HttpHandler | Makes an HTTP request with the PUT method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. | + +## Methods + +| Method | Description | +| --- | --- | +| [addLoadingCountSource(countSource$)](./kibana-plugin-public.httpsetup.addloadingcountsource.md) | Adds a new source of loading counts. Used to show the global loading indicator when sum of all observed counts are more than 0. | +| [getLoadingCount$()](./kibana-plugin-public.httpsetup.getloadingcount_.md) | Get the sum of all loading count sources as a single Observable. | +| [intercept(interceptor)](./kibana-plugin-public.httpsetup.intercept.md) | Adds a new [HttpInterceptor](./kibana-plugin-public.httpinterceptor.md) to the global HTTP client. | + diff --git a/docs/development/core/public/kibana-plugin-public.httpsetup.options.md b/docs/development/core/public/kibana-plugin-public.httpsetup.options.md new file mode 100644 index 0000000000000..4ea5be8826bff --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.httpsetup.options.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpSetup](./kibana-plugin-public.httpsetup.md) > [options](./kibana-plugin-public.httpsetup.options.md) + +## HttpSetup.options property + +Makes an HTTP request with the OPTIONS method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. + +Signature: + +```typescript +options: HttpHandler; +``` diff --git a/docs/development/core/public/kibana-plugin-public.httpsetup.patch.md b/docs/development/core/public/kibana-plugin-public.httpsetup.patch.md new file mode 100644 index 0000000000000..ef1d50005b012 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.httpsetup.patch.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpSetup](./kibana-plugin-public.httpsetup.md) > [patch](./kibana-plugin-public.httpsetup.patch.md) + +## HttpSetup.patch property + +Makes an HTTP request with the PATCH method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. + +Signature: + +```typescript +patch: HttpHandler; +``` diff --git a/docs/development/core/public/kibana-plugin-public.httpsetup.post.md b/docs/development/core/public/kibana-plugin-public.httpsetup.post.md new file mode 100644 index 0000000000000..1c19c35ac3038 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.httpsetup.post.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpSetup](./kibana-plugin-public.httpsetup.md) > [post](./kibana-plugin-public.httpsetup.post.md) + +## HttpSetup.post property + +Makes an HTTP request with the POST method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. + +Signature: + +```typescript +post: HttpHandler; +``` diff --git a/docs/development/core/public/kibana-plugin-public.httpsetup.put.md b/docs/development/core/public/kibana-plugin-public.httpsetup.put.md new file mode 100644 index 0000000000000..e5243d8c80dae --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.httpsetup.put.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [HttpSetup](./kibana-plugin-public.httpsetup.md) > [put](./kibana-plugin-public.httpsetup.put.md) + +## HttpSetup.put property + +Makes an HTTP request with the PUT method. See [HttpHandler](./kibana-plugin-public.httphandler.md) for options. + +Signature: + +```typescript +put: HttpHandler; +``` diff --git a/docs/development/core/public/kibana-plugin-public.httpstart.md b/docs/development/core/public/kibana-plugin-public.httpstart.md index bb9247c63897a..9abf319acf00d 100644 --- a/docs/development/core/public/kibana-plugin-public.httpstart.md +++ b/docs/development/core/public/kibana-plugin-public.httpstart.md @@ -4,10 +4,10 @@ ## HttpStart type -See [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) +See [HttpSetup](./kibana-plugin-public.httpsetup.md) Signature: ```typescript -export declare type HttpStart = HttpServiceBase; +export declare type HttpStart = HttpSetup; ``` diff --git a/docs/development/core/public/kibana-plugin-public.icontextcontainer.md b/docs/development/core/public/kibana-plugin-public.icontextcontainer.md index f16c07b3d7906..7a21df6b93bb5 100644 --- a/docs/development/core/public/kibana-plugin-public.icontextcontainer.md +++ b/docs/development/core/public/kibana-plugin-public.icontextcontainer.md @@ -12,13 +12,6 @@ An object that handles registration of context providers and configuring handler export interface IContextContainer> ``` -## Methods - -| Method | Description | -| --- | --- | -| [createHandler(pluginOpaqueId, handler)](./kibana-plugin-public.icontextcontainer.createhandler.md) | Create a new handler function pre-wired to context for the plugin. | -| [registerContext(pluginOpaqueId, contextName, provider)](./kibana-plugin-public.icontextcontainer.registercontext.md) | Register a new context provider. | - ## Remarks A [IContextContainer](./kibana-plugin-public.icontextcontainer.md) can be used by any Core service or plugin (known as the "service owner") which wishes to expose APIs in a handler function. The container object will manage registering context providers and configuring a handler with all of the contexts that should be exposed to the handler's plugin. This is dependent on the dependencies that the handler's plugin declares. @@ -78,3 +71,10 @@ class MyPlugin { ``` +## Methods + +| Method | Description | +| --- | --- | +| [createHandler(pluginOpaqueId, handler)](./kibana-plugin-public.icontextcontainer.createhandler.md) | Create a new handler function pre-wired to context for the plugin. | +| [registerContext(pluginOpaqueId, contextName, provider)](./kibana-plugin-public.icontextcontainer.registercontext.md) | Register a new context provider. | + diff --git a/docs/development/core/public/kibana-plugin-public.legacycoresetup.md b/docs/development/core/public/kibana-plugin-public.legacycoresetup.md index a753300437c1c..803c96cd0b22c 100644 --- a/docs/development/core/public/kibana-plugin-public.legacycoresetup.md +++ b/docs/development/core/public/kibana-plugin-public.legacycoresetup.md @@ -16,13 +16,13 @@ Setup interface exposed to the legacy platform via the `ui/new_platform` module. export interface LegacyCoreSetup extends CoreSetup ``` +## Remarks + +Some methods are not supported in the legacy platform and while present to make this type compatibile with [CoreSetup](./kibana-plugin-public.coresetup.md), unsupported methods will throw exceptions when called. + ## Properties | Property | Type | Description | | --- | --- | --- | | [injectedMetadata](./kibana-plugin-public.legacycoresetup.injectedmetadata.md) | InjectedMetadataSetup | | -## Remarks - -Some methods are not supported in the legacy platform and while present to make this type compatibile with [CoreSetup](./kibana-plugin-public.coresetup.md), unsupported methods will throw exceptions when called. - diff --git a/docs/development/core/public/kibana-plugin-public.legacycorestart.md b/docs/development/core/public/kibana-plugin-public.legacycorestart.md index 775c3fb1ffe3d..438a3d6110776 100644 --- a/docs/development/core/public/kibana-plugin-public.legacycorestart.md +++ b/docs/development/core/public/kibana-plugin-public.legacycorestart.md @@ -16,13 +16,13 @@ Start interface exposed to the legacy platform via the `ui/new_platform` module. export interface LegacyCoreStart extends CoreStart ``` +## Remarks + +Some methods are not supported in the legacy platform and while present to make this type compatibile with [CoreStart](./kibana-plugin-public.corestart.md), unsupported methods will throw exceptions when called. + ## Properties | Property | Type | Description | | --- | --- | --- | | [injectedMetadata](./kibana-plugin-public.legacycorestart.injectedmetadata.md) | InjectedMetadataStart | | -## Remarks - -Some methods are not supported in the legacy platform and while present to make this type compatibile with [CoreStart](./kibana-plugin-public.corestart.md), unsupported methods will throw exceptions when called. - diff --git a/docs/development/core/public/kibana-plugin-public.md b/docs/development/core/public/kibana-plugin-public.md index 2c43f36ede09e..e2c2866b57b6b 100644 --- a/docs/development/core/public/kibana-plugin-public.md +++ b/docs/development/core/public/kibana-plugin-public.md @@ -56,7 +56,7 @@ The plugin integrates with the core system via lifecycle events: `setup` | [HttpHeadersInit](./kibana-plugin-public.httpheadersinit.md) | | | [HttpInterceptor](./kibana-plugin-public.httpinterceptor.md) | An object that may define global interceptor functions for different parts of the request and response lifecycle. See [IHttpInterceptController](./kibana-plugin-public.ihttpinterceptcontroller.md). | | [HttpRequestInit](./kibana-plugin-public.httprequestinit.md) | Fetch API options available to [HttpHandler](./kibana-plugin-public.httphandler.md)s. | -| [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) | | +| [HttpSetup](./kibana-plugin-public.httpsetup.md) | | | [I18nStart](./kibana-plugin-public.i18nstart.md) | I18nStart.Context is required by any localizable React component from @kbn/i18n and @elastic/eui packages and is supposed to be used as the topmost component for any i18n-compatible React tree. | | [IAnonymousPaths](./kibana-plugin-public.ianonymouspaths.md) | APIs for denoting paths as not requiring authentication | | [IBasePath](./kibana-plugin-public.ibasepath.md) | APIs for manipulating the basePath on URL segments. | @@ -118,8 +118,7 @@ The plugin integrates with the core system via lifecycle events: `setup` | [HandlerContextType](./kibana-plugin-public.handlercontexttype.md) | Extracts the type of the first argument of a [HandlerFunction](./kibana-plugin-public.handlerfunction.md) to represent the type of the context. | | [HandlerFunction](./kibana-plugin-public.handlerfunction.md) | A function that accepts a context object and an optional number of additional arguments. Used for the generic types in [IContextContainer](./kibana-plugin-public.icontextcontainer.md) | | [HandlerParameters](./kibana-plugin-public.handlerparameters.md) | Extracts the types of the additional arguments of a [HandlerFunction](./kibana-plugin-public.handlerfunction.md), excluding the [HandlerContextType](./kibana-plugin-public.handlercontexttype.md). | -| [HttpSetup](./kibana-plugin-public.httpsetup.md) | See [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) | -| [HttpStart](./kibana-plugin-public.httpstart.md) | See [HttpServiceBase](./kibana-plugin-public.httpservicebase.md) | +| [HttpStart](./kibana-plugin-public.httpstart.md) | See [HttpSetup](./kibana-plugin-public.httpsetup.md) | | [IContextProvider](./kibana-plugin-public.icontextprovider.md) | A function that returns a context value for a specific key of given context type. | | [IToasts](./kibana-plugin-public.itoasts.md) | Methods for adding and removing global toast messages. See [ToastsApi](./kibana-plugin-public.toastsapi.md). | | [MountPoint](./kibana-plugin-public.mountpoint.md) | A function that should mount DOM content inside the provided container element and return a handler to unmount it. | diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsclient.md b/docs/development/core/public/kibana-plugin-public.savedobjectsclient.md index 3c4e33db4af91..88485aa71f7c5 100644 --- a/docs/development/core/public/kibana-plugin-public.savedobjectsclient.md +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsclient.md @@ -12,6 +12,10 @@ Saved Objects is Kibana's data persisentence mechanism allowing plugins to use E export declare class SavedObjectsClient ``` +## Remarks + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `SavedObjectsClient` class. + ## Properties | Property | Modifiers | Type | Description | @@ -30,7 +34,3 @@ export declare class SavedObjectsClient | [bulkUpdate(objects)](./kibana-plugin-public.savedobjectsclient.bulkupdate.md) | | Update multiple documents at once | | [update(type, id, attributes, { version, migrationVersion, references })](./kibana-plugin-public.savedobjectsclient.update.md) | | Updates an object | -## Remarks - -The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `SavedObjectsClient` class. - diff --git a/docs/development/core/server/kibana-plugin-server.basepath.md b/docs/development/core/server/kibana-plugin-server.basepath.md index 77f50abc60369..50a30f7c43fe6 100644 --- a/docs/development/core/server/kibana-plugin-server.basepath.md +++ b/docs/development/core/server/kibana-plugin-server.basepath.md @@ -12,6 +12,10 @@ Access or manipulate the Kibana base path export declare class BasePath ``` +## Remarks + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `BasePath` class. + ## Properties | Property | Modifiers | Type | Description | @@ -22,7 +26,3 @@ export declare class BasePath | [serverBasePath](./kibana-plugin-server.basepath.serverbasepath.md) | | string | returns the server's basePathSee [BasePath.get](./kibana-plugin-server.basepath.get.md) for getting the basePath value for a specific request | | [set](./kibana-plugin-server.basepath.set.md) | | (request: KibanaRequest<unknown, unknown, unknown, any> | LegacyRequest, requestSpecificBasePath: string) => void | sets basePath value, specific for an incoming request. | -## Remarks - -The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `BasePath` class. - diff --git a/docs/development/core/server/kibana-plugin-server.clusterclient.asscoped.md b/docs/development/core/server/kibana-plugin-server.clusterclient.asscoped.md index ed7d028a1ec8a..bb1f481c9ef4f 100644 --- a/docs/development/core/server/kibana-plugin-server.clusterclient.asscoped.md +++ b/docs/development/core/server/kibana-plugin-server.clusterclient.asscoped.md @@ -9,14 +9,14 @@ Creates an instance of [IScopedClusterClient](./kibana-plugin-server.iscopedclus Signature: ```typescript -asScoped(request?: KibanaRequest | LegacyRequest | FakeRequest): IScopedClusterClient; +asScoped(request?: ScopeableRequest): IScopedClusterClient; ``` ## Parameters | Parameter | Type | Description | | --- | --- | --- | -| request | KibanaRequest | LegacyRequest | FakeRequest | Request the IScopedClusterClient instance will be scoped to. Supports request optionality, Legacy.Request & FakeRequest for BWC with LegacyPlatform | +| request | ScopeableRequest | Request the IScopedClusterClient instance will be scoped to. Supports request optionality, Legacy.Request & FakeRequest for BWC with LegacyPlatform | Returns: diff --git a/docs/development/core/server/kibana-plugin-server.clusterclient.md b/docs/development/core/server/kibana-plugin-server.clusterclient.md index 5fdda7ef3e499..d547b846e65b7 100644 --- a/docs/development/core/server/kibana-plugin-server.clusterclient.md +++ b/docs/development/core/server/kibana-plugin-server.clusterclient.md @@ -4,7 +4,7 @@ ## ClusterClient class -Represents an Elasticsearch cluster API client and allows to call API on behalf of the internal Kibana user and the actual user that is derived from the request headers (via `asScoped(...)`). +Represents an Elasticsearch cluster API client created by the platform. It allows to call API on behalf of the internal Kibana user and the actual user that is derived from the request headers (via `asScoped(...)`). See [ClusterClient](./kibana-plugin-server.clusterclient.md). diff --git a/docs/development/core/server/kibana-plugin-server.configdeprecationfactory.md b/docs/development/core/server/kibana-plugin-server.configdeprecationfactory.md index f022d6c1d064a..0302797147cff 100644 --- a/docs/development/core/server/kibana-plugin-server.configdeprecationfactory.md +++ b/docs/development/core/server/kibana-plugin-server.configdeprecationfactory.md @@ -14,15 +14,6 @@ See methods documentation for more detailed examples. export interface ConfigDeprecationFactory ``` -## Methods - -| Method | Description | -| --- | --- | -| [rename(oldKey, newKey)](./kibana-plugin-server.configdeprecationfactory.rename.md) | Rename a configuration property from inside a plugin's configuration path. Will log a deprecation warning if the oldKey was found and deprecation applied. | -| [renameFromRoot(oldKey, newKey)](./kibana-plugin-server.configdeprecationfactory.renamefromroot.md) | Rename a configuration property from the root configuration. Will log a deprecation warning if the oldKey was found and deprecation applied.This should be only used when renaming properties from different configuration's path. To rename properties from inside a plugin's configuration, use 'rename' instead. | -| [unused(unusedKey)](./kibana-plugin-server.configdeprecationfactory.unused.md) | Remove a configuration property from inside a plugin's configuration path. Will log a deprecation warning if the unused key was found and deprecation applied. | -| [unusedFromRoot(unusedKey)](./kibana-plugin-server.configdeprecationfactory.unusedfromroot.md) | Remove a configuration property from the root configuration. Will log a deprecation warning if the unused key was found and deprecation applied.This should be only used when removing properties from outside of a plugin's configuration. To remove properties from inside a plugin's configuration, use 'unused' instead. | - ## Example @@ -34,3 +25,12 @@ const provider: ConfigDeprecationProvider = ({ rename, unused }) => [ ``` +## Methods + +| Method | Description | +| --- | --- | +| [rename(oldKey, newKey)](./kibana-plugin-server.configdeprecationfactory.rename.md) | Rename a configuration property from inside a plugin's configuration path. Will log a deprecation warning if the oldKey was found and deprecation applied. | +| [renameFromRoot(oldKey, newKey)](./kibana-plugin-server.configdeprecationfactory.renamefromroot.md) | Rename a configuration property from the root configuration. Will log a deprecation warning if the oldKey was found and deprecation applied.This should be only used when renaming properties from different configuration's path. To rename properties from inside a plugin's configuration, use 'rename' instead. | +| [unused(unusedKey)](./kibana-plugin-server.configdeprecationfactory.unused.md) | Remove a configuration property from inside a plugin's configuration path. Will log a deprecation warning if the unused key was found and deprecation applied. | +| [unusedFromRoot(unusedKey)](./kibana-plugin-server.configdeprecationfactory.unusedfromroot.md) | Remove a configuration property from the root configuration. Will log a deprecation warning if the unused key was found and deprecation applied.This should be only used when removing properties from outside of a plugin's configuration. To remove properties from inside a plugin's configuration, use 'unused' instead. | + diff --git a/docs/development/core/server/kibana-plugin-server.contextsetup.md b/docs/development/core/server/kibana-plugin-server.contextsetup.md index 1f285efe92b68..1b2a1e2f1b621 100644 --- a/docs/development/core/server/kibana-plugin-server.contextsetup.md +++ b/docs/development/core/server/kibana-plugin-server.contextsetup.md @@ -12,12 +12,6 @@ An object that handles registration of context providers and configuring handler export interface ContextSetup ``` -## Methods - -| Method | Description | -| --- | --- | -| [createContextContainer()](./kibana-plugin-server.contextsetup.createcontextcontainer.md) | Creates a new [IContextContainer](./kibana-plugin-server.icontextcontainer.md) for a service owner. | - ## Remarks A [IContextContainer](./kibana-plugin-server.icontextcontainer.md) can be used by any Core service or plugin (known as the "service owner") which wishes to expose APIs in a handler function. The container object will manage registering context providers and configuring a handler with all of the contexts that should be exposed to the handler's plugin. This is dependent on the dependencies that the handler's plugin declares. @@ -136,3 +130,9 @@ class VizRenderingPlugin { ``` +## Methods + +| Method | Description | +| --- | --- | +| [createContextContainer()](./kibana-plugin-server.contextsetup.createcontextcontainer.md) | Creates a new [IContextContainer](./kibana-plugin-server.icontextcontainer.md) for a service owner. | + diff --git a/docs/development/core/server/kibana-plugin-server.coresetup.md b/docs/development/core/server/kibana-plugin-server.coresetup.md index 3886b6e05e657..3f7f5b727ee80 100644 --- a/docs/development/core/server/kibana-plugin-server.coresetup.md +++ b/docs/development/core/server/kibana-plugin-server.coresetup.md @@ -22,4 +22,5 @@ export interface CoreSetup | [http](./kibana-plugin-server.coresetup.http.md) | HttpServiceSetup | [HttpServiceSetup](./kibana-plugin-server.httpservicesetup.md) | | [savedObjects](./kibana-plugin-server.coresetup.savedobjects.md) | SavedObjectsServiceSetup | [SavedObjectsServiceSetup](./kibana-plugin-server.savedobjectsservicesetup.md) | | [uiSettings](./kibana-plugin-server.coresetup.uisettings.md) | UiSettingsServiceSetup | [UiSettingsServiceSetup](./kibana-plugin-server.uisettingsservicesetup.md) | +| [uuid](./kibana-plugin-server.coresetup.uuid.md) | UuidServiceSetup | [UuidServiceSetup](./kibana-plugin-server.uuidservicesetup.md) | diff --git a/docs/development/core/server/kibana-plugin-server.coresetup.uuid.md b/docs/development/core/server/kibana-plugin-server.coresetup.uuid.md new file mode 100644 index 0000000000000..2b9077735d8e3 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.coresetup.uuid.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [CoreSetup](./kibana-plugin-server.coresetup.md) > [uuid](./kibana-plugin-server.coresetup.uuid.md) + +## CoreSetup.uuid property + +[UuidServiceSetup](./kibana-plugin-server.uuidservicesetup.md) + +Signature: + +```typescript +uuid: UuidServiceSetup; +``` diff --git a/docs/development/core/server/kibana-plugin-server.corestart.md b/docs/development/core/server/kibana-plugin-server.corestart.md index e523717a37ac8..167c69d5fe329 100644 --- a/docs/development/core/server/kibana-plugin-server.corestart.md +++ b/docs/development/core/server/kibana-plugin-server.corestart.md @@ -18,4 +18,5 @@ export interface CoreStart | --- | --- | --- | | [capabilities](./kibana-plugin-server.corestart.capabilities.md) | CapabilitiesStart | [CapabilitiesStart](./kibana-plugin-server.capabilitiesstart.md) | | [savedObjects](./kibana-plugin-server.corestart.savedobjects.md) | SavedObjectsServiceStart | [SavedObjectsServiceStart](./kibana-plugin-server.savedobjectsservicestart.md) | +| [uiSettings](./kibana-plugin-server.corestart.uisettings.md) | UiSettingsServiceStart | [UiSettingsServiceStart](./kibana-plugin-server.uisettingsservicestart.md) | diff --git a/docs/development/core/server/kibana-plugin-server.corestart.uisettings.md b/docs/development/core/server/kibana-plugin-server.corestart.uisettings.md new file mode 100644 index 0000000000000..323e929f2918e --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.corestart.uisettings.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [CoreStart](./kibana-plugin-server.corestart.md) > [uiSettings](./kibana-plugin-server.corestart.uisettings.md) + +## CoreStart.uiSettings property + +[UiSettingsServiceStart](./kibana-plugin-server.uisettingsservicestart.md) + +Signature: + +```typescript +uiSettings: UiSettingsServiceStart; +``` diff --git a/docs/development/core/server/kibana-plugin-server.cspconfig.md b/docs/development/core/server/kibana-plugin-server.cspconfig.md index e5276991be404..7e491cb0df912 100644 --- a/docs/development/core/server/kibana-plugin-server.cspconfig.md +++ b/docs/development/core/server/kibana-plugin-server.cspconfig.md @@ -12,6 +12,10 @@ CSP configuration for use in Kibana. export declare class CspConfig implements ICspConfig ``` +## Remarks + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `CspConfig` class. + ## Properties | Property | Modifiers | Type | Description | @@ -22,7 +26,3 @@ export declare class CspConfig implements ICspConfig | [strict](./kibana-plugin-server.cspconfig.strict.md) | | boolean | | | [warnLegacyBrowsers](./kibana-plugin-server.cspconfig.warnlegacybrowsers.md) | | boolean | | -## Remarks - -The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `CspConfig` class. - diff --git a/docs/development/core/server/kibana-plugin-server.elasticsearcherrorhelpers.md b/docs/development/core/server/kibana-plugin-server.elasticsearcherrorhelpers.md index c823da392042a..2e615acfeac6b 100644 --- a/docs/development/core/server/kibana-plugin-server.elasticsearcherrorhelpers.md +++ b/docs/development/core/server/kibana-plugin-server.elasticsearcherrorhelpers.md @@ -12,13 +12,6 @@ Helpers for working with errors returned from the Elasticsearch service.Since th export declare class ElasticsearchErrorHelpers ``` -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [decorateNotAuthorizedError(error, reason)](./kibana-plugin-server.elasticsearcherrorhelpers.decoratenotauthorizederror.md) | static | | -| [isNotAuthorizedError(error)](./kibana-plugin-server.elasticsearcherrorhelpers.isnotauthorizederror.md) | static | | - ## Example Handle errors @@ -33,3 +26,10 @@ try { ``` +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [decorateNotAuthorizedError(error, reason)](./kibana-plugin-server.elasticsearcherrorhelpers.decoratenotauthorizederror.md) | static | | +| [isNotAuthorizedError(error)](./kibana-plugin-server.elasticsearcherrorhelpers.isnotauthorizederror.md) | static | | + diff --git a/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.adminclient.md b/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.adminclient.md new file mode 100644 index 0000000000000..415423f555266 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.adminclient.md @@ -0,0 +1,22 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [ElasticsearchServiceSetup](./kibana-plugin-server.elasticsearchservicesetup.md) > [adminClient](./kibana-plugin-server.elasticsearchservicesetup.adminclient.md) + +## ElasticsearchServiceSetup.adminClient property + +A client for the `admin` cluster. All Elasticsearch config value changes are processed under the hood. See [IClusterClient](./kibana-plugin-server.iclusterclient.md). + +Signature: + +```typescript +readonly adminClient: IClusterClient; +``` + +## Example + + +```js +const client = core.elasticsearch.adminClient; + +``` + diff --git a/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.adminclient_.md b/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.adminclient_.md deleted file mode 100644 index b5bfc68d3ca0c..0000000000000 --- a/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.adminclient_.md +++ /dev/null @@ -1,19 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [ElasticsearchServiceSetup](./kibana-plugin-server.elasticsearchservicesetup.md) > [adminClient$](./kibana-plugin-server.elasticsearchservicesetup.adminclient_.md) - -## ElasticsearchServiceSetup.adminClient$ property - -Observable of clients for the `admin` cluster. Observable emits when Elasticsearch config changes on the Kibana server. See [IClusterClient](./kibana-plugin-server.iclusterclient.md). - - -```js -const client = await elasticsearch.adminClient$.pipe(take(1)).toPromise(); - -``` - -Signature: - -```typescript -readonly adminClient$: Observable; -``` diff --git a/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.createclient.md b/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.createclient.md index 3d26f2d4cec88..797f402cc2580 100644 --- a/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.createclient.md +++ b/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.createclient.md @@ -9,7 +9,7 @@ Create application specific Elasticsearch cluster API client with customized con Signature: ```typescript -readonly createClient: (type: string, clientConfig?: Partial) => IClusterClient; +readonly createClient: (type: string, clientConfig?: Partial) => ICustomClusterClient; ``` ## Example diff --git a/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.dataclient.md b/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.dataclient.md new file mode 100644 index 0000000000000..e9845dce6915d --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.dataclient.md @@ -0,0 +1,22 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [ElasticsearchServiceSetup](./kibana-plugin-server.elasticsearchservicesetup.md) > [dataClient](./kibana-plugin-server.elasticsearchservicesetup.dataclient.md) + +## ElasticsearchServiceSetup.dataClient property + +A client for the `data` cluster. All Elasticsearch config value changes are processed under the hood. See [IClusterClient](./kibana-plugin-server.iclusterclient.md). + +Signature: + +```typescript +readonly dataClient: IClusterClient; +``` + +## Example + + +```js +const client = core.elasticsearch.dataClient; + +``` + diff --git a/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.dataclient_.md b/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.dataclient_.md deleted file mode 100644 index 9411f2f6b8694..0000000000000 --- a/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.dataclient_.md +++ /dev/null @@ -1,19 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [ElasticsearchServiceSetup](./kibana-plugin-server.elasticsearchservicesetup.md) > [dataClient$](./kibana-plugin-server.elasticsearchservicesetup.dataclient_.md) - -## ElasticsearchServiceSetup.dataClient$ property - -Observable of clients for the `data` cluster. Observable emits when Elasticsearch config changes on the Kibana server. See [IClusterClient](./kibana-plugin-server.iclusterclient.md). - - -```js -const client = await elasticsearch.dataClient$.pipe(take(1)).toPromise(); - -``` - -Signature: - -```typescript -readonly dataClient$: Observable; -``` diff --git a/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.md b/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.md index e3d151cdc0d8b..2de3f6e6d1bbc 100644 --- a/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.md +++ b/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.md @@ -15,17 +15,7 @@ export interface ElasticsearchServiceSetup | Property | Type | Description | | --- | --- | --- | -| [adminClient$](./kibana-plugin-server.elasticsearchservicesetup.adminclient_.md) | Observable<IClusterClient> | Observable of clients for the admin cluster. Observable emits when Elasticsearch config changes on the Kibana server. See [IClusterClient](./kibana-plugin-server.iclusterclient.md). -```js -const client = await elasticsearch.adminClient$.pipe(take(1)).toPromise(); - -``` - | -| [createClient](./kibana-plugin-server.elasticsearchservicesetup.createclient.md) | (type: string, clientConfig?: Partial<ElasticsearchClientConfig>) => IClusterClient | Create application specific Elasticsearch cluster API client with customized config. See [IClusterClient](./kibana-plugin-server.iclusterclient.md). | -| [dataClient$](./kibana-plugin-server.elasticsearchservicesetup.dataclient_.md) | Observable<IClusterClient> | Observable of clients for the data cluster. Observable emits when Elasticsearch config changes on the Kibana server. See [IClusterClient](./kibana-plugin-server.iclusterclient.md). -```js -const client = await elasticsearch.dataClient$.pipe(take(1)).toPromise(); - -``` - | +| [adminClient](./kibana-plugin-server.elasticsearchservicesetup.adminclient.md) | IClusterClient | A client for the admin cluster. All Elasticsearch config value changes are processed under the hood. See [IClusterClient](./kibana-plugin-server.iclusterclient.md). | +| [createClient](./kibana-plugin-server.elasticsearchservicesetup.createclient.md) | (type: string, clientConfig?: Partial<ElasticsearchClientConfig>) => ICustomClusterClient | Create application specific Elasticsearch cluster API client with customized config. See [IClusterClient](./kibana-plugin-server.iclusterclient.md). | +| [dataClient](./kibana-plugin-server.elasticsearchservicesetup.dataclient.md) | IClusterClient | A client for the data cluster. All Elasticsearch config value changes are processed under the hood. See [IClusterClient](./kibana-plugin-server.iclusterclient.md). | diff --git a/docs/development/core/server/kibana-plugin-server.httpservicesetup.md b/docs/development/core/server/kibana-plugin-server.httpservicesetup.md index 99d4caf40c0d3..3b1993841339d 100644 --- a/docs/development/core/server/kibana-plugin-server.httpservicesetup.md +++ b/docs/development/core/server/kibana-plugin-server.httpservicesetup.md @@ -12,21 +12,6 @@ Kibana HTTP Service provides own abstraction for work with HTTP stack. Plugins d export interface HttpServiceSetup ``` -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [basePath](./kibana-plugin-server.httpservicesetup.basepath.md) | IBasePath | Access or manipulate the Kibana base path See [IBasePath](./kibana-plugin-server.ibasepath.md). | -| [createCookieSessionStorageFactory](./kibana-plugin-server.httpservicesetup.createcookiesessionstoragefactory.md) | <T>(cookieOptions: SessionStorageCookieOptions<T>) => Promise<SessionStorageFactory<T>> | Creates cookie based session storage factory [SessionStorageFactory](./kibana-plugin-server.sessionstoragefactory.md) | -| [createRouter](./kibana-plugin-server.httpservicesetup.createrouter.md) | () => IRouter | Provides ability to declare a handler function for a particular path and HTTP request method. | -| [csp](./kibana-plugin-server.httpservicesetup.csp.md) | ICspConfig | The CSP config used for Kibana. | -| [isTlsEnabled](./kibana-plugin-server.httpservicesetup.istlsenabled.md) | boolean | Flag showing whether a server was configured to use TLS connection. | -| [registerAuth](./kibana-plugin-server.httpservicesetup.registerauth.md) | (handler: AuthenticationHandler) => void | To define custom authentication and/or authorization mechanism for incoming requests. | -| [registerOnPostAuth](./kibana-plugin-server.httpservicesetup.registeronpostauth.md) | (handler: OnPostAuthHandler) => void | To define custom logic to perform for incoming requests. | -| [registerOnPreAuth](./kibana-plugin-server.httpservicesetup.registeronpreauth.md) | (handler: OnPreAuthHandler) => void | To define custom logic to perform for incoming requests. | -| [registerOnPreResponse](./kibana-plugin-server.httpservicesetup.registeronpreresponse.md) | (handler: OnPreResponseHandler) => void | To define custom logic to perform for the server response. | -| [registerRouteHandlerContext](./kibana-plugin-server.httpservicesetup.registerroutehandlercontext.md) | <T extends keyof RequestHandlerContext>(contextName: T, provider: RequestHandlerContextProvider<T>) => RequestHandlerContextContainer | Register a context provider for a route handler. | - ## Example To handle an incoming request in your plugin you should: - Create a `Router` instance. @@ -92,3 +77,18 @@ async (context, request, response) => { ``` +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [basePath](./kibana-plugin-server.httpservicesetup.basepath.md) | IBasePath | Access or manipulate the Kibana base path See [IBasePath](./kibana-plugin-server.ibasepath.md). | +| [createCookieSessionStorageFactory](./kibana-plugin-server.httpservicesetup.createcookiesessionstoragefactory.md) | <T>(cookieOptions: SessionStorageCookieOptions<T>) => Promise<SessionStorageFactory<T>> | Creates cookie based session storage factory [SessionStorageFactory](./kibana-plugin-server.sessionstoragefactory.md) | +| [createRouter](./kibana-plugin-server.httpservicesetup.createrouter.md) | () => IRouter | Provides ability to declare a handler function for a particular path and HTTP request method. | +| [csp](./kibana-plugin-server.httpservicesetup.csp.md) | ICspConfig | The CSP config used for Kibana. | +| [isTlsEnabled](./kibana-plugin-server.httpservicesetup.istlsenabled.md) | boolean | Flag showing whether a server was configured to use TLS connection. | +| [registerAuth](./kibana-plugin-server.httpservicesetup.registerauth.md) | (handler: AuthenticationHandler) => void | To define custom authentication and/or authorization mechanism for incoming requests. | +| [registerOnPostAuth](./kibana-plugin-server.httpservicesetup.registeronpostauth.md) | (handler: OnPostAuthHandler) => void | To define custom logic to perform for incoming requests. | +| [registerOnPreAuth](./kibana-plugin-server.httpservicesetup.registeronpreauth.md) | (handler: OnPreAuthHandler) => void | To define custom logic to perform for incoming requests. | +| [registerOnPreResponse](./kibana-plugin-server.httpservicesetup.registeronpreresponse.md) | (handler: OnPreResponseHandler) => void | To define custom logic to perform for the server response. | +| [registerRouteHandlerContext](./kibana-plugin-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-server.iclusterclient.md b/docs/development/core/server/kibana-plugin-server.iclusterclient.md index 834afa6db5157..e7435a9d91a74 100644 --- a/docs/development/core/server/kibana-plugin-server.iclusterclient.md +++ b/docs/development/core/server/kibana-plugin-server.iclusterclient.md @@ -4,12 +4,12 @@ ## IClusterClient type -Represents an Elasticsearch cluster API client and allows to call API on behalf of the internal Kibana user and the actual user that is derived from the request headers (via `asScoped(...)`). +Represents an Elasticsearch cluster API client created by the platform. It allows to call API on behalf of the internal Kibana user and the actual user that is derived from the request headers (via `asScoped(...)`). See [ClusterClient](./kibana-plugin-server.clusterclient.md). Signature: ```typescript -export declare type IClusterClient = Pick; +export declare type IClusterClient = Pick; ``` diff --git a/docs/development/core/server/kibana-plugin-server.icontextcontainer.md b/docs/development/core/server/kibana-plugin-server.icontextcontainer.md index 114da31442ff9..8235c40131536 100644 --- a/docs/development/core/server/kibana-plugin-server.icontextcontainer.md +++ b/docs/development/core/server/kibana-plugin-server.icontextcontainer.md @@ -12,13 +12,6 @@ An object that handles registration of context providers and configuring handler export interface IContextContainer> ``` -## Methods - -| Method | Description | -| --- | --- | -| [createHandler(pluginOpaqueId, handler)](./kibana-plugin-server.icontextcontainer.createhandler.md) | Create a new handler function pre-wired to context for the plugin. | -| [registerContext(pluginOpaqueId, contextName, provider)](./kibana-plugin-server.icontextcontainer.registercontext.md) | Register a new context provider. | - ## Remarks A [IContextContainer](./kibana-plugin-server.icontextcontainer.md) can be used by any Core service or plugin (known as the "service owner") which wishes to expose APIs in a handler function. The container object will manage registering context providers and configuring a handler with all of the contexts that should be exposed to the handler's plugin. This is dependent on the dependencies that the handler's plugin declares. @@ -78,3 +71,10 @@ class MyPlugin { ``` +## Methods + +| Method | Description | +| --- | --- | +| [createHandler(pluginOpaqueId, handler)](./kibana-plugin-server.icontextcontainer.createhandler.md) | Create a new handler function pre-wired to context for the plugin. | +| [registerContext(pluginOpaqueId, contextName, provider)](./kibana-plugin-server.icontextcontainer.registercontext.md) | Register a new context provider. | + diff --git a/docs/development/core/server/kibana-plugin-server.icustomclusterclient.md b/docs/development/core/server/kibana-plugin-server.icustomclusterclient.md new file mode 100644 index 0000000000000..bc9ea71bc2389 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.icustomclusterclient.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [ICustomClusterClient](./kibana-plugin-server.icustomclusterclient.md) + +## ICustomClusterClient type + +Represents an Elasticsearch cluster API client created by a plugin.. It allows to call API on behalf of the internal Kibana user and the actual user that is derived from the request headers (via `asScoped(...)`). + +See [ClusterClient](./kibana-plugin-server.clusterclient.md). + +Signature: + +```typescript +export declare type ICustomClusterClient = Pick; +``` diff --git a/docs/development/core/server/kibana-plugin-server.irenderoptions.includeusersettings.md b/docs/development/core/server/kibana-plugin-server.irenderoptions.includeusersettings.md new file mode 100644 index 0000000000000..cedf3d27d0887 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.irenderoptions.includeusersettings.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [IRenderOptions](./kibana-plugin-server.irenderoptions.md) > [includeUserSettings](./kibana-plugin-server.irenderoptions.includeusersettings.md) + +## IRenderOptions.includeUserSettings property + +Set whether to output user settings in the page metadata. `true` by default. + +Signature: + +```typescript +includeUserSettings?: boolean; +``` diff --git a/docs/development/core/server/kibana-plugin-server.irenderoptions.md b/docs/development/core/server/kibana-plugin-server.irenderoptions.md new file mode 100644 index 0000000000000..34bed8b5e078c --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.irenderoptions.md @@ -0,0 +1,19 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [IRenderOptions](./kibana-plugin-server.irenderoptions.md) + +## IRenderOptions interface + + +Signature: + +```typescript +export interface IRenderOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [includeUserSettings](./kibana-plugin-server.irenderoptions.includeusersettings.md) | boolean | Set whether to output user settings in the page metadata. true by default. | + diff --git a/docs/development/core/server/kibana-plugin-server.irouter.handlelegacyerrors.md b/docs/development/core/server/kibana-plugin-server.irouter.handlelegacyerrors.md index 2367420068064..ff71f13466cf8 100644 --- a/docs/development/core/server/kibana-plugin-server.irouter.handlelegacyerrors.md +++ b/docs/development/core/server/kibana-plugin-server.irouter.handlelegacyerrors.md @@ -9,5 +9,5 @@ Wrap a router handler to catch and converts legacy boom errors to proper custom Signature: ```typescript -handleLegacyErrors:

(handler: RequestHandler) => RequestHandler; +handleLegacyErrors: (handler: RequestHandler) => RequestHandler; ``` diff --git a/docs/development/core/server/kibana-plugin-server.irouter.md b/docs/development/core/server/kibana-plugin-server.irouter.md index 73e96191e02e7..a6536d2ed6763 100644 --- a/docs/development/core/server/kibana-plugin-server.irouter.md +++ b/docs/development/core/server/kibana-plugin-server.irouter.md @@ -18,7 +18,7 @@ export interface IRouter | --- | --- | --- | | [delete](./kibana-plugin-server.irouter.delete.md) | RouteRegistrar<'delete'> | Register a route handler for DELETE request. | | [get](./kibana-plugin-server.irouter.get.md) | RouteRegistrar<'get'> | Register a route handler for GET request. | -| [handleLegacyErrors](./kibana-plugin-server.irouter.handlelegacyerrors.md) | <P extends ObjectType, Q extends ObjectType, B extends ObjectType>(handler: RequestHandler<P, Q, B>) => RequestHandler<P, Q, B> | Wrap a router handler to catch and converts legacy boom errors to proper custom errors. | +| [handleLegacyErrors](./kibana-plugin-server.irouter.handlelegacyerrors.md) | <P, Q, B>(handler: RequestHandler<P, Q, B>) => RequestHandler<P, Q, B> | Wrap a router handler to catch and converts legacy boom errors to proper custom errors. | | [patch](./kibana-plugin-server.irouter.patch.md) | RouteRegistrar<'patch'> | Register a route handler for PATCH request. | | [post](./kibana-plugin-server.irouter.post.md) | RouteRegistrar<'post'> | Register a route handler for POST request. | | [put](./kibana-plugin-server.irouter.put.md) | RouteRegistrar<'put'> | Register a route handler for PUT request. | diff --git a/docs/development/core/server/kibana-plugin-server.iscopedrenderingclient.md b/docs/development/core/server/kibana-plugin-server.iscopedrenderingclient.md new file mode 100644 index 0000000000000..2e6daa58db25f --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.iscopedrenderingclient.md @@ -0,0 +1,19 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [IScopedRenderingClient](./kibana-plugin-server.iscopedrenderingclient.md) + +## IScopedRenderingClient interface + + +Signature: + +```typescript +export interface IScopedRenderingClient +``` + +## Methods + +| Method | Description | +| --- | --- | +| [render(options)](./kibana-plugin-server.iscopedrenderingclient.render.md) | Generate a KibanaResponse which renders an HTML page bootstrapped with the core bundle. Intended as a response body for HTTP route handlers. | + diff --git a/docs/development/core/server/kibana-plugin-server.iscopedrenderingclient.render.md b/docs/development/core/server/kibana-plugin-server.iscopedrenderingclient.render.md new file mode 100644 index 0000000000000..1bc78dd84571d --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.iscopedrenderingclient.render.md @@ -0,0 +1,41 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [IScopedRenderingClient](./kibana-plugin-server.iscopedrenderingclient.md) > [render](./kibana-plugin-server.iscopedrenderingclient.render.md) + +## IScopedRenderingClient.render() method + +Generate a `KibanaResponse` which renders an HTML page bootstrapped with the `core` bundle. Intended as a response body for HTTP route handlers. + +Signature: + +```typescript +render(options?: IRenderOptions): Promise; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| options | IRenderOptions | | + +Returns: + +`Promise` + +## Example + + +```ts +router.get( + { path: '/', validate: false }, + (context, request, response) => + response.ok({ + body: await context.core.rendering.render(), + headers: { + 'content-security-policy': context.core.http.csp.header, + }, + }) +); + +``` + diff --git a/docs/development/core/server/kibana-plugin-server.legacyservicesetupdeps.core.md b/docs/development/core/server/kibana-plugin-server.legacyservicesetupdeps.core.md index 09ebf1170715b..c4c043a903d06 100644 --- a/docs/development/core/server/kibana-plugin-server.legacyservicesetupdeps.core.md +++ b/docs/development/core/server/kibana-plugin-server.legacyservicesetupdeps.core.md @@ -7,7 +7,5 @@ Signature: ```typescript -core: InternalCoreSetup & { - plugins: PluginsServiceSetup; - }; +core: LegacyCoreSetup; ``` diff --git a/docs/development/core/server/kibana-plugin-server.legacyservicesetupdeps.md b/docs/development/core/server/kibana-plugin-server.legacyservicesetupdeps.md index 4475318522dfa..7961cedd2c054 100644 --- a/docs/development/core/server/kibana-plugin-server.legacyservicesetupdeps.md +++ b/docs/development/core/server/kibana-plugin-server.legacyservicesetupdeps.md @@ -18,6 +18,6 @@ export interface LegacyServiceSetupDeps | Property | Type | Description | | --- | --- | --- | -| [core](./kibana-plugin-server.legacyservicesetupdeps.core.md) | InternalCoreSetup & {
plugins: PluginsServiceSetup;
} | | +| [core](./kibana-plugin-server.legacyservicesetupdeps.core.md) | LegacyCoreSetup | | | [plugins](./kibana-plugin-server.legacyservicesetupdeps.plugins.md) | Record<string, unknown> | | diff --git a/docs/development/core/server/kibana-plugin-server.legacyservicestartdeps.core.md b/docs/development/core/server/kibana-plugin-server.legacyservicestartdeps.core.md index c5cf473aaa01a..47018f4594967 100644 --- a/docs/development/core/server/kibana-plugin-server.legacyservicestartdeps.core.md +++ b/docs/development/core/server/kibana-plugin-server.legacyservicestartdeps.core.md @@ -7,7 +7,5 @@ Signature: ```typescript -core: InternalCoreStart & { - plugins: PluginsServiceStart; - }; +core: LegacyCoreStart; ``` diff --git a/docs/development/core/server/kibana-plugin-server.legacyservicestartdeps.md b/docs/development/core/server/kibana-plugin-server.legacyservicestartdeps.md index 801138b64e46a..602fe5356d525 100644 --- a/docs/development/core/server/kibana-plugin-server.legacyservicestartdeps.md +++ b/docs/development/core/server/kibana-plugin-server.legacyservicestartdeps.md @@ -18,6 +18,6 @@ export interface LegacyServiceStartDeps | Property | Type | Description | | --- | --- | --- | -| [core](./kibana-plugin-server.legacyservicestartdeps.core.md) | InternalCoreStart & {
plugins: PluginsServiceStart;
} | | +| [core](./kibana-plugin-server.legacyservicestartdeps.core.md) | LegacyCoreStart | | | [plugins](./kibana-plugin-server.legacyservicestartdeps.plugins.md) | Record<string, unknown> | | diff --git a/docs/development/core/server/kibana-plugin-server.logger.get.md b/docs/development/core/server/kibana-plugin-server.logger.get.md new file mode 100644 index 0000000000000..b4a2d8a124260 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.logger.get.md @@ -0,0 +1,33 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [Logger](./kibana-plugin-server.logger.md) > [get](./kibana-plugin-server.logger.get.md) + +## Logger.get() method + +Returns a new [Logger](./kibana-plugin-server.logger.md) instance extending the current logger context. + +Signature: + +```typescript +get(...childContextPaths: string[]): Logger; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| childContextPaths | string[] | | + +Returns: + +`Logger` + +## Example + + +```typescript +const logger = loggerFactory.get('plugin', 'service'); // 'plugin.service' context +const subLogger = logger.get('feature'); // 'plugin.service.feature' context + +``` + diff --git a/docs/development/core/server/kibana-plugin-server.md b/docs/development/core/server/kibana-plugin-server.md index e97ecbcfaf739..3f01048846fe1 100644 --- a/docs/development/core/server/kibana-plugin-server.md +++ b/docs/development/core/server/kibana-plugin-server.md @@ -17,10 +17,11 @@ The plugin integrates with the core system via lifecycle events: `setup` | Class | Description | | --- | --- | | [BasePath](./kibana-plugin-server.basepath.md) | Access or manipulate the Kibana base path | -| [ClusterClient](./kibana-plugin-server.clusterclient.md) | Represents an Elasticsearch cluster API client and allows to call API on behalf of the internal Kibana user and the actual user that is derived from the request headers (via asScoped(...)).See [ClusterClient](./kibana-plugin-server.clusterclient.md). | +| [ClusterClient](./kibana-plugin-server.clusterclient.md) | Represents an Elasticsearch cluster API client created by the platform. It allows to call API on behalf of the internal Kibana user and the actual user that is derived from the request headers (via asScoped(...)).See [ClusterClient](./kibana-plugin-server.clusterclient.md). | | [CspConfig](./kibana-plugin-server.cspconfig.md) | CSP configuration for use in Kibana. | | [ElasticsearchErrorHelpers](./kibana-plugin-server.elasticsearcherrorhelpers.md) | Helpers for working with errors returned from the Elasticsearch service.Since the internal data of errors are subject to change, consumers of the Elasticsearch service should always use these helpers to classify errors instead of checking error internals such as body.error.header[WWW-Authenticate] | | [KibanaRequest](./kibana-plugin-server.kibanarequest.md) | Kibana specific abstraction for an incoming request. | +| [RouteValidationError](./kibana-plugin-server.routevalidationerror.md) | Error to return when the validation is not successful. | | [SavedObjectsClient](./kibana-plugin-server.savedobjectsclient.md) | | | [SavedObjectsErrorHelpers](./kibana-plugin-server.savedobjectserrorhelpers.md) | | | [SavedObjectsRepository](./kibana-plugin-server.savedobjectsrepository.md) | | @@ -69,7 +70,9 @@ The plugin integrates with the core system via lifecycle events: `setup` | [IKibanaResponse](./kibana-plugin-server.ikibanaresponse.md) | A response data object, expected to returned as a result of [RequestHandler](./kibana-plugin-server.requesthandler.md) execution | | [IKibanaSocket](./kibana-plugin-server.ikibanasocket.md) | A tiny abstraction for TCP socket. | | [IndexSettingsDeprecationInfo](./kibana-plugin-server.indexsettingsdeprecationinfo.md) | | +| [IRenderOptions](./kibana-plugin-server.irenderoptions.md) | | | [IRouter](./kibana-plugin-server.irouter.md) | Registers route handlers for specified resource path and method. See [RouteConfig](./kibana-plugin-server.routeconfig.md) and [RequestHandler](./kibana-plugin-server.requesthandler.md) for more information about arguments to route registrations. | +| [IScopedRenderingClient](./kibana-plugin-server.iscopedrenderingclient.md) | | | [IUiSettingsClient](./kibana-plugin-server.iuisettingsclient.md) | Server-side client that provides access to the advanced settings stored in elasticsearch. The settings provide control over the behavior of the Kibana application. For example, a user can specify how to display numeric or date fields. Users can adjust the settings via Management UI. | | [KibanaRequestRoute](./kibana-plugin-server.kibanarequestroute.md) | Request specific route information exposed to a handler. | | [LegacyRequest](./kibana-plugin-server.legacyrequest.md) | | @@ -90,11 +93,13 @@ The plugin integrates with the core system via lifecycle events: `setup` | [PluginManifest](./kibana-plugin-server.pluginmanifest.md) | Describes the set of required and optional properties plugin can define in its mandatory JSON manifest file. | | [PluginsServiceSetup](./kibana-plugin-server.pluginsservicesetup.md) | | | [PluginsServiceStart](./kibana-plugin-server.pluginsservicestart.md) | | -| [RequestHandlerContext](./kibana-plugin-server.requesthandlercontext.md) | Plugin specific context passed to a route handler.Provides the following clients: - [savedObjects.client](./kibana-plugin-server.savedobjectsclient.md) - Saved Objects client which uses the credentials of the incoming request - [elasticsearch.dataClient](./kibana-plugin-server.scopedclusterclient.md) - Elasticsearch data client which uses the credentials of the incoming request - [elasticsearch.adminClient](./kibana-plugin-server.scopedclusterclient.md) - Elasticsearch admin client which uses the credentials of the incoming request | +| [RequestHandlerContext](./kibana-plugin-server.requesthandlercontext.md) | Plugin specific context passed to a route handler.Provides the following clients: - [rendering](./kibana-plugin-server.iscopedrenderingclient.md) - Rendering client which uses the data of the incoming request - [savedObjects.client](./kibana-plugin-server.savedobjectsclient.md) - Saved Objects client which uses the credentials of the incoming request - [elasticsearch.dataClient](./kibana-plugin-server.scopedclusterclient.md) - Elasticsearch data client which uses the credentials of the incoming request - [elasticsearch.adminClient](./kibana-plugin-server.scopedclusterclient.md) - Elasticsearch admin client which uses the credentials of the incoming request - [uiSettings.client](./kibana-plugin-server.iuisettingsclient.md) - uiSettings client which uses the credentials of the incoming request | | [RouteConfig](./kibana-plugin-server.routeconfig.md) | Route specific configuration. | | [RouteConfigOptions](./kibana-plugin-server.routeconfigoptions.md) | Additional route options. | | [RouteConfigOptionsBody](./kibana-plugin-server.routeconfigoptionsbody.md) | Additional body options for a route | -| [RouteSchemas](./kibana-plugin-server.routeschemas.md) | RouteSchemas contains the schemas for validating the different parts of a request. | +| [RouteValidationResultFactory](./kibana-plugin-server.routevalidationresultfactory.md) | Validation result factory to be used in the custom validation function to return the valid data or validation errorsSee [RouteValidationFunction](./kibana-plugin-server.routevalidationfunction.md). | +| [RouteValidatorConfig](./kibana-plugin-server.routevalidatorconfig.md) | The configuration object to the RouteValidator class. Set params, query and/or body to specify the validation logic to follow for that property. | +| [RouteValidatorOptions](./kibana-plugin-server.routevalidatoroptions.md) | Additional options for the RouteValidator class to modify its default behaviour. | | [SavedObject](./kibana-plugin-server.savedobject.md) | | | [SavedObjectAttributes](./kibana-plugin-server.savedobjectattributes.md) | The data for a Saved Object is stored as an object in the attributes property. | | [SavedObjectReference](./kibana-plugin-server.savedobjectreference.md) | A reference to another saved object. | @@ -137,7 +142,9 @@ The plugin integrates with the core system via lifecycle events: `setup` | [SessionStorageFactory](./kibana-plugin-server.sessionstoragefactory.md) | SessionStorage factory to bind one to an incoming request | | [UiSettingsParams](./kibana-plugin-server.uisettingsparams.md) | UiSettings parameters defined by the plugins. | | [UiSettingsServiceSetup](./kibana-plugin-server.uisettingsservicesetup.md) | | +| [UiSettingsServiceStart](./kibana-plugin-server.uisettingsservicestart.md) | | | [UserProvidedValues](./kibana-plugin-server.userprovidedvalues.md) | Describes the values explicitly set by user. | +| [UuidServiceSetup](./kibana-plugin-server.uuidservicesetup.md) | APIs to access the application's instance uuid. | ## Variables @@ -168,8 +175,9 @@ The plugin integrates with the core system via lifecycle events: `setup` | [Headers](./kibana-plugin-server.headers.md) | Http request headers to read. | | [HttpResponsePayload](./kibana-plugin-server.httpresponsepayload.md) | Data send to the client as a response payload. | | [IBasePath](./kibana-plugin-server.ibasepath.md) | Access or manipulate the Kibana base path[BasePath](./kibana-plugin-server.basepath.md) | -| [IClusterClient](./kibana-plugin-server.iclusterclient.md) | Represents an Elasticsearch cluster API client and allows to call API on behalf of the internal Kibana user and the actual user that is derived from the request headers (via asScoped(...)).See [ClusterClient](./kibana-plugin-server.clusterclient.md). | +| [IClusterClient](./kibana-plugin-server.iclusterclient.md) | Represents an Elasticsearch cluster API client created by the platform. It allows to call API on behalf of the internal Kibana user and the actual user that is derived from the request headers (via asScoped(...)).See [ClusterClient](./kibana-plugin-server.clusterclient.md). | | [IContextProvider](./kibana-plugin-server.icontextprovider.md) | A function that returns a context value for a specific key of given context type. | +| [ICustomClusterClient](./kibana-plugin-server.icustomclusterclient.md) | Represents an Elasticsearch cluster API client created by a plugin.. It allows to call API on behalf of the internal Kibana user and the actual user that is derived from the request headers (via asScoped(...)).See [ClusterClient](./kibana-plugin-server.clusterclient.md). | | [IsAuthenticated](./kibana-plugin-server.isauthenticated.md) | Return authentication status for a request. | | [ISavedObjectsRepository](./kibana-plugin-server.isavedobjectsrepository.md) | See [SavedObjectsRepository](./kibana-plugin-server.savedobjectsrepository.md) | | [IScopedClusterClient](./kibana-plugin-server.iscopedclusterclient.md) | Serves the same purpose as "normal" ClusterClient but exposes additional callAsCurrentUser method that doesn't use credentials of the Kibana internal user (as callAsInternalUser does) to request Elasticsearch API, but rather passes HTTP headers extracted from the current user request to the API.See [ScopedClusterClient](./kibana-plugin-server.scopedclusterclient.md). | @@ -198,11 +206,15 @@ The plugin integrates with the core system via lifecycle events: `setup` | [RouteContentType](./kibana-plugin-server.routecontenttype.md) | The set of supported parseable Content-Types | | [RouteMethod](./kibana-plugin-server.routemethod.md) | The set of common HTTP methods supported by Kibana routing. | | [RouteRegistrar](./kibana-plugin-server.routeregistrar.md) | Route handler common definition | +| [RouteValidationFunction](./kibana-plugin-server.routevalidationfunction.md) | The custom validation function if @kbn/config-schema is not a valid solution for your specific plugin requirements. | +| [RouteValidationSpec](./kibana-plugin-server.routevalidationspec.md) | Allowed property validation options: either @kbn/config-schema validations or custom validation functionsSee [RouteValidationFunction](./kibana-plugin-server.routevalidationfunction.md) for custom validation. | +| [RouteValidatorFullConfig](./kibana-plugin-server.routevalidatorfullconfig.md) | Route validations config and options merged into one object | | [SavedObjectAttribute](./kibana-plugin-server.savedobjectattribute.md) | Type definition for a Saved Object attribute value | | [SavedObjectAttributeSingle](./kibana-plugin-server.savedobjectattributesingle.md) | Don't use this type, it's simply a helper type for [SavedObjectAttribute](./kibana-plugin-server.savedobjectattribute.md) | | [SavedObjectsClientContract](./kibana-plugin-server.savedobjectsclientcontract.md) | Saved Objects is Kibana's data persisentence mechanism allowing plugins to use Elasticsearch for storing plugin state.\#\# SavedObjectsClient errorsSince the SavedObjectsClient has its hands in everything we are a little paranoid about the way we present errors back to to application code. Ideally, all errors will be either:1. Caused by bad implementation (ie. undefined is not a function) and as such unpredictable 2. An error that has been classified and decorated appropriately by the decorators in [SavedObjectsErrorHelpers](./kibana-plugin-server.savedobjectserrorhelpers.md)Type 1 errors are inevitable, but since all expected/handle-able errors should be Type 2 the isXYZError() helpers exposed at SavedObjectsErrorHelpers should be used to understand and manage error responses from the SavedObjectsClient.Type 2 errors are decorated versions of the source error, so if the elasticsearch client threw an error it will be decorated based on its type. That means that rather than looking for error.body.error.type or doing substring checks on error.body.error.reason, just use the helpers to understand the meaning of the error:\`\`\`js if (SavedObjectsErrorHelpers.isNotFoundError(error)) { // handle 404 }if (SavedObjectsErrorHelpers.isNotAuthorizedError(error)) { // 401 handling should be automatic, but in case you wanted to know }// always rethrow the error unless you handle it throw error; \`\`\`\#\#\# 404s from missing indexFrom the perspective of application code and APIs the SavedObjectsClient is a black box that persists objects. One of the internal details that users have no control over is that we use an elasticsearch index for persistance and that index might be missing.At the time of writing we are in the process of transitioning away from the operating assumption that the SavedObjects index is always available. Part of this transition is handling errors resulting from an index missing. These used to trigger a 500 error in most cases, and in others cause 404s with different error messages.From my (Spencer) perspective, a 404 from the SavedObjectsApi is a 404; The object the request/call was targeting could not be found. This is why \#14141 takes special care to ensure that 404 errors are generic and don't distinguish between index missing or document missing.\#\#\# 503s from missing indexUnlike all other methods, create requests are supposed to succeed even when the Kibana index does not exist because it will be automatically created by elasticsearch. When that is not the case it is because Elasticsearch's action.auto_create_index setting prevents it from being created automatically so we throw a special 503 with the intention of informing the user that their Elasticsearch settings need to be updated.See [SavedObjectsClient](./kibana-plugin-server.savedobjectsclient.md) See [SavedObjectsErrorHelpers](./kibana-plugin-server.savedobjectserrorhelpers.md) | | [SavedObjectsClientFactory](./kibana-plugin-server.savedobjectsclientfactory.md) | Describes the factory used to create instances of the Saved Objects Client. | | [SavedObjectsClientWrapperFactory](./kibana-plugin-server.savedobjectsclientwrapperfactory.md) | Describes the factory used to create instances of Saved Objects Client Wrappers. | +| [ScopeableRequest](./kibana-plugin-server.scopeablerequest.md) | A user credentials container. It accommodates the necessary auth credentials to impersonate the current user.See [KibanaRequest](./kibana-plugin-server.kibanarequest.md). | | [SharedGlobalConfig](./kibana-plugin-server.sharedglobalconfig.md) | | | [UiSettingsType](./kibana-plugin-server.uisettingstype.md) | UI element type to represent the settings. | diff --git a/docs/development/core/server/kibana-plugin-server.pluginconfigdescriptor.md b/docs/development/core/server/kibana-plugin-server.pluginconfigdescriptor.md index 671298a67381a..3d661ac66d2b7 100644 --- a/docs/development/core/server/kibana-plugin-server.pluginconfigdescriptor.md +++ b/docs/development/core/server/kibana-plugin-server.pluginconfigdescriptor.md @@ -12,14 +12,6 @@ Describes a plugin configuration properties. export interface PluginConfigDescriptor ``` -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [deprecations](./kibana-plugin-server.pluginconfigdescriptor.deprecations.md) | ConfigDeprecationProvider | Provider for the [ConfigDeprecation](./kibana-plugin-server.configdeprecation.md) to apply to the plugin configuration. | -| [exposeToBrowser](./kibana-plugin-server.pluginconfigdescriptor.exposetobrowser.md) | {
[P in keyof T]?: boolean;
} | List of configuration properties that will be available on the client-side plugin. | -| [schema](./kibana-plugin-server.pluginconfigdescriptor.schema.md) | PluginConfigSchema<T> | Schema to use to validate the plugin configuration.[PluginConfigSchema](./kibana-plugin-server.pluginconfigschema.md) | - ## Example @@ -48,3 +40,11 @@ export const config: PluginConfigDescriptor = { ``` +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [deprecations](./kibana-plugin-server.pluginconfigdescriptor.deprecations.md) | ConfigDeprecationProvider | Provider for the [ConfigDeprecation](./kibana-plugin-server.configdeprecation.md) to apply to the plugin configuration. | +| [exposeToBrowser](./kibana-plugin-server.pluginconfigdescriptor.exposetobrowser.md) | {
[P in keyof T]?: boolean;
} | List of configuration properties that will be available on the client-side plugin. | +| [schema](./kibana-plugin-server.pluginconfigdescriptor.schema.md) | PluginConfigSchema<T> | Schema to use to validate the plugin configuration.[PluginConfigSchema](./kibana-plugin-server.pluginconfigschema.md) | + diff --git a/docs/development/core/server/kibana-plugin-server.pluginmanifest.md b/docs/development/core/server/kibana-plugin-server.pluginmanifest.md index 4a9498f0e9fab..9bb208a809b22 100644 --- a/docs/development/core/server/kibana-plugin-server.pluginmanifest.md +++ b/docs/development/core/server/kibana-plugin-server.pluginmanifest.md @@ -12,6 +12,10 @@ Describes the set of required and optional properties plugin can define in its m export interface PluginManifest ``` +## Remarks + +Should never be used in code outside of Core but is exported for documentation purposes. + ## Properties | Property | Type | Description | @@ -25,7 +29,3 @@ export interface PluginManifest | [ui](./kibana-plugin-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. | | [version](./kibana-plugin-server.pluginmanifest.version.md) | string | Version of the plugin. | -## Remarks - -Should never be used in code outside of Core but is exported for documentation purposes. - diff --git a/docs/development/core/server/kibana-plugin-server.requesthandler.md b/docs/development/core/server/kibana-plugin-server.requesthandler.md index 79abfd4293e9f..9fc183ffc334b 100644 --- a/docs/development/core/server/kibana-plugin-server.requesthandler.md +++ b/docs/development/core/server/kibana-plugin-server.requesthandler.md @@ -9,7 +9,7 @@ A function executed when route path matched requested resource path. Request han Signature: ```typescript -export declare type RequestHandler

| Type, Method extends RouteMethod = any> = (context: RequestHandlerContext, request: KibanaRequest, TypeOf, TypeOf, Method>, response: KibanaResponseFactory) => IKibanaResponse | Promise>; +export declare type RequestHandler

= (context: RequestHandlerContext, request: KibanaRequest, response: KibanaResponseFactory) => IKibanaResponse | Promise>; ``` ## Example diff --git a/docs/development/core/server/kibana-plugin-server.requesthandlercontext.core.md b/docs/development/core/server/kibana-plugin-server.requesthandlercontext.core.md index 2d8b27ecb6c67..d1760dafd5bb6 100644 --- a/docs/development/core/server/kibana-plugin-server.requesthandlercontext.core.md +++ b/docs/development/core/server/kibana-plugin-server.requesthandlercontext.core.md @@ -8,6 +8,7 @@ ```typescript core: { + rendering: IScopedRenderingClient; savedObjects: { client: SavedObjectsClientContract; }; diff --git a/docs/development/core/server/kibana-plugin-server.requesthandlercontext.md b/docs/development/core/server/kibana-plugin-server.requesthandlercontext.md index c9fc80596efa9..7c8625a5824ee 100644 --- a/docs/development/core/server/kibana-plugin-server.requesthandlercontext.md +++ b/docs/development/core/server/kibana-plugin-server.requesthandlercontext.md @@ -6,7 +6,7 @@ Plugin specific context passed to a route handler. -Provides the following clients: - [savedObjects.client](./kibana-plugin-server.savedobjectsclient.md) - Saved Objects client which uses the credentials of the incoming request - [elasticsearch.dataClient](./kibana-plugin-server.scopedclusterclient.md) - Elasticsearch data client which uses the credentials of the incoming request - [elasticsearch.adminClient](./kibana-plugin-server.scopedclusterclient.md) - Elasticsearch admin client which uses the credentials of the incoming request +Provides the following clients: - [rendering](./kibana-plugin-server.iscopedrenderingclient.md) - Rendering client which uses the data of the incoming request - [savedObjects.client](./kibana-plugin-server.savedobjectsclient.md) - Saved Objects client which uses the credentials of the incoming request - [elasticsearch.dataClient](./kibana-plugin-server.scopedclusterclient.md) - Elasticsearch data client which uses the credentials of the incoming request - [elasticsearch.adminClient](./kibana-plugin-server.scopedclusterclient.md) - Elasticsearch admin client which uses the credentials of the incoming request - [uiSettings.client](./kibana-plugin-server.iuisettingsclient.md) - uiSettings client which uses the credentials of the incoming request Signature: @@ -18,5 +18,5 @@ export interface RequestHandlerContext | Property | Type | Description | | --- | --- | --- | -| [core](./kibana-plugin-server.requesthandlercontext.core.md) | {
savedObjects: {
client: SavedObjectsClientContract;
};
elasticsearch: {
dataClient: IScopedClusterClient;
adminClient: IScopedClusterClient;
};
uiSettings: {
client: IUiSettingsClient;
};
} | | +| [core](./kibana-plugin-server.requesthandlercontext.core.md) | {
rendering: IScopedRenderingClient;
savedObjects: {
client: SavedObjectsClientContract;
};
elasticsearch: {
dataClient: IScopedClusterClient;
adminClient: IScopedClusterClient;
};
uiSettings: {
client: IUiSettingsClient;
};
} | | diff --git a/docs/development/core/server/kibana-plugin-server.routeconfig.md b/docs/development/core/server/kibana-plugin-server.routeconfig.md index 1970b23c7ec09..4beb12f0d056e 100644 --- a/docs/development/core/server/kibana-plugin-server.routeconfig.md +++ b/docs/development/core/server/kibana-plugin-server.routeconfig.md @@ -9,7 +9,7 @@ Route specific configuration. Signature: ```typescript -export interface RouteConfig

| Type, Method extends RouteMethod> +export interface RouteConfig ``` ## Properties @@ -18,5 +18,5 @@ export interface RouteConfig

RouteConfigOptions<Method> | Additional route options [RouteConfigOptions](./kibana-plugin-server.routeconfigoptions.md). | | [path](./kibana-plugin-server.routeconfig.path.md) | string | The endpoint \_within\_ the router path to register the route. | -| [validate](./kibana-plugin-server.routeconfig.validate.md) | RouteSchemas<P, Q, B> | false | A schema created with @kbn/config-schema that every request will be validated against. | +| [validate](./kibana-plugin-server.routeconfig.validate.md) | RouteValidatorFullConfig<P, Q, B> | false | A schema created with @kbn/config-schema that every request will be validated against. | diff --git a/docs/development/core/server/kibana-plugin-server.routeconfig.validate.md b/docs/development/core/server/kibana-plugin-server.routeconfig.validate.md index e1ec743ae71cc..23a72fc3c68b3 100644 --- a/docs/development/core/server/kibana-plugin-server.routeconfig.validate.md +++ b/docs/development/core/server/kibana-plugin-server.routeconfig.validate.md @@ -9,7 +9,7 @@ A schema created with `@kbn/config-schema` that every request will be validated Signature: ```typescript -validate: RouteSchemas | false; +validate: RouteValidatorFullConfig | false; ``` ## Remarks diff --git a/docs/development/core/server/kibana-plugin-server.routeregistrar.md b/docs/development/core/server/kibana-plugin-server.routeregistrar.md index 0f5f49636fdd5..901d260fee21d 100644 --- a/docs/development/core/server/kibana-plugin-server.routeregistrar.md +++ b/docs/development/core/server/kibana-plugin-server.routeregistrar.md @@ -9,5 +9,5 @@ Route handler common definition Signature: ```typescript -export declare type RouteRegistrar =

| Type>(route: RouteConfig, handler: RequestHandler) => void; +export declare type RouteRegistrar = (route: RouteConfig, handler: RequestHandler) => void; ``` diff --git a/docs/development/core/server/kibana-plugin-server.routeschemas.body.md b/docs/development/core/server/kibana-plugin-server.routeschemas.body.md deleted file mode 100644 index 78a9d25c25d9d..0000000000000 --- a/docs/development/core/server/kibana-plugin-server.routeschemas.body.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteSchemas](./kibana-plugin-server.routeschemas.md) > [body](./kibana-plugin-server.routeschemas.body.md) - -## RouteSchemas.body property - -Signature: - -```typescript -body?: B; -``` diff --git a/docs/development/core/server/kibana-plugin-server.routeschemas.md b/docs/development/core/server/kibana-plugin-server.routeschemas.md deleted file mode 100644 index 77b980551a8ff..0000000000000 --- a/docs/development/core/server/kibana-plugin-server.routeschemas.md +++ /dev/null @@ -1,22 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteSchemas](./kibana-plugin-server.routeschemas.md) - -## RouteSchemas interface - -RouteSchemas contains the schemas for validating the different parts of a request. - -Signature: - -```typescript -export interface RouteSchemas

| Type> -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [body](./kibana-plugin-server.routeschemas.body.md) | B | | -| [params](./kibana-plugin-server.routeschemas.params.md) | P | | -| [query](./kibana-plugin-server.routeschemas.query.md) | Q | | - diff --git a/docs/development/core/server/kibana-plugin-server.routeschemas.params.md b/docs/development/core/server/kibana-plugin-server.routeschemas.params.md deleted file mode 100644 index 3dbf9fed94dc0..0000000000000 --- a/docs/development/core/server/kibana-plugin-server.routeschemas.params.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteSchemas](./kibana-plugin-server.routeschemas.md) > [params](./kibana-plugin-server.routeschemas.params.md) - -## RouteSchemas.params property - -Signature: - -```typescript -params?: P; -``` diff --git a/docs/development/core/server/kibana-plugin-server.routeschemas.query.md b/docs/development/core/server/kibana-plugin-server.routeschemas.query.md deleted file mode 100644 index 5be5830cb4bc8..0000000000000 --- a/docs/development/core/server/kibana-plugin-server.routeschemas.query.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteSchemas](./kibana-plugin-server.routeschemas.md) > [query](./kibana-plugin-server.routeschemas.query.md) - -## RouteSchemas.query property - -Signature: - -```typescript -query?: Q; -``` diff --git a/docs/development/core/server/kibana-plugin-server.routevalidationerror._constructor_.md b/docs/development/core/server/kibana-plugin-server.routevalidationerror._constructor_.md new file mode 100644 index 0000000000000..551e13faaf154 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.routevalidationerror._constructor_.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteValidationError](./kibana-plugin-server.routevalidationerror.md) > [(constructor)](./kibana-plugin-server.routevalidationerror._constructor_.md) + +## RouteValidationError.(constructor) + +Constructs a new instance of the `RouteValidationError` class + +Signature: + +```typescript +constructor(error: Error | string, path?: string[]); +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| error | Error | string | | +| path | string[] | | + diff --git a/docs/development/core/server/kibana-plugin-server.routevalidationerror.md b/docs/development/core/server/kibana-plugin-server.routevalidationerror.md new file mode 100644 index 0000000000000..71bd72dca2eab --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.routevalidationerror.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteValidationError](./kibana-plugin-server.routevalidationerror.md) + +## RouteValidationError class + +Error to return when the validation is not successful. + +Signature: + +```typescript +export declare class RouteValidationError extends SchemaTypeError +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(error, path)](./kibana-plugin-server.routevalidationerror._constructor_.md) | | Constructs a new instance of the RouteValidationError class | + diff --git a/docs/development/core/server/kibana-plugin-server.routevalidationfunction.md b/docs/development/core/server/kibana-plugin-server.routevalidationfunction.md new file mode 100644 index 0000000000000..34fa096aaae78 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.routevalidationfunction.md @@ -0,0 +1,42 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteValidationFunction](./kibana-plugin-server.routevalidationfunction.md) + +## RouteValidationFunction type + +The custom validation function if @kbn/config-schema is not a valid solution for your specific plugin requirements. + +Signature: + +```typescript +export declare type RouteValidationFunction = (data: any, validationResult: RouteValidationResultFactory) => { + value: T; + error?: never; +} | { + value?: never; + error: RouteValidationError; +}; +``` + +## Example + +The validation should look something like: + +```typescript +interface MyExpectedBody { + bar: string; + baz: number; +} + +const myBodyValidation: RouteValidationFunction = (data, validationResult) => { + const { ok, badRequest } = validationResult; + const { bar, baz } = data || {}; + if (typeof bar === 'string' && typeof baz === 'number') { + return ok({ bar, baz }); + } else { + return badRequest('Wrong payload', ['body']); + } +} + +``` + diff --git a/docs/development/core/server/kibana-plugin-server.routevalidationresultfactory.badrequest.md b/docs/development/core/server/kibana-plugin-server.routevalidationresultfactory.badrequest.md new file mode 100644 index 0000000000000..36ea6103fb352 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.routevalidationresultfactory.badrequest.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteValidationResultFactory](./kibana-plugin-server.routevalidationresultfactory.md) > [badRequest](./kibana-plugin-server.routevalidationresultfactory.badrequest.md) + +## RouteValidationResultFactory.badRequest property + +Signature: + +```typescript +badRequest: (error: Error | string, path?: string[]) => { + error: RouteValidationError; + }; +``` diff --git a/docs/development/core/server/kibana-plugin-server.routevalidationresultfactory.md b/docs/development/core/server/kibana-plugin-server.routevalidationresultfactory.md new file mode 100644 index 0000000000000..5f44b490e9a17 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.routevalidationresultfactory.md @@ -0,0 +1,23 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteValidationResultFactory](./kibana-plugin-server.routevalidationresultfactory.md) + +## RouteValidationResultFactory interface + +Validation result factory to be used in the custom validation function to return the valid data or validation errors + +See [RouteValidationFunction](./kibana-plugin-server.routevalidationfunction.md). + +Signature: + +```typescript +export interface RouteValidationResultFactory +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [badRequest](./kibana-plugin-server.routevalidationresultfactory.badrequest.md) | (error: Error | string, path?: string[]) => {
error: RouteValidationError;
} | | +| [ok](./kibana-plugin-server.routevalidationresultfactory.ok.md) | <T>(value: T) => {
value: T;
} | | + diff --git a/docs/development/core/server/kibana-plugin-server.routevalidationresultfactory.ok.md b/docs/development/core/server/kibana-plugin-server.routevalidationresultfactory.ok.md new file mode 100644 index 0000000000000..eca6a31bd547f --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.routevalidationresultfactory.ok.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteValidationResultFactory](./kibana-plugin-server.routevalidationresultfactory.md) > [ok](./kibana-plugin-server.routevalidationresultfactory.ok.md) + +## RouteValidationResultFactory.ok property + +Signature: + +```typescript +ok: (value: T) => { + value: T; + }; +``` diff --git a/docs/development/core/server/kibana-plugin-server.routevalidationspec.md b/docs/development/core/server/kibana-plugin-server.routevalidationspec.md new file mode 100644 index 0000000000000..f5fc06544043f --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.routevalidationspec.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteValidationSpec](./kibana-plugin-server.routevalidationspec.md) + +## RouteValidationSpec type + +Allowed property validation options: either @kbn/config-schema validations or custom validation functions + +See [RouteValidationFunction](./kibana-plugin-server.routevalidationfunction.md) for custom validation. + +Signature: + +```typescript +export declare type RouteValidationSpec = ObjectType | Type | RouteValidationFunction; +``` diff --git a/docs/development/core/server/kibana-plugin-server.routevalidatorconfig.body.md b/docs/development/core/server/kibana-plugin-server.routevalidatorconfig.body.md new file mode 100644 index 0000000000000..8b5d2c0413087 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.routevalidatorconfig.body.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteValidatorConfig](./kibana-plugin-server.routevalidatorconfig.md) > [body](./kibana-plugin-server.routevalidatorconfig.body.md) + +## RouteValidatorConfig.body property + +Validation logic for the body payload + +Signature: + +```typescript +body?: RouteValidationSpec; +``` diff --git a/docs/development/core/server/kibana-plugin-server.routevalidatorconfig.md b/docs/development/core/server/kibana-plugin-server.routevalidatorconfig.md new file mode 100644 index 0000000000000..4637da7741d80 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.routevalidatorconfig.md @@ -0,0 +1,22 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteValidatorConfig](./kibana-plugin-server.routevalidatorconfig.md) + +## RouteValidatorConfig interface + +The configuration object to the RouteValidator class. Set `params`, `query` and/or `body` to specify the validation logic to follow for that property. + +Signature: + +```typescript +export interface RouteValidatorConfig +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [body](./kibana-plugin-server.routevalidatorconfig.body.md) | RouteValidationSpec<B> | Validation logic for the body payload | +| [params](./kibana-plugin-server.routevalidatorconfig.params.md) | RouteValidationSpec<P> | Validation logic for the URL params | +| [query](./kibana-plugin-server.routevalidatorconfig.query.md) | RouteValidationSpec<Q> | Validation logic for the Query params | + diff --git a/docs/development/core/server/kibana-plugin-server.routevalidatorconfig.params.md b/docs/development/core/server/kibana-plugin-server.routevalidatorconfig.params.md new file mode 100644 index 0000000000000..11de25ff3b19f --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.routevalidatorconfig.params.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteValidatorConfig](./kibana-plugin-server.routevalidatorconfig.md) > [params](./kibana-plugin-server.routevalidatorconfig.params.md) + +## RouteValidatorConfig.params property + +Validation logic for the URL params + +Signature: + +```typescript +params?: RouteValidationSpec

; +``` diff --git a/docs/development/core/server/kibana-plugin-server.routevalidatorconfig.query.md b/docs/development/core/server/kibana-plugin-server.routevalidatorconfig.query.md new file mode 100644 index 0000000000000..510325c2dfff7 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.routevalidatorconfig.query.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteValidatorConfig](./kibana-plugin-server.routevalidatorconfig.md) > [query](./kibana-plugin-server.routevalidatorconfig.query.md) + +## RouteValidatorConfig.query property + +Validation logic for the Query params + +Signature: + +```typescript +query?: RouteValidationSpec; +``` diff --git a/docs/development/core/server/kibana-plugin-server.routevalidatorfullconfig.md b/docs/development/core/server/kibana-plugin-server.routevalidatorfullconfig.md new file mode 100644 index 0000000000000..0f3785b954a3a --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.routevalidatorfullconfig.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteValidatorFullConfig](./kibana-plugin-server.routevalidatorfullconfig.md) + +## RouteValidatorFullConfig type + +Route validations config and options merged into one object + +Signature: + +```typescript +export declare type RouteValidatorFullConfig = RouteValidatorConfig & RouteValidatorOptions; +``` diff --git a/docs/development/core/server/kibana-plugin-server.routevalidatoroptions.md b/docs/development/core/server/kibana-plugin-server.routevalidatoroptions.md new file mode 100644 index 0000000000000..00b029d9928e3 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.routevalidatoroptions.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteValidatorOptions](./kibana-plugin-server.routevalidatoroptions.md) + +## RouteValidatorOptions interface + +Additional options for the RouteValidator class to modify its default behaviour. + +Signature: + +```typescript +export interface RouteValidatorOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [unsafe](./kibana-plugin-server.routevalidatoroptions.unsafe.md) | {
params?: boolean;
query?: boolean;
body?: boolean;
} | Set the unsafe config to avoid running some additional internal \*safe\* validations on top of your custom validation | + diff --git a/docs/development/core/server/kibana-plugin-server.routevalidatoroptions.unsafe.md b/docs/development/core/server/kibana-plugin-server.routevalidatoroptions.unsafe.md new file mode 100644 index 0000000000000..0406a372c4e9d --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.routevalidatoroptions.unsafe.md @@ -0,0 +1,17 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteValidatorOptions](./kibana-plugin-server.routevalidatoroptions.md) > [unsafe](./kibana-plugin-server.routevalidatoroptions.unsafe.md) + +## RouteValidatorOptions.unsafe property + +Set the `unsafe` config to avoid running some additional internal \*safe\* validations on top of your custom validation + +Signature: + +```typescript +unsafe?: { + params?: boolean; + query?: boolean; + body?: boolean; + }; +``` diff --git a/docs/development/core/server/kibana-plugin-server.savedobjectsclient.md b/docs/development/core/server/kibana-plugin-server.savedobjectsclient.md index 17d29bb912c83..e68486ecff874 100644 --- a/docs/development/core/server/kibana-plugin-server.savedobjectsclient.md +++ b/docs/development/core/server/kibana-plugin-server.savedobjectsclient.md @@ -10,6 +10,10 @@ export declare class SavedObjectsClient ``` +## Remarks + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `SavedObjectsClient` class. + ## Properties | Property | Modifiers | Type | Description | @@ -30,7 +34,3 @@ export declare class SavedObjectsClient | [get(type, id, options)](./kibana-plugin-server.savedobjectsclient.get.md) | | Retrieves a single object | | [update(type, id, attributes, options)](./kibana-plugin-server.savedobjectsclient.update.md) | | Updates an SavedObject | -## Remarks - -The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `SavedObjectsClient` class. - diff --git a/docs/development/core/server/kibana-plugin-server.savedobjectsservicesetup.md b/docs/development/core/server/kibana-plugin-server.savedobjectsservicesetup.md index dd97b45f590e2..95bd817a43da6 100644 --- a/docs/development/core/server/kibana-plugin-server.savedobjectsservicesetup.md +++ b/docs/development/core/server/kibana-plugin-server.savedobjectsservicesetup.md @@ -12,15 +12,6 @@ Saved Objects is Kibana's data persisentence mechanism allowing plugins to use E export interface SavedObjectsServiceSetup ``` -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [addClientWrapper](./kibana-plugin-server.savedobjectsservicesetup.addclientwrapper.md) | (priority: number, id: string, factory: SavedObjectsClientWrapperFactory<KibanaRequest>) => void | Add a client wrapper with the given priority. | -| [createInternalRepository](./kibana-plugin-server.savedobjectsservicesetup.createinternalrepository.md) | (extraTypes?: string[]) => ISavedObjectsRepository | Creates a [Saved Objects repository](./kibana-plugin-server.isavedobjectsrepository.md) that uses the internal Kibana user for authenticating with Elasticsearch. | -| [createScopedRepository](./kibana-plugin-server.savedobjectsservicesetup.createscopedrepository.md) | (req: KibanaRequest, extraTypes?: string[]) => ISavedObjectsRepository | Creates a [Saved Objects repository](./kibana-plugin-server.isavedobjectsrepository.md) that uses the credentials from the passed in request to authenticate with Elasticsearch. | -| [setClientFactory](./kibana-plugin-server.savedobjectsservicesetup.setclientfactory.md) | (customClientFactory: SavedObjectsClientFactory<KibanaRequest>) => void | Set a default factory for creating Saved Objects clients. Only one client factory can be set, subsequent calls to this method will fail. | - ## Remarks Note: The Saved Object setup API's should only be used for creating and registering client wrappers. Constructing a Saved Objects client or repository for use within your own plugin won't have any of the registered wrappers applied and is considered an anti-pattern. Use the Saved Objects client from the [SavedObjectsServiceStart\#getScopedClient](./kibana-plugin-server.savedobjectsservicestart.md) method or the [route handler context](./kibana-plugin-server.requesthandlercontext.md) instead. @@ -33,3 +24,12 @@ import {SavedObjectsClient, CoreSetup} from 'src/core/server'; export class Plugin() { setup: (core: CoreSetup) => { core.savedObjects.setClientFactory(({request: KibanaRequest}) => { return new SavedObjectsClient(core.savedObjects.scopedRepository(request)); }) } } +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [addClientWrapper](./kibana-plugin-server.savedobjectsservicesetup.addclientwrapper.md) | (priority: number, id: string, factory: SavedObjectsClientWrapperFactory<KibanaRequest>) => void | Add a client wrapper with the given priority. | +| [createInternalRepository](./kibana-plugin-server.savedobjectsservicesetup.createinternalrepository.md) | (extraTypes?: string[]) => ISavedObjectsRepository | Creates a [Saved Objects repository](./kibana-plugin-server.isavedobjectsrepository.md) that uses the internal Kibana user for authenticating with Elasticsearch. | +| [createScopedRepository](./kibana-plugin-server.savedobjectsservicesetup.createscopedrepository.md) | (req: KibanaRequest, extraTypes?: string[]) => ISavedObjectsRepository | Creates a [Saved Objects repository](./kibana-plugin-server.isavedobjectsrepository.md) that uses the credentials from the passed in request to authenticate with Elasticsearch. | +| [setClientFactory](./kibana-plugin-server.savedobjectsservicesetup.setclientfactory.md) | (customClientFactory: SavedObjectsClientFactory<KibanaRequest>) => void | Set a default factory for creating Saved Objects clients. Only one client factory can be set, subsequent calls to this method will fail. | + diff --git a/docs/development/core/server/kibana-plugin-server.scopeablerequest.md b/docs/development/core/server/kibana-plugin-server.scopeablerequest.md new file mode 100644 index 0000000000000..5a9443376996d --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.scopeablerequest.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [ScopeableRequest](./kibana-plugin-server.scopeablerequest.md) + +## ScopeableRequest type + +A user credentials container. It accommodates the necessary auth credentials to impersonate the current user. + +See [KibanaRequest](./kibana-plugin-server.kibanarequest.md). + +Signature: + +```typescript +export declare type ScopeableRequest = KibanaRequest | LegacyRequest | FakeRequest; +``` diff --git a/docs/development/core/server/kibana-plugin-server.uisettingsservicesetup.register.md b/docs/development/core/server/kibana-plugin-server.uisettingsservicesetup.register.md index 8091a7cec44aa..0047b5275408e 100644 --- a/docs/development/core/server/kibana-plugin-server.uisettingsservicesetup.register.md +++ b/docs/development/core/server/kibana-plugin-server.uisettingsservicesetup.register.md @@ -24,5 +24,17 @@ register(settings: Record): void; ## Example -setup(core: CoreSetup){ core.uiSettings.register(\[{ foo: { name: i18n.translate('my foo settings'), value: true, description: 'add some awesomeness', }, }\]); } + +```ts +setup(core: CoreSetup){ + core.uiSettings.register([{ + foo: { + name: i18n.translate('my foo settings'), + value: true, + description: 'add some awesomeness', + }, + }]); +} + +``` diff --git a/docs/development/core/server/kibana-plugin-server.uisettingsservicestart.asscopedtoclient.md b/docs/development/core/server/kibana-plugin-server.uisettingsservicestart.asscopedtoclient.md new file mode 100644 index 0000000000000..072dd39faa084 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.uisettingsservicestart.asscopedtoclient.md @@ -0,0 +1,37 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [UiSettingsServiceStart](./kibana-plugin-server.uisettingsservicestart.md) > [asScopedToClient](./kibana-plugin-server.uisettingsservicestart.asscopedtoclient.md) + +## UiSettingsServiceStart.asScopedToClient() method + +Creates a [IUiSettingsClient](./kibana-plugin-server.iuisettingsclient.md) with provided \*scoped\* saved objects client. + +This should only be used in the specific case where the client needs to be accessed from outside of the scope of a [RequestHandler](./kibana-plugin-server.requesthandler.md). + +Signature: + +```typescript +asScopedToClient(savedObjectsClient: SavedObjectsClientContract): IUiSettingsClient; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| savedObjectsClient | SavedObjectsClientContract | | + +Returns: + +`IUiSettingsClient` + +## Example + + +```ts +start(core: CoreStart) { + const soClient = core.savedObjects.getScopedClient(arbitraryRequest); + const uiSettingsClient = core.uiSettings.asScopedToClient(soClient); +} + +``` + diff --git a/docs/development/core/server/kibana-plugin-server.uisettingsservicestart.md b/docs/development/core/server/kibana-plugin-server.uisettingsservicestart.md new file mode 100644 index 0000000000000..ee3563552275a --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.uisettingsservicestart.md @@ -0,0 +1,19 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [UiSettingsServiceStart](./kibana-plugin-server.uisettingsservicestart.md) + +## UiSettingsServiceStart interface + + +Signature: + +```typescript +export interface UiSettingsServiceStart +``` + +## Methods + +| Method | Description | +| --- | --- | +| [asScopedToClient(savedObjectsClient)](./kibana-plugin-server.uisettingsservicestart.asscopedtoclient.md) | Creates a [IUiSettingsClient](./kibana-plugin-server.iuisettingsclient.md) with provided \*scoped\* saved objects client.This should only be used in the specific case where the client needs to be accessed from outside of the scope of a [RequestHandler](./kibana-plugin-server.requesthandler.md). | + diff --git a/docs/development/core/server/kibana-plugin-server.uuidservicesetup.getinstanceuuid.md b/docs/development/core/server/kibana-plugin-server.uuidservicesetup.getinstanceuuid.md new file mode 100644 index 0000000000000..e0b7012bea4aa --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.uuidservicesetup.getinstanceuuid.md @@ -0,0 +1,17 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [UuidServiceSetup](./kibana-plugin-server.uuidservicesetup.md) > [getInstanceUuid](./kibana-plugin-server.uuidservicesetup.getinstanceuuid.md) + +## UuidServiceSetup.getInstanceUuid() method + +Retrieve the Kibana instance uuid. + +Signature: + +```typescript +getInstanceUuid(): string; +``` +Returns: + +`string` + diff --git a/docs/development/core/server/kibana-plugin-server.uuidservicesetup.md b/docs/development/core/server/kibana-plugin-server.uuidservicesetup.md new file mode 100644 index 0000000000000..f2a6cfdeac704 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.uuidservicesetup.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [UuidServiceSetup](./kibana-plugin-server.uuidservicesetup.md) + +## UuidServiceSetup interface + +APIs to access the application's instance uuid. + +Signature: + +```typescript +export interface UuidServiceSetup +``` + +## Methods + +| Method | Description | +| --- | --- | +| [getInstanceUuid()](./kibana-plugin-server.uuidservicesetup.getinstanceuuid.md) | Retrieve the Kibana instance uuid. | + diff --git a/docs/discover/context.asciidoc b/docs/discover/context.asciidoc index 9049109d6124d..c402a734a16fa 100644 --- a/docs/discover/context.asciidoc +++ b/docs/discover/context.asciidoc @@ -1,90 +1,66 @@ [[document-context]] -== Viewing Document Context +== Viewing a document in context -For certain applications it can be useful to inspect a window of documents -surrounding a specific event. The context view enables you to do just that for -<> that are configured to contain time-based events. +Once you've narrowed your search to a specific event, +you might want to inspect the documents that occurred +immediately before and after the event. With the Context view, +you can do just that for index patterns that contain time-based events. -To show the context surrounding an anchor document, click the *Expand* button -image:images/ExpandButton.jpg[Expand Button] to the left of the document's -table entry and then click the *View surrounding documents* link. +To open the Context view, click the expand icon (<) in the document table, and then click +*View surrounding documents.* -image::images/Expanded-Document.png[Expanded Document] -{nbsp} +The documents are sorted +by the time field specified in the index pattern and displayed using the +same set of columns as the *Discover* view from which the context was opened. +The anchor document is highlighted in blue. -The context view displays a number of documents before and after the anchor -document. The anchor document itself is highlighted in blue. The view is sorted -by the time field specified in the index pattern configuration and uses the -same set of columns as the Discover view the context was opened from. If there -are multiple documents with the same time field value, the internal document -order is used as a secondary sorting criterion by default. - -[NOTE] --- -The field used for tiebreaking in case of equal time field values can be -configured using the advanced setting `context:tieBreakerFields` in -< Advanced Settings*>>, which defaults to the -`_doc` field. The value of this setting can be a comma-separated list of field -names, which will be checked in sequence for suitability when a context is -about to be displayed. The first suitable field is then used as the tiebreaking -field. A field is suitable if the field exists and is sortable in the index -pattern the context is based on. - -While not required, it is recommended to only -use fields which have {ref}/doc-values.html[doc values] enabled to achieve -good performance and avoid unnecessary {ref}/modules-fielddata.html[field -data] usage. Common examples for suitable fields include log line numbers, -monotonically increasing counters and high-precision timestamps. --- +[role="screenshot"] image::images/Discover-ContextView.png[Context View] -NOTE: The number of documents displayed by default can be configured -via the `context:defaultSize` setting in < -Advanced Settings*>>. - [float] -[[change-context-size]] -=== Changing the Context Size - -You can change the number documents displayed before and after the anchor -document independently. - -To increase the number of displayed documents that are newer than the anchor -document, click the *Load 5 more* button above the document list or enter the -desired number into the input box right of the button. - -image::images/Discover-ContextView-SizePicker-Newer.png[] -{nbsp} - -To increase the number of displayed documents that are older than the anchor -document, click the *Load 5 more* button below the document list or enter the -desired number into the input box right of the button. +[[filter-context]] +=== Filter the context -image::images/Discover-ContextView-SizePicker-Older.png[] -{nbsp} +The +filters you applied in *Discover* are carried over to the Context view. Pinned filters remain active, while normal +filters are copied in a disabled state. You can re-enable these filters to +refine your context view. -NOTE: The default number of documents loaded with each button click can be -configured via the `context:step` setting in < -Advanced Settings*>>. +If the Context view contains a large number of documents not related to the event under +investigation, you can use filters to restrict the documents to +display. [float] -[[filter-context]] -=== Filtering the Context - -Depending on how the documents are partitioned into index patterns, the context -view might contain a large number of documents not related to the event under -investigation. In order to adapt the focus of the context view to the task at -hand, you can use filters to restrict the documents considered by Kibana for -display in the context view. - -When switching from the discover view to the context view, the previously -applied filters are carried over. Pinned filters remain active while normal -filters are copied in a disabled state. You can selectively re-enabled them to -refine your context view. +[[change-context-size]] +=== Change the number of surrounding documents -New filters can be added via the *Add a filter* link in the filter bar, by -clicking the filter icons appearing when hovering a field, or by expanding -documents and clicking the filter icons in the table. +By default, the five newest and oldest +documents are listed. To increase the number of documents that surround the anchor document, +click *Load*. Five documents are added with each click. -image::images/Discover-ContextView-FilterMontage.png[] +[float] +[[configure-context-ContextView]] +=== Configure the context view + +To configure the Context view, use these settings in <>. + +[horizontal] +`context:defaultSize`:: The number of documents to display by default. +`context:step`:: The default number of documents to load with each button click. +`context:tieBreakerFields`:: The field to use for tiebreaking in case of equal time field values. +The default is the +`_doc` field. ++ +You can enter a comma-separated list of field +names, which is checked in sequence for suitability when a context is +displayed. The first suitable field is used as the tiebreaking +field. A field is suitable if the field exists and is sortable in the index +pattern the context is based on. ++ +Although not required, it is recommended to only +use fields that have {ref}/doc-values.html[doc values] enabled to achieve +good performance and avoid unnecessary {ref}/modules-fielddata.html[field +data] usage. Common examples for suitable fields include log line numbers, +monotonically increasing counters and high-precision timestamps. diff --git a/docs/discover/document-data.asciidoc b/docs/discover/document-data.asciidoc index dc6a45dc5ad7e..b45a31065aa9a 100644 --- a/docs/discover/document-data.asciidoc +++ b/docs/discover/document-data.asciidoc @@ -1,69 +1,55 @@ [[document-data]] -== Viewing Document Data +== Viewing document data -When you submit a search query, the 500 most recent documents that match the query -are listed in the Documents table. You can configure the number of documents shown -in the table by setting the `discover:sampleSize` property in <>. By default, the table shows the localized version of the time -field configured for the selected <> and the document `_source`. You can -<> from the Fields list. -You can <> by any indexed field that's included -in the table. - -To view a document's field data, click the *Expand* button -image:images/ExpandButton.jpg[Expand Button] to the left of the document's table -entry. - -image::images/Expanded-Document.png[] - -To view the original JSON document (pretty-printed), click the *JSON* tab. - -To view the document data as a separate page, click the *View single document* -link. You can bookmark and share this link to provide direct access to a -particular document. - -To display or hide a field's column in the Documents table, click the -image:images/add-column-button.png[Add Column] *Toggle column in table* button. - -To collapse the document details, click the *Collapse* button -image:images/CollapseButton.jpg[Collapse Button]. +When you submit a search query in *Discover*, the most recent documents that match the query +are listed in the documents table. +By default, the table includes columns for +the time field and the document `_source`, which shows all fields and values in the document. [float] [[sorting]] -=== Sorting the Document List -You can sort the documents in the Documents table by the values in any indexed -field. If a time field is configured for the current index pattern, the -documents are sorted in reverse chronological order by default. - -To change the sort order, hover over the name of the field you want to sort by -and click the sort button. Click again to reverse the sort order. +=== Modify the document table + +Use the following commands to +tailor the documents table to suit your needs. + +[horizontal] +Add a field column:: +Hover over the list of *Available fields* and then click *add* next to each field you want include as a column in the table. +The first field you add replaces the `_source` column. +Change sort order:: By default, columns are sorted by the values in the field. +If a time field is configured for the current index pattern, +the documents are sorted in reverse chronological order. ++ +To change the sort order, hover over the column +and click image:images/sort-icon.png[]. +The first click sorts by ascending order, the second click sorts by descending order, and the third +click removes the field from the sorted fields. + +Move a field column:: Hover over the column header and click the move left (<<) or move right icon (>>). +Remove a field column :: Hover over the list of *Specified fields* +and then click *remove*. +Or, use the (x) control in the column header. [float] -[[adding-columns]] -=== Adding Field Columns to the Documents Table -By default, the Documents table shows the localized version of the time field -that's configured for the selected index pattern and the document `_source`. -You can add fields to the table from the Fields list or from a document's -field data. - -To add a field column from the Fields list, hover over the field and click its -*add* button. +=== Drill down into field-level details +To view the document data in either table or JSON format, click the expand icon (>). +The expanded view provides these options for viewing your document: -To add a field column from a document's field data, expand the document -and click the field's -image:images/add-column-button.png[Add Column] *Toggle column in table* button. +* View the events that surround your document. +For example, you might want to see the 10 documents that occurred +immediately before and after your event. -Added field columns replace the `_source` column in the Documents table. The added -fields are also added to the *Selected Fields* list. +* View the document data as a separate page. You can bookmark and +share the link for direct access to a particular document. -To rearrange the field columns, hover over the header of the column you want to move -and click the *Move left* or *Move right* button. +[role="screenshot"] +image::images/Expanded-Document.png[] -image:images/Discover-MoveColumn.jpg[Move Column] [float] -[[removing-columns]] -=== Removing Field Columns from the Documents Table -To remove a field column from the Documents table, hover over the header of the -column you want to remove and click the *Remove* button -image:images/RemoveFieldButton.jpg[Remove Field Button]. \ No newline at end of file +=== Configure the number of documents to show + +By default, the documents table includes the 500 most recent documents that +match the query. To change this number, set the `discover:sampleSize` property in <>. diff --git a/docs/discover/field-filter.asciidoc b/docs/discover/field-filter.asciidoc index 5646fe079401e..49bb6078cdc58 100644 --- a/docs/discover/field-filter.asciidoc +++ b/docs/discover/field-filter.asciidoc @@ -1,127 +1,132 @@ [[field-filter]] -== Filtering by Field -You can filter the search results to display only those documents that contain -a particular value in a field. You can also create negative filters that -exclude documents that contain the specified field value. +== Filtering by field -You add field filters from the Fields list, the Documents table, or by manually -adding a filter. In addition to creating positive and negative filters, the -Documents table enables you to filter on whether or not a field is present. The -applied filters are shown below the Query bar. Negative filters are shown in red. +*Discover* offers +various types of filters, so you can restrict your documents to the exact data you want. +For example, you might look at the results for a +particular period of time. Or, you might include—or exclude— +all HTTP redirects that come from a specific IP and port. -To add a filter from the Fields list: +[float] +=== Add a filter + +A quick way to add a filter is from the fields list. -. Click the name of the field you want to filter on. This displays the top -five values for that field. +. Click the field to filter on. ++ +You'll see the number of documents that contain +the field, the top 5 values for the field, and the percentage of documents +that contain each value. + [role="screenshot"] image::images/filter-field.png[height=317] -. To add a positive filter, click the *Positive Filter* button -image:images/PositiveFilter.jpg[Positive Filter]. -This includes only those documents that contain that value in the field. -. To add a negative filter, click the *Negative Filter* button -image:images/NegativeFilter.jpg[Negative Filter]. -This excludes documents that contain that value in the field. - -To add a filter from the Documents table: - -. Expand a document in the Documents table by clicking the *Expand* button -image:images/ExpandButton.jpg[Expand Button] to the left of the document's -table entry. + +. Use the image:images/PositiveFilter.jpg[Positive Filter] icon to +show only documents that contain that value, +or image:images/NegativeFilter.jpg[Negative Filter] to exclude all documents with that value. + -image::images/Expanded-Document.png[] -. To add a positive filter, click the *Positive Filter* button -image:images/PositiveFilter.jpg[Positive Filter Button] to the right of the -field name. This includes only those documents that contain that value in the -field. -. To add a negative filter, click the *Negative Filter* button -image:images/NegativeFilter.jpg[Negative Filter Button] to the right of the -field name. This excludes documents that contain that value in the field. -. To filter on whether or not documents contain the field, click the -*Exists* button image:images/ExistsButton.jpg[Exists Button] to the right of the -field name. This includes only those documents that contain the field. - -To manually add a filter: - -. Click *Add Filter*. A popup will be displayed for you to create the filter. - -. Choose a field to filter by. This list of fields will include fields from the -index pattern you are currently querying against. +If there is no data to display, you might need to set a <>. +You can choose a time from the quick filter or choose your +own using absolute or relative times. + +. Try also these filtering options: ++ +* To limit the field +list to a particular data type, click *Filter by type*. +You can also filter for whether that type is +aggregatable or searchable. + -image::images/add_filter_field.png[] -. Choose an operation for your filter. +* To filter for whether a field is present, expand the document in +the document table, hover over the field, and click the *Filter for field present* icon. + +[float] +=== Filter by condition + +You can filter using advanced criteria, +such as if a value is equal to or in between certain values. + +. Click *Add Filter*. + +. Select a field. + +. Select an operation for your filter: + -image::images/add_filter_operator.png[] -The following operators can be selected: [horizontal] -`is`:: Filter where the value for the field matches the given value. -`is not`:: Filter where the value for the field does not match the given value. -`is one of`:: Filter where the value for the field matches one of the specified values. -`is not one of`:: Filter where the value for the field does not match any of the specified values. -`is between`:: Filter where the value for the field is in the given range. -`is not between`:: Filter where the value for the field is not in the given range. -`exists`:: Filter where any value is present for the field. -`does not exist`:: Filter where no value is present for the field. -. Choose the value(s) for your filter. Values from your indices may be suggested -as selections if you are filtering against an aggregatable field. +`is`:: The value for the field matches the given value. +`is not`:: The value for the field does not match the given value. +`is one of`:: The field matches one of the specified values. +`is not one of`:: The value for the field does not match any of the specified values. +`is between`:: The value for the field is in the given range. +`is not between`:: The value for the field is not in the given range. +`exists`:: Any value is present for the field. +`does not exist`:: No value is present for the field. +. Choose values for your filter. + -image::images/add_filter_value.png[] -. (Optional) Specify a label for the filter. If you specify a label, it will be -displayed below the query bar instead of the filter definition. -. Click *Save*. The filter will be applied to your search and be displayed below -the query bar. +Values from your indices may be suggested +as selections if you are filtering against an aggregatable field. +. (Optional) Specify a label for the filter. + +. Click *Save* to apply the filter to your search. ++ NOTE: If you are experiencing long-running queries as a result of the value suggestions, you can -turn off the suggestions by setting the advanced setting, `filterEditor:suggestValues`, to `false`. +turn off the suggestions by setting `filterEditor:suggestValues` to `false` +in <>. [float] [[filter-pinning]] -=== Managing Filters +=== Edit, disable, and delete filters + +To modify a filter, click its tag, and then select one of the following actions. + +*Pin across all apps*:: +Persist the filter +when you switch contexts in Kibana. For example, you can pin a filter +in *Discover* and it remains in place when you switch to *Visualize*. +A filter is based on a particular index field—if the indices being +searched do not contain the field in a pinned filter, it has no effect. -To modify a filter, click on it and click one of the action buttons. +*Edit filter*:: +Edit the +filter definition and label. -image::images/filter-allbuttons.png[] +*Exclude results*:: +Switch from a positive +filter to a negative filter, and vice versa. -  +*Temporarily disable*:: +Disable the filter without +removing it. Click again to reenable the filter. + +*Delete*:: +Delete the filter. + +To apply an action to all filters, +click the *Actions* icon, and then select the action. -Pin across all apps :: Pinned filters -persist when you switch contexts in Kibana. For example, you can pin a filter -in Discover and it remains in place when you switch to Visualize. -Note that a filter is based on a particular index field--if the indices being -searched don't contain the field in a pinned filter, it has no effect. -Edit Filter :: <> definition. Enables you to manually update the filter and -specify a label for the filter. -Exclude results :: Switch from a positive -filter to a negative filter and vice-versa. -Temporarily disable :: Disable the filter without -removing it. Click again to reenable the filter. Diagonal stripes indicate -that a filter is disabled. -Remove Filter :: Remove the filter. -To apply a filter action to all of the applied filters, -click *Actions* and select the action. [float] [[filter-edit]] -=== Editing a Filter -You can edit a filter by changing the field, operator, or value associated -with the filter (see the Add Filter section above), or by directly modifying -the filter query that is performed to filter your search results. This -enables you to create more complex filters that are based on multiple fields. - -. To edit the filter query, first click the edit button for the filter, then -click *Edit Query DSL*. -+ -image::images/edit_filter_query.png[] -. You can then edit the query for the filter. -+ -image::images/edit_filter_query_json.png[] +=== Modify the filter query -For example, you could use a -{ref}/query-dsl-bool-query.html[bool query] to create a filter for the -sample log data that displays the hits that originated from Canada or China that resulted in a 404 error: +You can directly modify +the query that filters your search results. This enables you +to create more complex filters using multiple fields. +. Click the filter tag, and then select *Edit > Edit Query DSL*. + +. Edit the query for the filter. ++ +//// +image::images/edit_filter_query_json.png[] ++ +//// +For example, if you are using the sample log data, you can use the +{ref}/query-dsl-bool-query.html[bool query] to create a filter +that displays the hits that originated from Canada or China that resulted in a 404 error: ++ ========== [source,json] { diff --git a/docs/discover/images/move-icon.png b/docs/discover/images/move-icon.png new file mode 100644 index 0000000000000..3fa1f9e2f1a59 Binary files /dev/null and b/docs/discover/images/move-icon.png differ diff --git a/docs/discover/images/sort-icon.png b/docs/discover/images/sort-icon.png new file mode 100644 index 0000000000000..7dd3719ec361b Binary files /dev/null and b/docs/discover/images/sort-icon.png differ diff --git a/docs/discover/viewing-field-stats.asciidoc b/docs/discover/viewing-field-stats.asciidoc index 96a26c78596e2..3631aba73fb20 100644 --- a/docs/discover/viewing-field-stats.asciidoc +++ b/docs/discover/viewing-field-stats.asciidoc @@ -1,14 +1,14 @@ [[viewing-field-stats]] == Viewing Field Data Statistics -From the Fields list, you can see how many of the documents in the Documents +From the fields list, you can see how many of the documents in the documents table contain a particular field, what the top 5 values are, and what percentage of documents contain each value. -Data can be visualized in various ways. The quick visualize can only be -applied to aggregatable fields. The keyword fields can be visualized and -they are available in the side bar if we uncheck "Hide missing fields". +You can visualize data in various ways. You can only apply the quick visualize +to aggregatable fields. You can visualize the keyword fields, and +they are available in the side bar if you uncheck "Hide missing fields". -To view field data statistics, click the name of a field in the Fields list. +To view field data statistics, click the name of a field in the fields list. -image:images/filter-field.png[Field Statistics,height=317] \ No newline at end of file +image:images/filter-field.png[Field Statistics,height=317] diff --git a/docs/images/Discover-ContextView-SizePicker-Newer.png b/docs/images/Discover-ContextView-SizePicker-Newer.png deleted file mode 100644 index 852cb22c1f27c..0000000000000 Binary files a/docs/images/Discover-ContextView-SizePicker-Newer.png and /dev/null differ diff --git a/docs/images/Discover-ContextView-SizePicker-Older.png b/docs/images/Discover-ContextView-SizePicker-Older.png deleted file mode 100644 index 38cd9acd1bee0..0000000000000 Binary files a/docs/images/Discover-ContextView-SizePicker-Older.png and /dev/null differ diff --git a/docs/images/Discover-ContextView.png b/docs/images/Discover-ContextView.png index 11d4a59c26e55..5c2de602f6b41 100644 Binary files a/docs/images/Discover-ContextView.png and b/docs/images/Discover-ContextView.png differ diff --git a/docs/images/Discover-Start.png b/docs/images/Discover-Start.png index 680aa3767bdf0..27e7a2c728597 100644 Binary files a/docs/images/Discover-Start.png and b/docs/images/Discover-Start.png differ diff --git a/docs/images/Expanded-Document.png b/docs/images/Expanded-Document.png index ad2f0db1a7ff9..4fa255e79a8ad 100644 Binary files a/docs/images/Expanded-Document.png and b/docs/images/Expanded-Document.png differ diff --git a/docs/images/canvas-add-pages.gif b/docs/images/canvas-add-pages.gif index 5f977c6afb10f..a1fa228645836 100644 Binary files a/docs/images/canvas-add-pages.gif and b/docs/images/canvas-add-pages.gif differ diff --git a/docs/images/canvas-align-elements.gif b/docs/images/canvas-align-elements.gif index d2e2cda475757..0081308d68795 100644 Binary files a/docs/images/canvas-align-elements.gif and b/docs/images/canvas-align-elements.gif differ diff --git a/docs/images/canvas-background-color-picker-min.gif b/docs/images/canvas-background-color-picker-min.gif deleted file mode 100644 index bd22941b35f5d..0000000000000 Binary files a/docs/images/canvas-background-color-picker-min.gif and /dev/null differ diff --git a/docs/images/canvas-background-color-picker.gif b/docs/images/canvas-background-color-picker.gif index 37d43d987f5c4..bd22941b35f5d 100644 Binary files a/docs/images/canvas-background-color-picker.gif and b/docs/images/canvas-background-color-picker.gif differ diff --git a/docs/images/canvas-change-your-expression-chart-no-legend.png b/docs/images/canvas-change-your-expression-chart-no-legend.png new file mode 100644 index 0000000000000..f54437c1eba3c Binary files /dev/null and b/docs/images/canvas-change-your-expression-chart-no-legend.png differ diff --git a/docs/images/canvas-change-your-expression-chart.png b/docs/images/canvas-change-your-expression-chart.png new file mode 100755 index 0000000000000..4400ce4dfb2c3 Binary files /dev/null and b/docs/images/canvas-change-your-expression-chart.png differ diff --git a/docs/images/canvas-create-URL-min.gif b/docs/images/canvas-create-URL-min.gif deleted file mode 100644 index 0c9fbf7201d80..0000000000000 Binary files a/docs/images/canvas-create-URL-min.gif and /dev/null differ diff --git a/docs/images/canvas-create-URL.gif b/docs/images/canvas-create-URL.gif index c7dfab28c681e..0c9fbf7201d80 100644 Binary files a/docs/images/canvas-create-URL.gif and b/docs/images/canvas-create-URL.gif differ diff --git a/docs/images/canvas-distribute-elements.gif b/docs/images/canvas-distribute-elements.gif index 2d7eca338d275..685d76ba22e40 100644 Binary files a/docs/images/canvas-distribute-elements.gif and b/docs/images/canvas-distribute-elements.gif differ diff --git a/docs/images/canvas-element-select.gif b/docs/images/canvas-element-select.gif index 9ead1c3243ee1..bd0e49377262e 100644 Binary files a/docs/images/canvas-element-select.gif and b/docs/images/canvas-element-select.gif differ diff --git a/docs/images/canvas-embed_workpad-min.gif b/docs/images/canvas-embed_workpad-min.gif deleted file mode 100644 index 293792c7fbcf2..0000000000000 Binary files a/docs/images/canvas-embed_workpad-min.gif and /dev/null differ diff --git a/docs/images/canvas-embed_workpad.gif b/docs/images/canvas-embed_workpad.gif index 0ffbdeab2862d..97a79d775fe36 100644 Binary files a/docs/images/canvas-embed_workpad.gif and b/docs/images/canvas-embed_workpad.gif differ diff --git a/docs/images/canvas-functions-can-take-arguments-donut-chart.png b/docs/images/canvas-functions-can-take-arguments-donut-chart.png new file mode 100644 index 0000000000000..d126830c4fdc9 Binary files /dev/null and b/docs/images/canvas-functions-can-take-arguments-donut-chart.png differ diff --git a/docs/images/canvas-functions-can-take-arguments-pie-chart.png b/docs/images/canvas-functions-can-take-arguments-pie-chart.png new file mode 100644 index 0000000000000..be923675bea80 Binary files /dev/null and b/docs/images/canvas-functions-can-take-arguments-pie-chart.png differ diff --git a/docs/images/canvas-generate-pdf-min.gif b/docs/images/canvas-generate-pdf-min.gif deleted file mode 100644 index 9ef16dc1e5017..0000000000000 Binary files a/docs/images/canvas-generate-pdf-min.gif and /dev/null differ diff --git a/docs/images/canvas-generate-pdf.gif b/docs/images/canvas-generate-pdf.gif index a51e04cb623a6..9ef16dc1e5017 100644 Binary files a/docs/images/canvas-generate-pdf.gif and b/docs/images/canvas-generate-pdf.gif differ diff --git a/docs/images/canvas_share_autoplay_480-min.gif b/docs/images/canvas_share_autoplay_480-min.gif deleted file mode 100644 index 84a108e58d3dc..0000000000000 Binary files a/docs/images/canvas_share_autoplay_480-min.gif and /dev/null differ diff --git a/docs/images/canvas_share_autoplay_480.gif b/docs/images/canvas_share_autoplay_480.gif index da6d8c74dd5ca..84a108e58d3dc 100644 Binary files a/docs/images/canvas_share_autoplay_480.gif and b/docs/images/canvas_share_autoplay_480.gif differ diff --git a/docs/images/canvas_share_hidetoolbar_480-min.gif b/docs/images/canvas_share_hidetoolbar_480-min.gif deleted file mode 100644 index 4706db48967b5..0000000000000 Binary files a/docs/images/canvas_share_hidetoolbar_480-min.gif and /dev/null differ diff --git a/docs/images/canvas_share_hidetoolbar_480.gif b/docs/images/canvas_share_hidetoolbar_480.gif index 6206714aa2804..282783057776a 100644 Binary files a/docs/images/canvas_share_hidetoolbar_480.gif and b/docs/images/canvas_share_hidetoolbar_480.gif differ diff --git a/docs/images/lens_data_info-min.gif b/docs/images/lens_data_info-min.gif deleted file mode 100644 index 39f9f668df4cd..0000000000000 Binary files a/docs/images/lens_data_info-min.gif and /dev/null differ diff --git a/docs/images/lens_data_info.gif b/docs/images/lens_data_info.gif deleted file mode 100644 index e2c565de9f6a7..0000000000000 Binary files a/docs/images/lens_data_info.gif and /dev/null differ diff --git a/docs/images/lens_data_info.png b/docs/images/lens_data_info.png new file mode 100644 index 0000000000000..3ceb7e5e990f7 Binary files /dev/null and b/docs/images/lens_data_info.png differ diff --git a/docs/images/lens_drag_drop-min.gif b/docs/images/lens_drag_drop-min.gif deleted file mode 100644 index 7219742114190..0000000000000 Binary files a/docs/images/lens_drag_drop-min.gif and /dev/null differ diff --git a/docs/images/lens_drag_drop.gif b/docs/images/lens_drag_drop.gif index 39cde64fb97eb..2a759abf03020 100644 Binary files a/docs/images/lens_drag_drop.gif and b/docs/images/lens_drag_drop.gif differ diff --git a/docs/images/lens_suggestions-min.gif b/docs/images/lens_suggestions-min.gif deleted file mode 100644 index de1d5b7096864..0000000000000 Binary files a/docs/images/lens_suggestions-min.gif and /dev/null differ diff --git a/docs/images/lens_suggestions.gif b/docs/images/lens_suggestions.gif index 0452207b86456..ad93a9d87d548 100644 Binary files a/docs/images/lens_suggestions.gif and b/docs/images/lens_suggestions.gif differ diff --git a/docs/images/time_range_per_panel-min.gif b/docs/images/time_range_per_panel-min.gif deleted file mode 100644 index 04d2e2f17b4f4..0000000000000 Binary files a/docs/images/time_range_per_panel-min.gif and /dev/null differ diff --git a/docs/images/time_range_per_panel.gif b/docs/images/time_range_per_panel.gif index aab8f68a0b50f..04d2e2f17b4f4 100644 Binary files a/docs/images/time_range_per_panel.gif and b/docs/images/time_range_per_panel.gif differ diff --git a/docs/limitations.asciidoc b/docs/limitations.asciidoc index 0b26a3cdcf71a..818cc766bf6a9 100644 --- a/docs/limitations.asciidoc +++ b/docs/limitations.asciidoc @@ -12,11 +12,11 @@ These {stack} features also have limitations that affect {kib}: * {ref}/watcher-limitations.html[Alerting] -* {stack-ov}/ml-limitations.html[Machine learning] +* {ml-docs}/ml-limitations.html[Machine learning] * {ref}/security-limitations.html[Security] -- include::limitations/nested-objects.asciidoc[] -include::limitations/export-data.asciidoc[] +include::limitations/export-data.asciidoc[] \ No newline at end of file diff --git a/docs/management/index-patterns.asciidoc b/docs/management/index-patterns.asciidoc index 8d9ef515108ed..8e687f641c92b 100644 --- a/docs/management/index-patterns.asciidoc +++ b/docs/management/index-patterns.asciidoc @@ -1,17 +1,22 @@ [[index-patterns]] -== Index patterns +== Creating an index pattern -To visualize and explore data in {kib}, you must create an index pattern. -An index pattern tells {kib} which {es} indices contain the data that you want to work with. -An index pattern can match a single index, multiple indices, and a rollup index. +To explore and visualize data in {kib}, you must create an index pattern. +An index pattern tells {kib} which {es} indices contain the data that +you want to work with. +Once you create an index pattern, you're ready to: + +* Interactively explore your data in <>. +* Analyze your data in charts, tables, gauges, tag clouds, and more in <>. +* Show off your data in a <> workpad. +* If your data includes geo data, visualize it with <>. [float] [[index-patterns-read-only-access]] === [xpack]#Read-only access# -If you have insufficient privileges to create or save index patterns, a read-only +If you have insufficient privileges to create or save index patterns, a read-only indicator appears in Kibana. The buttons to create new index patterns or save -existing index patterns are not visible. For more information on granting access to -Kibana see <>. +existing index patterns are not visible. For more information, see <>. [role="screenshot"] image::images/management-index-read-only-badge.png[Example of Index Pattern Management's read only access indicator in Kibana's header] @@ -20,12 +25,9 @@ image::images/management-index-read-only-badge.png[Example of Index Pattern Mana [[settings-create-pattern]] === Create an index pattern -To get started, go to *Management > Kibana > Index Patterns*. You begin with -an overview of your index patterns, including any that were added when you -downloaded sample data sets. - -You can create a standard index pattern, and if a rollup index is detected in the -cluster, a rollup index pattern. +If you are in an app that requires an index pattern, and you don't have one yet, +{kib} prompts you to create one. Or, you can go directly to +*Management > Kibana > Index Patterns*. [role="screenshot"] image:management/index-patterns/images/rollup-index-pattern.png["Menu with rollup index pattern"] @@ -33,83 +35,93 @@ image:management/index-patterns/images/rollup-index-pattern.png["Menu with rollu [float] ==== Standard index pattern -{kib} makes it easy for you to create an index pattern by walking you through -the process. Just start typing in the *Index pattern* field, and {kib} looks for -the names of {es} indices that match your input. Make sure that the name of the +Just start typing in the *Index pattern* field, and {kib} looks for +the names of {es} indices that match your input. Make sure that the name of the index pattern is unique. - -If you want to include system indices in your search, toggle the switch in the -upper right. +To include system indices in your search, toggle the switch in the upper right. [role="screenshot"] image:management/index-patterns/images/create-index-pattern.png["Create index pattern"] -Your index pattern can match multiple {es} indices. -Use a comma to separate the names, with no space after the comma. The notation for -wildcards (`*`) and the ability to "exclude" (`-`) also apply +Your index pattern can match multiple {es} indices. +Use a comma to separate the names, with no space after the comma. The notation for +wildcards (`*`) and the ability to "exclude" (`-`) also apply (for example, `test*,-test3`). -When {kib} detects an index with a timestamp, you’re asked to choose a field to -filter your data by time. If you don’t specify a field, you won’t be able +If {kib} detects an index with a timestamp, you’re asked to choose a field to +filter your data by time. If you don’t specify a field, you won’t be able to use the time filter. -Once you’ve created your index pattern, you can start working with -your {es} data in {kib}. Here are some things to try: -* Interactively explore your data in <>. -* Present your data in charts, tables, gauges, tag clouds, and more in <>. -* Show off your data in a <> presentation. -* If your data includes geo data, visualize it using <>. - -For a walkthrough of creating an index pattern and visualizing the data, -see <>. [float] ==== Rollup index pattern -If a rollup index is detected in the cluster, clicking *Create index pattern* -includes an item for creating a rollup index pattern. You create an -index pattern for rolled up data the same way you do for any data. +If a rollup index is detected in the cluster, clicking *Create index pattern* +includes an item for creating a rollup index pattern. +You can match an index pattern to only rolled up data, or mix both rolled +up and raw data to explore and visualize all data together. +An index pattern can match +only one rollup index. + +[float] +[[management-cross-cluster-search]] +==== {ccs-cap} index pattern + +If your {es} clusters are configured for {ref}/modules-cross-cluster-search.html[{ccs}], you can create +index patterns to search across the clusters of your choosing. Using the +same syntax that you'd use in a raw {ccs} request in {es}, create your +index pattern with the convention `:`. + +For example, to query {ls} indices across two {es} clusters +that you set up for {ccs}, which are named `cluster_one` and `cluster_two`, +you would use `cluster_one:logstash-*,cluster_two:logstash-*` as your index pattern. + +You can use wildcards in your cluster names +to match any number of clusters, so if you want to search {ls} indices across +clusters named `cluster_foo`, `cluster_bar`, and so on, you would use `cluster_*:logstash-*` +as your index pattern. -You can match an index pattern to only rolled up data, or mix both rolled -up and raw data to visualize all data together. An index pattern can match -only one rollup index, not multiple. There is no restriction on the -number of standard indices that an index pattern can match. +To query across all {es} clusters that have been configured for {ccs}, +use a standalone wildcard for your cluster name in your index +pattern: `*:logstash-*`. -See <> -for more detailed information. +Once an index pattern is configured using the {ccs} syntax, all searches and +aggregations using that index pattern in {kib} take advantage of {ccs}. [float] === Manage your index pattern -Once you’ve created an index pattern, you’re presented a table of all fields -and associated data types in the index. +Once you create an index pattern, manually or with a sample data set, +you can look at its fields and associated data types. +You can also perform housekeeping tasks, such as making the +index pattern the default or deleting it when you longer need it. +To drill down into the details of an index pattern, click its name in +the *Index patterns* overview. [role="screenshot"] image:management/index-patterns/images/new-index-pattern.png["Index files and data types"] -You can perform the following actions: +From the detailed view, you can perform the following actions: -* *Manage the index fields.* Click a column header to sort the table by that column. -Use the field dropdown menu to limit to display to a specific field. -See <> for more detailed information. +* *Manage the index fields.* You can add formatters to format values and create +scripted fields. +See <> for more information. -* [[set-default-pattern]]*Set the default index pattern.* {kib} uses a badge to make users -aware of which index pattern is the default. The first pattern -you create is automatically designated as the default pattern. The default -index pattern is loaded when you view the Discover tab. +* [[set-default-pattern]]*Set the default index pattern.* {kib} uses a badge to make users +aware of which index pattern is the default. The first pattern +you create is automatically designated as the default pattern. The default +index pattern is loaded when you open *Discover*. -* [[reload-fields]]*Reload the index fields list.* You can reload the index fields list to -pick up any newly-added fields. Doing so also resets Kibana’s popularity counters -for the fields. The popularity counters keep track of the fields -you’ve used most often in {kib} and are used to sort fields in lists. +* [[reload-fields]]*Refresh the index fields list.* You can refresh the index fields list to +pick up any newly-added fields. Doing so also resets Kibana’s popularity counters +for the fields. The popularity counters are used in *Discover* to sort fields in lists. -* [[delete-pattern]]*Delete the index pattern.* This action removes the pattern from the list of -Saved Objects in {kib}. You will not be able to recover field formatters, +* [[delete-pattern]]*Delete the index pattern.* This action removes the pattern from the list of +Saved Objects in {kib}. You will not be able to recover field formatters, scripted fields, source filters, and field popularity data associated with the index pattern. -+ -Deleting an index pattern breaks all visualizations, saved searches, and -other saved objects that reference the pattern. Deleting an index pattern does +Deleting an index pattern does not remove any indices or data documents from {es}. - -include::index-patterns/management-cross-cluster-search.asciidoc[] ++ +WARNING: Deleting an index pattern breaks all visualizations, saved searches, and +other saved objects that reference the pattern. diff --git a/docs/management/index-patterns/management-cross-cluster-search.asciidoc b/docs/management/index-patterns/management-cross-cluster-search.asciidoc deleted file mode 100644 index 9fd8deb7f34be..0000000000000 --- a/docs/management/index-patterns/management-cross-cluster-search.asciidoc +++ /dev/null @@ -1,30 +0,0 @@ -[[management-cross-cluster-search]] -=== {ccs-cap} - -{es} supports the ability to run search and aggregation requests across multiple -clusters using a module called _{ccs}_. - -In order to take advantage of {ccs}, you must configure your {es} -clusters accordingly. Review the corresponding {es} -{ref}/modules-cross-cluster-search.html[documentation] before attempting to use {ccs} in {kib}. - -Once your {es} clusters are configured for {ccs}, you can create -specific index patterns in {kib} to search across the clusters of your choosing. Using the -same syntax that you'd use in a raw {ccs} request in {es}, create your -index pattern in {kib} with the convention `:`. - -For example, if you want to query {ls} indices across two of the {es} clusters -that you set up for {ccs}, which were named `cluster_one` and `cluster_two`, -you would use `cluster_one:logstash-*,cluster_two:logstash-*` as your index pattern in {kib}. - -Just like in raw search requests in {es}, you can use wildcards in your cluster names -to match any number of clusters, so if you wanted to search {ls} indices across any -clusters named `cluster_foo`, `cluster_bar`, and so on, you would use `cluster_*:logstash-*` -as your index pattern in {kib}. - -If you want to query across all {es} clusters that have been configured for {ccs}, -then use a standalone wildcard for your cluster name in your {kib} index -pattern: `*:logstash-*`. - -Once an index pattern is configured using the {ccs} syntax, all searches and -aggregations using that index pattern in {kib} take advantage of {ccs}. diff --git a/docs/maps/maps-aggregations.asciidoc b/docs/maps/maps-aggregations.asciidoc index 98aa21f6a07a3..627fd49dafa51 100644 --- a/docs/maps/maps-aggregations.asciidoc +++ b/docs/maps/maps-aggregations.asciidoc @@ -47,6 +47,7 @@ To enable top hits: . Set *Entity* to the field that identifies entities in your documents. This field will be used in the terms aggregation to group your documents into entity buckets. . Set *Documents per entity* to configure the maximum number of documents accumulated per entity. +This setting is limited to the `index.max_inner_result_window` index setting, which defaults to 100. [role="screenshot"] image::maps/images/top_hits.png[] diff --git a/docs/maps/vector-layer.asciidoc b/docs/maps/vector-layer.asciidoc index 1b9d0e6556f54..1d4ba9912529a 100644 --- a/docs/maps/vector-layer.asciidoc +++ b/docs/maps/vector-layer.asciidoc @@ -15,7 +15,7 @@ See map.regionmap.* in <> for details. *Documents*:: Vector data from a Kibana index pattern. The index must contain at least one field mapped as {ref}/geo-point.html[geo_point] or {ref}/geo-shape.html[geo_shape]. -NOTE: Document results are limited to the first 10000 matching documents. +NOTE: Document results are limited to the `index.max_result_window` index setting, which defaults to 10000. Use <> to plot large data sets. *Grid aggregation*:: Geospatial data grouped in grids with metrics for each gridded cell. diff --git a/docs/maps/vector-style-properties.asciidoc b/docs/maps/vector-style-properties.asciidoc index f51632218add1..5656a7f04d0e3 100644 --- a/docs/maps/vector-style-properties.asciidoc +++ b/docs/maps/vector-style-properties.asciidoc @@ -8,32 +8,52 @@ Point, polygon, and line features support different styling properties. [[point-style-properties]] ==== Point style properties +You can add text labels to your Point features by configuring label style properties. + +[cols="2*"] +|=== +|*Label* +|Specifies label content. +|*Label color* +|The text color. +|*Label size* +|The size of the text font, in pixels. +|=== + You can symbolize Point features as *Circle markers* or *Icons*. Use *Circle marker* to symbolize Points as circles. -*Fill color*:: The fill color of the point features. - -*Border color*:: The border color of the point features. - -*Border width*:: The border width of the point features. - -*Symbol size*:: The radius of the symbol size, in pixels. +[cols="2*"] +|=== +|*Border color* +|The border color of the point features. +|*Border width* +|The border width of the point features. +|*Fill color* +|The fill color of the point features. +|*Symbol size* +|The radius of the symbol size, in pixels. +|=== Use *Icon* to symbolize Points as icons. -*Fill color*:: The fill color of the point features. - -*Border color*:: The border color of the point features. - -*Border width*:: The border width of the point features. +[cols="2*"] +|=== +|*Border color* +|The border color of the point features. +|*Border width* +|The border width of the point features. +|*Fill color* +|The fill color of the point features. +|*Symbol orientation* +|The symbol orientation rotating the icon clockwise. +|*Symbol size* +|The radius of the symbol size, in pixels. +|=== -*Symbol orientation*:: The symbol orientation rotating the icon clockwise. - -*Symbol size*:: The radius of the symbol size, in pixels. -+ Available icons -+ + [role="screenshot"] image::maps/images/maki-icons.png[] @@ -42,17 +62,25 @@ image::maps/images/maki-icons.png[] [[polygon-style-properties]] ==== Polygon style properties -*Fill color*:: The fill color of the polygon features. - -*Border color*:: The border color of the polygon features. - -*Border width*:: The border width of the polygon features. +[cols="2*"] +|=== +|*Border color* +|The border color of the polygon features. +|*Border width* +|The border width of the polygon features. +|*Fill color* +|The fill color of the polygon features. +|=== [float] [[line-style-properties]] ==== Line style properties -*Border color*:: The color of the line features. - -*Border width*:: The width of the line features. +[cols="2*"] +|=== +|*Border color* +|The color of the line features. +|*Border width* +|The width of the line features. +|=== diff --git a/docs/settings/apm-settings.asciidoc b/docs/settings/apm-settings.asciidoc index 8cbbcdcbca3ef..8d28b55a6502f 100644 --- a/docs/settings/apm-settings.asciidoc +++ b/docs/settings/apm-settings.asciidoc @@ -13,6 +13,10 @@ copy and paste the relevant settings below into your `kibana.yml` configuration [[general-apm-settings-kb]] ==== General APM settings +// This content is reused in the APM app documentation. +// Any changes made in this file will be seen there as well. +// tag::general-apm-settings[] + xpack.apm.enabled:: Set to `false` to disabled the APM plugin {kib}. Defaults to `true`. @@ -37,3 +41,4 @@ apm_oss.metricsIndices:: Matcher for indices containing metric documents. Defaul apm_oss.sourcemapIndices:: Matcher for indices containing sourcemap documents. Defaults to `apm-*`. +// end::general-apm-settings[] diff --git a/docs/setup/docker.asciidoc b/docs/setup/docker.asciidoc index f3e7273adedee..8fd7b0490e194 100644 --- a/docs/setup/docker.asciidoc +++ b/docs/setup/docker.asciidoc @@ -5,7 +5,7 @@ base image is https://hub.docker.com/_/centos/[centos:7]. A list of all published Docker images and tags is available at https://www.docker.elastic.co[www.docker.elastic.co]. The source code is in -https://github.com/elastic/kibana-docker/tree/{branch}[GitHub]. +https://github.com/elastic/dockerfiles/tree/{branch}/kibana[GitHub]. These images are free to use under the Elastic license. They contain open source and free commercial features and access to paid commercial features. diff --git a/docs/setup/settings.asciidoc b/docs/setup/settings.asciidoc index 414d4ef34db55..01e6bd51ea50b 100644 --- a/docs/setup/settings.asciidoc +++ b/docs/setup/settings.asciidoc @@ -164,7 +164,7 @@ that feature would not take any effect. `logging.rotate.everyBytes:`:: [experimental] *Default: 10485760* The maximum size of a log file (that is `not an exact` limit). After the limit is reached, a new log file is generated. The default size limit is 10485760 (10 MB) and -this option should be at least greater than 1024. +this option should be in the range of 102400 (100KB) to 1073741824 (1GB). `logging.rotate.keepFiles:`:: [experimental] *Default: 7* The number of most recent rotated log files to keep on disk. Older files are deleted during log rotation. The default value is 7. The `logging.rotate.keepFiles` @@ -352,6 +352,18 @@ all http requests to https over the port configured as `server.port`. `server.ssl.supportedProtocols:`:: *Default: TLSv1.1, TLSv1.2* An array of supported protocols with versions. Valid protocols: `TLSv1`, `TLSv1.1`, `TLSv1.2` +`server.xsrf.whitelist:`:: It is not recommended to disable protections for +arbitrary API endpoints. Instead, supply the `kbn-xsrf` header. There are some +scenarios where whitelisting is required, however, such as +<>. +The `server.xsrf.whitelist` setting requires the following format: + +[source,text] + +---- +*Default: [ ]* An array of API endpoints which should be exempt from Cross-Site Request Forgery ("XSRF") protections. +---- + `status.allowAnonymous:`:: *Default: false* If authentication is enabled, setting this to `true` enables unauthenticated users to access the Kibana server status API and status page. @@ -378,6 +390,15 @@ Rollup user interface. `i18n.locale`:: *Default: en* Set this value to change the Kibana interface language. Valid locales are: `en`, `zh-CN`, `ja-JP`. +`xpack.actions.enabledActionTypes:`:: *Default: +[ {asterisk} ]+* Set this value +to an array of action types that are enabled. An element of `*` indicates all +action types registered are enabled. The action types provided by Kibana are: +`.server-log`, `.slack`, `.email`, `.index`, `.pagerduty`, `.webhook`. + +`xpack.actions.whitelistedHosts:`:: *Default: +[ {asterisk} ]+* Set this value +to an array of host names which actions such as email, slack, pagerduty, and +webhook can connect to. An element of `*` indicates any host can be connected +to. An empty array indicates no hosts can be connected to. include::{docdir}/settings/apm-settings.asciidoc[] include::{docdir}/settings/dev-settings.asciidoc[] diff --git a/docs/user/canvas.asciidoc b/docs/user/canvas.asciidoc index c58635ba97769..5c5f5c2f80bf9 100644 --- a/docs/user/canvas.asciidoc +++ b/docs/user/canvas.asciidoc @@ -37,6 +37,8 @@ include::{kib-repo-dir}/canvas/canvas-present-workpad.asciidoc[] include::{kib-repo-dir}/canvas/canvas-share-workpad.asciidoc[] +include::{kib-repo-dir}/canvas/canvas-expression-lifecycle.asciidoc[] + include::{kib-repo-dir}/canvas/canvas-function-reference.asciidoc[] -include::{kib-repo-dir}/canvas/canvas-tinymath-functions.asciidoc[] +include::{kib-repo-dir}/canvas/canvas-tinymath-functions.asciidoc[] \ No newline at end of file diff --git a/docs/user/discover.asciidoc b/docs/user/discover.asciidoc index fa583918703f3..7de7d73bf1664 100644 --- a/docs/user/discover.asciidoc +++ b/docs/user/discover.asciidoc @@ -3,17 +3,105 @@ [partintro] -- -*Discover* enables you to explore your data with {kib}'s data discovery functions. -You have access to every document in every index that matches the selected <>. -You can submit search queries, filter the search results, and view document data. -You can also see the number of documents that match the search query and get field value statistics. -If a time field is configured for the selected index pattern, the distribution of -documents over time is displayed in a histogram at the top of the page. + +When you know what your data includes, you can create visualizations +that best display that data and build better dashboards. +*Discover* enables you to explore your data, find +hidden insights and relationships, and get answers to your questions. + +With *Discover*, you can: + +* Access every document in every index that matches your selected index pattern +* Search your data and filter the search results +* Get field-level details about the documents that match your search +* View the events that occurred just before and after a document [role="screenshot"] image::images/Discover-Start.png[Discover] + + +[float] +=== Set up your index pattern + +The first thing to do in *Discover* is to select an <>, which +defines the data you want to explore and visualize. The current index pattern is in the upper left. +If you haven't yet created an index pattern, you can add a <>, +which has a pre-built index pattern. + +[float] +=== Set a time filter + +By default, *Discover* shows data for the last 15 minutes. +If you have a time-based index, and no data displays, +you might need to increase the time range. Using the <> in the upper right, +you can specify a common or recently-used time range, a relative time +from now, or an absolute time range. + +[float] +=== Search your data + +Now that you have your data and set the time span, you can start asking your questions. +You can search your data using the <>, +which offers a simplified query syntax. +For example, if +you search for `day_of_week : Friday`, you'll get a list of all documents +in which `day_of_week` is set to `Friday`. If you prefer +<>, you can access it from the KQL menu. + +[float] +=== Filter your search results + +Next, you'll want narrow your search results to a more manageable data set. +When you click on a name in the field list, you'll see +the top five values for the field, the number of documents that contain the field, +and the percentage of documents that contain each value. From this view, you can +use the (+) magnifier icon to quickly find all +documents that have that value, or (-) to exclude all +documents with that value. For more filter options, see <>. + +[role="screenshot"] +image::images/filter-field.png[height=317] + + +[float] +=== Add and remove fields + +The sortable documents table +lists the documents that match your search. +By default, the table includes columns for the time field and the document `_source`. +To zero in on a specific field, click *add* next to the field name in the left sidebar. +For example, if you add the `currency`, `customer_last_name`, and `day_of_week` fields, +the document table includes columns for those three fields. + +[float] +=== Examine document contents + +From the documents table, you can expand a document to +examine its field data in either table or JSON format. +The table view provides yet another filtering option—filtering for whether the field +is present. See <> for details. + +[float] +=== View a document in context + +Suppose you're troubleshooting your data, and you've narrowed down your results to a single document. +Now you want to to see the events that occurred just before and after the +document that you are looking at. You can do that by expanding the document and +clicking <>. + +[float] +=== Save and share your search + +Finally, its time to save and share your data. You can export your data as a CSV file +or create a direct link to share. The *Save* and *Share* actions are in the menu bar. + + + + -- +include::{kib-repo-dir}/management/index-patterns.asciidoc[] + include::{kib-repo-dir}/discover/set-time-filter.asciidoc[] include::{kib-repo-dir}/discover/search.asciidoc[] diff --git a/docs/user/management.asciidoc b/docs/user/management.asciidoc index d1acb915f1973..2c41d0072fe5b 100644 --- a/docs/user/management.asciidoc +++ b/docs/user/management.asciidoc @@ -13,8 +13,6 @@ visualizations, and dashboards. include::{kib-repo-dir}/management/managing-licenses.asciidoc[] -include::{kib-repo-dir}/management/index-patterns.asciidoc[] - include::{kib-repo-dir}/management/rollups/create_and_manage_rollups.asciidoc[] include::{kib-repo-dir}/management/index-lifecycle-policies/intro-to-lifecycle-policies.asciidoc[] @@ -40,5 +38,3 @@ include::{kib-repo-dir}/management/managing-beats.asciidoc[] include::{kib-repo-dir}/management/managing-remote-clusters.asciidoc[] include::{kib-repo-dir}/management/snapshot-restore/index.asciidoc[] - - diff --git a/docs/user/ml/index.asciidoc b/docs/user/ml/index.asciidoc index a2c23aad98d5b..cca0dc5e4530f 100644 --- a/docs/user/ml/index.asciidoc +++ b/docs/user/ml/index.asciidoc @@ -50,8 +50,8 @@ pane: image::user/ml/images/ml-job-management.jpg[Job Management] You can use the *Settings* pane to create and edit -{stack-ov}/ml-calendars.html[calendars] and the filters that are used in -{stack-ov}/ml-rules.html[custom rules]: +{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] @@ -73,7 +73,7 @@ image::user/ml/images/ml-annotations-list.jpg[Single Metric Viewer with annotati In some circumstances, annotations are also added automatically. For example, if the {anomaly-job} detects that there is missing data, it annotates the affected time period. For more information, see -{stack-ov}/ml-delayed-data-detection.html[Handling delayed data]. The +{ml-docs}/ml-delayed-data-detection.html[Handling delayed data]. The *Job Management* pane shows the full list of annotations for each job. NOTE: The {kib} {ml-features} use pop-ups. You must configure your web @@ -82,7 +82,7 @@ browser so that it does not block pop-up windows or create an exception for your For more information about the {anomaly-detect} feature, see https://www.elastic.co/what-is/elastic-stack-machine-learning[{ml-cap} in the {stack}] -and {stack-ov}/xpack-ml.html[{ml-cap} {anomaly-detect}]. +and {ml-docs}/xpack-ml.html[{ml-cap} {anomaly-detect}]. [[xpack-ml-dfanalytics]] == {dfanalytics-cap} @@ -99,4 +99,4 @@ in {kib}. For example: image::user/ml/images/outliers.jpg[{oldetection-cap} results in {kib}] For more information about the {dfanalytics} feature, see -{stack-ov}/ml-dfanalytics.html[{ml-cap} {dfanalytics}]. \ No newline at end of file +{ml-docs}/ml-dfanalytics.html[{ml-cap} {dfanalytics}]. \ No newline at end of file diff --git a/docs/user/reporting/images/shareable-container.png b/docs/user/reporting/images/shareable-container.png new file mode 100644 index 0000000000000..db5a41dcff471 Binary files /dev/null and b/docs/user/reporting/images/shareable-container.png differ diff --git a/docs/user/reporting/index.asciidoc b/docs/user/reporting/index.asciidoc index 06af9e6038445..fde88130a26b4 100644 --- a/docs/user/reporting/index.asciidoc +++ b/docs/user/reporting/index.asciidoc @@ -6,11 +6,11 @@ -- -You can generate a report that contains a {kib} dashboard, visualization, -saved search, or Canvas workpad. Depending on the object type, you can export the data as +You can generate a report that contains a {kib} dashboard, visualization, +saved search, or Canvas workpad. Depending on the object type, you can export the data as a PDF, PNG, or CSV document, which you can keep for yourself, or share with others. -Reporting is available from the *Share* menu +Reporting is available from the *Share* menu in *Discover*, *Visualize*, *Dashboard*, and *Canvas*. [role="screenshot"] @@ -40,9 +40,9 @@ for an example. [[manually-generate-reports]] == Generate a report manually -. Open the dashboard, visualization, Canvas workpad, or saved search that you want to include in the report. +. Open the dashboard, visualization, Canvas workpad, or saved search that you want to include in the report. -. In the {kib} toolbar, click *Share*. If you are working in Canvas, +. In the {kib} toolbar, click *Share*. If you are working in Canvas, click the share icon image:user/reporting/images/canvas-share-button.png["Canvas Share button"]. . Select the option appropriate for your object. You can export: @@ -55,14 +55,36 @@ click the share icon image:user/reporting/images/canvas-share-button.png["Canvas + A notification appears when the report is complete. +[float] +[[reporting-layout-sizing]] +== Layout and sizing +The layout and size of the PDF or PNG image depends on the {kib} app +with which the Reporting plugin is integrated. For Canvas, the +worksheet dimensions determine the size for Reporting. In other apps, +the dimensions are taken on the fly by looking at +the size of the visualization elements or panels on the page. + +The size dimensions are part of the reporting job parameters. Therefore, to +make the report output larger or smaller, you can change the size of the browser. +This resizes the shareable container before generating the +report, so the desired dimensions are passed in the job parameters. + +In the following {kib} dashboard, the shareable container is highlighted. +The shareable container is captured when you click the +*Generate* or *Copy POST URL* button. It might take some trial and error +before you're satisfied with the layout and dimensions in the resulting +PNG or PDF image. + +[role="screenshot"] +image::user/reporting/images/shareable-container.png["Shareable Container"] + + + [float] [[optimize-pdf]] == Optimize PDF for print—dashboard only -By default, {kib} creates a PDF -using the existing layout and size of the dashboard. To create a -printer-friendly PDF with multiple A4 portrait pages and two visualizations -per page, turn on *Optimize for printing*. +To create a printer-friendly PDF with multiple A4 portrait pages and two visualizations per page, turn on *Optimize for printing*. [role="screenshot"] image::user/reporting/images/preserve-layout-switch.png["Share"] @@ -72,8 +94,8 @@ image::user/reporting/images/preserve-layout-switch.png["Share"] [[manage-report-history]] == View and manage report history -For a list of your reports, go to *Management > Reporting*. -From this view, you can monitor the generation of a report and +For a list of your reports, go to *Management > Reporting*. +From this view, you can monitor the generation of a report and download reports that you previously generated. [float] diff --git a/docs/user/reporting/reporting-troubleshooting.asciidoc b/docs/user/reporting/reporting-troubleshooting.asciidoc index 92464c24b45ea..dc4ffdfebdae9 100644 --- a/docs/user/reporting/reporting-troubleshooting.asciidoc +++ b/docs/user/reporting/reporting-troubleshooting.asciidoc @@ -7,16 +7,25 @@ Having trouble? Here are solutions to common problems you might encounter while using Reporting. +* <> +* <> +* <> +* <> +* <> +* <> +* <> + [float] [[reporting-troubleshooting-system-dependencies]] === System dependencies Reporting launches a "headless" web browser called Chromium on the Kibana server. It is a custom build made by Elastic of an open source project, and it is intended to have minimal dependencies on OS libraries. However, the Kibana server OS might still require additional -dependencies for Chromium. +dependencies to run the Chromium executable. Make sure Kibana server OS has the appropriate packages installed for the distribution. If you are using CentOS/RHEL systems, install the following packages: + * `ipa-gothic-fonts` * `xorg-x11-fonts-100dpi` * `xorg-x11-fonts-75dpi` @@ -28,22 +37,34 @@ If you are using CentOS/RHEL systems, install the following packages: * `freetype` If you are using Ubuntu/Debian systems, install the following packages: + * `fonts-liberation` * `libfontconfig1` +If the system is missing dependencies, then Reporting will fail in a non-deterministic way. {kib} runs a self-test at server startup, and +if it encounters errors, logs them in the Console. Unfortunately, the error message does not include +information about why Chromium failed to run. The most common error message is `Error: connect ECONNREFUSED`, which indicates +that {kib} could not connect to the Chromium process. + +To troubleshoot the problem, start the {kib} server with environment variables that tell Chromium to print verbose logs. See the +<> for more information. + [float] -=== Text is rendered incorrectly in generated reports +[[reporting-troubleshooting-text-incorrect]] +=== Text rendered incorrectly in generated reports If a report label is rendered as an empty rectangle, no system fonts are available. Install at least one font package on the system. If the report is missing certain Chinese, Japanese or Korean characters, ensure that a system font with those characters is installed. [float] +[[reporting-troubleshooting-missing-data]] === Missing data in PDF report of data table visualization There is currently a known limitation with the Data Table visualization that only the first page of data rows, which are the only data visible on the screen, are shown in PDF reports. [float] +[[reporting-troubleshooting-file-permissions]] === File permissions Ensure that the `headless_shell` binary located in your Kibana data directory is owned by the user who is running Kibana, that the user has the execute permission, and if applicable, that the filesystem is mounted with the `exec` option. @@ -61,25 +82,25 @@ Whenever possible, a Reporting error message tries to be as self-explanatory as along with the solution. [float] -==== "Max attempts reached" +==== Max attempts reached There are two primary causes of this error: -. You're creating a PDF of a visualization or dashboard that spans a large amount of data and Kibana is hitting the `xpack.reporting.queue.timeout` +* You're creating a PDF of a visualization or dashboard that spans a large amount of data and Kibana is hitting the `xpack.reporting.queue.timeout` -. Kibana is hosted behind a reverse-proxy, and the <> are not configured correctly +* Kibana is hosted behind a reverse-proxy, and the <> are not configured correctly Create a Markdown visualization and then create a PDF report. If this succeeds, increase the `xpack.reporting.queue.timeout` setting. If the PDF report fails with "Max attempts reached," check your <>. [float] [[reporting-troubleshooting-nss-dependency]] -==== "You must install nss for Reporting to work" +==== You must install nss for Reporting to work Reporting using the Chromium browser relies on the Network Security Service libraries (NSS). Install the appropriate nss package for your distribution. [float] [[reporting-troubleshooting-sandbox-dependency]] -==== "Unable to use Chromium sandbox" +==== Unable to use Chromium sandbox Chromium uses sandboxing techniques that are built on top of operating system primitives. The Linux sandbox depends on user namespaces, which were introduced with the 3.8 Linux kernel. However, many distributions don't have user namespaces enabled by default, or they require the CAP_SYS_ADMIN capability. @@ -88,6 +109,7 @@ Elastic recommends that you research the feasibility of enabling unprivileged us is if you are running Kibana in Docker because the container runs in a user namespace with the built-in seccomp/bpf filters. [float] +[[reporting-troubleshooting-verbose-logs]] === Verbose logs {kib} server logs have a lot of useful information for troubleshooting and understanding how things work. If you're having any issues at all, the full logs from Reporting will be the first place to look. In `kibana.yml`: @@ -99,15 +121,29 @@ logging.verbose: true For more information about logging, see <>. +[float] +[[reporting-troubleshooting-puppeteer-debug-logs]] === Puppeteer debug logs The Chromium browser that {kib} launches on the server is driven by a NodeJS library for Chromium called Puppeteer. The Puppeteer library has its own command-line method to generate its own debug logs, which can sometimes be helpful, particularly to figure out if a problem is -caused by Kibana or Chromium. See more at https://github.com/GoogleChrome/puppeteer/blob/v1.19.0/README.md#debugging-tips +caused by Kibana or Chromium. See more at https://github.com/GoogleChrome/puppeteer/blob/v1.19.0/README.md#debugging-tips[debugging tips]. Using Puppeteer's debug method when launching Kibana would look like: -> Enable verbose logging - internal DevTools protocol traffic will be logged via the debug module under the puppeteer namespace. -> ``` -> env DEBUG="puppeteer:*" ./bin/kibana -> ``` +``` +env DEBUG="puppeteer:*" ./bin/kibana +``` +The internal DevTools protocol traffic will be logged via the `debug` module under the `puppeteer` namespace. + The Puppeteer logs are very verbose and could possibly contain sensitive information. Handle the generated output with care. + +[float] +[[reporting-troubleshooting-system-requirements]] +=== System requirements +In Elastic Cloud, the {kib} instances that most configurations provide by default is for 1GB of RAM for the instance. That is enough for +{kib} Reporting when the visualization or dashboard is relatively simple, such as a single pie chart or a dashboard with +a few visualizations. However, certain visualization types incur more load than others. For example, a TSVB panel has a lot of network +requests to render. + +If the {kib} instance doesn't have enough memory to run the report, the report fails with an error such as `Error: Page crashed!` +In this case, try increasing the memory for the {kib} instance to 2GB. diff --git a/docs/user/reporting/watch-example.asciidoc b/docs/user/reporting/watch-example.asciidoc index 4c769c85975c4..627e31017230c 100644 --- a/docs/user/reporting/watch-example.asciidoc +++ b/docs/user/reporting/watch-example.asciidoc @@ -56,7 +56,16 @@ report from the Kibana UI. //For more information, see <>. //<>. -NOTE: Reporting is integrated with Watcher only as an email attachment type. +[NOTE] +==== +Reporting is integrated with Watcher only as an email attachment type. + +The report Generation URL might contain date-math expressions +that cause the watch to fail with a `parse_exception`. +Remove curly braces `{` `}` from date-math expressions and +URL-encode characters to avoid this. +For example: `...(range:(%27@timestamp%27:(gte:now-15m%2Fd,lte:now%2Fd))))...` For more information about configuring watches, see {ref}/how-watcher-works.html[How Watcher works]. +==== diff --git a/docs/user/security/reporting.asciidoc b/docs/user/security/reporting.asciidoc index 86599be9af375..c2ed295e83ce9 100644 --- a/docs/user/security/reporting.asciidoc +++ b/docs/user/security/reporting.asciidoc @@ -57,6 +57,30 @@ that provides read and write privileges in Go to *Management > Users*, add a new user, and assign the user the built-in `reporting_user` role and your new custom role, `custom_reporting_user`. +[float] +==== With a custom index + +If you are using Reporting with a custom index, +the `xpack.reporting.index` setting should begin +with `.reporting-*`. The default {kib} system user has +`all` privileges against the `.reporting-*` pattern of indices. + +[source,js] +xpack.reporting.index: '.reporting-custom-index' + +If you use a different pattern for the `xpack.reporting.index` setting, +you must create a custom role with appropriate access to the index, similar +to the following: + +. Go to *Management > Roles*, and click *Create role*. +. Name the role `custom-reporting-user`. +. Specify the custom index and assign it the `all` index privilege. +. Go to *Management > Users* and create a new user with +the `kibana_system` role and the `custom-reporting-user` role. +. Configure {kib} to use the new account: +[source,js] +elasticsearch.username: 'custom_kibana_system' + [float] [[reporting-roles-user-api]] ==== With the user API diff --git a/docs/visualize/lens.asciidoc b/docs/visualize/lens.asciidoc index 086f88c636c81..e61895a29891b 100644 --- a/docs/visualize/lens.asciidoc +++ b/docs/visualize/lens.asciidoc @@ -60,7 +60,7 @@ The summary shows the distribution of values in the time range. To view the data information, navigate to a data field, then click *i*. [role="screenshot"] -image::images/lens_data_info.gif[] +image::images/lens_data_info.png[] [float] [[change-the-visualization-type]] diff --git a/examples/demo_search/package.json b/examples/demo_search/package.json index 404002a50e710..d29ad55b32db2 100644 --- a/examples/demo_search/package.json +++ b/examples/demo_search/package.json @@ -1,7 +1,7 @@ { "name": "demo_data_search", "version": "1.0.0", - "main": "target/test/plugin_functional/plugins/demo_data_search", + "main": "target/examples/demo_data_search", "kibana": { "version": "kibana", "templateVersion": "1.0.0" @@ -12,6 +12,6 @@ "build": "rm -rf './target' && tsc" }, "devDependencies": { - "typescript": "3.5.3" + "typescript": "3.7.2" } } diff --git a/examples/embeddable_examples/kibana.json b/examples/embeddable_examples/kibana.json new file mode 100644 index 0000000000000..c70bc7009ff51 --- /dev/null +++ b/examples/embeddable_examples/kibana.json @@ -0,0 +1,10 @@ +{ + "id": "embeddableExamples", + "version": "0.0.1", + "kibanaVersion": "kibana", + "configPath": ["embeddable_examples"], + "server": false, + "ui": true, + "requiredPlugins": ["embeddable"], + "optionalPlugins": [] +} diff --git a/examples/embeddable_examples/package.json b/examples/embeddable_examples/package.json new file mode 100644 index 0000000000000..055ee6d731512 --- /dev/null +++ b/examples/embeddable_examples/package.json @@ -0,0 +1,17 @@ +{ + "name": "embeddable_examples", + "version": "1.0.0", + "main": "target/examples/embeddable_examples", + "kibana": { + "version": "kibana", + "templateVersion": "1.0.0" + }, + "license": "Apache-2.0", + "scripts": { + "kbn": "node ../../scripts/kbn.js", + "build": "rm -rf './target' && tsc" + }, + "devDependencies": { + "typescript": "3.7.2" + } +} diff --git a/src/plugins/embeddable/public/lib/test_samples/embeddables/hello_world/hello_world_embeddable.tsx b/examples/embeddable_examples/public/hello_world/hello_world_embeddable.tsx similarity index 92% rename from src/plugins/embeddable/public/lib/test_samples/embeddables/hello_world/hello_world_embeddable.tsx rename to examples/embeddable_examples/public/hello_world/hello_world_embeddable.tsx index dc41eb037caf1..f2839f1bc984b 100644 --- a/src/plugins/embeddable/public/lib/test_samples/embeddables/hello_world/hello_world_embeddable.tsx +++ b/examples/embeddable_examples/public/hello_world/hello_world_embeddable.tsx @@ -16,14 +16,14 @@ * specific language governing permissions and limitations * under the License. */ -import { Embeddable, EmbeddableInput, IContainer } from '../../..'; +import { Embeddable, EmbeddableInput, IContainer } from '../../../../src/plugins/embeddable/public'; -export const HELLO_WORLD_EMBEDDABLE_TYPE = 'HELLO_WORLD_EMBEDDABLE_TYPE'; +export const HELLO_WORLD_EMBEDDABLE = 'HELLO_WORLD_EMBEDDABLE'; export class HelloWorldEmbeddable extends Embeddable { // The type of this embeddable. This will be used to find the appropriate factory // to instantiate this kind of embeddable. - public readonly type = HELLO_WORLD_EMBEDDABLE_TYPE; + public readonly type = HELLO_WORLD_EMBEDDABLE; constructor(initialInput: EmbeddableInput, parent?: IContainer) { super( diff --git a/src/plugins/embeddable/public/lib/test_samples/embeddables/hello_world/hello_world_embeddable_factory.ts b/examples/embeddable_examples/public/hello_world/hello_world_embeddable_factory.ts similarity index 80% rename from src/plugins/embeddable/public/lib/test_samples/embeddables/hello_world/hello_world_embeddable_factory.ts rename to examples/embeddable_examples/public/hello_world/hello_world_embeddable_factory.ts index 6007d5a0aca62..de5a3d9380def 100644 --- a/src/plugins/embeddable/public/lib/test_samples/embeddables/hello_world/hello_world_embeddable_factory.ts +++ b/examples/embeddable_examples/public/hello_world/hello_world_embeddable_factory.ts @@ -18,11 +18,15 @@ */ import { i18n } from '@kbn/i18n'; -import { IContainer, EmbeddableInput, EmbeddableFactory } from '../../..'; -import { HelloWorldEmbeddable, HELLO_WORLD_EMBEDDABLE_TYPE } from './hello_world_embeddable'; +import { + IContainer, + EmbeddableInput, + EmbeddableFactory, +} from '../../../../src/plugins/embeddable/public'; +import { HelloWorldEmbeddable, HELLO_WORLD_EMBEDDABLE } from './hello_world_embeddable'; export class HelloWorldEmbeddableFactory extends EmbeddableFactory { - public readonly type = HELLO_WORLD_EMBEDDABLE_TYPE; + public readonly type = HELLO_WORLD_EMBEDDABLE; /** * In our simple example, we let everyone have permissions to edit this. Most @@ -38,7 +42,7 @@ export class HelloWorldEmbeddableFactory extends EmbeddableFactory { } public getDisplayName() { - return i18n.translate('embeddableApi.samples.helloworld.displayName', { + return i18n.translate('embeddableExamples.helloworld.displayName', { defaultMessage: 'hello world', }); } diff --git a/src/plugins/embeddable/public/lib/test_samples/embeddables/hello_world/index.ts b/examples/embeddable_examples/public/hello_world/index.ts similarity index 100% rename from src/plugins/embeddable/public/lib/test_samples/embeddables/hello_world/index.ts rename to examples/embeddable_examples/public/hello_world/index.ts diff --git a/examples/embeddable_examples/public/index.ts b/examples/embeddable_examples/public/index.ts new file mode 100644 index 0000000000000..1c2c3911d1006 --- /dev/null +++ b/examples/embeddable_examples/public/index.ts @@ -0,0 +1,34 @@ +/* + * 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'; +export { + HELLO_WORLD_EMBEDDABLE, + HelloWorldEmbeddable, + HelloWorldEmbeddableFactory, +} from './hello_world'; +export { ListContainer, LIST_CONTAINER } from './list_container'; +export { TODO_EMBEDDABLE } from './todo'; + +import { EmbeddableExamplesPlugin } from './plugin'; + +export { SearchableListContainer, SEARCHABLE_LIST_CONTAINER } from './searchable_list_container'; +export { MULTI_TASK_TODO_EMBEDDABLE } from './multi_task_todo'; + +export const plugin: PluginInitializer = () => new EmbeddableExamplesPlugin(); diff --git a/examples/embeddable_examples/public/list_container/embeddable_list_item.tsx b/examples/embeddable_examples/public/list_container/embeddable_list_item.tsx new file mode 100644 index 0000000000000..2c80cef8a6364 --- /dev/null +++ b/examples/embeddable_examples/public/list_container/embeddable_list_item.tsx @@ -0,0 +1,64 @@ +/* + * 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 { EuiPanel, EuiLoadingSpinner, EuiFlexItem } from '@elastic/eui'; +import { IEmbeddable } from '../../../../src/plugins/embeddable/public'; + +interface Props { + embeddable: IEmbeddable; +} + +export class EmbeddableListItem extends React.Component { + private embeddableRoot: React.RefObject; + private rendered = false; + + constructor(props: Props) { + super(props); + this.embeddableRoot = React.createRef(); + } + + public componentDidMount() { + if (this.embeddableRoot.current && this.props.embeddable) { + this.props.embeddable.render(this.embeddableRoot.current); + this.rendered = true; + } + } + + public componentDidUpdate() { + if (this.embeddableRoot.current && this.props.embeddable && !this.rendered) { + this.props.embeddable.render(this.embeddableRoot.current); + this.rendered = true; + } + } + + public render() { + return ( + + + {this.props.embeddable ? ( +

+ ) : ( + + )} + + + ); + } +} diff --git a/examples/embeddable_examples/public/list_container/index.ts b/examples/embeddable_examples/public/list_container/index.ts new file mode 100644 index 0000000000000..581739f6b5458 --- /dev/null +++ b/examples/embeddable_examples/public/list_container/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 { ListContainer, LIST_CONTAINER } from './list_container'; +export { ListContainerFactory } from './list_container_factory'; diff --git a/examples/embeddable_examples/public/list_container/list_container.tsx b/examples/embeddable_examples/public/list_container/list_container.tsx new file mode 100644 index 0000000000000..35a674a03573a --- /dev/null +++ b/examples/embeddable_examples/public/list_container/list_container.tsx @@ -0,0 +1,57 @@ +/* + * 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 { + Container, + ContainerInput, + GetEmbeddableFactory, +} from '../../../../src/plugins/embeddable/public'; +import { ListContainerComponent } from './list_container_component'; + +export const LIST_CONTAINER = 'LIST_CONTAINER'; + +export class ListContainer extends Container<{}, ContainerInput> { + public readonly type = LIST_CONTAINER; + private node?: HTMLElement; + + constructor(input: ContainerInput, getEmbeddableFactory: GetEmbeddableFactory) { + super(input, { embeddableLoaded: {} }, getEmbeddableFactory); + } + + // This container has no input itself. + getInheritedInput(id: string) { + return {}; + } + + public render(node: HTMLElement) { + this.node = node; + if (this.node) { + ReactDOM.unmountComponentAtNode(this.node); + } + ReactDOM.render(, node); + } + + public destroy() { + super.destroy(); + if (this.node) { + ReactDOM.unmountComponentAtNode(this.node); + } + } +} diff --git a/examples/embeddable_examples/public/list_container/list_container_component.tsx b/examples/embeddable_examples/public/list_container/list_container_component.tsx new file mode 100644 index 0000000000000..f6e04933ee897 --- /dev/null +++ b/examples/embeddable_examples/public/list_container/list_container_component.tsx @@ -0,0 +1,74 @@ +/* + * 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 { EuiFlexGroup, EuiSpacer, EuiFlexItem, EuiText, EuiPanel } from '@elastic/eui'; +import { + IContainer, + withEmbeddableSubscription, + ContainerInput, + ContainerOutput, +} from '../../../../src/plugins/embeddable/public'; +import { EmbeddableListItem } from './embeddable_list_item'; + +interface Props { + embeddable: IContainer; + input: ContainerInput; + output: ContainerOutput; +} + +function renderList(embeddable: IContainer, panels: ContainerInput['panels']) { + let number = 0; + const list = Object.values(panels).map(panel => { + const child = embeddable.getChild(panel.explicitInput.id); + number++; + return ( + + + + +

{number}

+
+
+ + + +
+
+ ); + }); + return list; +} + +export function ListContainerComponentInner(props: Props) { + return ( +
+

{props.embeddable.getTitle()}

+ + {renderList(props.embeddable, props.input.panels)} +
+ ); +} + +// You don't have to use this helper wrapper, but it handles a lot of the React boilerplate for +// embeddables, like setting up the subscriptions to cause the component to refresh whenever +// anything on input or output state changes. If you don't want that to happen (for example +// if you expect something on input or output state to change frequently that your react +// component does not care about, then you should probably hook this up manually). +export const ListContainerComponent = withEmbeddableSubscription(ListContainerComponentInner); diff --git a/examples/embeddable_examples/public/list_container/list_container_factory.ts b/examples/embeddable_examples/public/list_container/list_container_factory.ts new file mode 100644 index 0000000000000..de6b7d5f5e503 --- /dev/null +++ b/examples/embeddable_examples/public/list_container/list_container_factory.ts @@ -0,0 +1,49 @@ +/* + * 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 { i18n } from '@kbn/i18n'; +import { + EmbeddableFactory, + GetEmbeddableFactory, + ContainerInput, +} from '../../../../src/plugins/embeddable/public'; +import { LIST_CONTAINER, ListContainer } from './list_container'; + +export class ListContainerFactory extends EmbeddableFactory { + public readonly type = LIST_CONTAINER; + public readonly isContainerType = true; + + constructor(private getEmbeddableFactory: GetEmbeddableFactory) { + super(); + } + + public isEditable() { + return true; + } + + public async create(initialInput: ContainerInput) { + return new ListContainer(initialInput, this.getEmbeddableFactory); + } + + public getDisplayName() { + return i18n.translate('embeddableExamples.searchableListContainer.displayName', { + defaultMessage: 'List container', + }); + } +} diff --git a/examples/embeddable_examples/public/multi_task_todo/index.ts b/examples/embeddable_examples/public/multi_task_todo/index.ts new file mode 100644 index 0000000000000..2063bf2c06223 --- /dev/null +++ b/examples/embeddable_examples/public/multi_task_todo/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 './multi_task_todo_embeddable'; +export * from './multi_task_todo_embeddable_factory'; diff --git a/examples/embeddable_examples/public/multi_task_todo/multi_task_todo_component.tsx b/examples/embeddable_examples/public/multi_task_todo/multi_task_todo_component.tsx new file mode 100644 index 0000000000000..e33dfab0eaf4a --- /dev/null +++ b/examples/embeddable_examples/public/multi_task_todo/multi_task_todo_component.tsx @@ -0,0 +1,94 @@ +/* + * 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 } from '@elastic/eui'; + +import { + EuiText, + EuiAvatar, + EuiIcon, + EuiFlexGrid, + EuiListGroup, + EuiListGroupItem, +} from '@elastic/eui'; +import { withEmbeddableSubscription } from '../../../../src/plugins/embeddable/public'; +import { + MultiTaskTodoEmbeddable, + MultiTaskTodoOutput, + MultiTaskTodoInput, +} from './multi_task_todo_embeddable'; + +interface Props { + embeddable: MultiTaskTodoEmbeddable; + input: MultiTaskTodoInput; + output: MultiTaskTodoOutput; +} + +function wrapSearchTerms(task: string, search?: string) { + if (!search) return task; + const parts = task.split(new RegExp(`(${search})`, 'g')); + return parts.map((part, i) => + part === search ? ( + + {part} + + ) : ( + part + ) + ); +} + +function renderTasks(tasks: MultiTaskTodoOutput['tasks'], search?: string) { + return tasks.map(task => ( + + )); +} + +export function MultiTaskTodoEmbeddableComponentInner({ + input: { title, icon, search }, + output: { tasks }, +}: Props) { + return ( + + + {icon ? : } + + + + + +

{wrapSearchTerms(title, search)}

+
+
+ + {renderTasks(tasks, search)} + +
+
+
+ ); +} + +export const MultiTaskTodoEmbeddableComponent = withEmbeddableSubscription( + MultiTaskTodoEmbeddableComponentInner +); diff --git a/examples/embeddable_examples/public/multi_task_todo/multi_task_todo_embeddable.tsx b/examples/embeddable_examples/public/multi_task_todo/multi_task_todo_embeddable.tsx new file mode 100644 index 0000000000000..a2197c9c06fe9 --- /dev/null +++ b/examples/embeddable_examples/public/multi_task_todo/multi_task_todo_embeddable.tsx @@ -0,0 +1,99 @@ +/* + * 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, +} from '../../../../src/plugins/embeddable/public'; +import { MultiTaskTodoEmbeddableComponent } from './multi_task_todo_component'; + +export const MULTI_TASK_TODO_EMBEDDABLE = 'MULTI_TASK_TODO_EMBEDDABLE'; + +export interface MultiTaskTodoInput extends EmbeddableInput { + tasks: string[]; + icon?: string; + search?: string; + title: string; +} + +// This embeddable has output! It's the tasks list that is filtered. +// Output state is something only the embeddable itself can update. It +// can be something completely internal, or it can be state that is +// derived from input state and updates when input does. +export interface MultiTaskTodoOutput extends EmbeddableOutput { + tasks: string[]; +} + +function getFilteredTasks(tasks: string[], search?: string) { + const filteredTasks: string[] = []; + if (search === undefined) return tasks; + + tasks.forEach(task => { + if (task.match(search)) { + filteredTasks.push(task); + } + }); + + return filteredTasks; +} + +function getOutput(input: MultiTaskTodoInput) { + const tasks = getFilteredTasks(input.tasks, input.search); + return { tasks, hasMatch: tasks.length > 0 || (input.search && input.title.match(input.search)) }; +} + +export class MultiTaskTodoEmbeddable extends Embeddable { + public readonly type = MULTI_TASK_TODO_EMBEDDABLE; + private subscription: Subscription; + private node?: HTMLElement; + + constructor(initialInput: MultiTaskTodoInput, parent?: IContainer) { + super(initialInput, getOutput(initialInput), parent); + + // If you have any output state that changes as a result of input state changes, you + // should use an subcription. Here, any time input tasks list, or the input filter + // changes, we want to update the output tasks list as well as whether a match has + // been found. + this.subscription = this.getInput$().subscribe(() => { + this.updateOutput(getOutput(this.input)); + }); + } + + public render(node: HTMLElement) { + if (this.node) { + ReactDOM.unmountComponentAtNode(this.node); + } + this.node = node; + ReactDOM.render(, node); + } + + public reload() {} + + public destroy() { + super.destroy(); + this.subscription.unsubscribe(); + if (this.node) { + ReactDOM.unmountComponentAtNode(this.node); + } + } +} diff --git a/examples/embeddable_examples/public/multi_task_todo/multi_task_todo_embeddable_factory.ts b/examples/embeddable_examples/public/multi_task_todo/multi_task_todo_embeddable_factory.ts new file mode 100644 index 0000000000000..37ac63e380f96 --- /dev/null +++ b/examples/embeddable_examples/public/multi_task_todo/multi_task_todo_embeddable_factory.ts @@ -0,0 +1,44 @@ +/* + * 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 { i18n } from '@kbn/i18n'; +import { IContainer, EmbeddableFactory } from '../../../../src/plugins/embeddable/public'; +import { + MultiTaskTodoEmbeddable, + MULTI_TASK_TODO_EMBEDDABLE, + MultiTaskTodoInput, +} from './multi_task_todo_embeddable'; + +export class MultiTaskTodoEmbeddableFactory extends EmbeddableFactory { + public readonly type = MULTI_TASK_TODO_EMBEDDABLE; + + public isEditable() { + return true; + } + + public async create(initialInput: MultiTaskTodoInput, parent?: IContainer) { + return new MultiTaskTodoEmbeddable(initialInput, parent); + } + + public getDisplayName() { + return i18n.translate('embeddableExamples.multiTaskTodo.displayName', { + defaultMessage: 'Multi-task todo item', + }); + } +} diff --git a/examples/embeddable_examples/public/plugin.ts b/examples/embeddable_examples/public/plugin.ts new file mode 100644 index 0000000000000..e75165bfbef18 --- /dev/null +++ b/examples/embeddable_examples/public/plugin.ts @@ -0,0 +1,72 @@ +/* + * 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 { IEmbeddableSetup, IEmbeddableStart } from '../../../src/plugins/embeddable/public'; +import { Plugin, CoreSetup, CoreStart } from '../../../src/core/public'; +import { HelloWorldEmbeddableFactory, HELLO_WORLD_EMBEDDABLE } from './hello_world'; +import { TODO_EMBEDDABLE, TodoEmbeddableFactory } from './todo'; +import { MULTI_TASK_TODO_EMBEDDABLE, MultiTaskTodoEmbeddableFactory } from './multi_task_todo'; +import { + SEARCHABLE_LIST_CONTAINER, + SearchableListContainerFactory, +} from './searchable_list_container'; +import { LIST_CONTAINER, ListContainerFactory } from './list_container'; + +interface EmbeddableExamplesSetupDependencies { + embeddable: IEmbeddableSetup; +} + +interface EmbeddableExamplesStartDependencies { + embeddable: IEmbeddableStart; +} + +export class EmbeddableExamplesPlugin + implements + Plugin { + public setup(core: CoreSetup, deps: EmbeddableExamplesSetupDependencies) { + deps.embeddable.registerEmbeddableFactory( + HELLO_WORLD_EMBEDDABLE, + new HelloWorldEmbeddableFactory() + ); + + deps.embeddable.registerEmbeddableFactory(TODO_EMBEDDABLE, new TodoEmbeddableFactory()); + + deps.embeddable.registerEmbeddableFactory( + MULTI_TASK_TODO_EMBEDDABLE, + new MultiTaskTodoEmbeddableFactory() + ); + } + + public start(core: CoreStart, deps: EmbeddableExamplesStartDependencies) { + // These are registered in the start method because `getEmbeddableFactory ` + // is only available in start. We could reconsider this I think and make it + // available in both. + deps.embeddable.registerEmbeddableFactory( + SEARCHABLE_LIST_CONTAINER, + new SearchableListContainerFactory(deps.embeddable.getEmbeddableFactory) + ); + + deps.embeddable.registerEmbeddableFactory( + LIST_CONTAINER, + new ListContainerFactory(deps.embeddable.getEmbeddableFactory) + ); + } + + public stop() {} +} diff --git a/examples/embeddable_examples/public/searchable_list_container/index.ts b/examples/embeddable_examples/public/searchable_list_container/index.ts new file mode 100644 index 0000000000000..c422fdba5835d --- /dev/null +++ b/examples/embeddable_examples/public/searchable_list_container/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 { SearchableListContainer, SEARCHABLE_LIST_CONTAINER } from './searchable_list_container'; +export { SearchableListContainerFactory } from './searchable_list_container_factory'; diff --git a/examples/embeddable_examples/public/searchable_list_container/searchable_list_container.tsx b/examples/embeddable_examples/public/searchable_list_container/searchable_list_container.tsx new file mode 100644 index 0000000000000..3079abb867c38 --- /dev/null +++ b/examples/embeddable_examples/public/searchable_list_container/searchable_list_container.tsx @@ -0,0 +1,70 @@ +/* + * 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 { + Container, + ContainerInput, + GetEmbeddableFactory, + EmbeddableInput, +} from '../../../../src/plugins/embeddable/public'; +import { SearchableListContainerComponent } from './searchable_list_container_component'; + +export const SEARCHABLE_LIST_CONTAINER = 'SEARCHABLE_LIST_CONTAINER'; + +export interface SearchableContainerInput extends ContainerInput { + search?: string; +} + +interface ChildInput extends EmbeddableInput { + search?: string; +} + +export class SearchableListContainer extends Container { + public readonly type = SEARCHABLE_LIST_CONTAINER; + private node?: HTMLElement; + + constructor(input: SearchableContainerInput, getEmbeddableFactory: GetEmbeddableFactory) { + super(input, { embeddableLoaded: {} }, getEmbeddableFactory); + } + + // TODO: add a more advanced example here where inherited child input is derived from container + // input and not just an exact pass through. + getInheritedInput(id: string) { + return { + id, + search: this.getInput().search, + }; + } + + public render(node: HTMLElement) { + if (this.node) { + ReactDOM.unmountComponentAtNode(this.node); + } + this.node = node; + ReactDOM.render(, node); + } + + public destroy() { + super.destroy(); + if (this.node) { + ReactDOM.unmountComponentAtNode(this.node); + } + } +} diff --git a/examples/embeddable_examples/public/searchable_list_container/searchable_list_container_component.tsx b/examples/embeddable_examples/public/searchable_list_container/searchable_list_container_component.tsx new file mode 100644 index 0000000000000..b79f86e2a0192 --- /dev/null +++ b/examples/embeddable_examples/public/searchable_list_container/searchable_list_container_component.tsx @@ -0,0 +1,188 @@ +/* + * 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, { Component } from 'react'; + +import { + EuiLoadingSpinner, + EuiButton, + EuiFormRow, + EuiFlexGroup, + EuiSpacer, + EuiFlexItem, + EuiFieldText, + EuiPanel, + EuiCheckbox, +} from '@elastic/eui'; +import * as Rx from 'rxjs'; +import { + withEmbeddableSubscription, + ContainerOutput, + EmbeddableOutput, +} from '../../../../src/plugins/embeddable/public'; +import { EmbeddableListItem } from '../list_container/embeddable_list_item'; +import { SearchableListContainer, SearchableContainerInput } from './searchable_list_container'; + +interface Props { + embeddable: SearchableListContainer; + input: SearchableContainerInput; + output: ContainerOutput; +} + +interface State { + checked: { [key: string]: boolean }; + hasMatch: { [key: string]: boolean }; +} + +interface HasMatchOutput { + hasMatch: boolean; +} + +function hasHasMatchOutput(output: EmbeddableOutput | HasMatchOutput): output is HasMatchOutput { + return (output as HasMatchOutput).hasMatch !== undefined; +} + +export class SearchableListContainerComponentInner extends Component { + private subscriptions: { [id: string]: Rx.Subscription } = {}; + constructor(props: Props) { + super(props); + + const checked: { [id: string]: boolean } = {}; + const hasMatch: { [id: string]: boolean } = {}; + props.embeddable.getChildIds().forEach(id => { + checked[id] = false; + const output = props.embeddable.getChild(id).getOutput(); + hasMatch[id] = hasHasMatchOutput(output) && output.hasMatch; + }); + props.embeddable.getChildIds().forEach(id => (checked[id] = false)); + this.state = { + checked, + hasMatch, + }; + } + + componentDidMount() { + this.props.embeddable.getChildIds().forEach(id => { + this.subscriptions[id] = this.props.embeddable + .getChild(id) + .getOutput$() + .subscribe(output => { + if (hasHasMatchOutput(output)) { + this.setState(prevState => ({ + hasMatch: { + ...prevState.hasMatch, + [id]: output.hasMatch, + }, + })); + } + }); + }); + } + + componentWillUnmount() { + Object.values(this.subscriptions).forEach(sub => sub.unsubscribe()); + } + + private updateSearch = (search: string) => { + this.props.embeddable.updateInput({ search }); + }; + + private deleteChecked = () => { + Object.values(this.props.input.panels).map(panel => { + if (this.state.checked[panel.explicitInput.id]) { + this.props.embeddable.removeEmbeddable(panel.explicitInput.id); + this.subscriptions[panel.explicitInput.id].unsubscribe(); + } + }); + }; + + private toggleCheck = (isChecked: boolean, id: string) => { + this.setState(prevState => ({ checked: { ...prevState.checked, [id]: isChecked } })); + }; + + public renderControls() { + return ( + + + + this.deleteChecked()}> + Delete checked + + + + + + this.updateSearch(ev.target.value)} + /> + + + + + ); + } + + public render() { + const { embeddable } = this.props; + return ( +
+

{embeddable.getTitle()}

+ + {this.renderControls()} + + {this.renderList()} +
+ ); + } + + private renderList() { + let id = 0; + const list = Object.values(this.props.input.panels).map(panel => { + const embeddable = this.props.embeddable.getChild(panel.explicitInput.id); + if (this.props.input.search && !this.state.hasMatch[panel.explicitInput.id]) return; + id++; + return embeddable ? ( + + + + this.toggleCheck(e.target.checked, embeddable.id)} + /> + + + + + + + ) : ( + + ); + }); + return list; + } +} + +export const SearchableListContainerComponent = withEmbeddableSubscription( + SearchableListContainerComponentInner +); diff --git a/examples/embeddable_examples/public/searchable_list_container/searchable_list_container_factory.ts b/examples/embeddable_examples/public/searchable_list_container/searchable_list_container_factory.ts new file mode 100644 index 0000000000000..359878857eebb --- /dev/null +++ b/examples/embeddable_examples/public/searchable_list_container/searchable_list_container_factory.ts @@ -0,0 +1,49 @@ +/* + * 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 { i18n } from '@kbn/i18n'; +import { EmbeddableFactory, GetEmbeddableFactory } from '../../../../src/plugins/embeddable/public'; +import { + SEARCHABLE_LIST_CONTAINER, + SearchableListContainer, + SearchableContainerInput, +} from './searchable_list_container'; + +export class SearchableListContainerFactory extends EmbeddableFactory { + public readonly type = SEARCHABLE_LIST_CONTAINER; + public readonly isContainerType = true; + + constructor(private getEmbeddableFactory: GetEmbeddableFactory) { + super(); + } + + public isEditable() { + return true; + } + + public async create(initialInput: SearchableContainerInput) { + return new SearchableListContainer(initialInput, this.getEmbeddableFactory); + } + + public getDisplayName() { + return i18n.translate('embeddableExamples.searchableListContainer.displayName', { + defaultMessage: 'Searchable list container', + }); + } +} diff --git a/examples/embeddable_examples/public/todo/index.ts b/examples/embeddable_examples/public/todo/index.ts new file mode 100644 index 0000000000000..cac0b85b40d5c --- /dev/null +++ b/examples/embeddable_examples/public/todo/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 './todo_embeddable'; +export * from './todo_embeddable_factory'; diff --git a/examples/embeddable_examples/public/todo/todo_component.tsx b/examples/embeddable_examples/public/todo/todo_component.tsx new file mode 100644 index 0000000000000..fbebfc98627b5 --- /dev/null +++ b/examples/embeddable_examples/public/todo/todo_component.tsx @@ -0,0 +1,74 @@ +/* + * 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 } from '@elastic/eui'; + +import { EuiText } from '@elastic/eui'; +import { EuiAvatar } from '@elastic/eui'; +import { EuiIcon } from '@elastic/eui'; +import { EuiFlexGrid } from '@elastic/eui'; +import { + withEmbeddableSubscription, + EmbeddableOutput, +} from '../../../../src/plugins/embeddable/public'; +import { TodoEmbeddable, TodoInput } from './todo_embeddable'; + +interface Props { + embeddable: TodoEmbeddable; + input: TodoInput; + output: EmbeddableOutput; +} + +function wrapSearchTerms(task: string, search?: string) { + if (!search) return task; + const parts = task.split(new RegExp(`(${search})`, 'g')); + return parts.map((part, i) => + part === search ? ( + + {part} + + ) : ( + part + ) + ); +} + +export function TodoEmbeddableComponentInner({ input: { icon, title, task, search } }: Props) { + return ( + + + {icon ? : } + + + + + +

{wrapSearchTerms(title || '', search)}

+
+
+ + {wrapSearchTerms(task, search)} + +
+
+
+ ); +} + +export const TodoEmbeddableComponent = withEmbeddableSubscription(TodoEmbeddableComponentInner); diff --git a/examples/embeddable_examples/public/todo/todo_embeddable.tsx b/examples/embeddable_examples/public/todo/todo_embeddable.tsx new file mode 100644 index 0000000000000..b081253d86341 --- /dev/null +++ b/examples/embeddable_examples/public/todo/todo_embeddable.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 from 'react'; +import ReactDOM from 'react-dom'; +import { Subscription } from 'rxjs'; +import { + Embeddable, + EmbeddableInput, + IContainer, + EmbeddableOutput, +} from '../../../../src/plugins/embeddable/public'; +import { TodoEmbeddableComponent } from './todo_component'; + +export const TODO_EMBEDDABLE = 'TODO_EMBEDDABLE'; + +export interface TodoInput extends EmbeddableInput { + task: string; + icon?: string; + search?: string; +} + +export interface TodoOutput extends EmbeddableOutput { + hasMatch: boolean; +} + +function getOutput(input: TodoInput): TodoOutput { + return { + hasMatch: input.search + ? Boolean(input.task.match(input.search) || (input.title && input.title.match(input.search))) + : true, + }; +} + +export class TodoEmbeddable extends Embeddable { + // The type of this embeddable. This will be used to find the appropriate factory + // to instantiate this kind of embeddable. + public readonly type = TODO_EMBEDDABLE; + private subscription: Subscription; + private node?: HTMLElement; + + constructor(initialInput: TodoInput, parent?: IContainer) { + super(initialInput, getOutput(initialInput), parent); + + // If you have any output state that changes as a result of input state changes, you + // should use an subcription. Here, we use output to indicate whether this task + // matches the search string. + this.subscription = this.getInput$().subscribe(() => { + this.updateOutput(getOutput(this.input)); + }); + } + + public render(node: HTMLElement) { + this.node = node; + if (this.node) { + ReactDOM.unmountComponentAtNode(this.node); + } + ReactDOM.render(, node); + } + + /** + * Not relevant. + */ + public reload() {} + + public destroy() { + super.destroy(); + this.subscription.unsubscribe(); + if (this.node) { + ReactDOM.unmountComponentAtNode(this.node); + } + } +} diff --git a/examples/embeddable_examples/public/todo/todo_embeddable_factory.ts b/examples/embeddable_examples/public/todo/todo_embeddable_factory.ts new file mode 100644 index 0000000000000..386b3f296d998 --- /dev/null +++ b/examples/embeddable_examples/public/todo/todo_embeddable_factory.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 { i18n } from '@kbn/i18n'; +import { IContainer, EmbeddableFactory } from '../../../../src/plugins/embeddable/public'; +import { TodoEmbeddable, TODO_EMBEDDABLE, TodoInput } from './todo_embeddable'; + +export class TodoEmbeddableFactory extends EmbeddableFactory { + public readonly type = TODO_EMBEDDABLE; + + public isEditable() { + return true; + } + + public async create(initialInput: TodoInput, parent?: IContainer) { + return new TodoEmbeddable(initialInput, parent); + } + + public getDisplayName() { + return i18n.translate('embeddableExamples.todo.displayName', { + defaultMessage: 'Todo item', + }); + } +} diff --git a/examples/embeddable_examples/tsconfig.json b/examples/embeddable_examples/tsconfig.json new file mode 100644 index 0000000000000..091130487791b --- /dev/null +++ b/examples/embeddable_examples/tsconfig.json @@ -0,0 +1,15 @@ +{ + "extends": "../../tsconfig.json", + "compilerOptions": { + "outDir": "./target", + "skipLibCheck": true + }, + "include": [ + "index.ts", + "public/**/*.ts", + "public/**/*.tsx", + "server/**/*.ts", + "../../typings/**/*" + ], + "exclude": [] +} diff --git a/examples/embeddable_explorer/kibana.json b/examples/embeddable_explorer/kibana.json new file mode 100644 index 0000000000000..4ca63e1a36242 --- /dev/null +++ b/examples/embeddable_explorer/kibana.json @@ -0,0 +1,10 @@ +{ + "id": "embeddableExplorer", + "version": "0.0.1", + "kibanaVersion": "kibana", + "configPath": ["embeddable_explorer"], + "server": false, + "ui": true, + "requiredPlugins": ["embeddable", "embeddableExamples"], + "optionalPlugins": [] +} diff --git a/examples/embeddable_explorer/package.json b/examples/embeddable_explorer/package.json new file mode 100644 index 0000000000000..771c5c9be9c06 --- /dev/null +++ b/examples/embeddable_explorer/package.json @@ -0,0 +1,17 @@ +{ + "name": "embeddable_explorer", + "version": "1.0.0", + "main": "target/examples/embeddable_explorer", + "kibana": { + "version": "kibana", + "templateVersion": "1.0.0" + }, + "license": "Apache-2.0", + "scripts": { + "kbn": "node ../../scripts/kbn.js", + "build": "rm -rf './target' && tsc" + }, + "devDependencies": { + "typescript": "3.7.2" + } +} diff --git a/examples/embeddable_explorer/public/app.tsx b/examples/embeddable_explorer/public/app.tsx new file mode 100644 index 0000000000000..be27fd04556ea --- /dev/null +++ b/examples/embeddable_explorer/public/app.tsx @@ -0,0 +1,126 @@ +/* + * 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, EuiSideNav } from '@elastic/eui'; + +import { IEmbeddableStart } from 'src/plugins/embeddable/public'; +import { AppMountContext, AppMountParameters, CoreStart } from '../../../src/core/public'; +import { HelloWorldEmbeddableExample } from './hello_world_embeddable_example'; +import { TodoEmbeddableExample } from './todo_embeddable_example'; +import { ListContainerExample } from './list_container_example'; + +interface PageDef { + title: string; + id: string; + component: React.ReactNode; +} + +type NavProps = RouteComponentProps & { + navigateToApp: AppMountContext['core']['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 EmbeddableExplorerApp = ({ + basename, + navigateToApp, + embeddableApi, +}: { + basename: string; + navigateToApp: CoreStart['application']['navigateToApp']; + embeddableApi: IEmbeddableStart; +}) => { + const pages: PageDef[] = [ + { + title: 'Hello world embeddable', + id: 'helloWorldEmbeddableSection', + component: ( + + ), + }, + { + title: 'Todo embeddable', + id: 'todoEmbeddableSection', + component: ( + + ), + }, + { + title: 'List container embeddable', + id: 'listContainerSection', + component: , + }, + ]; + + const routes = pages.map((page, i) => ( + page.component} /> + )); + + return ( + + + +