github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-24 01:38:56 -04:00
Code Issues Projects Releases Packages Wiki Activity

Clean up Developer Guide (#108259)

Browse source 
* update plugin docs

* address code review feedback
This commit is contained in:
Stacey Gammon 2021-08-12 14:05:43 -04:00 • committed by GitHub
parent db9407c47c
commit 21b080b61b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 104 additions and 66 deletions
Download patch file Download diff file Expand all files Collapse all files

37
dev_docs/getting_started/add_data.mdx Normal file
View file

@ -0,0 +1,37 @@
---
id: kibDevAddData
slug: /kibana-dev-docs/tutorial/sample-data
title: Add data
summary: Learn how to add data to Kibana
date: 2021-08-11
tags: ['kibana', 'onboarding', 'dev', 'architecture', 'tutorials']
---
Building a feature and need an easy way to test it out with some data? Below are three options.
## 1. Add Sample Data from the UI
Kibana ships with sample data that you can install at the click of the button. If you are building a feature and need some data to test it out with, sample data is a great option. The only limitation is that this data will not work for Security or Observability solutions (see [#62962](https://github.com/elastic/kibana/issues/62962)).
1. Navigate to the home page.
2. Click **Add data**.
3. Click on the **Sample data** tab.
4. Select a dataset by clicking on the **Add data** button.
![Sample Data](../assets/sample_data.png)
## CSV Upload
1. If you don't have any data, navigate to Stack Management > Index Patterns and click the link to the uploader. If you do have data, navigate to the **Machine Learning** application.
2. Click on the **Data Visualizer** tab.
3. Click on **Select file** in the **Import data** container.
![CSV Upload](../assets/ml_csv_upload.png)
## makelogs
The makelogs script generates sample web server logs. Make sure Elasticsearch is running before running the script.
```sh
node scripts/makelogs --auth <username>:<password>
```

3
dev_docs/getting_started/dev_welcome.mdx
View file

@ -14,7 +14,8 @@ Kibana ships with many out-of-the-box capabilities that can be extended and enha
Recommended next reading:
1. <DocLink id="kibDevTutorialSetupDevEnv" text="Set up your development environment" />
2. Create a simple <DocLink id="kibHelloWorldApp" text="Hello World plugin"/>.
2. Create a <DocLink id="kibHelloWorldApp" text="Hello World plugin"/>.
3. <DocLink id="kibDevAddData" text="Add data" />.
Check out our <DocLink id="kibDevDocsApiWelcome" text="API documentation" /> to dig into the nitty gritty details of
every public plugin API.

16
dev_docs/getting_started/hello_world_plugin.mdx
View file

@ -27,7 +27,7 @@ $ mkdir hello_world
$ cd hello_world
```
2. Create the <DocLink id="kibDevTutorialBuildAPlugin" section="1-kibanajson" text="kibana.json manifest file"/>.
2. Create the <DocLink id="kibDevAnatomyOfAPlugin" section="kibanajson" text="kibana.json manifest file"/>.
```
$ touch kibana.json
@ -44,7 +44,7 @@ and add the following:
}
```
3. Create a `tsconfig.json` file.
3. Create a <DocLink id="kibDevAnatomyOfAPlugin" section="tsconfigjson" text="tsconfig.json file" />.
```
$ touch tsconfig.json
@ -56,8 +56,7 @@ And add the following to it:
{
"extends": "../../tsconfig.json",
"compilerOptions": {
"outDir": "./target",
"skipLibCheck": true
"outDir": "./target/types",
},
"include": [
"index.ts",
@ -67,11 +66,14 @@ And add the following to it:
"server/**/*.ts",
"../../typings/**/*"
],
"exclude": []
"exclude": [],
"references": [
{ "path": "../../src/core/tsconfig.json" }
]
}
```
4. Create a <DocLink id="kibDevTutorialBuildAPlugin" section="2-publicindexts" text="`public/plugin.tsx` file "/>.
4. Create a <DocLink id="kibDevAnatomyOfAPlugin" section="publicindexts" text="`public/plugin.tsx` file "/>.
```
$ mkdir public
@ -104,7 +106,7 @@ export class HelloWorldPlugin implements Plugin {
}
```
5. Create a <DocLink id="kibDevTutorialBuildAPlugin" section="3-publicplugints" text="`public/index.ts` file "/>.
5. Create a <DocLink id="kibDevAnatomyOfAPlugin" section="publicplugints" text="`public/index.ts` file "/>.
```
$ touch index.ts

76
dev_docs/key_concepts/anatomy_of_a_plugin.mdx
View file

@ -1,6 +1,6 @@
---
id: kibDevTutorialBuildAPlugin
slug: /kibana-dev-docs/tutorials/anatomy-of-a-plugin
id: kibDevAnatomyOfAPlugin
slug: /kibana-dev-docs/anatomy-of-a-plugin
title: Anatomy of a plugin
summary: Anatomy of a Kibana plugin.
date: 2021-08-03
@ -22,22 +22,23 @@ The basic file structure of a Kibana plugin named demo that has both client-side
```
plugins/
demo
kibana.json [1]
kibana.json
tsconfig.json
public
index.ts [2]
plugin.ts [3]
index.ts
plugin.ts
server
index.ts [4]
plugin.ts [5]
index.ts
plugin.ts
common
index.ts [6]
index.ts
```
### [1] kibana.json
### 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:
```
```json
{
"id": "examplePluginId",
"version": "1.0.0",
@ -88,12 +89,38 @@ plugins/
You don't need to declare a dependency on a plugin if you only wish to access its types.
</DocCallOut>
### [2] public/index.ts
### tsconfig.json
If you are developing in TypeScript (which we recommend), you will need to add a `tsconfig.json` file. Here is an example file that you would use if adding a plugin into the `examples` directory.
```json
{
"extends": "../../tsconfig.json", // Extend kibana/tsconfig.json
"compilerOptions": {
"outDir": "./target/types"
},
"include": [
"index.ts",
"../../typings/**/*",
// The following paths are optional, based on whether you have common code,
// or are building a client-side-only or server-side-only plugin.
"common/**/*.ts",
"public/**/*.ts",
"public/**/*.tsx",
"server/**/*.ts"
],
"exclude": [],
// If you import another plugin's types, point to their `tsconfig.json` file.
"references": [{ "path": "../../src/core/tsconfig.json" }]
}
```
### public/index.ts
`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.
```
```ts
import type { PluginInitializerContext } from 'kibana/server';
import { DemoPlugin } from './plugin';
@ -122,7 +149,7 @@ Using the non-`type` variation will increase the bundle size unnecessarily and m
</DocCallOut>
### [3] public/plugin.ts
### 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.
@ -147,11 +174,11 @@ export class DemoPlugin implements Plugin {
}
```
### [4] server/index.ts
### 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:
### [5] server/plugin.ts
### server/plugin.ts
`server/plugin.ts` is the server-side plugin definition. The shape of this plugin is the same as it’s client-side counter-part:
@ -178,7 +205,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
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
### common/index.ts
`common/index.ts` is the entry-point into code that can be used both server-side or client side.
@ -208,13 +235,15 @@ dependency in it’s kibana.json manifest file.
** foobar plugin.ts: **
```
```ts
import type { Plugin } from 'kibana/server';
export interface FoobarPluginSetup { [1]
// [1]
export interface FoobarPluginSetup {
getFoo(): string;
}
export interface FoobarPluginStart { [1]
// [1]
export interface FoobarPluginStart {
getBar(): string;
}
@ -256,7 +285,8 @@ 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];
// [1]
interface DemoSetupPlugins {
foobar: FoobarPluginSetup;
}
@ -265,13 +295,15 @@ interface DemoStartPlugins {
}
export class DemoPlugin {
public setup(core: CoreSetup, plugins: DemoSetupPlugins) { [2];
// [2]
public setup(core: CoreSetup, plugins: DemoSetupPlugins) {
const { foobar } = plugins;
foobar.getFoo(); // 'foo'
foobar.getBar(); // throws because getBar does not exist
}
public start(core: CoreStart, plugins: DemoStartPlugins) { [3];
//[3]
public start(core: CoreStart, plugins: DemoStartPlugins) {
const { foobar } = plugins;
foobar.getFoo(); // throws because getFoo does not exist
foobar.getBar(); // 'bar'

33
dev_docs/tutorials/sample_data.mdx
View file

@ -1,33 +0,0 @@
---
id: kibDevTutorialSampleData
slug: /kibana-dev-docs/tutorial/sample-data
title: Add sample data
summary: Learn how to add sample data to Kibana
date: 2021-04-26
tags: ['kibana', 'onboarding', 'dev', 'architecture', 'tutorials']
---
## Installation from the UI
1. Navigate to the home page.
2. Click **Add data**.
3. Click on the **Sample data** tab.
4. Select a dataset by clicking on the **Add data** button.
![Sample Data](../assets/sample_data.png)
## CSV Upload
1. Navigate to the **Machine Learning** application.
2. Click on the **Data Visualizer** tab.
3. Click on **Select file** in the **Import data** container.
![CSV Upload](../assets/ml_csv_upload.png)
## makelogs
The makelogs script generates sample web server logs. Make sure Elasticsearch is running before running the script.
```sh
node scripts/makelogs --auth <username>:<password>
```

5
examples/hello_world/tsconfig.json
View file

@ -1,8 +1,7 @@
{
"extends": "../../tsconfig.json",
"compilerOptions": {
"outDir": "./target",
"skipLibCheck": true
"outDir": "./target/types"
},
"include": [
"index.ts",
@ -15,6 +14,6 @@
"exclude": [],
"references": [
{ "path": "../../src/core/tsconfig.json" },
{ "path": "../developer_examples/tsconfig.json" },
{ "path": "../developer_examples/tsconfig.json" }
]
}