From 80e8ac640ea15701b5c45dda456eb7f01b5679bf Mon Sep 17 00:00:00 2001 From: Andres Martinez Gotor Date: Fri, 10 Mar 2023 15:07:35 +0100 Subject: [PATCH] Docs: Update plugin.json docs and schema (#64297) --- docs/sources/developers/plugins/metadata.md | 22 +- .../developers/plugins/plugin.schema.json | 347 +++++++++--------- pkg/plugins/plugindef/plugindef.cue | 142 ++++--- pkg/plugins/plugindef/plugindef_types_gen.go | 33 +- 4 files changed, 266 insertions(+), 278 deletions(-) diff --git a/docs/sources/developers/plugins/metadata.md b/docs/sources/developers/plugins/metadata.md index 2b2b343499f..9a6628e4173 100644 --- a/docs/sources/developers/plugins/metadata.md +++ b/docs/sources/developers/plugins/metadata.md @@ -22,25 +22,23 @@ The plugin.json file is required for all plugins. When Grafana starts, it scans | `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. | | `dependencies` | [object](#dependencies) | **Yes** | Dependency information related to Grafana and other plugins. | | `$schema` | string | No | Schema definition for the plugin.json file. Used primarily for schema validation. | -| `alerting` | boolean | No | For data source plugins, if the plugin supports alerting. | +| `alerting` | boolean | No | For data source plugins, if the plugin supports alerting. Requires `backend` to be set to `true`. | | `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 | +| `autoEnabled` | boolean | No | Set to true for app plugins that should be enabled and pinned to the navigation bar 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. | +| `category` | string | No | Plugin category used on the "Add data source" page. Possible values are: `tsdb`, `logging`, `cloud`, `tracing`, `profiling`, `sql`, `enterprise`, `iot`, `other`. | +| `enterpriseFeatures` | [object](#enterprisefeatures) | No | Grafana Enterprise 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. | +| `logs` | boolean | No | For data source plugins, if the plugin supports logs. It may be used to filter logs only features. | +| `metrics` | boolean | No | For data source plugins, if the plugin supports metric queries. Used to enable the plugin in the panel editor. | +| `preload` | boolean | No | Initialize plugin on startup. By default, the plugin initializes on first use. Useful for app plugins that should load without user interaction. | | `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. | +| `streaming` | boolean | No | For data source plugins, if the plugin supports streaming. Used in Explore to start live streaming. | +| `tracing` | boolean | No | For data source plugins, if the plugin supports tracing. Used for example to link logs (e.g. Loki logs) with tracing plugins. | ## dependencies @@ -69,7 +67,7 @@ Plugin dependency. Used to display information about plugin dependencies in the ## enterpriseFeatures -Grafana Enerprise specific features. +Grafana Enterprise specific features. ### Properties diff --git a/docs/sources/developers/plugins/plugin.schema.json b/docs/sources/developers/plugins/plugin.schema.json index 374d11028af..b90c6addc15 100644 --- a/docs/sources/developers/plugins/plugin.schema.json +++ b/docs/sources/developers/plugins/plugin.schema.json @@ -17,166 +17,6 @@ "description": "Plugin type.", "enum": ["app", "datasource", "panel", "renderer", "secretsmanager"] }, - "name": { - "type": "string", - "description": "Human-readable name of the plugin that is shown to the user in the UI." - }, - "dependencies": { - "type": "object", - "description": "Dependency information related to Grafana and other plugins.", - "required": ["grafanaDependency"], - "additionalProperties": false, - "properties": { - "grafanaVersion": { - "type": "string", - "description": "(Deprecated) 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-9]+)(\\.[0-9x]+)?(\\.[0-9x])?$" - }, - "grafanaDependency": { - "type": "string", - "description": "Required Grafana version for this plugin. Validated using https://github.com/npm/node-semver.", - "pattern": "^(<=|>=|<|>|=|~|\\^)?([0-9]+)(\\.[0-9x\\*]+)(\\.[0-9x\\*]+)?(\\s(<=|>=|<|=>)?([0-9]+)(\\.[0-9x]+)(\\.[0-9x]+))?$" - }, - "plugins": { - "type": "array", - "description": "An array of required plugins on which this plugin depends.", - "additionalItems": false, - "items": { - "type": "object", - "description": "Plugin dependency. Used to display information about plugin dependencies in the Grafana UI.", - "required": ["id", "name", "type", "version"], - "properties": { - "id": { - "type": "string", - "pattern": "^[0-9a-z]+\\-([0-9a-z]+\\-)?(app|panel|datasource|secretsmanager)$" - }, - "type": { - "type": "string", - "enum": ["app", "datasource", "panel", "secretsmanager"] - }, - "name": { - "type": "string" - }, - "version": { - "type": "string" - } - } - } - } - } - }, - "$schema": { - "type": "string", - "description": "Schema definition for the plugin.json file. Used primarily for schema validation." - }, - "category": { - "type": "string", - "description": "Plugin category used on the Add data source page.", - "enum": ["tsdb", "logging", "cloud", "tracing", "sql", "enterprise", "other"] - }, - "annotations": { - "type": "boolean", - "description": "For data source plugins, if the plugin supports annotation queries." - }, - "alerting": { - "type": "boolean", - "description": "For data source plugins, if the plugin supports alerting." - }, - "backend": { - "type": "boolean", - "description": "If the plugin has a backend component." - }, - "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 `_<$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." - }, - "preload": { - "type": "boolean", - "description": "Initialize plugin on startup. By default, the plugin initializes on first use." - }, - "state": { - "type": "string", - "description": "Marks a plugin as a pre-release.", - "enum": ["alpha", "beta"] - }, - "includes": { - "type": "array", - "description": "Resources to include in plugin.", - "items": { - "type": "object", - "additionalItems": false, - "properties": { - "uid": { - "type": "string", - "description": "Unique identifier of the included resource" - }, - "type": { - "type": "string", - "enum": ["dashboard", "page", "panel", "datasource", "secretsmanager"] - }, - "name": { - "type": "string" - }, - "component": { - "type": "string", - "description": "(Legacy) The Angular component to use for a page." - }, - "role": { - "type": "string", - "description": "The minimum role a user must have to see this page in the navigation menu.", - "enum": ["Admin", "Editor", "Viewer"] - }, - "path": { - "type": "string", - "description": "Used for app plugins." - }, - "addToNav": { - "type": "boolean", - "description": "Add the include to the navigation menu." - }, - "defaultNav": { - "type": "boolean", - "description": "Page or dashboard when user clicks the icon in the side menu." - }, - "icon": { - "type": "string", - "description": "Icon to use in the side menu. For information on available icon, refer to [Icons Overview](https://developers.grafana.com/ui/latest/index.html?path=/story/docs-overview-icon--icons-overview)." - } - } - } - }, - "logs": { - "type": "boolean", - "description": "For data source plugins, if the plugin supports logs." - }, - "skipDataQuery": { - "type": "boolean", - "description": "For panel plugins. Hides the query editor." - }, - "metrics": { - "type": "boolean", - "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." - }, - "tables": { - "type": "boolean", - "description": "This is an undocumented feature." - }, - "tracing": { - "type": "boolean", - "description": "For data source plugins, if the plugin supports tracing." - }, - "hiddenQueries": { - "type": "boolean", - "description": "For data source plugins, include hidden queries in the data request." - }, - "autoEnabled": { - "type": "boolean", - "description": "Set to true for app plugins that should be enabled by default in all orgs" - }, "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.", @@ -308,6 +148,166 @@ } } }, + "name": { + "type": "string", + "description": "Human-readable name of the plugin that is shown to the user in the UI." + }, + "dependencies": { + "type": "object", + "description": "Dependency information related to Grafana and other plugins.", + "required": ["grafanaDependency"], + "additionalProperties": false, + "properties": { + "grafanaVersion": { + "type": "string", + "description": "(Deprecated) 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-9]+)(\\.[0-9x]+)?(\\.[0-9x])?$" + }, + "grafanaDependency": { + "type": "string", + "description": "Required Grafana version for this plugin. Validated using https://github.com/npm/node-semver.", + "pattern": "^(<=|>=|<|>|=|~|\\^)?([0-9]+)(\\.[0-9x\\*]+)(\\.[0-9x\\*]+)?(\\s(<=|>=|<|=>)?([0-9]+)(\\.[0-9x]+)(\\.[0-9x]+))?$" + }, + "plugins": { + "type": "array", + "description": "An array of required plugins on which this plugin depends.", + "additionalItems": false, + "items": { + "type": "object", + "description": "Plugin dependency. Used to display information about plugin dependencies in the Grafana UI.", + "required": ["id", "name", "type", "version"], + "properties": { + "id": { + "type": "string", + "pattern": "^[0-9a-z]+\\-([0-9a-z]+\\-)?(app|panel|datasource|secretsmanager)$" + }, + "type": { + "type": "string", + "enum": ["app", "datasource", "panel", "secretsmanager"] + }, + "name": { + "type": "string" + }, + "version": { + "type": "string" + } + } + } + } + } + }, + "$schema": { + "type": "string", + "description": "Schema definition for the plugin.json file. Used primarily for schema validation." + }, + "alerting": { + "type": "boolean", + "description": "For data source plugins, if the plugin supports alerting. Requires `backend` to be set to `true`." + }, + "annotations": { + "type": "boolean", + "description": "For data source plugins, if the plugin supports annotation queries." + }, + "autoEnabled": { + "type": "boolean", + "description": "Set to true for app plugins that should be enabled and pinned to the navigation bar in all orgs." + }, + "backend": { + "type": "boolean", + "description": "If the plugin has a backend component." + }, + "builtIn": { + "type": "boolean", + "description": "[internal only] Indicates whether the plugin is developed and shipped as part of Grafana. Also known as a 'core plugin'." + }, + "category": { + "type": "string", + "description": "Plugin category used on the Add data source page.", + "enum": ["tsdb", "logging", "cloud", "tracing", "profiling", "sql", "enterprise", "iot", "other"] + }, + "enterpriseFeatures": { + "type": "object", + "description": "Grafana Enterprise specific features", + "additionalProperties": true, + "properties": { + "healthDiagnosticsErrors": { + "type": "boolean", + "description": "Enable/Disable health diagnostics errors. Requires Grafana >=7.5.5.", + "default": false + } + } + }, + "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 `_<$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." + }, + "hideFromList": { + "type": "boolean", + "description": "[internal only] Excludes the plugin from listings in Grafana's UI. Only allowed for `builtIn` plugins." + }, + "includes": { + "type": "array", + "description": "Resources to include in plugin.", + "items": { + "type": "object", + "additionalItems": false, + "properties": { + "uid": { + "type": "string", + "description": "Unique identifier of the included resource" + }, + "type": { + "type": "string", + "enum": ["dashboard", "page", "panel", "datasource", "secretsmanager"] + }, + "name": { + "type": "string" + }, + "component": { + "type": "string", + "description": "(Legacy) The Angular component to use for a page." + }, + "role": { + "type": "string", + "description": "The minimum role a user must have to see this page in the navigation menu.", + "enum": ["Admin", "Editor", "Viewer"] + }, + "path": { + "type": "string", + "description": "Used for app plugins." + }, + "addToNav": { + "type": "boolean", + "description": "Add the include to the navigation menu." + }, + "defaultNav": { + "type": "boolean", + "description": "Page or dashboard when user clicks the icon in the side menu." + }, + "icon": { + "type": "string", + "description": "Icon to use in the side menu. For information on available icon, refer to [Icons Overview](https://developers.grafana.com/ui/latest/index.html?path=/story/docs-overview-icon--icons-overview)." + } + } + } + }, + "logs": { + "type": "boolean", + "description": "For data source plugins, if the plugin supports logs. It may be used to filter logs only features." + }, + "metrics": { + "type": "boolean", + "description": "For data source plugins, if the plugin supports metric queries. Used to enable the plugin in the panel editor." + }, + "pascalName": { + "type": "string", + "description": "[internal only] The PascalCase name for the plugin. Used for creating machine-friendly identifiers, typically in code generation. If not provided, defaults to name, but title-cased and sanitized (only alphabetical characters allowed).", + "pattern": "^([A-Z][a-zA-Z]{1,62})$" + }, + "preload": { + "type": "boolean", + "description": "Initialize plugin on startup. By default, the plugin initializes on first use. Useful for app plugins that should load without user interaction." + }, "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.", @@ -461,17 +461,22 @@ } } }, - "enterpriseFeatures": { - "type": "object", - "description": "Grafana Enterprise specific features.", - "additionalProperties": true, - "properties": { - "healthDiagnosticsErrors": { - "type": "boolean", - "description": "Enable/Disable health diagnostics errors. Requires Grafana >=7.5.5.", - "default": false - } - } + "skipDataQuery": { + "type": "boolean", + "description": "For panel plugins. Hides the query editor." + }, + "state": { + "type": "string", + "description": "Marks a plugin as a pre-release.", + "enum": ["alpha", "beta"] + }, + "streaming": { + "type": "boolean", + "description": "For data source plugins, if the plugin supports streaming. Used in Explore to start live streaming." + }, + "tracing": { + "type": "boolean", + "description": "For data source plugins, if the plugin supports tracing. Used for example to link logs (e.g. Loki logs) with tracing plugins." } } } diff --git a/pkg/plugins/plugindef/plugindef.cue b/pkg/plugins/plugindef/plugindef.cue index 550a8d447ed..69c53b9a1c2 100644 --- a/pkg/plugins/plugindef/plugindef.cue +++ b/pkg/plugins/plugindef/plugindef.cue @@ -146,38 +146,33 @@ seqs: [ // Schema definition for the plugin.json file. Used primarily for schema validation. $schema?: string - // FIXME there appears to be a bug in thema that prevents this from working. Maybe it'd - // help to refer to it with an alias, but thema can't support using current list syntax. - // syntax (fixed by grafana/thema#82). Either way, for now, pascalName gets populated in Go. - let sani = (strings.ToTitle(regexp.ReplaceAllLiteral("[^a-zA-Z]+", name, ""))) - - // The PascalCase name for the plugin. Used for creating machine-friendly - // identifiers, typically in code generation. - // - // If not provided, defaults to name, but title-cased and sanitized (only - // alphabetical characters allowed). - pascalName: string & =~"^([A-Z][a-zA-Z]{1,62})$" | *sani - - // Plugin category used on the Add data source page. - category?: "tsdb" | "logging" | "cloud" | "tracing" | "sql" | "enterprise" | "profiling" | "other" + // For data source plugins, if the plugin supports alerting. Requires `backend` to be set to `true`. + alerting?: bool // For data source plugins, if the plugin supports annotation // queries. annotations?: bool - // For data source plugins, if the plugin supports alerting. - alerting?: bool + // Set to true for app plugins that should be enabled and pinned to the navigation bar in all orgs. + autoEnabled?: bool // If the plugin has a backend component. backend?: bool - // builtin indicates whether the plugin is developed and shipped as part - // of Grafana. Also known as a "core plugin." + // [internal only] Indicates whether the plugin is developed and shipped as part + // of Grafana. Also known as a 'core plugin'. builtIn: bool | *false - // hideFromList excludes the plugin from listings in Grafana's UI. Only - // allowed for builtin plugins. - hideFromList: bool | *false + // Plugin category used on the Add data source page. + category?: "tsdb" | "logging" | "cloud" | "tracing" | "profiling" | "sql" | "enterprise" | "iot" | "other" + + // Grafana Enterprise specific features. + enterpriseFeatures?: { + // Enable/Disable health diagnostics errors. Requires Grafana + // >=7.5.5. + healthDiagnosticsErrors?: bool | *false + ... + } // The first part of the file name of the backend component // executable. There can be multiple executables built for @@ -188,15 +183,9 @@ seqs: [ // https://golang.org/doc/install/source#environment. executable?: string - // Initialize plugin on startup. By default, the plugin - // initializes on first use. - preload?: bool - - // Marks a plugin as a pre-release. - state?: #ReleaseState - - // ReleaseState indicates release maturity state of a plugin. - #ReleaseState: "alpha" | "beta" | "deprecated" | *"stable" + // [internal only] Excludes the plugin from listings in Grafana's UI. Only + // allowed for `builtIn` plugins. + hideFromList: bool | *false // Resources to include in plugin. includes?: [...#Include] @@ -233,33 +222,64 @@ seqs: [ ... } - // For data source plugins, if the plugin supports logs. + // For data source plugins, if the plugin supports logs. It may be used to filter logs only features. logs?: bool + // For data source plugins, if the plugin supports metric queries. + // Used to enable the plugin in the panel editor. + metrics?: bool + + // FIXME there appears to be a bug in thema that prevents this from working. Maybe it'd + // help to refer to it with an alias, but thema can't support using current list syntax. + // syntax (fixed by grafana/thema#82). Either way, for now, pascalName gets populated in Go. + let sani = (strings.ToTitle(regexp.ReplaceAllLiteral("[^a-zA-Z]+", name, ""))) + + // [internal only] The PascalCase name for the plugin. Used for creating machine-friendly + // identifiers, typically in code generation. + // + // If not provided, defaults to name, but title-cased and sanitized (only + // alphabetical characters allowed). + pascalName: string & =~"^([A-Z][a-zA-Z]{1,62})$" | *sani + + // Initialize plugin on startup. By default, the plugin + // initializes on first use. + preload?: bool + + // 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. + queryOptions?: { + // For data source plugins. If the `max data points` option should + // be shown in the query options section in the query editor. + maxDataPoints?: bool + + // For data source plugins. If the `min interval` option should be + // shown in the query options section in the query editor. + minInterval?: bool + + // For data source plugins. If the `cache timeout` option should + // be shown in the query options section in the query editor. + cacheTimeout?: bool + } + + // Routes is a list of proxy routes, if any. For datasource plugins only. + routes?: [...#Route] + // For panel plugins. Hides the query editor. skipDataQuery?: bool - // For data source plugins, if the plugin supports metric queries. - // Used in Explore. - metrics?: bool + // Marks a plugin as a pre-release. + state?: #ReleaseState - // For data source plugins, if the plugin supports streaming. + // ReleaseState indicates release maturity state of a plugin. + #ReleaseState: "alpha" | "beta" | "deprecated" | *"stable" + + // For data source plugins, if the plugin supports streaming. Used in Explore to start live streaming. streaming?: bool - // This is an undocumented feature. - tables?: bool - - // For data source plugins, if the plugin supports tracing. + // For data source plugins, if the plugin supports tracing. Used for example to link logs (e.g. Loki logs) with tracing plugins. tracing?: bool - // For data source plugins, include hidden queries in the data - // request. - hiddenQueries?: bool - - // Set to true for app plugins that should be enabled by default - // in all orgs - autoEnabled?: bool - // Optional list of RBAC RoleRegistrations. // Describes and organizes the default permissions associated with any of the Grafana basic roles, // which characterizes what viewers, editors, admins, or grafana admins can do on the plugin. @@ -305,26 +325,6 @@ seqs: [ // in turn inherits them from the Viewer basic role. #BasicRole: "Grafana Admin" | "Admin" | "Editor" | "Viewer" - // 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. - queryOptions?: { - // For data source plugins. If the `max data points` option should - // be shown in the query options section in the query editor. - maxDataPoints?: bool - - // For data source plugins. If the `min interval` option should be - // shown in the query options section in the query editor. - minInterval?: bool - - // For data source plugins. If the `cache timeout` option should - // be shown in the query options section in the query editor. - cacheTimeout?: bool - } - - // Routes is a list of proxy routes, if any. For datasource plugins only. - routes?: [...#Route] - // Header describes an HTTP header that is forwarded with a proxied request for // a plugin route. #Header: { @@ -406,14 +406,6 @@ seqs: [ // Parameters for the JWT token authentication request. params: [string]: string } - - // Grafana Enerprise specific features. - enterpriseFeatures?: { - // Enable/Disable health diagnostics errors. Requires Grafana - // >=7.5.5. - healthDiagnosticsErrors?: bool | *false - ... - } }, ] }, diff --git a/pkg/plugins/plugindef/plugindef_types_gen.go b/pkg/plugins/plugindef/plugindef_types_gen.go index 6a19e32a452..3c3832925d5 100644 --- a/pkg/plugins/plugindef/plugindef_types_gen.go +++ b/pkg/plugins/plugindef/plugindef_types_gen.go @@ -46,6 +46,7 @@ const ( const ( CategoryCloud Category = "cloud" CategoryEnterprise Category = "enterprise" + CategoryIot Category = "iot" CategoryLogging Category = "logging" CategoryOther Category = "other" CategoryProfiling Category = "profiling" @@ -252,29 +253,28 @@ type PluginDef struct { // Schema definition for the plugin.json file. Used primarily for schema validation. Schema *string `json:"$schema,omitempty"` - // For data source plugins, if the plugin supports alerting. + // For data source plugins, if the plugin supports alerting. Requires `backend` to be set to `true`. Alerting *bool `json:"alerting,omitempty"` // For data source plugins, if the plugin supports annotation // queries. Annotations *bool `json:"annotations,omitempty"` - // Set to true for app plugins that should be enabled by default - // in all orgs + // Set to true for app plugins that should be enabled and pinned to the navigation bar in all orgs. AutoEnabled *bool `json:"autoEnabled,omitempty"` // If the plugin has a backend component. Backend *bool `json:"backend,omitempty"` - // builtin indicates whether the plugin is developed and shipped as part - // of Grafana. Also known as a "core plugin." + // [internal only] Indicates whether the plugin is developed and shipped as part + // of Grafana. Also known as a 'core plugin'. BuiltIn bool `json:"builtIn"` // Plugin category used on the Add data source page. Category *Category `json:"category,omitempty"` Dependencies Dependencies `json:"dependencies"` - // Grafana Enerprise specific features. + // Grafana Enterprise specific features. EnterpriseFeatures *struct { // Enable/Disable health diagnostics errors. Requires Grafana // >=7.5.5. @@ -290,12 +290,8 @@ type PluginDef struct { // https://golang.org/doc/install/source#environment. Executable *string `json:"executable,omitempty"` - // For data source plugins, include hidden queries in the data - // request. - HiddenQueries *bool `json:"hiddenQueries,omitempty"` - - // hideFromList excludes the plugin from listings in Grafana's UI. Only - // allowed for builtin plugins. + // [internal only] Excludes the plugin from listings in Grafana's UI. Only + // allowed for `builtIn` plugins. HideFromList bool `json:"hideFromList"` // Unique name of the plugin. If the plugin is published on @@ -310,18 +306,18 @@ type PluginDef struct { // page in Grafana and others on grafana.com, if the plugin is published. Info Info `json:"info"` - // For data source plugins, if the plugin supports logs. + // For data source plugins, if the plugin supports logs. It may be used to filter logs only features. Logs *bool `json:"logs,omitempty"` // For data source plugins, if the plugin supports metric queries. - // Used in Explore. + // Used to enable the plugin in the panel editor. Metrics *bool `json:"metrics,omitempty"` // Human-readable name of the plugin that is shown to the user in // the UI. Name string `json:"name"` - // The PascalCase name for the plugin. Used for creating machine-friendly + // [internal only] The PascalCase name for the plugin. Used for creating machine-friendly // identifiers, typically in code generation. // // If not provided, defaults to name, but title-cased and sanitized (only @@ -365,13 +361,10 @@ type PluginDef struct { // ReleaseState indicates release maturity state of a plugin. State *ReleaseState `json:"state,omitempty"` - // For data source plugins, if the plugin supports streaming. + // For data source plugins, if the plugin supports streaming. Used in Explore to start live streaming. Streaming *bool `json:"streaming,omitempty"` - // This is an undocumented feature. - Tables *bool `json:"tables,omitempty"` - - // For data source plugins, if the plugin supports tracing. + // For data source plugins, if the plugin supports tracing. Used for example to link logs (e.g. Loki logs) with tracing plugins. Tracing *bool `json:"tracing,omitempty"` // type indicates which type of Grafana plugin this is, of the defined