Skip to content

Commit

Permalink
Merge branch 'master' into apm-fleet-tutorial
Browse files Browse the repository at this point in the history
  • Loading branch information
kibanamachine authored Jun 16, 2021
2 parents 7e441d2 + 036c157 commit f5c3464
Show file tree
Hide file tree
Showing 768 changed files with 18,532 additions and 12,997 deletions.
3 changes: 2 additions & 1 deletion .ci/Jenkinsfile_flaky
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ library 'kibana-pipeline-library'
kibanaLibrary.load()

def TASK_PARAM = params.TASK ?: params.CI_GROUP

// Looks like 'oss:ciGroup:1', 'oss:firefoxSmoke'
def JOB_PARTS = TASK_PARAM.split(':')
def IS_XPACK = JOB_PARTS[0] == 'xpack'
Expand Down Expand Up @@ -111,6 +110,8 @@ def getWorkerFromParams(isXpack, job, ciGroup) {
return kibanaPipeline.scriptTaskDocker('Jest Integration Tests', 'test/scripts/test/jest_integration.sh')
} else if (job == 'apiIntegration') {
return kibanaPipeline.scriptTask('API Integration Tests', 'test/scripts/test/api_integration.sh')
} else if (job == 'pluginFunctional') {
return kibanaPipeline.functionalTestProcess('oss-pluginFunctional', './test/scripts/jenkins_plugin_functional.sh')
} else {
return kibanaPipeline.ossCiGroupProcess(ciGroup)
}
Expand Down
4 changes: 2 additions & 2 deletions .ci/end2end.groovy
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,12 @@ pipeline {
BASE_DIR = 'src/github.com/elastic/kibana'
HOME = "${env.WORKSPACE}"
E2E_DIR = 'x-pack/plugins/apm/e2e'
PIPELINE_LOG_LEVEL = 'DEBUG'
PIPELINE_LOG_LEVEL = 'INFO'
KBN_OPTIMIZER_THEMES = 'v7light'
}
options {
timeout(time: 1, unit: 'HOURS')
buildDiscarder(logRotator(numToKeepStr: '40', artifactNumToKeepStr: '20', daysToKeepStr: '30'))
buildDiscarder(logRotator(numToKeepStr: '30', artifactNumToKeepStr: '10', daysToKeepStr: '30'))
timestamps()
ansiColor('xterm')
disableResume()
Expand Down
79 changes: 59 additions & 20 deletions dev_docs/tutorials/building_a_plugin.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ slug: /kibana-dev-docs/tutorials/build-a-plugin
title: Kibana plugin tutorial
summary: Anatomy of a Kibana plugin and how to build one
date: 2021-02-05
tags: ['kibana','onboarding', 'dev', 'tutorials']
tags: ['kibana', 'onboarding', 'dev', 'tutorials']
---

Prereading material:
Expand All @@ -14,7 +14,7 @@ Prereading material:
## The anatomy of a plugin

Plugins are defined as classes and present themselves to Kibana through a simple wrapper function. A plugin can have browser-side code, server-side code,
or both. There is no architectural difference between a plugin in the browser and a plugin on the server. In both places, you describe your plugin similarly,
or both. There is no architectural difference between a plugin in the browser and a plugin on the server. In both places, you describe your plugin similarly,
and you interact with Core and other plugins in the same way.

The basic file structure of a Kibana plugin named demo that has both client-side and server-side code would be:
Expand All @@ -33,7 +33,7 @@ plugins/
index.ts [6]
```

### [1] kibana.json
### [1] kibana.json

`kibana.json` is a static manifest file that is used to identify the plugin and to specify if this plugin has server-side code, browser-side code, or both:

Expand All @@ -42,14 +42,33 @@ plugins/
"id": "demo",
"version": "kibana",
"server": true,
"ui": true
"ui": true,
"owner": { [1]
"name": "App Services",
"githubTeam": "kibana-app-services"
},
"description": "This plugin extends Kibana by doing xyz, and allows other plugins to extend Kibana by offering abc functionality. It also exposes some helper utilities that do efg", [2]
"requiredPlugins": ["data"], [3]
"optionalPlugins": ["alerting"] [4]
"requiredBundles": ["anotherPlugin"] [5]
}
```

[1], [2]: Every internal plugin should fill in the owner and description properties.

[3], [4]: Any plugin that you have a dependency on should be listed in `requiredPlugins` or `optionalPlugins`. Doing this will ensure that you have access to that plugin's start and setup contract inside your own plugin's start and setup lifecycle methods. If a plugin you optionally depend on is not installed or disabled, it will be undefined if you try to access it. If a plugin you require is not installed or disabled, kibana will fail to build.

[5]: Don't worry too much about getting 5 right. The build optimizer will complain if any of these values are incorrect.


<DocCallOut>
You don't need to declare a dependency on a plugin if you only wish to access its types.
</DocCallOut>

### [2] public/index.ts

`public/index.ts` is the entry point into the client-side code of this plugin. It must export a function named plugin, which will receive a standard set of
core capabilities as an argument. It should return an instance of its plugin class for Kibana to load.
`public/index.ts` is the entry point into the client-side code of this plugin. Everything exported from this file will be a part of the plugins <DocLink id="kibPlatformIntro" section="public-plugin-api" text="public API"/>. If the plugin only exists to export static utilities, consider using a package. Otherwise, this file must export a function named plugin, which will receive a standard set of
core capabilities as an argument. It should return an instance of its plugin class for Kibana to load.

```
import type { PluginInitializerContext } from 'kibana/server';
Expand All @@ -60,13 +79,32 @@ export function plugin(initializerContext: PluginInitializerContext) {
}
```

<DocCallOut title="Best practices for every top level index.ts file">

1. When possible, use

```
export type { AType } from '...'`
```

instead of

```
export { AType } from '...'`.
```

Using the non-`type` variation will increase the bundle size unnecessarily and may unwillingly provide access to the implementation of `AType` class.

2. Don't use `export *` in these top level index.ts files

</DocCallOut>

### [3] public/plugin.ts

`public/plugin.ts` is the client-side plugin definition itself. Technically speaking, it does not need to be a class or even a separate file from the entry
point, but all plugins at Elastic should be consistent in this way.
point, but all plugins at Elastic should be consistent in this way.


```ts
```ts
import type { Plugin, PluginInitializerContext, CoreSetup, CoreStart } from 'kibana/server';

export class DemoPlugin implements Plugin {
Expand All @@ -84,10 +122,9 @@ export class DemoPlugin implements Plugin {
// called when plugin is torn down during Kibana's shutdown sequence
}
}
```

```

### [4] server/index.ts
### [4] server/index.ts

`server/index.ts` is the entry-point into the server-side code of this plugin. It is identical in almost every way to the client-side entry-point:

Expand Down Expand Up @@ -115,7 +152,7 @@ export class DemoPlugin implements Plugin {
}
```

Kibana does not impose any technical restrictions on how the the internals of a plugin are architected, though there are certain
Kibana does not impose any technical restrictions on how the the internals of a plugin are architected, though there are certain
considerations related to how plugins integrate with core APIs and APIs exposed by other plugins that may greatly impact how they are built.

### [6] common/index.ts
Expand All @@ -124,8 +161,8 @@ considerations related to how plugins integrate with core APIs and APIs exposed

## How plugin's interact with each other, and Core

The lifecycle-specific contracts exposed by core services are always passed as the first argument to the equivalent lifecycle function in a plugin.
For example, the core http service exposes a function createRouter to all plugin setup functions. To use this function to register an HTTP route handler,
The lifecycle-specific contracts exposed by core services are always passed as the first argument to the equivalent lifecycle function in a plugin.
For example, the core http service exposes a function createRouter to all plugin setup functions. To use this function to register an HTTP route handler,
a plugin just accesses it off of the first argument:

```ts
Expand All @@ -135,14 +172,16 @@ export class DemoPlugin {
public setup(core: CoreSetup) {
const router = core.http.createRouter();
// handler is called when '/path' resource is requested with `GET` method
router.get({ path: '/path', validate: false }, (context, req, res) => res.ok({ content: 'ok' }));
router.get({ path: '/path', validate: false }, (context, req, res) =>
res.ok({ content: 'ok' })
);
}
}
```

Unlike core, capabilities exposed by plugins are not automatically injected into all plugins.
Instead, if a plugin wishes to use the public interface provided by another plugin, it must first declare that plugin as a
dependency in its kibana.json manifest file.
dependency in it’s kibana.json manifest file.

** foobar plugin.ts: **

Expand Down Expand Up @@ -174,8 +213,8 @@ export class MyPlugin implements Plugin<FoobarPluginSetup, FoobarPluginStart> {
}
}
```
[1] We highly encourage plugin authors to explicitly declare public interfaces for their plugins.

[1] We highly encourage plugin authors to explicitly declare public interfaces for their plugins.

** demo kibana.json**

Expand All @@ -194,7 +233,7 @@ With that specified in the plugin manifest, the appropriate interfaces are then
import type { CoreSetup, CoreStart } from 'kibana/server';
import type { FoobarPluginSetup, FoobarPluginStart } from '../../foobar/server';

interface DemoSetupPlugins { [1]
interface DemoSetupPlugins { [1]
foobar: FoobarPluginSetup;
}

Expand All @@ -218,7 +257,7 @@ export class DemoPlugin {
public stop() {}
}
```

[1] The interface for plugin’s dependencies must be manually composed. You can do this by importing the appropriate type from the plugin and constructing an interface where the property name is the plugin’s ID.

[2] These manually constructed types should then be used to specify the type of the second argument to the plugin.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ Note that when generating absolute urls, the origin (protocol, host and port) ar
getUrlForApp(appId: string, options?: {
path?: string;
absolute?: boolean;
deepLinkId?: string;
}): string;
```

Expand All @@ -24,7 +25,7 @@ getUrlForApp(appId: string, options?: {
| Parameter | Type | Description |
| --- | --- | --- |
| appId | <code>string</code> | |
| options | <code>{</code><br/><code> path?: string;</code><br/><code> absolute?: boolean;</code><br/><code> }</code> | |
| options | <code>{</code><br/><code> path?: string;</code><br/><code> absolute?: boolean;</code><br/><code> deepLinkId?: string;</code><br/><code> }</code> | |

<b>Returns:</b>

Expand Down
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [Plugin](./kibana-plugin-plugins-data-public.plugin.md) &gt; [(constructor)](./kibana-plugin-plugins-data-public.plugin._constructor_.md)
[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [DataPlugin](./kibana-plugin-plugins-data-public.dataplugin.md) &gt; [(constructor)](./kibana-plugin-plugins-data-public.dataplugin._constructor_.md)

## Plugin.(constructor)
## DataPlugin.(constructor)

Constructs a new instance of the `DataPublicPlugin` class

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [DataPlugin](./kibana-plugin-plugins-data-public.dataplugin.md)

## DataPlugin class

<b>Signature:</b>

```typescript
export declare class DataPublicPlugin implements Plugin<DataPublicPluginSetup, DataPublicPluginStart, DataSetupDependencies, DataStartDependencies>
```
## Constructors
| Constructor | Modifiers | Description |
| --- | --- | --- |
| [(constructor)(initializerContext)](./kibana-plugin-plugins-data-public.dataplugin._constructor_.md) | | Constructs a new instance of the <code>DataPublicPlugin</code> class |
## Methods
| Method | Modifiers | Description |
| --- | --- | --- |
| [setup(core, { bfetch, expressions, uiActions, usageCollection, inspector })](./kibana-plugin-plugins-data-public.dataplugin.setup.md) | | |
| [start(core, { uiActions })](./kibana-plugin-plugins-data-public.dataplugin.start.md) | | |
| [stop()](./kibana-plugin-plugins-data-public.dataplugin.stop.md) | | |
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [Plugin](./kibana-plugin-plugins-data-public.plugin.md) &gt; [setup](./kibana-plugin-plugins-data-public.plugin.setup.md)
[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [DataPlugin](./kibana-plugin-plugins-data-public.dataplugin.md) &gt; [setup](./kibana-plugin-plugins-data-public.dataplugin.setup.md)

## Plugin.setup() method
## DataPlugin.setup() method

<b>Signature:</b>

Expand Down
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [Plugin](./kibana-plugin-plugins-data-public.plugin.md) &gt; [start](./kibana-plugin-plugins-data-public.plugin.start.md)
[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [DataPlugin](./kibana-plugin-plugins-data-public.dataplugin.md) &gt; [start](./kibana-plugin-plugins-data-public.dataplugin.start.md)

## Plugin.start() method
## DataPlugin.start() method

<b>Signature:</b>

Expand Down
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [Plugin](./kibana-plugin-plugins-data-public.plugin.md) &gt; [stop](./kibana-plugin-plugins-data-public.plugin.stop.md)
[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [DataPlugin](./kibana-plugin-plugins-data-public.dataplugin.md) &gt; [stop](./kibana-plugin-plugins-data-public.dataplugin.stop.md)

## Plugin.stop() method
## DataPlugin.stop() method

<b>Signature:</b>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
| [AggConfig](./kibana-plugin-plugins-data-public.aggconfig.md) | |
| [AggConfigs](./kibana-plugin-plugins-data-public.aggconfigs.md) | |
| [AggParamType](./kibana-plugin-plugins-data-public.aggparamtype.md) | |
| [DataPlugin](./kibana-plugin-plugins-data-public.dataplugin.md) | |
| [DuplicateIndexPatternError](./kibana-plugin-plugins-data-public.duplicateindexpatternerror.md) | |
| [FieldFormat](./kibana-plugin-plugins-data-public.fieldformat.md) | |
| [FilterManager](./kibana-plugin-plugins-data-public.filtermanager.md) | |
Expand All @@ -19,7 +20,6 @@
| [IndexPatternsService](./kibana-plugin-plugins-data-public.indexpatternsservice.md) | |
| [OptionedParamType](./kibana-plugin-plugins-data-public.optionedparamtype.md) | |
| [PainlessError](./kibana-plugin-plugins-data-public.painlesserror.md) | |
| [Plugin](./kibana-plugin-plugins-data-public.plugin.md) | |
| [SearchInterceptor](./kibana-plugin-plugins-data-public.searchinterceptor.md) | |
| [SearchSource](./kibana-plugin-plugins-data-public.searchsource.md) | \* |
| [SearchTimeoutError](./kibana-plugin-plugins-data-public.searchtimeouterror.md) | Request Failure - When an entire multi request fails |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Constructs a new instance of the `AddPanelAction` class
<b>Signature:</b>

```typescript
constructor(getFactory: EmbeddableStart['getEmbeddableFactory'], getAllFactories: EmbeddableStart['getEmbeddableFactories'], overlays: OverlayStart, notifications: NotificationsStart, SavedObjectFinder: React.ComponentType<any>);
constructor(getFactory: EmbeddableStart['getEmbeddableFactory'], getAllFactories: EmbeddableStart['getEmbeddableFactories'], overlays: OverlayStart, notifications: NotificationsStart, SavedObjectFinder: React.ComponentType<any>, reportUiCounter?: ((appName: string, type: import("@kbn/analytics").UiCounterMetricType, eventNames: string | string[], count?: number | undefined) => void) | undefined);
```

## Parameters
Expand All @@ -21,4 +21,5 @@ constructor(getFactory: EmbeddableStart['getEmbeddableFactory'], getAllFactories
| overlays | <code>OverlayStart</code> | |
| notifications | <code>NotificationsStart</code> | |
| SavedObjectFinder | <code>React.ComponentType&lt;any&gt;</code> | |
| reportUiCounter | <code>((appName: string, type: import(&quot;@kbn/analytics&quot;).UiCounterMetricType, eventNames: string &#124; string[], count?: number &#124; undefined) =&gt; void) &#124; undefined</code> | |

Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ export declare class AddPanelAction implements Action<ActionContext>
| Constructor | Modifiers | Description |
| --- | --- | --- |
| [(constructor)(getFactory, getAllFactories, overlays, notifications, SavedObjectFinder)](./kibana-plugin-plugins-embeddable-public.addpanelaction._constructor_.md) | | Constructs a new instance of the <code>AddPanelAction</code> class |
| [(constructor)(getFactory, getAllFactories, overlays, notifications, SavedObjectFinder, reportUiCounter)](./kibana-plugin-plugins-embeddable-public.addpanelaction._constructor_.md) | | Constructs a new instance of the <code>AddPanelAction</code> class |
## Properties
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,14 +15,15 @@ export declare function openAddPanelFlyout(options: {
notifications: NotificationsStart;
SavedObjectFinder: React.ComponentType<any>;
showCreateNewMenu?: boolean;
reportUiCounter?: UsageCollectionStart['reportUiCounter'];
}): OverlayRef;
```

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| options | <code>{</code><br/><code> embeddable: IContainer;</code><br/><code> getFactory: EmbeddableStart['getEmbeddableFactory'];</code><br/><code> getAllFactories: EmbeddableStart['getEmbeddableFactories'];</code><br/><code> overlays: OverlayStart;</code><br/><code> notifications: NotificationsStart;</code><br/><code> SavedObjectFinder: React.ComponentType&lt;any&gt;;</code><br/><code> showCreateNewMenu?: boolean;</code><br/><code>}</code> | |
| options | <code>{</code><br/><code> embeddable: IContainer;</code><br/><code> getFactory: EmbeddableStart['getEmbeddableFactory'];</code><br/><code> getAllFactories: EmbeddableStart['getEmbeddableFactories'];</code><br/><code> overlays: OverlayStart;</code><br/><code> notifications: NotificationsStart;</code><br/><code> SavedObjectFinder: React.ComponentType&lt;any&gt;;</code><br/><code> showCreateNewMenu?: boolean;</code><br/><code> reportUiCounter?: UsageCollectionStart['reportUiCounter'];</code><br/><code>}</code> | |

<b>Returns:</b>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ export interface ExpressionFunctionDefinitions
| [derivative](./kibana-plugin-plugins-expressions-public.expressionfunctiondefinitions.derivative.md) | <code>ExpressionFunctionDerivative</code> | |
| [font](./kibana-plugin-plugins-expressions-public.expressionfunctiondefinitions.font.md) | <code>ExpressionFunctionFont</code> | |
| [moving\_average](./kibana-plugin-plugins-expressions-public.expressionfunctiondefinitions.moving_average.md) | <code>ExpressionFunctionMovingAverage</code> | |
| [overall\_metric](./kibana-plugin-plugins-expressions-public.expressionfunctiondefinitions.overall_metric.md) | <code>ExpressionFunctionOverallMetric</code> | |
| [theme](./kibana-plugin-plugins-expressions-public.expressionfunctiondefinitions.theme.md) | <code>ExpressionFunctionTheme</code> | |
| [var\_set](./kibana-plugin-plugins-expressions-public.expressionfunctiondefinitions.var_set.md) | <code>ExpressionFunctionVarSet</code> | |
| [var](./kibana-plugin-plugins-expressions-public.expressionfunctiondefinitions.var.md) | <code>ExpressionFunctionVar</code> | |
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [ExpressionFunctionDefinitions](./kibana-plugin-plugins-expressions-public.expressionfunctiondefinitions.md) &gt; [overall\_metric](./kibana-plugin-plugins-expressions-public.expressionfunctiondefinitions.overall_metric.md)

## ExpressionFunctionDefinitions.overall\_metric property

<b>Signature:</b>

```typescript
overall_metric: ExpressionFunctionOverallMetric;
```
Loading

0 comments on commit f5c3464

Please sign in to comment.