DevelopersBuild a pluginplugin.json

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

PropertyTypeRequiredDescription
dependenciesobjectYesDependencies needed by the plugin.
idstringYesUnique name of the plugin. If the plugin is published on grafana.com, then the plugin id has to follow the naming conventions.
infoobjectYesMetadata for the plugin. Some fields are used on the plugins page in Grafana and others on grafana.com if the plugin is published.
namestringYesHuman-readable name of the plugin that is shown to the user in the UI.
typestringYesPlugin type. Possible values are: app, datasource, panel.
$schemastringNoSchema definition for the plugin.json file.
alertingbooleanNoFor data source plugins, if the plugin supports alerting.
annotationsbooleanNoFor data source plugins, if the plugin supports annotation queries.
autoEnabledbooleanNoSet to true for app plugins that should be enabled by default in all orgs
backendbooleanNoIf the plugin has a backend component.
categorystringNoPlugin category used on the Add data source page. Possible values are: tsdb, logging, cloud, tracing, sql, enterprise, other.
enterpriseFeaturesobjectNoGrafana Enerprise specific features.
executablestringNoThe 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.
hiddenQueriesbooleanNoFor data source plugins, include hidden queries in the data request.
includesobject[]NoResources to include in plugin.
logsbooleanNoFor data source plugins, if the plugin supports logs.
metricsbooleanNoFor data source plugins, if the plugin supports metric queries. Used in Explore.
preloadbooleanNoInitialize plugin on startup. By default, the plugin initializes on first use.
queryOptionsobjectNoFor data source plugins. There is a query options section in the plugin’s query editor and these options can be turned on if needed.
routesobject[]NoFor 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.
skipDataQuerybooleanNoFor panel plugins. Hides the query editor.
statestringNoMarks a plugin as a pre-release. Possible values are: alpha, beta.
streamingbooleanNoFor data source plugins, if the plugin supports streaming.
tablesbooleanNoThis is an undocumented feature.
tracingbooleanNoFor data source plugins, if the plugin supports tracing.

dependencies

Dependencies needed by the plugin.

Properties

PropertyTypeRequiredDescription
grafanaDependencystringYesRequired Grafana version for this plugin. Validated using https://github.com/npm/node-semver.
grafanaVersionstringNo(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.
pluginsobject[]NoAn array of required plugins on which this plugin depends.

plugins

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

Properties

PropertyTypeRequiredDescription
idstringYes
namestringYes
typestringYesPossible values are: app, datasource, panel.
versionstringYes

enterpriseFeatures

Grafana Enerprise specific features.

Properties

PropertyTypeRequiredDescription
healthDiagnosticsErrorsbooleanNoEnable/Disable health diagnostics errors. Requires Grafana >=7.5.5.

includes

Properties

PropertyTypeRequiredDescription
addToNavbooleanNoAdd the include to the side menu.
componentstringNo(Legacy) The Angular component to use for a page.
defaultNavbooleanNoPage or dashboard when user clicks the icon in the side menu.
iconstringNoIcon to use in the side menu. For information on available icon, refer to Icons Overview.
namestringNo
pathstringNoUsed for app plugins.
rolestringNoPossible values are: Admin, Editor, Viewer.
typestringNoPossible values are: dashboard, page, panel, datasource.
uidstringNoUnique identifier of the included resource

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

PropertyTypeRequiredDescription
keywordsstring[]YesArray of plugin keywords. Used for search on grafana.com.
logosobjectYesSVG images that are used as plugin icons.
updatedstringYesDate when this plugin was built.
versionstringYesProject version of this commit, e.g. 6.7.x.
authorobjectNoInformation about the plugin author.
buildobjectNoBuild information
descriptionstringNoDescription of plugin. Used on the plugins page in Grafana and for search on grafana.com.
linksobject[]NoAn array of link objects to be displayed on this plugin’s project page in the form {name: 'foo', url: 'http://example.com'}
screenshotsobject[]NoAn array of screenshot objects in the form {name: 'bar', path: 'img/screenshot.png'}

author

Information about the plugin author.

Properties

PropertyTypeRequiredDescription
emailstringNoAuthor’s name.
namestringNoAuthor’s name.
urlstringNoLink to author’s website.

build

Build information

Properties

PropertyTypeRequiredDescription
branchstringNoGit branch the plugin was built from.
hashstringNoGit hash of the commit the plugin was built from
numbernumberNo
prnumberNoGitHub pull request the plugin was built from
repostringNo
timenumberNoTime when the plugin was built, as a Unix timestamp.

Properties

PropertyTypeRequiredDescription
namestringNo
urlstringNo

logos

SVG images that are used as plugin icons.

Properties

PropertyTypeRequiredDescription
largestringYesLink to the “large” version of the plugin logo, which must be an SVG image. “Large” and “small” logos can be the same image.
smallstringYesLink 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

PropertyTypeRequiredDescription
namestringNo
pathstringNo

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

PropertyTypeRequiredDescription
cacheTimeoutbooleanNoFor data source plugins. If the cache timeout option should be shown in the query options section in the query editor.
maxDataPointsbooleanNoFor data source plugins. If the max data points option should be shown in the query options section in the query editor.
minIntervalbooleanNoFor 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.

Properties

PropertyTypeRequiredDescription
bodyobjectNoFor data source plugins. Route headers set the body content and length to the proxied request.
headersarrayNoFor data source plugins. Route headers adds HTTP headers to the proxied request.
jwtTokenAuthobjectNoFor data source plugins. Token authentication section used with an JWT OAuth API.
methodstringNoFor data source plugins. Route method matches the HTTP verb like GET or POST. Multiple methods can be provided as a comma-separated list.
pathstringNoFor data source plugins. The route path that is replaced by the route URL field when proxying the call.
reqRolestringNo
reqSignedInbooleanNo
tokenAuthobjectNoFor data source plugins. Token authentication section used with an OAuth API.
urlstringNoFor data source plugins. Route URL is where the request is proxied to.

body

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

PropertyTypeRequiredDescription

jwtTokenAuth

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

Properties

PropertyTypeRequiredDescription
paramsobjectNoParameters for the JWT token authentication request.
scopesstring[]NoThe list of scopes that your application should be granted access to.
urlstringNoURL to fetch the JWT token.

params

Parameters for the JWT token authentication request.

Properties
PropertyTypeRequiredDescription
client_emailstringNo
private_keystringNo
token_uristringNo

tokenAuth

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

Properties

PropertyTypeRequiredDescription
paramsobjectNoParameters for the token authentication request.
scopesstring[]NoThe list of scopes that your application should be granted access to.
urlstringNoURL to fetch the authentication token.

params

Parameters for the token authentication request.

Properties
PropertyTypeRequiredDescription
client_idstringNoOAuth client ID
client_secretstringNoOAuth client secret. Usually populated by decrypting the secret from the SecureJson blob.
grant_typestringNoOAuth grant type
resourcestringNoOAuth resource