mirror of
https://github.com/grafana/grafana.git
synced 2024-11-29 12:14:08 -06:00
docs(): updated plugin docs
This commit is contained in:
Torkel Ödegaard
parent
f27ce7e1e4
commit
545d3208c8
@ -86,13 +86,12 @@ pages:
|
||||
- ['http_api/snapshot.md', 'API', 'Snapshot API']
|
||||
- ['http_api/other.md', 'API', 'Other API']
|
||||
|
||||
- ['plugins/overview.md', 'Plugins', 'Overview']
|
||||
- ['plugins/index.md', 'Plugins', 'Overview']
|
||||
- ['plugins/installation.md', 'Plugins', 'Installation']
|
||||
- ['plugins/app.md', 'Plugins', 'App plugins']
|
||||
- ['plugins/datasources.md', 'Plugins', 'Datasource plugins']
|
||||
- ['plugins/panels.md', 'Plugins', 'Panel plugins']
|
||||
- ['plugins/development.md', 'Plugins', 'Plugin development']
|
||||
- ['plugins/plugin.json.md', 'Plugins', 'Plugin json']
|
||||
- ['plugins/development.md', 'Plugins', 'Development']
|
||||
- ['plugins/apps.md', 'Plugins', 'Apps']
|
||||
- ['plugins/datasources.md', 'Plugins', 'Datasources']
|
||||
- ['plugins/panels.md', 'Plugins', 'Panels']
|
||||
|
||||
- ['tutorials/index.md', 'Tutorials', 'Tutorials']
|
||||
- ['tutorials/hubot_howto.md', 'Tutorials', 'How To integrate Hubot and Grafana']
|
||||
|
||||
@ -1,46 +0,0 @@
|
||||
---
|
||||
page_title: App plugin
|
||||
page_description: App plugin for Grafana
|
||||
page_keywords: grafana, plugins, documentation
|
||||
---
|
||||
|
||||
> Our goal is not to have a very extensive documentation but rather have actual code that people can look at. An example implementation of an app can be found in this [example app repo](https://github.com/grafana/example-app)
|
||||
|
||||
# Apps
|
||||
|
||||
App plugins is a new kind of grafana plugin that can bundle datasource and panel plugins within one package. It also enable the plugin author to create custom pages within grafana. The custom pages enables the plugin author to include things like documentation, sign up forms or controlling other services using HTTP requests.
|
||||
|
||||
Datasource and panel plugins will show up like normal plugins. The app pages will be available in the main menu.
|
||||
|
||||
<img class="no-shadow" src="/img/v3/app-in-main-menu.png">
|
||||
|
||||
## Enabling app plugins
|
||||
After installing an app it have to be enabled before it show up as an datasource or panel. You can do that on the app page in the config tab.
|
||||
|
||||
## README.md
|
||||
|
||||
The readme file in the mounted folder will show up in the overview tab on the app page.
|
||||
|
||||
## Module exports
|
||||
```javascript
|
||||
export {
|
||||
ExampleAppConfigCtrl as ConfigCtrl,
|
||||
StreamPageCtrl,
|
||||
LogsPageCtrl
|
||||
};
|
||||
```
|
||||
The only required export is the ConfigCtrl. Both StreamPageCtrl and LogsPageCtrl are custom pages defined in plugin.json
|
||||
|
||||
## Custom pages
|
||||
Custom pages are defined in the plugin.json like this.
|
||||
```json
|
||||
"pages": [
|
||||
{ "name": "Live stream", "component": "StreamPageCtrl", "role": "Editor"},
|
||||
{ "name": "Log view", "component": "LogsPageCtrl", "role": "Viewer"}
|
||||
]
|
||||
```
|
||||
The component field have to match one of the components exported in the module.js in the root of the plugin.
|
||||
|
||||
## Bundled plugins
|
||||
|
||||
When Grafana starts it will scan all directories within an app plugin and load folders containing a plugin.json as an plugin.
|
||||
24
docs/sources/plugins/apps.md
Normal file
24
docs/sources/plugins/apps.md
Normal file
@ -0,0 +1,24 @@
|
||||
---
|
||||
page_title: App plugin
|
||||
page_description: App plugin for Grafana
|
||||
page_keywords: grafana, plugins, documentation
|
||||
---
|
||||
|
||||
|
||||
# Apps
|
||||
|
||||
App plugins is a new kind of grafana plugin that can bundle datasource and panel plugins within one package. It also enable the plugin author to create custom pages within grafana. The custom pages enables the plugin author to include things like documentation, sign up forms or controlling other services using HTTP requests.
|
||||
|
||||
Datasource and panel plugins will show up like normal plugins. The app pages will be available in the main menu.
|
||||
|
||||
<img class="no-shadow" src="/img/v3/app-in-main-menu.png">
|
||||
|
||||
## Enabling app plugins
|
||||
After installing an app it have to be enabled before it show up as an datasource or panel. You can do that on the app page in the config tab.
|
||||
|
||||
### Develop your own App
|
||||
|
||||
> Our goal is not to have a very extensive documentation but rather have actual
|
||||
> code that people can look at. An example implementation of an app can be found
|
||||
> in this [example app repo](https://github.com/grafana/example-app)
|
||||
|
||||
@ -4,11 +4,18 @@ page_description: Datasource plugins for Grafana
|
||||
page_keywords: grafana, plugins, documentation
|
||||
---
|
||||
|
||||
> Our goal is not to have a very extensive documentation but rather have actual code that people can look at. An example implementation of a datasource can be found in this [example datasource repo](https://github.com/grafana/simple-json-datasource)
|
||||
|
||||
# Datasources
|
||||
|
||||
Datasource plugins enables people to develop plugins for any database that communicates over http. Its up to the plugin to transform the data into time series data so that any grafana panel can then show it.
|
||||
Datasource plugins enables people to develop plugins for any database that
|
||||
communicates over http. Its up to the plugin to transform the data into
|
||||
time series data so that any grafana panel can then show it.
|
||||
|
||||
## Datasource development
|
||||
|
||||
> Our goal is not to have a very extensive documentation but rather have actual
|
||||
> code that people can look at. An example implementation of a datasource can be
|
||||
> found in this [example datasource repo](https://github.com/grafana/simple-json-datasource)
|
||||
|
||||
To interact with the rest of grafana the plugins module file can export 5 different components.
|
||||
|
||||
@ -19,11 +26,14 @@ To interact with the rest of grafana the plugins module file can export 5 differ
|
||||
- AnnotationsQueryCtrl
|
||||
|
||||
## Plugin json
|
||||
|
||||
There are two datasource specific settings for the plugin.json
|
||||
|
||||
```javascript
|
||||
"metrics": true,
|
||||
"annotations": false,
|
||||
```
|
||||
|
||||
These settings indicates what kind of data the plugin can deliver. At least one of them have to be true
|
||||
|
||||
## Datasource
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
---
|
||||
page_title: Plugin development
|
||||
page_title: Plugin development guide
|
||||
page_description: Plugin development for Grafana
|
||||
page_keywords: grafana, plugins, documentation, development
|
||||
---
|
||||
@ -11,7 +11,7 @@ From grafana 3.0 it's very easy to develop your own plugins and share them with
|
||||
## Short version
|
||||
|
||||
1. [Setup grafana](https://github.com/grafana/grafana/blob/master/DEVELOPMENT.md)
|
||||
2. Clone an example plugin into ```data/plugins```
|
||||
2. Clone an example plugin into ```/var/lib/grafana/plugins``` or `data/plugins` (relative to grafana git repo if your running development version from source dir)
|
||||
3. Code away!
|
||||
|
||||
## What languages?
|
||||
@ -26,20 +26,25 @@ All our example plugins have build scripted configured.
|
||||
|
||||
## module.(js|ts)
|
||||
|
||||
This is the entry point for every plugin. This is the place where you should export your plugin implementation. Depending on what kind of plugin you are developing you will be expected to export different things. You can find whats expected for [datasource](http://docs.grafana.org/v3.0/plugins/datasources/), [panels](http://docs.grafana.org/v3.0/plugins/panels/) and [apps](http://docs.grafana.org/v3.0/plugins/app/)
|
||||
plugins in the documentation.
|
||||
This is the entry point for every plugin. This is the place where you should export
|
||||
your plugin implementation. Depending on what kind of plugin you are developing you
|
||||
will be expected to export different things. You can find what's expected for [datasource](./datasources.md), [panels](./panels.md)
|
||||
and [apps](./apps.md) plugins in the documentation.
|
||||
|
||||
## Start developing your plugin
|
||||
There are two ways that you can start developing a Grafana plugin.
|
||||
1. Setup a Grafana development environment. [(described here)](https://github.com/grafana/grafana/blob/master/DEVELOPMENT.md) and place your plugin in the ```data/plugins``` folder.
|
||||
2. Install Grafana and place your plugin the plugins directory which is set in your [config file](http://docs.grafana.org/installation/configuration/)
|
||||
|
||||
1. Setup a Grafana development environment. [(described here)](https://github.com/grafana/grafana/blob/master/DEVELOPMENT.md) and place your plugin in the ```data/plugins``` folder.
|
||||
2. Install Grafana and place your plugin in the plugins directory which is set in your [config file](../installation/configuration.md). By default this is `/var/lib/grafana/plugins` on Linux systems.
|
||||
3. Place your plugin directory anywhere you like and specify it grafana.ini.
|
||||
|
||||
We encourage people to setup the full Grafana environment so that you can get inspiration from the rest of grafana code base.
|
||||
|
||||
When Grafana starts it will scan the plugin folders and mount every folder that contains a plugin.json file unless the folder contains a subfolder named dist. In that case grafana will mount the dist folder instead.
|
||||
This makes it possible to have both built and src content in the same plugin folder.
|
||||
When Grafana starts it will scan the plugin folders and mount every folder that contains a plugin.json file unless
|
||||
the folder contains a subfolder named dist. In that case grafana will mount the dist folder instead.
|
||||
This makes it possible to have both built and src content in the same plugin git repo.
|
||||
|
||||
## Boilerplate
|
||||
## Examples
|
||||
We currently have three different examples that you can fork/download to get started developing your grafana plugin.
|
||||
|
||||
- [simple-json-datasource](https://github.com/grafana/simple-json-datasource) (small datasource plugin for querying json data from backends)
|
||||
21
docs/sources/plugins/index.md
Normal file
21
docs/sources/plugins/index.md
Normal file
@ -0,0 +1,21 @@
|
||||
---
|
||||
page_title: Plugin overview
|
||||
page_description: Plugins for Grafana
|
||||
page_keywords: grafana, plugins, documentation
|
||||
---
|
||||
|
||||
# Plugins
|
||||
|
||||
From Grafana 3.0 not only datasource plugins are supported but also panel plugins and apps.
|
||||
Having panels as plugins make it easy to create and add any kind of panel, to show your data
|
||||
or improve your favorite dashboards. Apps is something new in Grafana that enables
|
||||
bundling of datasources, panels, dashboards and Grafana pages into a cohesive experiance.
|
||||
|
||||
Grafana already have a strong community of contributors and plugin developers.
|
||||
By making it easier to develop and install plugins we hope that the community
|
||||
can grow even stronger and develop new plugins that we would never think about.
|
||||
|
||||
You can discover available plugins on [Grafana.net](http://grafana.net)
|
||||
|
||||
|
||||
|
||||
@ -4,14 +4,12 @@ page_description: Plugin installation for Grafana
|
||||
page_keywords: grafana, plugins, documentation
|
||||
---
|
||||
|
||||
# Plugins
|
||||
|
||||
## Installing plugins
|
||||
# Installing plugins
|
||||
|
||||
The easiest way to install plugins is by using the CLI tool grafana-cli which is bundled with grafana. Before any modification take place after modifying plugins, grafana-server needs to be restarted.
|
||||
|
||||
### Grafana plugin directory
|
||||
On Linux systems the grafana-cli will assume that the grafana plugin directory is "/var/lib/grafana/plugins". It's possible to override the directory which grafana-cli will operate on by specifying the --path flag. On Windows systems this parameter have to be specified for every call.
|
||||
On Linux systems the grafana-cli will assume that the grafana plugin directory is `/var/lib/grafana/plugins`. It's possible to override the directory which grafana-cli will operate on by specifying the --path flag. On Windows systems this parameter have to be specified for every call.
|
||||
|
||||
### Grafana-cli commands
|
||||
|
||||
|
||||
@ -1,12 +0,0 @@
|
||||
---
|
||||
page_title: Plugin overview
|
||||
page_description: Plugins for Grafana
|
||||
page_keywords: grafana, plugins, documentation
|
||||
---
|
||||
|
||||
# Plugins
|
||||
|
||||
From Grafana 3.0 not only datasource plugins are supported but also panel plugins and apps. Having panels as plugins make it easy to create and add any kind of panel, to show your data or improve your favorite dashboards. Apps is something new in Grafana that enables bundling of datasources, panels that belongs together.
|
||||
|
||||
Grafana already have a strong community of contributors and plugin developers. By making it easier to develop and install plugins we hope that the community can grow even stronger and develop new plugins that we would never think about.
|
||||
|
||||
@ -4,26 +4,15 @@ page_description: Panel plugins for Grafana
|
||||
page_keywords: grafana, plugins, documentation
|
||||
---
|
||||
|
||||
> Our goal is not to have a very extensive documentation but rather have actual code that people can look at. An example implementation of a datasource can be found in the grafana repo under /examples/panel-boilerplate-es5
|
||||
|
||||
# Panels
|
||||
|
||||
To interact with the rest of grafana the panel plugin need to export a class in the module.js.
|
||||
This class have to inherit from sdk.PanelCtrl or sdk.MetricsPanelCtrl and be exported as PanelCtrl.
|
||||
Panels are the main bulding block of dashboards.
|
||||
|
||||
```javascript
|
||||
return {
|
||||
PanelCtrl: BoilerPlatePanelCtrl
|
||||
};
|
||||
```
|
||||
## Panel development
|
||||
|
||||
This class will be instantiated once for every panel of its kind in a dashboard and treated as an AngularJs controller.
|
||||
Examples
|
||||
|
||||
## MetricsPanelCtrl or PanelCtrl
|
||||
|
||||
MetricsPanelCtrl inherits from PanelCtrl and adds some common features for datasource usage. So if your Panel will be working with a datasource you should inherit from MetricsPanelCtrl. If don't need to access any datasource then you should inherit from PanelCtrl instead.
|
||||
|
||||
## Implementing a MetricsPanelCtrl
|
||||
|
||||
If you choose to inherit from MetricsPanelCtrl you should implement a function called refreshData that will take a datasource as in parameter when its time to get new data. Its recommended that the refreshData function calls the issueQueries in the base class but its not mandatory. An examples of such implementation can be found in our [example panel](https://github.com/grafana/grafana/blob/master/examples/panel-boilerplate-es5/module.js#L27-L38)
|
||||
- [clock-panel](https://github.com/grafana/clock-panel)
|
||||
- [singlestat-panel](https://github.com/grafana/grafana/blob/master/public/app/plugins/panel/singlestat/module.ts)
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user