Merge branch 'main' into kql-named-arg

NOTICE.txt

@@ -295,7 +295,7 @@ MIT License http://www.opensource.org/licenses/mit-license
 ---
 This product includes code that is adapted from mapbox-gl-js, which is
 available under a "BSD-3-Clause" license.
-https://github.com/mapbox/mapbox-gl-js/blob/master/src/util/image.js
+https://github.com/mapbox/mapbox-gl-js/blob/v1.13.2/src/util/image.js
 
 Copyright (c) 2016, Mapbox
 

dev_docs/api_welcome.mdx

@@ -44,7 +44,7 @@ This documentation is being automatically generated using an
 There is one extra step required to have your API docs show up in the _navigation_ of the docs system. Follow
 the instructions <DocLink id="docsSetup" section="configure-the-nav-for-your-content" text="here" /> to learn how to 
 configure the navigation menu.  The nav file you need to
- edit is: [https://github.com/elastic/elastic-docs/blob/master/config/nav-kibana-dev.ts](https://github.com/elastic/elastic-docs/blob/master/config/nav-kibana-dev.ts)
+ edit is: [https://github.com/elastic/elastic-docs/blob/main/config/nav-kibana-dev.ts](https://github.com/elastic/elastic-docs/blob/main/config/nav-kibana-dev.ts)
 
 Your API docs will exist in the top level [`api_docs` folder](https://github.com/elastic/kibana/tree/main/api_docs) and will use a doc id of the pattern `kib${PluginName}PluginApi`.
 

dev_docs/contributing/best_practices.mdx

@@ -141,6 +141,9 @@ export type foo: string | AnInterface;
 
 Running Kibana with `yarn start --run-examples` will include all [example plugins](https://github.com/elastic/kibana/tree/main/examples). These are tested examples of platform services in use. We strongly encourage anyone providing a platform level service or <DocLink id="kibBuildingBlocks" text="building block"/> to include a tutorial that links to a tested example plugin. This is better than relying on copied code snippets, which can quickly get out of date.
 
+You can also visit these [examples plugins hosted online](https://demo.kibana.dev/8.0/app/home). Note that because anonymous access is enabled, some
+of the demos are currently not working. 
+
 ## Performance
 
 Build with scalability in mind.
@@ -150,6 +153,8 @@ Build with scalability in mind.
 - Consider large data sets, that span a long time range
 - Consider slow internet and low bandwidth environments
 
+<DocLink id="kibDevPerformance" text="Read more about performance."/>
+
 ## Accessibility
 
 Did you know Kibana makes a public statement about our commitment to creating an accessible product for people
@@ -202,13 +207,13 @@ Kibana code base, try not to contribute to this volatility. Doing this can:
 
 All of the above contributes to more bugs being found in the QA cycle and can cause a delay in the release. Prefer instead to merge
 your large change right _after_ feature freeze. If you are worried about missing your initial release version goals, review our
-[release train philophy](https://github.com/elastic/dev/blob/master/shared/time-based-releases.md). It's okay!
+<DocLink id="devTimeBasedReleases" text="release train philosophy"/>. It's okay!
 
 </DocCallOut>
 
 ### Size
 
-When possible, build features with incrementals sets of small and focused PRs, but don't check in unused code, and don't expose any feature on master that you would not be comfortable releasing.
+When possible, build features with incremental sets of small and focused PRs, but don't check in unused code, and don't expose any feature on main that you would not be comfortable releasing.
 
 ![product_stages](../assets/product_stages.png)
 

dev_docs/contributing/code_walkthrough.mdx

@@ -21,7 +21,7 @@ Managed by the operations team to contain Jenkins settings. Can be ignored by fo
 
 ## [.github](https://github.com/elastic/kibana/tree/main/.github)
 
-Contains GitHub configuration settings. This file contains issue templates, and the [CODEOWNERS](https://github.com/elastic/kibana/blob/main/.github/CODEOWNERS) file. It's important for teams to keep the CODEOWNERS file up-to-date so the right team is pinged for a code owner review on PRs that edit certain files. Note that the `CODEOWNERS` file only exists on the main/master branch, and is not backported to other branches in the repo.
+Contains GitHub configuration settings. This file contains issue templates, and the [CODEOWNERS](https://github.com/elastic/kibana/blob/main/.github/CODEOWNERS) file. It's important for teams to keep the CODEOWNERS file up-to-date so the right team is pinged for a code owner review on PRs that edit certain files. Note that the `CODEOWNERS` file only exists on the main branch, and is not backported to other branches in the repo.
 
 ## [api_docs](https://github.com/elastic/kibana/tree/main/api_docs)
 

dev_docs/contributing/how_we_use_github.mdx

@@ -15,16 +15,14 @@ We follow the [GitHub forking model](https://help.github.com/articles/fork-a-rep
 
 At Elastic, all products in the stack, including Kibana, are released at the same time with the same version number. Most of these projects have the following branching strategy:
 
-- master is the next major version.
-- `<major>.x` is the next minor version.
-- `<major>.<minor>` is the next release of a minor version, including patch releases.
+- `main` points to the next minor version.
+- `<major>.<minor>` is the previously released minor version, including patch releases.
 
-As an example, let’s assume that the 7.x branch is currently a not-yet-released 7.6.0. Once 7.6.0 has reached feature freeze, it will be branched to 7.6 and 7.x will be updated to reflect 7.7.0. The release of 7.6.0 and subsequent patch releases will be cut from the 7.6 branch. At any time, you can verify the current version of a branch by inspecting the version attribute in the package.json file within the Kibana source.
+As an example, let’s assume that the main branch is currently a not-yet-released 8.1.0. Once 8.1.0 has reached feature freeze, it will be branched to 8.1 and main will be updated to reflect 8.2.0. The release of 8.1.0 and subsequent patch releases will be cut from the 8.1 branch. At any time, you can verify the current version of a branch by inspecting the version attribute in the package.json file within the Kibana source.
 
-Pull requests are made into the master branch and then backported when it is safe and appropriate.
+Pull requests are made into the main branch and only backported when it is safe and appropriate.
 
-- Breaking changes do not get backported and only go into master.
-- All non-breaking changes can be backported to the `<major>.x` branch.
+- Breaking changes can _only_ be made to `main` if there has been at least an 18 month deprecation period _and_ the breaking change has been approved. Telemetry showing current usage is crucial for gaining approval.
 - Features should not be backported to a `<major>.<minor>` branch.
 - Bug fixes can be backported to a `<major>.<minor>` branch if the changes are safe and appropriate. Safety is a judgment call you make based on factors like the bug’s severity, test coverage, confidence in the changes, etc. Your reasoning should be included in the pull request description.
 - Documentation changes can be backported to any branch at any time.
@@ -63,26 +61,26 @@ In order to assist with developer tooling we ask that all Elastic engineers use
 
 Rebasing can be tricky, and fixing merge conflicts can be even trickier because it involves force pushing. This is all compounded by the fact that attempting to push a rebased branch remotely will be rejected by git, and you’ll be prompted to do a pull, which is not at all what you should do (this will really mess up your branch’s history).
 
-Here’s how you should rebase master onto your branch, and how to fix merge conflicts when they arise.
+Here’s how you should rebase main onto your branch, and how to fix merge conflicts when they arise.
 
-First, make sure master is up-to-date.
+First, make sure main is up-to-date.
 
 ```bash
-git checkout master
+git checkout main
 git fetch upstream
-git rebase upstream/master
+git rebase upstream/main
 ```
 
-Then, check out your branch and rebase master on top of it, which will apply all of the new commits on master to your branch, and then apply all of your branch’s new commits after that.
+Then, check out your branch and rebase main on top of it, which will apply all of the new commits on main to your branch, and then apply all of your branch’s new commits after that.
 
 ```bash
 git checkout name-of-your-branch
-git rebase master
+git rebase main
 ```
 
 You want to make sure there are no merge conflicts. If there are merge conflicts, git will pause the rebase and allow you to fix the conflicts before continuing.
 
-You can use git status to see which files contain conflicts. They’ll be the ones that aren’t staged for commit. Open those files, and look for where git has marked the conflicts. Resolve the conflicts so that the changes you want to make to the code have been incorporated in a way that doesn’t destroy work that’s been done in master. Refer to master’s commit history on GitHub if you need to gain a better understanding of how code is conflicting and how best to resolve it.
+You can use git status to see which files contain conflicts. They’ll be the ones that aren’t staged for commit. Open those files, and look for where git has marked the conflicts. Resolve the conflicts so that the changes you want to make to the code have been incorporated in a way that doesn’t destroy work that’s been done in main. Refer to main commit history on GitHub if you need to gain a better understanding of how code is conflicting and how best to resolve it.
 
 Once you’ve resolved all of the merge conflicts, use git add -A to stage them to be committed, and then use git rebase --continue to tell git to continue the rebase.
 

dev_docs/tutorials/expressions.mdx

@@ -57,7 +57,7 @@ const result = await executionContract.getData();
 ```
 
 <DocCallOut>
-  Check the full spec of execute function [here](https://github.com/elastic/kibana/blob/main/docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.execution.md)
+  Check the full spec of execute function <DocLink id="kibExpressionsPluginApi" section="def-common.ExpressionsService.execute" text="here" />
 </DocCallOut>
 
 In addition, on the browser side, there are two additional ways to run expressions and render the results.
@@ -71,7 +71,7 @@ This is the easiest way to get expressions rendered inside your application.
 ```
 
 <DocCallOut>
-  Check the full spec of ReactExpressionRenderer component props [here](https://github.com/elastic/kibana/blob/main/docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.reactexpressionrendererprops.md)
+  Check the full spec of ReactExpressionRenderer component props <DocLink id="kibExpressionsPluginApi" section="def-public.ReactExpressionRendererProps" text="here" />
 </DocCallOut>
 
 #### Expression loader
@@ -83,7 +83,7 @@ const handler = loader(domElement, expression, params);
 ```
 
 <DocCallOut>
-  Check the full spec of expression loader params [here](https://github.com/elastic/kibana/blob/main/docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.iexpressionloaderparams.md)
+  Check the full spec of expression loader params <DocLink id="kibExpressionsPluginApi" section="def-public.IExpressionLoaderParams" text="here" />
 </DocCallOut>
 
 ### Creating new expression functions
@@ -106,7 +106,7 @@ expressions.registerFunction(functionDefinition);
 ```
 
 <DocCallOut>
-  Check the full interface of ExpressionFuntionDefinition [here](https://github.com/elastic/kibana/blob/main/docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.expressionfunctiondefinition.md)
+  Check the full interface of ExpressionFuntionDefinition <DocLink id="kibExpressionsPluginApi" section="def-common.ExpressionFunctionDefinition" text="here" />
 </DocCallOut>
 
 ### Creating new expression renderers
@@ -128,5 +128,5 @@ expressions.registerRenderer(rendererDefinition);
 ```
 
 <DocCallOut>
-  Check the full interface of ExpressionRendererDefinition [here](https://github.com/elastic/kibana/blob/main/docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.expressionrenderdefinition.md)
+  Check the full interface of ExpressionRendererDefinition <DocLink id="kibExpressionsPluginApi" section="def-common.ExpressionRenderDefinition" text="here" />
 </DocCallOut>

dev_docs/tutorials/submit_a_pull_request.mdx

@@ -23,7 +23,7 @@ After cloning your fork and navigating to the directory containing your fork:
 
 ```bash
 # Make sure you currently have the branch checked out off of which you'd like to work
-git checkout master
+git checkout main
 
 # Create a new branch
 git checkout -b fix-typos-in-readme
@@ -76,7 +76,7 @@ See [Pull request review guidelines](https://www.elastic.co/guide/en/kibana/mast
 
 ## Updating your PR with upstream
 
-If your pull request hasn't been updated with the latest code from the upstream/target branch, e.g. `master`, in the last 48 hours, it won't be able to merge until it is updated. This is to help prevent problems that could occur by merging stale code into upstream, e.g. something new was recently merged that is incompatible with something in your pull request.
+If your pull request hasn't been updated with the latest code from the upstream/target branch, e.g. `main`, in the last 48 hours, it won't be able to merge until it is updated. This is to help prevent problems that could occur by merging stale code into upstream, e.g. something new was recently merged that is incompatible with something in your pull request.
 
 As an alternative to using `git` to manually update your branch, you can leave a comment on your pull request with the text `@elasticmachine merge upstream`. This will automatically update your branch and kick off CI for it.
 

docs/developer/getting-started/debugging.asciidoc

@@ -130,71 +130,3 @@ Once you're finished, you can stop Kibana normally, then stop the {es} and APM s
 ----
 ./scripts/compose.py stop
 ----
-
-=== Using {kib} server logs
-{kib} Logs is a great way to see what's going on in your application and to debug performance issues. Navigating through a large number of generated logs can be overwhelming, and following are some techniques that you can use to optimize the process.
-
-Start by defining a problem area that you are interested in. For example, you might be interested in seeing how a particular {kib} Plugin is performing, so no need to gather logs for all of {kib}. Or you might want to focus on a particular feature, such as requests from the {kib} server to the {es} server.
-Depending on your needs, you can configure {kib} to generate logs for a specific feature.
-[source,yml]
-----
-logging:
-  appenders:
-    file:
-      type: file
-      fileName: ./kibana.log
-      layout:
-        type: json
-
-### gather all the Kibana logs into a file
-logging.root:
-    appenders: [file]
-    level: all
-
-### or gather a subset of the logs
-logging.loggers:
-  ### responses to an HTTP request
-  - name: http.server.response
-    level: debug
-    appenders: [file]
-  ### result of a query to the Elasticsearch server
-  - name: elasticsearch.query
-    level: debug
-    appenders: [file]
-  ### logs generated by my plugin
-  - name: plugins.myPlugin
-    level: debug
-    appenders: [file]
-----
-WARNING: Kibana's `file` appender is configured to produce logs in https://www.elastic.co/guide/en/ecs/master/ecs-reference.html[ECS JSON] format. It's the only format that includes the meta information necessary for https://www.elastic.co/guide/en/apm/agent/nodejs/current/log-correlation.html[log correlation] out-of-the-box.
-
-The next step is to define what https://www.elastic.co/observability[observability tools] are available. 
-For a better experience, set up an https://www.elastic.co/guide/en/apm/get-started/current/observability-integrations.html[Observability integration] provided by Elastic to debug your application with the <<debugging-logs-apm-ui, APM UI.>>
-To debug something quickly without setting up additional tooling, you can work with <<plain-kibana-logs, the plain {kib} logs.>>
-
-[[debugging-logs-apm-ui]]
-==== APM UI
-*Prerequisites* {kib} logs are configured to be in https://www.elastic.co/guide/en/ecs/master/ecs-reference.html[ECS JSON] format to include tracing identifiers.
-
-To debug {kib} with the APM UI, you must set up the APM infrastructure. You can find instructions for the setup process
-https://www.elastic.co/guide/en/apm/get-started/current/observability-integrations.html[on the Observability integrations page].
-
-Once you set up the APM infrastructure, you can enable the APM agent and put {kib} under load to collect APM events. To analyze the collected metrics and logs, use the APM UI as demonstrated https://www.elastic.co/guide/en/kibana/master/transactions.html#transaction-trace-sample[in the docs].
-
-[[plain-kibana-logs]]
-==== Plain {kib} logs
-*Prerequisites* {kib} logs are configured to be in https://www.elastic.co/guide/en/ecs/master/ecs-reference.html[ECS JSON] format to include tracing identifiers.
-
-Open {kib} Logs and search for an operation you are interested in.
-For example, suppose you want to investigate the response times for queries to the `/api/telemetry/v2/clusters/_stats` {kib} endpoint.
-Open Kibana Logs and search for the HTTP server response for the endpoint. It looks similar to the following (some fields are omitted for brevity).
-[source,json]
-----
-{
-  "message":"POST /api/telemetry/v2/clusters/_stats 200 1014ms - 43.2KB",
-  "log":{"level":"DEBUG","logger":"http.server.response"},
-  "trace":{"id":"9b99131a6f66587971ef085ef97dfd07"},
-  "transaction":{"id":"d0c5bbf14f5febca"}
-}
-----
-You are interested in the https://www.elastic.co/guide/en/ecs/current/ecs-tracing.html#field-trace-id[trace.id] field, which is a unique identifier of a trace. The `trace.id` provides a way to group multiple events, like transactions, which belong together. You can search for `"trace":{"id":"9b99131a6f66587971ef085ef97dfd07"}` to get all the logs that belong to the same trace. This enables you to see how many {es} requests were triggered during the `9b99131a6f66587971ef085ef97dfd07` trace, what they looked like, what {es} endpoints were hit, and so on.