IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-02-25 18:55:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

Update plugin metadata (#24633)

Browse Source
This commit is contained in:
Marcus Olsson 2020-05-14 11:21:31 +02:00 committed by GitHub
parent 37a2ac20c3
commit e323f7be51
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 580 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

191
docs/sources/developers/plugins/metadata.md
View File

@ -7,30 +7,177 @@ aliases = ["/docs/grafana/latest/plugins/developing/plugin.json/"]
# plugin.json
The plugin.json file is mandatory for all plugins. 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.
The plugin.json file is required for all plugins. When Grafana starts, it scans the plugin folders and mounts every folder that contains a plugin.json file unless the folder contains a subfolder named dist. In that case, Grafana mounts the dist folder instead.
## Schema
## Properties
| Property | Description |
|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| id | Unique name of the plugin. |
| type | One of `app`, `datasource`, `panel` |
| name | Human-readable name of the plugin |
| dependencies.grafanaVersion | Required Grafana version for this plugin |
| dependencies.plugins | An array of required plugins on which this plugin depends |
| info.author.name | Author's name |
| info.author.url | Link to author's website |
| info.description | Description of plugin. Used for search on grafana.com |
| info.keywords | Array of plugin keywords. Used for search on grafana.com |
| info.links | An array of link objects to be displayed on this plugin's project page in the form `{name: 'foo', url: 'http://example.com'}` |
| info.logos.small | Link to the "small" version of the plugin logo, which must be an SVG image. "Large" and "small" logos can be the same image. |
| info.logos.large | Link to the "large" version of the plugin logo, which must be an SVG image. "Large" and "small" logos can be the same image. |
| info.screenshots | An array of screenshot objects in the form `{name: 'bar', path: 'img/screenshot.png'}` |
| info.updated | Date when this plugin was built. Use `%TODAY%` for Grafana to autopopulate this value. |
| info.version | Project version of this commit. Use `%VERSION%` for Grafana to autopopulate this value. |
| Property | Type | Required | Description |
|-----------------|-------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `dependencies` | [object](#dependencies) | **Yes** | Plugin dependencies. |
| `id` | string | **Yes** | Unique name of the plugin. If the plugin is published on grafana.com, then the plugin id has to follow the naming conventions. |
| `info` | [object](#info) | **Yes** | Metadata for the plugin. Some fields are used on the plugins page in Grafana and others on grafana.com if the plugin is published. |
| `name` | string | **Yes** | Human-readable name of the plugin that is shown to the user in the UI. |
| `type` | string | **Yes** | Plugin type. Possible values are `app`, `datasource`, and `panel`. |
| `alerting` | boolean | No | For data source plugins. If the plugin supports alerting. |
| `annotations` | boolean | No | For data source plugins. If the plugin supports annotation queries. |
| `backend` | boolean | No | If the plugin has a backend component. |
| `category` | string | No | Plugin category used on the Add data source page. Possible values are: `tsdb`, `logging`, `cloud`, `tracing`, and `sql`. |
| `executable` | string | No | The first part of the file name of the backend component executable. There can be multiple executables built for different operating system and architecture. Grafana will check for executables named `<executable>_<$GOOS>_<lower case $GOARCH><.exe for Windows>`, e.g. `plugin_linux_amd64`. Combination of $GOOS and $GOARCH can be found here: https://golang.org/doc/install/source#environment. |
| `hiddenQueries` | boolean | No | |
| `includes` | [array](#includes) | No | |
| `logs` | boolean | No | For data source plugins. If the plugin supports logs. |
| `metrics` | boolean | No | For data source plugins. If the plugin supports metric queries. Used in the Explore feature. |
| `mixed` | boolean | No | Not to be used by external plugins. Special property for the built-in mixed plugin. |
| `module` | string | No | |
| `partials` | [object](#partials) | No | |
| `queryOptions` | [object](#queryoptions) | No | For data source plugins. There is a query options section in the plugin's query editor and these options can be turned on if needed. |
| `routes` | [array](#routes) | No | For data source plugins. Proxy routes used for plugin authentication and adding headers to HTTP requests made by the plugin. For more information, refer to [Authentication for data source plugins](https://grafana.com/docs/grafana/latest/developers/plugins/authentication/). |
| `sort` | number | No | Internal property for sorting. Cannot be used as will be overwritten by Grafana. |
| `staticRoot` | string | No | |
| `streaming` | boolean | No | For data source plugins. If the plugin supports streaming. |
| `tables` | boolean | No | |
| `tracing` | boolean | No | For data source plugins. If the plugin supports tracing. |
## Plugin.json Example
## dependencies
Plugin dependencies.
### Properties
| Property | Type | Required | Description |
|------------------|-------------------|----------|------------------------------------------------------------------------------------------------------------------|
| `grafanaVersion` | string | **Yes** | Required Grafana version for this plugin, e.g. `6.x.x 7.x.x` to denote plugin requires Grafana v6.x.x or v7.x.x. |
| `plugins` | [array](#plugins) | No | An array of required plugins on which this plugin depends. |
## includes
### Properties
| Property | Type | Required | Description |
|--------------|---------|----------|-------------|
| `addToNav` | boolean | No | |
| `component` | string | No | |
| `defaultNav` | boolean | No | |
| `name` | string | No | |
| `role` | string | No | |
| `type` | string | No | |
## info
Metadata for the plugin. Some fields are used on the plugins page in Grafana and others on grafana.com if the plugin is published.
### Properties
| Property | Type | Required | Description |
|---------------|-----------------------|----------|-------------------------------------------------------------------------------------------------------------------------------|
| `logos` | [object](#logos) | **Yes** | SVG images that are used as plugin icons. |
| `updated` | string | **Yes** | Date when this plugin was built. |
| `version` | string | **Yes** | Project version of this commit, e.g. `6.7.x`. |
| `author` | [object](#author) | No | Information about the plugin author. |
| `description` | string | No | Description of plugin. Used on the plugins page in Grafana and for search on grafana.com. |
| `keywords` | [array](#keywords) | No | Array of plugin keywords. Used for search on grafana.com. |
| `links` | [array](#links) | No | An array of link objects to be displayed on this plugin's project page in the form `{name: 'foo', url: 'http://example.com'}` |
| `screenshots` | [array](#screenshots) | No | An array of screenshot objects in the form `{name: 'bar', path: 'img/screenshot.png'}` |
### author
Information about the plugin author.
#### Properties
| Property | Type | Required | Description |
|----------|--------|----------|---------------------------|
| `email` | string | No | Author's name. |
| `name` | string | No | Author's name. |
| `url` | string | No | Link to author's website. |
### links
#### Properties
| Property | Type | Required | Description |
|----------|--------|----------|-------------|
| `name` | string | No | |
| `url` | string | No | |
### logos
SVG images that are used as plugin icons.
#### Properties
| Property | Type | Required | Description |
|----------|--------|----------|------------------------------------------------------------------------------------------------------------------------------|
| `large` | string | **Yes** | Link to the "large" version of the plugin logo, which must be an SVG image. "Large" and "small" logos can be the same image. |
| `small` | string | **Yes** | Link to the "small" version of the plugin logo, which must be an SVG image. "Large" and "small" logos can be the same image. |
### screenshots
#### Properties
| Property | Type | Required | Description |
|----------|--------|----------|-------------|
| `name` | string | No | |
| `path` | string | No | |
## partials
### Properties
| Property | Type | Required | Description |
|----------|--------|----------|-------------|
| `config` | string | No | |
## queryOptions
For data source plugins. There is a query options section in the plugin's query editor and these options can be turned on if needed.
### Properties
| Property | Type | Required | Description |
|-----------------|---------|----------|----------------------------------------------------------------------------------------------------------------------------|
| `cacheTimeout` | boolean | No | For data source plugins. If the `cache timeout` option should be shown in the query options section in the query editor. |
| `maxDataPoints` | boolean | No | For data source plugins. If the `max data points` option should be shown in the query options section in the query editor. |
| `minInterval` | boolean | No | For data source plugins. If the `min interval` option should be shown in the query options section in the query editor. |
## routes
For data source plugins. Proxy routes used for plugin authentication and adding headers to HTTP requests made by the plugin. For more information, refer to [Authentication for data source plugins](https://grafana.com/docs/grafana/latest/developers/plugins/authentication/).
### Properties
| Property | Type | Required | Description |
|---------------|----------------------|----------|---------------------------------------------------------------------------------------------------------|
| `headers` | array | No | For data source plugins. Route headers adds HTTP headers to the proxied request. |
| `method` | string | No | For data source plugins. Route method matches the HTTP verb like GET or POST. |
| `path` | string | No | For data source plugins. The route path that is replaced by the route URL field when proxying the call. |
| `reqRole` | string | No | |
| `reqSignedIn` | boolean | No | |
| `tokenAuth` | [object](#tokenauth) | No | For data source plugins. Token authentication section used with an OAuth API. |
| `url` | string | No | For data source plugins. Route URL is where the request is proxied to. |
### tokenAuth
For data source plugins. Token authentication section used with an OAuth API.
#### Properties
| Property | Type | Required | Description |
|----------|-------------------|----------|---------------------------------------------------------------------------|
| `params` | [object](#params) | No | For data source plugins. Parameters for the token authentication request. |
| `url` | string | No | For data source plugins. URL to fetch the authentication token. |
#### params
For data source plugins. Parameters for the token authentication request.
##### Properties
| Property | Type | Required | Description |
|-----------------|--------|----------|--------------------------------------------------------------------------------------------------------------------|
| `client_id` | string | No | For data source plugins. OAuth client id. |
| `client_secret` | string | No | For data source plugins. OAuth client secret. Usually populated by decrypting the secret from the SecureJson blob. |
| `grant_type` | string | No | For data source plugins. OAuth grant type. |
| `resource` | string | No | For data source plugins. OAuth resource. |
Here's an example of an up-to-date plugin.json file:
https://github.com/grafana/clock-panel/blob/master/src/plugin.json

8
docs/sources/developers/plugins/metadata.md.tpl Normal file
View File

@ -0,0 +1,8 @@
+++
title = "plugin.json"
keywords = ["grafana", "plugins", "documentation"]
type = "docs"
aliases = ["/docs/grafana/latest/plugins/developing/plugin.json/"]
+++
{{ .Markdown 1 }}

403
docs/sources/developers/plugins/plugin.schema.json Normal file
View File

@ -0,0 +1,403 @@
{
"$schema": "http://json-schema.org/draft-07/schema",
"$id": "http://example.com/example.json",
"type": "object",
"title": "plugin.json",
"description": "The plugin.json file is required for all plugins. When Grafana starts, it scans the plugin folders and mounts every folder that contains a plugin.json file unless the folder contains a subfolder named dist. In that case, Grafana mounts the dist folder instead.",
"required": ["type", "name", "id", "info", "dependencies"],
"additionalProperties": false,
"properties": {
"id": {
"$id": "#/properties/id",
"type": "string",
"description": "Unique name of the plugin. If the plugin is published on grafana.com, then the plugin id has to follow the naming conventions.",
"pattern": "^[0-9a-z\\-]+$"
},
"type": {
"$id": "#/properties/type",
"type": "string",
"description": "Plugin type. Possible values are `app`, `datasource`, and `panel`.",
"enum": ["app", "datasource", "panel"]
},
"name": {
"$id": "#/properties/name",
"type": "string",
"description": "Human-readable name of the plugin that is shown to the user in the UI."
},
"category": {
"$id": "#/properties/category",
"type": "string",
"description": "Plugin category used on the Add data source page. Possible values are: `tsdb`, `logging`, `cloud`, `tracing`, and `sql`.",
"enum": ["tsdb", "logging", "cloud", "tracing", "sql"]
},
"annotations": {
"$id": "#/properties/annotations",
"type": "boolean",
"description": "For data source plugins. If the plugin supports annotation queries.",
"default": false
},
"alerting": {
"$id": "#/properties/alerting",
"type": "boolean",
"description": "For data source plugins. If the plugin supports alerting.",
"default": false
},
"backend": {
"$id": "#/properties/backend",
"type": "boolean",
"description": "If the plugin has a backend component.",
"default": false
},
"executable": {
"$id": "#/properties/executable",
"type": "string",
"description": "The first part of the file name of the backend component executable. There can be multiple executables built for different operating system and architecture. Grafana will check for executables named `<executable>_<$GOOS>_<lower case $GOARCH><.exe for Windows>`, e.g. `plugin_linux_amd64`. Combination of $GOOS and $GOARCH can be found here: https://golang.org/doc/install/source#environment."
},
"includes": {
"$id": "#/properties/includes",
"type": "array",
"items": {
"$id": "#/properties/includes/items",
"type": "object",
"additionalItems": false,
"properties": {
"type": {
"$id": "#/properties/includes/items/properties/type",
"type": "string"
},
"name": {
"$id": "#/properties/includes/items/properties/name",
"type": "string"
},
"component": {
"$id": "#/properties/includes/items/properties/component",
"type": "string"
},
"role": {
"$id": "#/properties/includes/items/properties/role",
"type": "string"
},
"addToNav": {
"$id": "#/properties/includes/items/properties/addToNav",
"type": "boolean"
},
"defaultNav": {
"$id": "#/properties/includes/items/properties/defaultNav",
"type": "boolean"
}
}
}
},
"logs": {
"$id": "#/properties/logs",
"type": "boolean",
"description": "For data source plugins. If the plugin supports logs.",
"default": false
},
"partials": {
"$id": "#/properties/partials",
"type": "object",
"additionalItems": false,
"properties": {
"config": {
"$id": "#/properties/partials/properties/config",
"type": "string"
}
}
},
"metrics": {
"$id": "#/properties/metrics",
"type": "boolean",
"description": "For data source plugins. If the plugin supports metric queries. Used in the Explore feature.",
"default": false
},
"mixed": {
"$id": "#/properties/mixed",
"type": "boolean",
"description": "Not to be used by external plugins. Special property for the built-in mixed plugin."
},
"module": {
"$id": "#/properties/module",
"type": "string"
},
"sort": {
"$id": "#/properties/sort",
"type": "number",
"description": "Internal property for sorting. Cannot be used as will be overwritten by Grafana."
},
"staticRoot": {
"$id": "#/properties/staticRoot",
"type": "string"
},
"streaming": {
"$id": "#/properties/streaming",
"type": "boolean",
"description": "For data source plugins. If the plugin supports streaming.",
"default": false
},
"tables": {
"$id": "#/properties/tables",
"type": "boolean",
"default": false
},
"tracing": {
"$id": "#/properties/tracing",
"type": "boolean",
"description": "For data source plugins. If the plugin supports tracing.",
"default": false
},
"hiddenQueries": {
"$id": "#/properties/hiddenQueries",
"type": "boolean"
},
"dependencies": {
"$id": "#/properties/dependencies",
"type": "object",
"description": "Plugin dependencies.",
"required": ["grafanaVersion"],
"additionalProperties": false,
"properties": {
"grafanaVersion": {
"$id": "#/properties/dependencies/properties/grafanaVersion",
"type": "string",
"description": "Required Grafana version for this plugin, e.g. `6.x.x 7.x.x` to denote plugin requires Grafana v6.x.x or v7.x.x.",
"pattern": "^([0-9x]+\\.[0-9x]+\\.*[0-9x]*\\s*)+$"
},
"plugins": {
"$id": "#/properties/dependencies/properties/plugins",
"type": "array",
"description": "An array of required plugins on which this plugin depends.",
"items": {
"$id": "#/properties/dependencies/properties/plugins/items"
}
}
}
},
"info": {
"$id": "#/properties/info",
"type": "object",
"description": "Metadata for the plugin. Some fields are used on the plugins page in Grafana and others on grafana.com if the plugin is published.",
"required": ["logos", "version", "updated"],
"additionalProperties": false,
"properties": {
"author": {
"$id": "#/properties/info/properties/author",
"type": "object",
"description": "Information about the plugin author.",
"additionalProperties": false,
"properties": {
"name": {
"$id": "#/properties/info/properties/author/properties/name",
"type": "string",
"description": "Author's name."
},
"email": {
"$id": "#/properties/info/properties/author/properties/email",
"type": "string",
"description": "Author's name.",
"format": "email"
},
"url": {
"$id": "#/properties/info/properties/author/properties/url",
"type": "string",
"description": "Link to author's website.",
"format": "uri"
}
}
},
"description": {
"$id": "#/properties/info/properties/description",
"type": "string",
"description": "Description of plugin. Used on the plugins page in Grafana and for search on grafana.com."
},
"keywords": {
"$id": "#/properties/info/properties/keywords",
"type": "array",
"description": "Array of plugin keywords. Used for search on grafana.com.",
"items": {
"$id": "#/properties/info/properties/keywords/items"
}
},
"links": {
"$id": "#/properties/info/properties/links",
"type": "array",
"description": "An array of link objects to be displayed on this plugin's project page in the form `{name: 'foo', url: 'http://example.com'}`",
"items": {
"$id": "#/properties/info/properties/links/items",
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
}
}
}
},
"logos": {
"$id": "#/properties/info/properties/logos",
"type": "object",
"description": "SVG images that are used as plugin icons.",
"required": ["small", "large"],
"additionalProperties": false,
"properties": {
"small": {
"$id": "#/properties/info/properties/logos/properties/small",
"type": "string",
"description": "Link to the \"small\" version of the plugin logo, which must be an SVG image. \"Large\" and \"small\" logos can be the same image.",
"examples": ["img/logo.svg"]
},
"large": {
"$id": "#/properties/info/properties/logos/properties/large",
"type": "string",
"description": "Link to the \"large\" version of the plugin logo, which must be an SVG image. \"Large\" and \"small\" logos can be the same image.",
"examples": ["img/logo.svg"]
}
}
},
"screenshots": {
"$id": "#/properties/info/properties/screenshots",
"type": "array",
"description": "An array of screenshot objects in the form `{name: 'bar', path: 'img/screenshot.png'}`",
"items": {
"$id": "#/properties/info/properties/screenshots/items",
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"$id": "#/properties/info/properties/screenshots/items/properties/name",
"type": "string"
},
"path": {
"$id": "#/properties/info/properties/screenshots/items/properties/path",
"type": "string"
}
}
}
},
"updated": {
"$id": "#/properties/info/properties/updated",
"type": "string",
"description": "Date when this plugin was built.",
"pattern": "^(\\d{4}-\\d{2}-\\d{2}|\\%TODAY\\%)$"
},
"version": {
"$id": "#/properties/info/properties/version",
"type": "string",
"description": "Project version of this commit, e.g. `6.7.x`.",
"pattern": "^([0-9x]+\\.[0-9x]+\\.*[0-9x]*$|\\%VERSION\\%)"
}
}
},
"queryOptions": {
"$id": "#/properties/queryOptions",
"type": "object",
"description": "For data source plugins. There is a query options section in the plugin's query editor and these options can be turned on if needed.",
"additionalProperties": false,
"properties": {
"maxDataPoints": {
"$id": "#/properties/queryOptions/properties/maxDataPoints",
"type": "boolean",
"description": "For data source plugins. If the `max data points` option should be shown in the query options section in the query editor."
},
"minInterval": {
"$id": "#/properties/queryOptions/properties/minInterval",
"type": "boolean",
"description": "For data source plugins. If the `min interval` option should be shown in the query options section in the query editor."
},
"cacheTimeout": {
"$id": "#/properties/queryOptions/properties/cacheTimeout",
"type": "boolean",
"description": "For data source plugins. If the `cache timeout` option should be shown in the query options section in the query editor."
}
}
},
"routes": {
"$id": "#/properties/routes",
"type": "array",
"description": "For data source plugins. Proxy routes used for plugin authentication and adding headers to HTTP requests made by the plugin. For more information, refer to [Authentication for data source plugins](https://grafana.com/docs/grafana/latest/developers/plugins/authentication/).",
"items": {
"$id": "#/properties/routes/items",
"type": "object",
"description": "For data source plugins. Proxy routes used for plugin authentication and adding headers to HTTP requests made by the plugin. For more information, refer to [Authentication for data source plugins](https://grafana.com/docs/grafana/latest/developers/plugins/authentication/).",
"additionalProperties": false,
"properties": {
"path": {
"$id": "#/properties/routes/items/properties/path",
"type": "string",
"description": "For data source plugins. The route path that is replaced by the route URL field when proxying the call."
},
"method": {
"$id": "#/properties/routes/items/properties/method",
"type": "string",
"description": "For data source plugins. Route method matches the HTTP verb like GET or POST."
},
"url": {
"$id": "#/properties/routes/items/properties/url",
"type": "string",
"description": "For data source plugins. Route URL is where the request is proxied to.",
"format": "uri"
},
"reqSignedIn": {
"$id": "#/properties/routes/items/properties/reqSignedIn",
"type": "boolean"
},
"reqRole": {
"$id": "#/properties/routes/items/properties/reqRole",
"type": "string"
},
"headers": {
"$id": "#/properties/routes/items/properties/headers",
"type": "array",
"description": "For data source plugins. Route headers adds HTTP headers to the proxied request."
},
"tokenAuth": {
"$id": "#/properties/routes/items/properties/tokenAuth",
"type": "object",
"description": "For data source plugins. Token authentication section used with an OAuth API.",
"additionalProperties": false,
"properties": {
"url": {
"$id": "#/properties/routes/items/properties/tokenAuth/properties/url",
"type": "string",
"description": "For data source plugins. URL to fetch the authentication token.",
"format": "uri"
},
"params": {
"$id": "#/properties/routes/items/properties/tokenAuth/properties/params",
"type": "object",
"description": "For data source plugins. Parameters for the token authentication request.",
"additionalProperties": false,
"properties": {
"grant_type": {
"$id": "#/properties/routes/items/properties/tokenAuth/properties/params/properties/grant_type",
"type": "string",
"description": "For data source plugins. OAuth grant type."
},
"client_id": {
"$id": "#/properties/routes/items/properties/tokenAuth/properties/params/properties/client_id",
"type": "string",
"description": "For data source plugins. OAuth client id."
},
"client_secret": {
"$id": "#/properties/routes/items/properties/tokenAuth/properties/params/properties/client_secret",
"type": "string",
"description": "For data source plugins. OAuth client secret. Usually populated by decrypting the secret from the SecureJson blob."
},
"resource": {
"$id": "#/properties/routes/items/properties/tokenAuth/properties/params/properties/client_secret",
"type": "string",
"description": "For data source plugins. OAuth resource."
}
}
}
}
}
}
}
}
}
}