@grafana/create-plugin 7.14.0 → 7.15.0

package/templates/docs/datasource/docs/configure.md

@@ -0,0 +1,114 @@
+---
+title: Configure
+description: "Add the {{{yamlEscape pluginName}}} data source in Grafana and connect it to your service."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - data source
+  - configuration
+  - provisioning
+sidebar_position: 2
+---
+
+This document explains how to add and configure the {{{pluginName}}} data source in Grafana. After you configure the data source, refer to the [{{{pluginName}}} query editor](./query-editor.md) to start querying your data.
+
+## Before you begin
+
+Before you configure the data source, ensure you have:
+
+- **Grafana permissions:** The `Organization administrator` role. Only organization administrators can add data sources.
+
+<!-- section-brief
+Fill this in: Keep the list above. Add a bullet in the same **Label:** form for each other thing the reader needs: the instance of the service {{{pluginName}}} connects to and how Grafana reaches it, such as its address, default port and network access, and the credentials and permissions needed on it. If the service can sit behind a firewall, add a `> [!NOTE]` callout telling Grafana Cloud users to allowlist the Grafana Cloud outbound IP addresses, and link to https://grafana.com/docs/grafana-cloud/account-management/allow-traffic/.
+-->
+
+## Set up access in {{{pluginName}}}
+
+<!-- section-brief
+Fill this in: Steps the reader follows in the service {{{pluginName}}} connects to before adding the data source, such as creating a user, an API token or a cloud role. Take what's needed from the credential fields in the config editor, and work out the least access that works from what the backend calls, such as API endpoints, SQL statements or settings it changes. Say what fails if a permission is missing. Change the heading if necessary to name the task, such as "Create a read-only user". Leave the Grafana fields to Configure settings below.
+
+If the reader only needs credentials they already have, remove this section and keep them as a bullet in Before you begin.
+-->
+
+## Add the data source
+
+To add the {{{pluginName}}} data source:
+
+1. Click **Connections** in the left-side menu.
+1. Click **Add new connection**.
+1. Enter `{{{pluginName}}}` in the search bar.
+1. Select **{{{pluginName}}}**.
+1. Click **Add new data source**.
+
+## Configure settings
+
+<!-- section-brief
+Fill this in: An H3 for each section of the config editor, named and ordered as the editor shows them, such as Connection, Authentication, TLS or Additional settings. Under each H3, a table with this shape:
+
+| Setting | Description | Required |
+| ------- | ----------- | -------- |
+
+Start the first table with **Name** and **Default**. Use the field labels from the config editor, in bold. Find the settings in the config editor component and the options type, including `jsonData` and `secureJsonData`.
+
+In a description, say when a field only appears for some choice, such as a protocol, and when it affects another setting, such as a port that must change when TLS is turned on. If source shows the editor lacks an option readers expect, such as TLS settings, say so and what to do instead. For each authentication method, say when to use it. Use a `> [!NOTE]` callout for a method or setting that's only available in Grafana Cloud or Grafana Enterprise.
+
+When a feature needs more than a table row, such as forwarding OAuth identity or HTTP headers, or cloud provider auth like AWS SigV4, give it its own H2 after this section with its setup, requirements and behavior.
+-->
+{{#if hasBackend}}
+
+## Private data source connect
+
+<!-- section-brief
+Fill this in: Explain how to reach a service on a private network from Grafana Cloud with private data source connect (PDC), and link to https://grafana.com/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/ for setup. Start with a `> [!NOTE]` callout saying PDC is only available in Grafana Cloud. Name the toggle the config editor shows, and say it only appears when the secure SOCKS proxy is enabled for the Grafana instance. For self-managed Grafana, show the setting that enables it:
+
+```ini
+[secure_socks_datasource_proxy]
+enabled = true
+```
+
+Keep this section only if the backend supports the secure SOCKS proxy (look for `EnableSecureSocksProxy` or `secureSocksProxyEnabled` in source). Otherwise, remove it entirely.
+-->
+{{/if}}
+
+## Verify the connection
+
+Click **Save & test** to verify the connection.
+
+<!-- section-brief
+Fill this in: Give the message the reader sees when the connection works and the most common failure messages, each with what it means. Take the messages from the health check in source (`CheckHealth` in the backend, or `testDatasource` in the frontend). Link failures to [troubleshooting](./troubleshooting.md) with a relative link.
+-->
+
+## Provision the data source
+
+You can provision the {{{pluginName}}} data source as code, with a Grafana provisioning file or with the Grafana Terraform provider.
+
+<!-- section-brief
+Fill this in: List the placeholders the examples below use, such as `<HOST>` or `<API_TOKEN>`, each with what to replace it with.
+-->
+
+### Provision with a configuration file
+
+You can define the data source in a YAML file as part of the Grafana provisioning system. For more information, refer to [Provision Grafana](https://grafana.com/docs/grafana/latest/administration/provisioning/#data-sources).
+
+<!-- section-brief
+Fill this in: A YAML example with this shape, using the real `jsonData` and `secureJsonData` keys from the options type and placeholders for every value the reader must supply:
+
+```yaml
+apiVersion: 1
+
+datasources:
+  - name: {{{pluginName}}}
+    type: {{pluginId}}
+    jsonData: {}
+    secureJsonData: {}
+```
+
+Follow it with a table of the keys it uses and what each one sets. Include `url`, `user` or other top-level fields only if the plugin reads them.
+-->
+
+### Provision with Terraform
+
+You can provision the data source with the [Grafana Terraform provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/data_source) using the `grafana_data_source` resource.
+
+<!-- section-brief
+Fill this in: A Terraform example with `type = "{{pluginId}}"` that sets the same values as the YAML example. Pass `jsonData` through `json_data_encoded` and `secureJsonData` through `secure_json_data_encoded`, both wrapped in `jsonencode()`.
+-->

package/templates/docs/datasource/docs/dashboards.md

@@ -0,0 +1,28 @@
+---
+title: Dashboards
+description: "Import and use the dashboards that ship with {{{yamlEscape pluginName}}}."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - data source
+  - dashboards
+sidebar_position: 7
+---
+
+{{{pluginName}}} ships with ready-made dashboards that you can import and use as they are, or as a starting point for your own. For general information about dashboards, refer to [Dashboards](https://grafana.com/docs/grafana/latest/dashboards/).
+
+## Import a dashboard
+
+To import a dashboard that ships with {{{pluginName}}}:
+
+1. Click **Connections** > **Data sources** in the left-side menu.
+1. Select your {{{pluginName}}} data source.
+1. Click the **Dashboards** tab.
+1. Click **Import** next to the dashboard.
+
+Imported dashboards don't update when you upgrade the plugin. When a plugin upgrade ships a newer version of a dashboard, click **Update** next to it. This overwrites any changes you made to it.
+
+## Included dashboards
+
+<!-- section-brief
+Fill this in: One H3 per dashboard in the `includes` list of `src/plugin.json` whose `type` is `dashboard`, using its `name`. For each one, describe what it shows and what data or settings it needs to work, based on the panels and queries in its JSON file.
+-->

package/templates/docs/datasource/docs/index.md

@@ -0,0 +1,40 @@
+---
+title: Introduction
+description: "Where to start and what to read next in the {{{yamlEscape pluginName}}} docs."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - data source
+sidebar_position: 1
+---
+
+<!-- section-brief
+Fill this in: Write a short orientation for someone who already has {{{pluginName}}} installed and landed here from the Documentation tab. One or two sentences on what this section covers and how it's organized. Do not restate what the data source connects to, its feature list or its requirements - that's the README's job on the Overview tab, and this reader has already seen it there. Do not list every page in this folder either - the sidebar already does that; use prose to say what to read first and why.
+-->
+
+## Recommended path
+
+<!-- section-brief
+Fill this in: Give a short, ordered reading path for someone new to {{{pluginName}}} - two or three sentences, not a repeat of the sidebar. Most readers need to connect the data source before anything else, e.g. "Start with **Configure** to connect {{{pluginName}}} to your service, then read **Query editor** to build your first query."
+-->
+
+## Common tasks
+
+<!-- section-brief
+Fill this in: List the jobs someone lands here to do, phrased as tasks rather than page titles, each linked to the page that answers it. For a typical data source plugin this might look like:
+
+- [Connect {{{pluginName}}} and choose an authentication method](./configure.md)
+- [Build and run a query](./query-editor.md)
+- [Make dashboards dynamic with template variables](./template-variables.md)
+{{#if hasAnnotations}}
+- [Mark events on your graphs with annotations](./annotations.md)
+{{/if}}
+{{#if hasAlerting}}
+- [Create alert rules from your queries](./alerting.md)
+{{/if}}
+{{#if hasDashboards}}
+- [Import the dashboards that ship with the plugin](./dashboards.md)
+{{/if}}
+- [Fix connection, authentication and query errors](./troubleshooting.md)
+
+Adapt this to {{{pluginName}}}'s actual entry points - add, remove or reword tasks so each one matches a real job a user comes here to do. This is a curated set of jobs, not a mechanical list of every file in this folder.
+-->

package/templates/docs/datasource/docs/query-editor.md

@@ -0,0 +1,72 @@
+---
+title: Query editor
+description: "Build and run queries with the {{{yamlEscape pluginName}}} query editor."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - data source
+  - query editor
+  - queries
+sidebar_position: 3
+---
+
+This document explains how to use the {{{pluginName}}} query editor to build queries and visualize {{{pluginName}}} data in Grafana dashboards.
+
+## Before you begin
+
+- [Configure the {{{pluginName}}} data source](./configure.md).
+
+<!-- section-brief
+Fill this in: Keep the bullet above. Add a bullet for each other thing a reader needs before writing a query, such as read access to the data they query, a feature to enable on the target service or a query language to know. For access, link to the matching section of [configure](./configure.md). If there is nothing else, delete only this brief.
+-->
+
+## Editor modes
+
+<!-- section-brief
+Fill this in: An H3 for each mode the editor offers, such as a builder and a code editor, named as the editor names them. Say what each is for and when to use it, and how to switch between them. Add a screenshot of each mode when you can capture one, saved under `img/`. Never link an image that doesn't exist.
+
+If the editor has one mode, remove this section entirely.
+-->
+
+## Query types
+
+<!-- section-brief
+Fill this in: Document the fields the editor shows, in tables with this shape:
+
+| Field | Description |
+| ----- | ----------- |
+
+Use the field labels from the editor, in bold, and say which fields are required and their defaults and limits. If the editor has several query types or APIs, put the fields every type shares in a table first, then an H3 for each type that says when to use it and lists its own fields. Mention any shortcut that runs the query, such as **Shift+Enter**. Take the fields from the query editor component and the query type in source.
+
+If the editor has one query type, skip the H3s, give one table of its fields and rename the heading to "Query fields".
+-->
+
+## Format the query results
+
+<!-- section-brief
+Fill this in: Describe each result format the editor can return, such as time series, table, logs or traces, and say when to use each. For each format, say what the query must return for Grafana to show it, such as a `time` column plus at least one numeric column, sorted by time, and the column order that produces several series. Take the formats from the query editor and the code that builds data frames in source.
+
+If the editor has one result format, describe what the query must return in a paragraph without listing formats.
+-->
+{{#if hasBackend}}
+
+## Macros
+
+<!-- section-brief
+Fill this in: A table of every macro the plugin expands in queries, such as `$__timeFilter`, with this shape:
+
+| Macro | Description | Example |
+| ----- | ----------- | ------- |
+
+Macros are expanded in the backend, in the `QueryData` handler that implements `backend.QueryDataHandler`, or in code it calls. Take the macros from there, and show the syntax exactly as a reader writes it. Start with one example query that uses a macro. If a standard Grafana macro such as `$__timeGroup` doesn't work with this service, add a `> [!WARNING]` callout saying what to use instead.
+
+If the plugin has no macros, remove this section entirely.
+-->
+{{/if}}
+
+## Query examples
+
+<!-- section-brief
+Fill this in: Give realistic examples of the common query types from Query types, with an H3 for each type. If there is only one type, give examples for the jobs people use {{{pluginName}}} for instead. For each example, say what it does and show the query the way a reader enters it in the editor, using the field names and syntax the editor really accepts.
+
+Follow each example with the query as dashboard JSON stores it, a `targets` entry in a `json` code block. Take the shape from the query model in source and from any dashboard JSON under `provisioning/dashboards/`, and replace real UIDs and credentials with placeholders.
+-->

package/templates/docs/datasource/docs/template-variables.md

@@ -0,0 +1,69 @@
+---
+title: Template variables
+description: "Use template variables with {{{yamlEscape pluginName}}} to build dynamic, reusable dashboards."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - data source
+  - template variables
+sidebar_position: 4
+---
+
+Use template variables to create dynamic, reusable dashboards that let you change query parameters without editing individual panels. For general information about template variables, refer to [Templates and variables](https://grafana.com/docs/grafana/latest/dashboards/variables/).
+
+<!-- section-brief
+Fill this in: Delete only this brief.
+
+If the plugin supports no variable types and interpolates no variables in its queries, delete this page and its link in `index.md`.
+-->
+
+## Before you begin
+
+- [Configure the {{{pluginName}}} data source](./configure.md).
+- Understand [Grafana template variables](https://grafana.com/docs/grafana/latest/dashboards/variables/).
+- Know how to write queries in the [{{{pluginName}}} query editor](./query-editor.md).
+
+## Supported variable types
+
+The {{{pluginName}}} data source supports the following variable types:
+
+<!-- section-brief
+Fill this in: A table with a Yes or No for each variable type, in this order:
+
+| Variable type  | Supported |
+| -------------- | --------- |
+| Query          |           |
+| Custom         | Yes       |
+| Data source    | Yes       |
+| Ad hoc filters |           |
+
+Custom and Data source variables are handled by Grafana itself and work with every data source, so keep them as Yes. Query is Yes if the data source class sets `variables` or implements `metricFindQuery`. Ad hoc filters is Yes if it implements both `getTagKeys` and `getTagValues`.
+-->
+
+## Use variables in queries
+
+<!-- section-brief
+Fill this in: Explain how to use a variable in the {{{pluginName}}} query editor, field by field, since fields accept variables in different ways. For each field that accepts one, say how the reader adds it: picked from a drop-down that lists dashboard variables, perhaps with a prefix such as `var:`, or typed into an input or code editor as `$variable` or `${variable}`. Note fields that don't accept variables, and any difference between editor modes, such as a builder and a code editor. Give an example, and say how a single value is substituted, such as whether a string needs quotes. Say which Grafana global variables, such as `$__interval` or `$__from`, work and in which fields.
+
+Find which fields list variables in the query editor component, usually from `getTemplateSrv().getVariables()`, and which fields are interpolated in `applyTemplateVariables` or `interpolateVariablesInQueries`, or in the backend.
+
+If the plugin doesn't interpolate variables in its queries, remove this section entirely.
+-->
+
+## Query variables
+
+A query variable fills its drop-down by running a query against {{{pluginName}}}, so its options stay current with your data. Use one to let viewers pick a value, such as a host, a table or a project, and update every panel that uses it.
+
+To create a query variable:
+
+1. Navigate to **Dashboard settings** > **Variables**.
+1. Click **Add variable**.
+1. Select **Query** as the variable type.
+1. Select the **{{{pluginName}}}** data source.
+
+<!-- section-brief
+Fill this in: Continue the list above with the steps for the variable query editor, using its field labels in bold. Say whether it's the same editor as the query editor or a separate one, from the variable support in source.
+
+If the variable query editor has several query types, such as projects or environments, add an H3 for each that says what it lists, its fields and which part of each result becomes the display text and which the value. Otherwise, explain how the query result becomes the options: which column becomes the display text and which the value, and whether columns are matched by name, such as `text` and `value`, or by position, with one example for a single column and one for separate text and value. Take this from `metricFindQuery` or the variable support class in source.
+
+If the plugin doesn't support query variables, remove this whole section, including its heading and the text above.
+-->

package/templates/docs/datasource/docs/troubleshooting.md

@@ -0,0 +1,73 @@
+---
+title: Troubleshooting
+description: "Troubleshoot common {{{yamlEscape pluginName}}} connection, authentication and query errors."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - data source
+  - troubleshooting
+sidebar_position: 8
+---
+
+This page explains how to fix common issues when you configure or use the {{{pluginName}}} data source. For setup instructions, refer to [Configure the {{{pluginName}}} data source](./configure.md).
+
+<!-- section-brief
+Fill this in: Never guess failures. Each symptom must come from an error message in source, a known issue in the README or other docs or a reported issue.
+
+Replace this brief with one H2 per category that has real failures, in this order:
+
+- `## Connection errors`: Grafana can't reach the service, such as timeouts or TLS errors.
+- `## Authentication errors`: wrong credentials, expired tokens or missing permissions.
+- `## Query errors`: queries that fail or return no data.
+- `## Template variable errors`: variables that return no or wrong values, or load slowly.
+{{#if hasAnnotations}}
+- `## Annotation errors`: annotations that don't appear, linking to [annotations](./annotations.md).
+{{/if}}
+{{#if hasAlerting}}
+- `## Alerting errors`: alert rules that fail or don't fire, such as a query that works on a dashboard but not in an alert rule, which skips the frontend data source class. Link to [alerting](./alerting.md).
+{{/if}}
+{{#if hasBackend}}
+- `## Private data source connect errors`: connections through PDC that fail, if the backend supports the secure SOCKS proxy.
+{{/if}}
+- `## Performance issues`: slow dashboards, timeouts or rate limits, and the settings that help.
+
+Add an H2 if the backend classifies its errors, or for another feature with real failures, such as ad hoc filters.
+
+Open each H2 with one sentence on when its errors occur. Add an H3 per symptom, named after the error message in quotes, such as `### "Password authentication failed"`, then **Symptoms:** and a **Possible causes and solutions:** table, or a numbered **Solutions:** list for a single cause.
+-->
+
+## Get more detail about an error
+
+To see the raw request and response for a panel, open the panel editor and click **Query inspector**.
+{{#if hasBackend}}
+
+In self-managed Grafana, you can also find more detail in the Grafana server logs:
+
+1. Set the log level to `debug` in the Grafana configuration file:
+
+   ```ini
+   [log]
+   level = debug
+   ```
+
+1. Restart Grafana and reproduce the error.
+1. Look for log lines with `logger=plugin.{{{pluginId}}}`.
+1. Set the log level back to `info` when you're done, to keep the logs small.
+{{/if}}
+
+## Get additional help
+
+If this page doesn't solve your problem:
+
+- Search the [Grafana community forums](https://community.grafana.com/).
+- If your Grafana Cloud or Grafana Enterprise plan includes support, contact Grafana Support.
+
+<!-- section-brief
+Fill this in: Add links to the plugin's issue tracker and the service's docs to the list above.
+-->
+
+When you report an issue, include:
+
+- The Grafana and plugin versions.
+- The error message, with sensitive information removed.
+- The steps to reproduce the issue.
+- The relevant data source settings, with credentials removed.

package/templates/docs/panel/docs/AGENTS.md

@@ -43,6 +43,12 @@ a `sidebar_position` that puts it where it belongs and link it from `index.md`.
 | RBAC role declarations in `src/plugin.json`                                        | `permissions.md`   | What each role grants, default assignments.                  |
 | Substantial accessibility considerations (keyboard shortcuts, screen reader notes) | `accessibility.md` | Keyboard interaction, ARIA, contrast, motion preferences.    |
 
+## What not to write
+
+Never write installation instructions, such as installing the plugin with `grafana-cli`, from a zip file or
+in Docker. The Installation tab on the plugin page covers them, and these docs start from a plugin that is
+already installed. When the README has an installation section, leave it out of the pages.
+
 ## Section briefs
 
 Each section of a scaffolded page has a brief telling you what belongs there. A brief is an HTML comment