Docs: Updated Sentry docs

README.md

@@ -1,131 +1,71 @@
-# Sentry data source plugin with Grafana
+# Sentry data source plugin for Grafana
 
-The Sentry data source plugin allows you to query and visualize Sentry data within Grafana.
+The Sentry data source plugin lets you query and visualize [Sentry](https://sentry.io/) data within Grafana.
 
-## Requirements
+For user-facing documentation on configuration, query types, template variables, and troubleshooting, refer to the [Sentry data source documentation](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/).
 
-The Sentry data source has the following requirements:
+## Requirements
 
-- Grafana user with a server or organization administration role; refer to [Permissions](https://grafana.com/docs/grafana/latest/permissions/).
+- Grafana 10.4.0 or later
 - An active Sentry account
-- In Sentry, The Admin, Manager, or Owner role is required to get an internal integration token
-
-## Known limitations
-
-With the Grafana Sentry data source plugin, you are able to visualize issues, events or usage statistics within an organization. For more information, see [Issues](https://docs.sentry.io/product/issues/), [Events](https://docs.sentry.io/product/discover-queries/) and [Org Stats](https://docs.sentry.io/product/accounts/quotas/org-stats/).
 
-## Install the Sentry data source plugin
+## Install the plugin
 
 To install the Sentry data source plugin in your Grafana instance, refer to [Installation](https://grafana.com/grafana/plugins/grafana-sentry-datasource/?tab=installation).
 
-## Get an authentication token from Sentry
-
-To configure the Sentry data source plugin within Grafana, get an internal integration token from Sentry:
-
-1. Go to `https://sentry.io`.
-2. Navigate to **Organization Settings**
-3. Under **Developer Settings** select **Custom Integrations**.
-4. Click **Create New Integration** and then select **Internal Integration**
-5. Use a valid name such as _Grafana_.
-6. Go to **PERMISSIONS**, provide **Read** permissions to the required resources such as "Project", "Issue and Event", and "Organization".
-7. Click **Save Changes** then scroll down to **TOKENS** and click **+ New Token**
-8. Copy the token for the **Sentry Auth Token** field when configuring the data source within Grafana.
-
-> Note: In Sentry, The Admin, Manager, or Owner role is required to get an internal integration token
-
-## Configure the data source in Grafana
+## Development
 
-[Add a data source](https://grafana.com/docs/grafana/latest/datasources/add-a-data-source/) by filling in the following fields:
+### Frontend
 
-| Field name        | Description                                                                                                                                                            |
-| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Sentry URL        | Sentry URL to be used. If left blank, the default is `https://sentry.io`.                                                                                              |
-| Sentry Org        | Sentry Org slug. Typically this is in the URL, such as `https://sentry.io/organizations/{organization_slug}/`.                                                         |
-| Sentry Auth Token | Sentry Auth token. You can generate this from `https://sentry.io/settings/{organization_slug}/developer-settings/`) using the steps specified in the previous section. |
+1. Install dependencies:
 
-## Configure the data source via provisioning
+   ```bash
+   npm install
+   ```
 
-You can configure data sources to use Grafana’s provisioning system. For more information about how provisioning works, and all of the settings that you can set for data sources, see [Provisioning Grafana](https://grafana.com/docs/grafana/latest/administration/provisioning/#datasources).
+1. Build the plugin in development mode:
 
-Here is an example for provisioning this data source:
+   ```bash
+   npm run dev
+   ```
 
-```yml
-apiVersion: 1
-datasources:
-  - name: Sentry
-    type: grafana-sentry-datasource
-    access: proxy
-    orgId: 1
-    version: 1
-    editable: false
-    jsonData:
-      url: https://sentry.io
-      orgSlug: xxxxxxxxxxxxx
-    secureJsonData:
-      authToken: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-```
-
-## Query the data source
-
-The query editor allows you to query Sentry, get sentry issues, events and stats and display them in Grafana dashboard panels. You can choose one of the following query types, to get the relevant data.
-
-### Sentry issues
+1. Build the plugin in production mode:
 
-To get the list of Sentry issues, select **Sentry Issues** as the query type. Issues are filtered based on Grafana’s selected time range.
+   ```bash
+   npm run build
+   ```
 
-| Field        | Description                                                       |
-| ------------ | ----------------------------------------------------------------- |
-| Query Type   | Choose **Issues** as query type.                                  |
-| Projects     | (optional) Select one or more projects to filter the results.     |
-| Environments | (optional) Select one or more environments to filter the results. |
-| Query        | (optional) Enter your Sentry query to get the relevant results. If you wish to filter by fields on the `issues` query type, you should use the format `FIELD_NAME:FIELD_VALUE`. |
-| Sort By      | (optional) Select the order of results you want to display.       |
-| Limit        | (optional) Limit the number of results displayed.                 |
+### Backend
 
-### Sentry events
+1. Build the backend plugin binaries:
 
-To get the list of Sentry events, select **Sentry Events** as the query type. Events are filtered based on Grafana’s selected time range.
+   ```bash
+   mage -v build:linux
+   ```
 
-| Field        | Description                                                                                                                                  |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| Query Type   | Choose **Events** as query type.                                                                                                             |
-| Projects     | (optional) Select one or more projects to filter the results.                                                                                |
-| Environments | (optional) Select one or more environments to filter the results.                                                                            |
-| Query        | (optional) Enter your sentry query to get the relevant results. More on [query syntax](https://docs.sentry.io/product/sentry-basics/search/) |
-| Sort By      | (optional) Select the order of results you want to display.                                                                                  |
-| Limit        | (optional) Limit the number of results displayed. Max limit - 100.                                                                           |
+1. List all available Mage targets:
 
-### Sentry Org stats
+   ```bash
+   mage -l
+   ```
 
-To get the trend of Sentry Org stats, select **Stats** as the query type. Org stats are filtered based on Grafana’s selected time range.
+### Run Grafana with the plugin
 
-| Field           | Description                                                                                                      |
-| --------------- | ---------------------------------------------------------------------------------------------------------------- |
-| Query Type      | Choose **Stats** as query type.                                                                                  |
-| Field           | Select the field type you want to trend. Currently, you must choose either `sum(quantity)` or `sum(times_seen)`. |
-| Category Filter | Select the category you want to filter the results. You must to choose one the available option there.           |
-| Group By        | (optional) Select one or more fields you want to group the results.                                              |
-| Projects        | (optional) Select one or more projects to filter the results.                                                    |
-| Outcome Filter  | (optional) Select one of more outcomes to filter the results.                                                    |
-| Reason Filter   | (optional) Enter comma separated list of reasons you want to filter.                                             |
+Use Docker Compose to start a Grafana instance with the plugin installed:
 
-## Templates and variables
-
-In Grafana dashboards, you can use Sentry entities as dashboard variables. Sentry data source supports following variables:
-
-| Variable name | Description                                                                                                                             |
-| ------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| Teams         | Lists the Sentry teams. The team name is used as the display value, and team slug is used as as actual value.                           |
-| Projects      | Lists the Sentry projects. The project name is used as the display value, and each project ID is used as an actual value.               |
-| Environments  | Lists the Sentry environments for the selected projects. If you do not select a project, all of the applicable environments are listed. |
+```bash
+docker compose up
+```
 
-## Annotations
+### Run tests
 
-Annotations give you the ability to overlay Sentry issues on graphs. In the annotations editor, you have to choose **Issues** for creating annotations from Sentry issues.
+```bash
+npm run test
+```
 
-## Get the most out of the plugin
+## Learn more
 
-- Add [Annotations](https://grafana.com/docs/grafana/latest/dashboards/annotations/).
-- Configure and use [Templates and variables](https://grafana.com/docs/grafana/latest/variables/).
-- Add [Transformations](https://grafana.com/docs/grafana/latest/panels/transformations/).
-- Set up alerting; refer to [Alerts overview](https://grafana.com/docs/grafana/latest/alerting/).
+- [Sentry data source documentation](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/)
+- [Build a data source plugin tutorial](https://grafana.com/docs/grafana/latest/developers/plugins/)
+- [Grafana documentation](https://grafana.com/docs/)
+- [Grafana tutorials](https://grafana.com/tutorials/)

cspell.config.json

@@ -25,6 +25,7 @@
     "httpclient",
     "instancemgmt",
     "jackspeak",
+    "jsonencode",
     "errorsource",
     "mhdw",
     "nolint",

docs/Makefile

@@ -0,0 +1,8 @@
+.ONESHELL:
+.DELETE_ON_ERROR:
+export SHELL     := bash
+export SHELLOPTS := pipefail:errexit
+MAKEFLAGS += --warn-undefined-variables
+MAKEFLAGS += --no-builtin-rule
+
+include docs.mk

docs/docs.mk

@@ -0,0 +1,112 @@
+# The source of this file is https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk.
+# A changelog is included in the head of the `make-docs` script.
+include variables.mk
+-include variables.mk.local
+
+.ONESHELL:
+.DELETE_ON_ERROR:
+export SHELL     := bash
+export SHELLOPTS := pipefail:errexit
+MAKEFLAGS += --warn-undefined-variables
+MAKEFLAGS += --no-builtin-rule
+
+.DEFAULT_GOAL: help
+
+# Adapted from https://www.thapaliya.com/en/writings/well-documented-makefiles/
+.PHONY: help
+help: ## Display this help.
+help:
+	@awk 'BEGIN { \
+		FS = ": ##"; \
+		printf "Usage:\n  make <target>\n\nTargets:\n" \
+	} \
+	/^[a-zA-Z0-9_\.\-\/%]+: ##/ { printf "  %-15s %s\n", $$1, $$2 }' \
+	$(MAKEFILE_LIST)
+
+GIT_ROOT := $(shell git rev-parse --show-toplevel)
+
+PODMAN := $(shell if command -v podman >/dev/null 2>&1; then echo podman; else echo docker; fi)
+
+ifeq ($(PROJECTS),)
+$(error "PROJECTS variable must be defined in variables.mk")
+endif
+
+# First project is considered the primary one used for doc-validator.
+PRIMARY_PROJECT := $(subst /,-,$(firstword $(subst :, ,$(firstword $(PROJECTS)))))
+
+# Host port to publish container port to.
+ifeq ($(origin DOCS_HOST_PORT), undefined)
+export DOCS_HOST_PORT := 3002
+endif
+
+# Container image used to perform Hugo build.
+ifeq ($(origin DOCS_IMAGE), undefined)
+export DOCS_IMAGE := grafana/docs-base:latest
+endif
+
+# Container image used for doc-validator linting.
+ifeq ($(origin DOC_VALIDATOR_IMAGE), undefined)
+export DOC_VALIDATOR_IMAGE := grafana/doc-validator:latest
+endif
+
+# Container image used for vale linting.
+ifeq ($(origin VALE_IMAGE), undefined)
+export VALE_IMAGE := grafana/vale:latest
+endif
+
+# PATH-like list of directories within which to find projects.
+# If all projects are checked out into the same directory, ~/repos/ for example, then the default should work.
+ifeq ($(origin REPOS_PATH), undefined)
+export REPOS_PATH := $(realpath $(GIT_ROOT)/..)
+endif
+
+# How to treat Hugo relref errors.
+ifeq ($(origin HUGO_REFLINKSERRORLEVEL), undefined)
+export HUGO_REFLINKSERRORLEVEL := WARNING
+endif
+
+.PHONY: docs-rm
+docs-rm: ## Remove the docs container.
+	$(PODMAN) rm -f $(DOCS_CONTAINER)
+
+.PHONY: docs-pull
+docs-pull: ## Pull documentation base image.
+	$(PODMAN) pull -q $(DOCS_IMAGE)
+
+make-docs: ## Fetch the latest make-docs script.
+make-docs:
+	if [[ ! -f "$(CURDIR)/make-docs" ]]; then
+		echo 'WARN: No make-docs script found in the working directory. Run `make update` to download it.' >&2
+		exit 1
+	fi
+
+.PHONY: docs
+docs: ## Serve documentation locally, which includes pulling the latest `DOCS_IMAGE` (default: `grafana/docs-base:latest`) container image. See also `docs-no-pull`.
+docs: docs-pull make-docs
+	$(CURDIR)/make-docs $(PROJECTS)
+
+.PHONY: docs-no-pull
+docs-no-pull: ## Serve documentation locally without pulling the `DOCS_IMAGE` (default: `grafana/docs-base:latest`) container image.
+docs-no-pull: make-docs
+	$(CURDIR)/make-docs $(PROJECTS)
+
+.PHONY: docs-debug
+docs-debug: ## Run Hugo web server with debugging enabled. TODO: support all SERVER_FLAGS defined in website Makefile.
+docs-debug: make-docs
+	WEBSITE_EXEC='hugo server --bind 0.0.0.0 --port 3002 --debug' $(CURDIR)/make-docs $(PROJECTS)
+
+.PHONY: doc-validator
+doc-validator: ## Run doc-validator on the entire docs folder.
+doc-validator: make-docs
+	DOCS_IMAGE=$(DOC_VALIDATOR_IMAGE) $(CURDIR)/make-docs $(PROJECTS)
+
+.PHONY: vale
+vale: ## Run vale on the entire docs folder.
+vale: make-docs
+	DOCS_IMAGE=$(VALE_IMAGE) $(CURDIR)/make-docs $(PROJECTS)
+
+.PHONY: update
+update: ## Fetch the latest version of this Makefile and the `make-docs` script from Writers' Toolkit.
+	curl -s -LO https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk
+	curl -s -LO https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/make-docs
+	chmod +x make-docs