From 8bb9600cc64a4dc47da42ccd0cdfd25d1ec8b8f0 Mon Sep 17 00:00:00 2001 From: Stephanie Closson Date: Tue, 24 Aug 2021 11:45:41 -0300 Subject: [PATCH] Chore: Updated plugin schema docs ref PR@38463 (#38501) * updated plugin schema docs ref PR@38463 * Documentation updates as per review --- docs/sources/developers/plugins/metadata.md | 66 +++++++++++-------- .../developers/plugins/plugin.schema.json | 24 +++---- 2 files changed, 52 insertions(+), 38 deletions(-) diff --git a/docs/sources/developers/plugins/metadata.md b/docs/sources/developers/plugins/metadata.md index ee0a31de9ff..f2be588ede9 100644 --- a/docs/sources/developers/plugins/metadata.md +++ b/docs/sources/developers/plugins/metadata.md @@ -13,32 +13,33 @@ The plugin.json file is required for all plugins. When Grafana starts, it scans ## Properties -| Property | Type | Required | Description | -| --------------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `dependencies` | [object](#dependencies) | **Yes** | Dependencies needed by the plugin. | -| `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`, `panel`. | -| `$schema` | string | No | Schema definition for the plugin.json file | -| `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. | -| `autoEnabled` | boolean | No | Set to true for app plugins that should be enabled by default in all orgs | -| `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`, `sql`, `enterprise`, `other`. | -| `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 `_<$GOOS>_<.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` | [object](#includes)[] | No | Resources to include in plugin. | -| `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. | -| `preload` | boolean | No | Initialize plugin on startup. By default, the plugin initializes on first use. | -| `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` | [object](#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 [Add authentication for data source plugins]({{< relref "add-authentication-for-data-source-plugins.md">}}). | -| `skipDataQuery` | boolean | No | For panel plugins. Hides the query editor. | -| `state` | string | No | Marks a plugin as a pre-release. Possible values are: `alpha`, `beta`. | -| `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. | +| Property | Type | Required | Description | +| -------------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `dependencies` | [object](#dependencies) | **Yes** | Dependencies needed by the plugin. | +| `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`, `panel`. | +| `$schema` | string | No | Schema definition for the plugin.json file. | +| `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. | +| `autoEnabled` | boolean | No | Set to true for app plugins that should be enabled by default in all orgs | +| `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`, `sql`, `enterprise`, `other`. | +| `enterpriseFeatures` | [object](#enterprisefeatures) | No | Grafana Enerprise specific features. | +| `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 `_<$GOOS>_<.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 | For data source plugins, include hidden queries in the data request. | +| `includes` | [object](#includes)[] | No | Resources to include in plugin. | +| `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 Explore. | +| `preload` | boolean | No | Initialize plugin on startup. By default, the plugin initializes on first use. | +| `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` | [object](#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/). | +| `skipDataQuery` | boolean | No | For panel plugins. Hides the query editor. | +| `state` | string | No | Marks a plugin as a pre-release. Possible values are: `alpha`, `beta`. | +| `streaming` | boolean | No | For data source plugins, if the plugin supports streaming. | +| `tables` | boolean | No | This is an undocumented feature. | +| `tracing` | boolean | No | For data source plugins, if the plugin supports tracing. | ## dependencies @@ -65,6 +66,16 @@ Plugin dependency. Used to display information about plugin dependencies in the | `type` | string | **Yes** | Possible values are: `app`, `datasource`, `panel`. | | `version` | string | **Yes** | | +## enterpriseFeatures + +Grafana Enerprise specific features. + +### Properties + +| Property | Type | Required | Description | +| ------------------------- | ------- | -------- | ------------------------------------------------------------------- | +| `healthDiagnosticsErrors` | boolean | No | Enable/Disable health diagnostics errors. Requires Grafana >=7.5.5. | + ## includes ### Properties @@ -79,6 +90,7 @@ Plugin dependency. Used to display information about plugin dependencies in the | `path` | string | No | Used for app plugins. | | `role` | string | No | Possible values are: `Admin`, `Editor`, `Viewer`. | | `type` | string | No | Possible values are: `dashboard`, `page`, `panel`, `datasource`. | +| `uid` | string | No | Unique identifier of the included resource | ## info @@ -168,7 +180,7 @@ For data source plugins. There is a query options section in the plugin's query ## 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 [Add authentication for data source plugins]({{< relref "add-authentication-for-data-source-plugins.md">}}). +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 diff --git a/docs/sources/developers/plugins/plugin.schema.json b/docs/sources/developers/plugins/plugin.schema.json index 7a4ec27de32..f478c070201 100644 --- a/docs/sources/developers/plugins/plugin.schema.json +++ b/docs/sources/developers/plugins/plugin.schema.json @@ -9,7 +9,7 @@ "properties": { "$schema": { "type": "string", - "description": "Schema definition for the plugin.json file" + "description": "Schema definition for the plugin.json file." }, "id": { "type": "string", @@ -32,11 +32,11 @@ }, "annotations": { "type": "boolean", - "description": "For data source plugins. If the plugin supports annotation queries." + "description": "For data source plugins, if the plugin supports annotation queries." }, "alerting": { "type": "boolean", - "description": "For data source plugins. If the plugin supports alerting." + "description": "For data source plugins, if the plugin supports alerting." }, "backend": { "type": "boolean", @@ -102,7 +102,7 @@ }, "logs": { "type": "boolean", - "description": "For data source plugins. If the plugin supports logs." + "description": "For data source plugins, if the plugin supports logs." }, "skipDataQuery": { "type": "boolean", @@ -110,21 +110,23 @@ }, "metrics": { "type": "boolean", - "description": "For data source plugins. If the plugin supports metric queries. Used in the Explore feature." + "description": "For data source plugins, if the plugin supports metric queries. Used in Explore." }, "streaming": { "type": "boolean", - "description": "For data source plugins. If the plugin supports streaming." + "description": "For data source plugins, if the plugin supports streaming." }, "tables": { - "type": "boolean" + "type": "boolean", + "description": "This is an undocumented feature." }, "tracing": { "type": "boolean", - "description": "For data source plugins. If the plugin supports tracing." + "description": "For data source plugins, if the plugin supports tracing." }, "hiddenQueries": { - "type": "boolean" + "type": "boolean", + "description": "For data source plugins, include hidden queries in the data request." }, "autoEnabled": { "type": "boolean", @@ -443,12 +445,12 @@ }, "enterpriseFeatures": { "type": "object", - "description": "Grafana Enerprise specific features", + "description": "Grafana Enerprise specific features.", "additionalProperties": true, "properties": { "healthDiagnosticsErrors": { "type": "boolean", - "description": "Enable/Disable health diagnostics errors. Requires Grafana >=7.5.5", + "description": "Enable/Disable health diagnostics errors. Requires Grafana >=7.5.5.", "default": false } }