metadata.md

id	plugin-json
title	Metadata (plugin.json)
description	Reference for the Grafana plugin.json metadata file.
keywords	grafana plugins documentation plugin.json API reference API
sidebar_position	10

Plugin metadata (plugin.json)

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.

Properties

Name	Type	Description	Required
id	string	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]+\-([0-9a-z]+\-)?(app|panel|datasource)$	✅
type	string	Plugin type. Possible values are: "app", "datasource", "panel", "renderer"	✅
info	object	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	Human-readable name of the plugin that is shown to the user in the UI.	✅
dependencies	object	Dependency information related to Grafana and other plugins.	✅
$schema	string	Schema definition for the plugin.json file. Used primarily for schema validation.
alerting	boolean	For data source plugins, if the plugin supports alerting. Requires backend to be set to true.
annotations	boolean	For data source plugins, if the plugin supports annotation queries.
autoEnabled	boolean	Set to true for app plugins that should be enabled and pinned to the navigation bar in all orgs.
backend	boolean	If the plugin has a backend component.
buildMode	string	The build mode of the plugin. This field is set automatically at build time, so it should not be provided manually.
builtIn	boolean	[internal only] Indicates whether the plugin is developed and shipped as part of Grafana. Also known as a 'core plugin'.
category	string	Plugin category used on the Add new connection page. Can be one from the list: "tsdb", "logging", "cloud", "tracing", "profiling", "sql", "enterprise", "iot", "other", empty string or custom string
enterpriseFeatures	object	Grafana Enterprise specific features
executable	string	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.
hideFromList	boolean	[internal only] Excludes the plugin from listings in Grafana's UI. Only allowed for builtIn plugins.
includes	object[]	Resources to include in plugin.
logs	boolean	For data source plugins, if the plugin supports logs. It may be used to filter logs only features.
metrics	boolean	For data source plugins, if the plugin supports metric queries. Used to enable the plugin in the panel editor.
multiValueFilterOperators	boolean	For data source plugins, if the plugin supports multi value operators in filters.
pascalName	string	[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	boolean	Initialize plugin on startup. By default, the plugin initializes on first use, but when preload is set to true the plugin loads when the Grafana web app loads the first time. Only applicable to app plugins. When setting to true, implement frontend code splitting to minimise performance implications.
suggestions	boolean	For panel plugins. If set to true, the plugin's suggestions supplier will be invoked and any suggestions returned will be included in the Suggestions pane in the Panel Editor.
queryOptions	object	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[]	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.
skipDataQuery	boolean	For panel plugins. Hides the query editor.
state	string	Describes plugins life cycle status Possible values are: "alpha", "beta", "stable", "deprecated"
streaming	boolean	For data source plugins, if the plugin supports streaming. Used in Explore to start live streaming.
tracing	boolean	For data source plugins, if the plugin supports tracing. Used for example to link logs (e.g. Loki logs) with tracing plugins.
iam	object	Grafana reads the Identity and Access Management section and initializes a service account for the plugin, with a tailored set of Grafana RBAC permissions. Grafana will share the service account's bearer token with the plugin backend using the GF_PLUGIN_APP_CLIENT_SECRET environment variable. Requires Grafana version 10.3.0 or later. Currently, this is behind the externalServiceAccounts feature toggle. To try this feature out, follow this guide.
roles	object[]	List of RBAC roles defined by the plugin and their default assignments to basic roles (Viewer, Editor, Admin, Grafana Admin). Requires Grafana version 9.4.0 or later.
extensions	object	Plugin extensions are a way to extend either the UI of core Grafana or other plugins.
languages	string[]	The list of languages supported by the plugin. Each entry should be a locale identifier in the format language-COUNTRY (for example en-US, es-ES, de-DE).

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

Name	Type	Description	Required
author	object	Information about the plugin author.
build	object	Build information
description	string	Description of plugin. Used on the plugins page in Grafana and for search on grafana.com.
keywords	string[]	Array of plugin keywords. Used for search on grafana.com.	✅
links	object[]	An array of link objects to be displayed on this plugin's project page in the form {name: 'foo', url: 'http://example.com'}
logos	object	SVG images that are used as plugin icons.	✅
screenshots	object[]	An array of screenshot objects in the form {name: 'bar', path: 'img/screenshot.png'}
updated	string	Date when this plugin was built. Pattern: ^(\d{4}-\d{2}-\d{2}|\%TODAY\%)$	✅
version	string	SemVer version of this commit, e.g. 6.7.1. Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)|(\%VERSION\%)$	✅

info.author

Information about the plugin author.

Properties

Name	Type	Description	Required
name	string	Author's name.
email	string	Author's name. Format: "email"
url	string	Link to author's website. Format: "uri"

info.build

Build information

Properties

Name	Type	Description	Required
time	number	Time when the plugin was built, as a Unix timestamp.
repo	string
branch	string	Git branch the plugin was built from.
hash	string	Git hash of the commit the plugin was built from
number	number
pr	number	GitHub pull request the plugin was built from
build	number	Build job number used to build this plugin.

info.keywords[]

Array of plugin keywords. Used for search on grafana.com.

Items

Item Type: string
Minimum Items: 1

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'}

Items

Item Properties

Name	Type	Description	Required
name	string	Display name of the link. Special names with predefined behavior: • documentation - sets Documentation link on plugins detail page • repository - used to determine and link to repository of the plugin • license - sets License link on plugins detail page • raise issue - sets Raise an Issue link on plugins detail page • sponsorship - sets Sponsor this developer link on plugins detail page to direct users to how they can support your work
url	string	URL value to use for this specific link. Format: "uri"
target	string	A string that indicates where to display the linked resource Possible values are: "_blank", "_self", "_parent", "_top"

info.logos

SVG images that are used as plugin icons.

Properties

Name	Type	Description	Required
small	string	Link to the "small" version of the plugin logo, which must be an SVG image. "Large" and "small" logos can be the same image.	✅
large	string	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'}

Items

Item Properties

Name	Type	Description	Required
name	string
path	string

dependencies

Dependency information related to Grafana and other plugins.

Properties

| Name | Type | Description | Required | | ----------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | | grafanaVersion | string | (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 | string | Required Grafana version for this plugin. Validated using https://github.com/npm/node-semver.
Pattern: ^(<=\|>=\|<\|>\|=\|~\|\^)?([0-9]+)(\.[0-9x\*]+)?(\.[0-9x\*]+)?(-[0-9A-Za-z-.]+)?(\s(<=\|>=\|<\|=>)?([0-9]+)(\.[0-9x\*]+)?(\.[0-9x\*]+)?(-[0-9A-Za-z-.]+)?)?(\s\\ | \\ | \s(<=\|>=\|<\|>\|=\|~\|\^)?([0-9]+)(\.[0-9x\*]+)?(\.[0-9x\*]+)?(-[0-9A-Za-z-.]+)?(\s(<=\|>=\|<\|=>)?([0-9]+)(\.[0-9x\*]+)?(\.[0-9x\*]+)?(-[0-9A-Za-z-.]+)?)?)\*$
| ✅ | | plugins | object[] | An array of required plugins on which this plugin depends. Only non-core (that is, external plugins) have to be specified in this list.
| | | extensions | object | Plugin extensions that this plugin depends on.
| |

dependencies.plugins[]

An array of required plugins on which this plugin depends. Only non-core (that is, external plugins) have to be specified in this list.

Items

Plugin dependency. Used to display information about plugin dependencies in the Grafana UI.

Item Properties

Name	Type	Description	Required
id	string	Pattern: ^[0-9a-z]+\-([0-9a-z]+\-)?(app|panel|datasource)$	✅
type	string	Possible values are: "app", "datasource", "panel"	✅
name	string		✅

dependencies.extensions

Plugin extensions that this plugin depends on.

Properties

Name	Type	Description	Required
exposedComponents	string[]	An array of exposed component ids that this plugin depends on.

dependencies.extensions.exposedComponents[]

An array of exposed component ids that this plugin depends on.

Items

Item Type: string

enterpriseFeatures

Grafana Enterprise specific features

Properties

Name	Type	Description	Required
healthDiagnosticsErrors	boolean	Enable/Disable health diagnostics errors. Requires Grafana >=7.5.5. Default: false

includes[]

Resources to include in plugin.

Items

Item Properties

Name	Type	Description	Required
uid	string	Unique identifier of the included resource
type	string	Possible values are: "dashboard", "page", "panel", "datasource"	✅
name	string
component	string	(Legacy) The Angular component to use for a page.
role	string	The minimum role a user must have to see this page in the navigation menu. Possible values are: "Admin", "Editor", "Viewer"
action	string	The RBAC action a user must have to see this page in the navigation menu. Warning: unless the action targets the plugin, only the action is verified, not what it applies to.
path	string	Used for app plugins.
addToNav	boolean	Add the include to the navigation menu.
defaultNav	boolean	Page or dashboard when user clicks the icon in the side menu.
icon	string	Icon to use in the side menu. For information on available icon, refer to Icons Overview.

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

Name	Type	Description	Required
maxDataPoints	boolean	For data source plugins. If the max data points option should be shown in the query options section in the query editor.
minInterval	boolean	For data source plugins. If the min interval option should be shown in the query options section in the query editor.
cacheTimeout	boolean	For data source plugins. If the cache timeout 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.

Items

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.

Item Properties

Name	Type	Description	Required
path	string	For data source plugins. The route path that is replaced by the route URL field when proxying the call. Warning: Don't use an empty string ("").	✅
method	string	For data source plugins. Route method matches the HTTP verb like GET or POST. Multiple methods can be provided as a comma-separated list.
url	string	For data source plugins. Route URL is where the request is proxied to.
reqSignedIn	boolean
reqRole	string
reqAction	string	The RBAC action a user must have to use this route. Warning: unless the action targets the plugin (or a nested datasource plugin), only the action is verified, not what it applies to.
headers	array	For data source plugins. Route headers adds HTTP headers to the proxied request.
body	object	For data source plugins. Route headers set the body content and length to the proxied request.
tokenAuth	object	For data source plugins. Token authentication section used with an OAuth API.
jwtTokenAuth	object	For data source plugins. Token authentication section used with an JWT OAuth API.
urlParams	object[]	Add URL parameters to a proxy route

routes[].headers[]

For data source plugins. Route headers adds HTTP headers to the proxied request.

routes[].body

For data source plugins. Route headers set the body content and length to the proxied request.

routes[].tokenAuth

For data source plugins. Token authentication section used with an OAuth API.

Properties

Name	Type	Description	Required
url	string	URL to fetch the authentication token.
scopes	string[]	The list of scopes that your application should be granted access to.
params	object	Parameters for the token authentication request.

routes[].tokenAuth.scopes[]

The list of scopes that your application should be granted access to.

Items

Item Type: string

routes[].tokenAuth.params

Parameters for the token authentication request.

Properties

Name	Type	Description	Required
grant_type	string	OAuth grant type
client_id	string	OAuth client ID
client_secret	string	OAuth client secret. Usually populated by decrypting the secret from the SecureJson blob.
resource	string	OAuth resource

routes[].jwtTokenAuth

For data source plugins. Token authentication section used with an JWT OAuth API.

Properties

Name	Type	Description	Required
url	string	URL to fetch the JWT token. Format: "uri"
scopes	string[]	The list of scopes that your application should be granted access to.
params	object	Parameters for the JWT token authentication request.

routes[].jwtTokenAuth.scopes[]

The list of scopes that your application should be granted access to.

Items

Item Type: string

routes[].jwtTokenAuth.params

Parameters for the JWT token authentication request.

Properties

Name	Type	Description	Required
token_uri	string
client_email	string
private_key	string

routes[].urlParams[]

Add URL parameters to a proxy route

Items

Item Properties

Name	Type	Description	Required
name	string	Name of the URL parameter
content	string	Value of the URL parameter

iam

Grafana reads the Identity and Access Management section and initializes a service account for the plugin, with a tailored set of Grafana RBAC permissions. Grafana will share the service account's bearer token with the plugin backend using the GF_PLUGIN_APP_CLIENT_SECRET environment variable. Requires Grafana version 10.3.0 or later. Currently, this is behind the externalServiceAccounts feature toggle. To try this feature out, follow this guide.

Properties

Name	Type	Description	Required
permissions	object[]	Permissions are the permissions that the plugin needs its associated service account to have to query Grafana.

iam.permissions[]

Permissions are the permissions that the plugin needs its associated service account to have to query Grafana.

Items

Item Properties

Name	Type	Description	Required
action	string	Action, for example: teams:read.
scope	string	The scope that the plugin needs to access e.g: teams:*.

roles[]

List of RBAC roles defined by the plugin and their default assignments to basic roles (Viewer, Editor, Admin, Grafana Admin). Requires Grafana version 9.4.0 or later.

Items

Item Properties

Name	Type	Description	Required
role	object	A role groups your plugin's related RBAC permissions (ex: Projects Admin would group permissions to create, read, write and delete projects). The RBAC actions defined in your role must start with your plugin id (ex: grafana-test-app.projects:read).
grants	string[]	Default assignments of the role to Grafana basic roles (Viewer, Editor, Admin, Grafana Admin).

roles[].role

A role groups your plugin's related RBAC permissions (ex: Projects Admin would group permissions to create, read, write and delete projects). The RBAC actions defined in your role must start with your plugin id (ex: grafana-test-app.projects:read).

Properties

Name	Type	Description	Required
name	string	Display name of the role.
description	string	Describes the aim of the role.
permissions	object[]	RBAC permission on the plugin.

roles[].role.permissions[]

RBAC permission on the plugin.

Items

Item Properties

Name	Type	Description	Required
action	string
scope	string

roles[].grants[]

Default assignments of the role to Grafana basic roles (Viewer, Editor, Admin, Grafana Admin).

Items

Item Type: string

extensions

Plugin extensions are a way to extend either the UI of core Grafana or other plugins.

Properties

Name	Type	Description	Required
addedComponents	object[]	This list must contain all component extensions that your plugin registers to other extension points using .addComponent(). Components that are not listed here won't work.
addedLinks	object[]	This list must contain all link extensions that your plugin registers to other extension points using .addLink(). Links that are not listed here won't work.
addedFunctions	object[]	This list must contain all function extensions that your plugin registers to other extension points using .addedFunctions(). Functions that are not listed here won't work.
exposedComponents	object[]	This list must contain all components that your plugin exposes using .exposeComponent(). Components that are not listed here won't work.
extensionPoints	object[]	This list must contain all extension points that your plugin defines using usePluginLinks() or usePluginComponents(). Extension points that are not listed in here won't work.

extensions.addedComponents[]

This list must contain all component extensions that your plugin registers to other extension points using .addComponent(). Components that are not listed here won't work.

Items

Item Properties

Name	Type	Description	Required
targets	string[]	The extension point ids your plugin registers the extension to, e.g. ["grafana/user/profile/tab"]	✅
title	string	The title of your component extension. Minimal Length: 10	✅
description	string	Additional information about your component extension.

extensions.addedComponents[].targets[]

The extension point ids your plugin registers the extension to, e.g. ["grafana/user/profile/tab"]

Items

Item Type: string

extensions.addedLinks[]

This list must contain all link extensions that your plugin registers to other extension points using .addLink(). Links that are not listed here won't work.

Items

Item Properties

Name	Type	Description	Required
targets	string[]	The extension point ids your plugin registers the extension to, e.g. ["grafana/dashboard/panel/menu"]	✅
title	string	The title of your link extension. Minimal Length: 10	✅
description	string	Additional information about your link extension.

extensions.addedLinks[].targets[]

The extension point ids your plugin registers the extension to, e.g. ["grafana/dashboard/panel/menu"]

Items

Item Type: string

extensions.addedFunctions[]

This list must contain all function extensions that your plugin registers to other extension points using .addedFunctions(). Functions that are not listed here won't work.

Items

Item Properties

Name	Type	Description	Required
targets	string[]	The extension point ids your plugin registers the extension to, e.g. ["grafana/dashboard/panel/menu"]	✅
title	string	The title of your function extension. Minimal Length: 10	✅
description	string	Additional information about your function extension.

extensions.addedFunctions[].targets[]

The extension point ids your plugin registers the extension to, e.g. ["grafana/dashboard/panel/menu"]

Items

Item Type: string

extensions.exposedComponents[]

This list must contain all components that your plugin exposes using .exposeComponent(). Components that are not listed here won't work.

Items

Item Properties

Name	Type	Description	Required
id	string	A unique identifier for your exposed component. This is used to reference the component in other plugins. It must be in the following format: {PLUGIN_ID}/name-of-component/v1. It is recommended to add a version suffix to prevent future breaking changes. E.g.: myorg-extensions-app/exposed-component/v1. Pattern: ^[0-9a-z]+-([0-9a-z]+-)?(app|panel|datasource)\/[a-zA-Z0-9_-]+\/v[0-9_.-]+$	✅
title	string	The title of your exposed component.
description	string	Additional information about your exposed component.

extensions.extensionPoints[]

This list must contain all extension points that your plugin defines using usePluginLinks() or usePluginComponents(). Extension points that are not listed in here won't work.

Items

Item Properties

Name	Type	Description	Required
id	string	A unique identifier for your extension point. This is used to reference the extension point in other plugins. It must be in the following format: {PLUGIN_ID}/name-of-my-extension-point/v1. It is recommended to add a version suffix to prevent future breaking changes. E.g.: myorg-extensions-app/extension-point/v1. Pattern: ^[0-9a-z]+-([0-9a-z]+-)?(app|panel|datasource)\/[a-zA-Z0-9_-]+\/v[0-9_.-]+$	✅
title	string	The title of your extension point.
description	string	Additional information about your extension point.

languages[]

The list of languages supported by the plugin. Each entry should be a locale identifier in the format language-COUNTRY (for example en-US, es-ES, de-DE).

Items

Item Type: string