diff --git a/README.md b/README.md index c3ddb097..5dc4c188 100644 --- a/README.md +++ b/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/) diff --git a/cspell.config.json b/cspell.config.json index a3b0b869..3d3042c3 100644 --- a/cspell.config.json +++ b/cspell.config.json @@ -25,6 +25,7 @@ "httpclient", "instancemgmt", "jackspeak", + "jsonencode", "errorsource", "mhdw", "nolint", diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..2ea93f45 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/docs.mk b/docs/docs.mk new file mode 100644 index 00000000..ad04633e --- /dev/null +++ b/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 \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 \ No newline at end of file diff --git a/docs/make-docs b/docs/make-docs new file mode 100755 index 00000000..77cb039b --- /dev/null +++ b/docs/make-docs @@ -0,0 +1,799 @@ +#!/bin/sh +# The source of this file is https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/make-docs. +# # `make-docs` procedure changelog +# +# Updates should conform to the guidelines in https://keepachangelog.com/en/1.1.0/. +# [Semantic versioning](https://semver.org/) is used to help the reader identify the significance of changes. +# Changes are relevant to this script and the support docs.mk GNU Make interface. +# + +# ## 5.1.2 (2023-11-08) +# +# ### Added +# +# - Hide manual_mount warning messages from non-debug output. +# Set the DEBUG environment variable to see all hidden messages. +# +# ## 5.1.1 (2023-10-30) +# +# ### Added +# +# - Support for Datadog and Oracle data source plugins repositories. +# +# ## 5.1.0 (2023-10-20) +# +# ### Added +# +# - Support for the plugins monorepo. +# +# ## 5.0.0 (2023-10-18) +# +# ### Added +# +# - Improved support for website repository. +# +# Mount more content and provide some feedback to users that the build can take time. +# +# - Ability to enter the `grafana/docs-base` container with a shell using the `ENTER` environment variable. +# +# ### Fixed +# +# - Correct key combination for interrupting the process. +# +# Keyboards use capital letters so this more accurately reflects the exact key combination users are expected to press. +# +# ### Removed +# +# - Imperfect implementation of container name. +# +# Facilitates running `make vale` and `make docs` at once. +# Container names are convenient for recognition in `docker ps` but the current implementation has more downsides than upsides. +# +# - Forced platform specification now that multiple architecture images exist. +# +# Significantly speeds up build times on larger repositories. +# +# ## 4.2.2 (2023-10-05) + +# - Added support for Jira data source and MongoDB data source plugins repositories. +# +# ## 4.2.1 (2023-09-13) + +# ## Fixed +# +# - Improved consistency of the webserver request loop by polling the Hugo port rather than the proxy port. +# +# ## 4.2.0 (2023-09-01) +# +# ### Added +# +# - Retry the initial webserver request up to ten times to allow for the process to start. +# If it is still failing after ten seconds, an error message is logged. +# +# ## 4.1.1 (2023-07-20) +# +# ### Fixed +# +# - Replaced use of `realpath` with POSIX compatible alternative to determine default value for REPOS_PATH. +# +# ## 4.1.0 (2023-06-16) +# +# ### Added +# +# - Mounts of `layouts` and `config` directories for the `website` project. +# Ensures that local changes to mounts or shortcodes are reflected in the development server. +# +# ### Fixed +# +# - Version inference for versioned docs pages. +# Pages in versioned projects now have the `versioned: true` front matter set to ensure that "version" in $.Page.Scratch is set on builds. +# +# ## 4.0.0 (2023-06-06) +# +# ### Removed +# +# - `doc-validator/%` target. +# The behavior of the target was not as described. +# Instead, to limit `doc-validator` to only specific files, refer to https://grafana.com/docs/writers-toolkit/writing-guide/tooling-and-workflows/validate-technical-documentation/#run-on-specific-files. +# +# ## 3.0.0 (2023-05-18) +# +# ### Fixed +# +# - Compatibility with the updated Make targets in the `website` repository. +# `docs` now runs this script itself, `server-docs` builds the site with the `docs` Hugo environment. +# +# ## 2.0.0 (2023-05-18) +# +# ### Added +# +# - Support for the grafana-cloud/frontend-observability/faro-web-sdk project. +# - Use of `doc-validator` v2.0.x which includes breaking changes to command line options. +# +# ### Fixed +# +# - Source grafana-cloud project from website repository. +# +# ### Added +# +# - Support for running the Vale linter with `make vale`. +# +# ## 1.2.1 (2023-05-05) +# +# ### Fixed +# +# - Use `latest` tag of `grafana/vale` image by default instead of hardcoded older version. +# - Fix mounting multiple projects broken by the changes in 1.0.1 +# +# ## 1.2.0 (2023-05-05) +# +# ### Added +# +# - Support for running the Vale linter with `make vale`. +# +# ### Fixed +# +# ## 1.1.0 (2023-05-05) +# +# ### Added +# +# - Rewrite error output so it can be followed by text editors. +# +# ### Fixed +# +# - Fix `docs-debug` container process port. +# +# ## 1.0.1 (2023-05-04) +# +# ### Fixed +# +# - Ensure complete section hierarchy so that all projects have a visible menu. +# +# ## 1.0.0 (2023-05-04) +# +# ### Added +# +# - Build multiple projects simultaneously if all projects are checked out locally. +# - Run [`doc-validator`](https://github.com/grafana/technical-documentation/tree/main/tools/cmd/doc-validator) over projects. +# - Redirect project root to mounted version. +# For example redirect `/docs/grafana/` to `/docs/grafana/latest/`. +# - Support for Podman or Docker containers with `PODMAN` environment variable. +# - Support for projects: +# - agent +# - enterprise-logs +# - enterprise-metrics +# - enterprise-traces +# - grafana +# - grafana-cloud +# - grafana-cloud/machine-learning +# - helm-charts/mimir-distributed +# - helm-charts/tempo-distributed +# - incident +# - loki +# - mimir +# - oncall +# - opentelemetry +# - phlare +# - plugins +# - slo +# - tempo +# - writers-toolkit + + +set -ef + +readonly DOCS_HOST_PORT="${DOCS_HOST_PORT:-3002}" +readonly DOCS_IMAGE="${DOCS_IMAGE:-grafana/docs-base:latest}" + +readonly DOC_VALIDATOR_INCLUDE="${DOC_VALIDATOR_INCLUDE:-.+\.md$}" +readonly DOC_VALIDATOR_SKIP_CHECKS="${DOC_VALIDATOR_SKIP_CHECKS:-^image-}" + +readonly HUGO_REFLINKSERRORLEVEL="${HUGO_REFLINKSERRORLEVEL:-WARNING}" +readonly VALE_MINALERTLEVEL="${VALE_MINALERTLEVEL:-error}" +readonly WEBSITE_EXEC="${WEBSITE_EXEC:-make server-docs}" +# If set, the docs-base image will run a prebuild script that sets up Hugo mounts. +readonly WEBSITE_MOUNTS="${WEBSITE_MOUNTS:-}" + +PODMAN="$(if command -v podman >/dev/null 2>&1; then echo podman; else echo docker; fi)" + +if ! command -v curl >/dev/null 2>&1; then + if ! command -v wget >/dev/null 2>&1; then + errr 'either `curl` or `wget` must be installed for this script to work.' + + exit 1 + fi +fi + +if ! command -v "${PODMAN}" >/dev/null 2>&1; then + errr 'either `podman` or `docker` must be installed for this script to work.' + + exit 1 +fi + + +about() { + cat <...]> $0 [[:[:[:]]]...] + +Examples: + REPOS_PATH=~/ext/grafana/ $0 writers-toolkit tempo:latest helm-charts/mimir-distributed:latest:mimir:docs/sources/mimir-distributed +EOF +} + +if [ $# -lt 1 ]; then + cat <&2 +ERRR: arguments required but not supplied. + +$(about) + +$(usage) +EOF + exit 1 +fi + +readonly REPOS_PATH="${REPOS_PATH:-$(cd "$(git rev-parse --show-toplevel)/.." && echo "${PWD}")}" + +if [ -z "${REPOS_PATH}" ]; then + cat <&2 +ERRR: REPOS_PATH environment variable is required but has not been provided. + +$(usage) +EOF + exit 1 +fi + +SOURCES_as_code='as-code-docs' +SOURCES_enterprise_metrics='backend-enterprise' +SOURCES_enterprise_metrics_='backend-enterprise' +SOURCES_grafana_cloud='website' +SOURCES_grafana_cloud_alerting_and_irm_machine_learning='machine-learning' +SOURCES_grafana_cloud_alerting_and_irm_slo='slo' +SOURCES_grafana_cloud_k6='k6-docs' +SOURCES_grafana_cloud_data_configuration_integrations='cloud-onboarding' +SOURCES_grafana_cloud_frontend_observability_faro_web_sdk='faro-web-sdk' +SOURCES_helm_charts_mimir_distributed='mimir' +SOURCES_helm_charts_tempo_distributed='tempo' +SOURCES_opentelemetry='opentelemetry-docs' +SOURCES_plugins_grafana_datadog_datasource='datadog-datasource' +SOURCES_plugins_grafana_jira_datasource='jira-datasource' +SOURCES_plugins_grafana_mongodb_datasource='mongodb-datasource' +SOURCES_plugins_grafana_oracle_datasource='oracle-datasource' +SOURCES_plugins_grafana_splunk_datasource='splunk-datasource' +SOURCES_plugins_grafana_sentry_datasource='sentry-datasource' +SOURCES_plugins_yesoreyeram_infinity_datasource='infinity-datasource' + +VERSIONS_as_code='UNVERSIONED' +VERSIONS_grafana_cloud='UNVERSIONED' +VERSIONS_grafana_cloud_alerting_and_irm_machine_learning='UNVERSIONED' +VERSIONS_grafana_cloud_alerting_and_irm_slo='UNVERSIONED' +VERSIONS_grafana_cloud_k6='UNVERSIONED' +VERSIONS_grafana_cloud_data_configuration_integrations='UNVERSIONED' +VERSIONS_grafana_cloud_frontend_observability_faro_web_sdk='UNVERSIONED' +VERSIONS_opentelemetry='UNVERSIONED' +VERSIONS_plugins_grafana_datadog_datasource='latest' +VERSIONS_plugins_grafana_jira_datasource='latest' +VERSIONS_plugins_grafana_mongodb_datasource='latest' +VERSIONS_plugins_grafana_oracle_datasource='latest' +VERSIONS_plugins_grafana_splunk_datasource='latest' +VERSIONS_plugins_yesoreyeram_infinity_datasource='latest' +VERSIONS_technical_documentation='UNVERSIONED' +VERSIONS_website='UNVERSIONED' +VERSIONS_writers_toolkit='UNVERSIONED' + +PATHS_grafana_cloud='content/docs/grafana-cloud' +PATHS_helm_charts_mimir_distributed='docs/sources/helm-charts/mimir-distributed' +PATHS_helm_charts_tempo_distributed='docs/sources/helm-charts/tempo-distributed' +PATHS_mimir='docs/sources/mimir' +PATHS_plugins_grafana_datadog_datasource='docs/sources' +PATHS_plugins_grafana_jira_datasource='docs/sources' +PATHS_plugins_grafana_mongodb_datasource='docs/sources' +PATHS_plugins_grafana_oracle_datasource='docs/sources' +PATHS_plugins_grafana_sentry_datasource='docs/sources' +PATHS_plugins_grafana_splunk_datasource='docs/sources' +PATHS_plugins_yesoreyeram_infinity_datasource='docs/sources' +PATHS_tempo='docs/sources/tempo' +PATHS_website='content' + +# identifier STR +# Replace characters that are not valid in an identifier with underscores. +identifier() { + echo "$1" | tr -C '[:alnum:]_\n' '_' +} + +# aget ARRAY KEY +# Get the value of KEY from associative array ARRAY. +# Characters that are not valid in an identifier are replaced with underscores. +aget() { + eval echo '$'"$(identifier "$1")_$(identifier "$2")" +} + +# src returns the project source repository name for a project. +src() { + _project="$1" + + case "${_project}" in + plugins/*) + if [ -z "$(aget SOURCES "${_project}")" ]; then + echo plugins-private + else + aget SOURCES "${_project}" + fi + ;; + *) + if [ -z "$(aget SOURCES "${_project}")" ]; then + echo "${_project}" + else + aget SOURCES "${_project}" + fi + ;; + esac + + unset _project +} + +# path returns the relative path within the repository that contain the docs for a project. +path() { + _project="$1" + + case "${_project}" in + plugins/*) + if [ -z "$(aget PATHS "${_project}")" ]; then + echo "${_project}/docs/sources" + else + aget PATHS "${_project}" + fi + ;; + *) + if [ -z "$(aget PATHS "${_project}")" ]; then + echo "docs/sources" + else + aget PATHS "${_project}" + fi + esac + + unset _project +} + +# version returns the version for a project. Unversioned projects return the special value 'UNVERSIONED'. +version() { + _project="$1" + + case "${_project}" in + plugins/*) + if [ -z "$(aget VERSIONS "${_project}")" ]; then + echo "UNVERSIONED" + else + aget VERSIONS "${_project}" + fi + ;; + *) + if [ -z "$(aget VERSIONS "${_project}")" ]; then + echo latest + else + aget VERSIONS "${_project}" + fi + esac + + unset _project +} + + +# new_proj populates a new project structure. +new_proj() { + _project="$1" + _version="$2" + _repo="$3" + _path="$4" + + # If version is not set, use the script mapping of project to default versions if it exists. + # Fallback to 'latest'. + if [ -z "${_version}" ]; then + _version="$(version "${_project}")" + fi + + # If repo is not set, use the script mapping of project to repo name if it exists. + # Fallback to using the project name. + if [ -z "${_repo}" ]; then + _repo="$(src "${_project}")" + fi + + # If path is not set, use the script mapping of project to docs sources path if it exists. + # Fallback to using 'docs/sources'. + if [ -z "${_path}" ]; then + _path="$(path "${_project}")" + fi + + echo "${_project}:${_version}:${_repo}:${_path}" + unset _project _version _repo _path +} + +# proj_url returns the webserver URL for a project. +# It expects a complete project structure as input. +proj_url() { + IFS=: read -r _project _version _ _ <&2 + fi +} + +errr() { + echo "ERRR: $1" >&2 +} + +note() { + echo "NOTE: $1" >&2 +} + +url_src_dst_vers="$(url_src_dst_vers "$@")" + +volumes="" +redirects="" + +for arg in "$@"; do + IFS=: read -r _project _ _repo _ <"${tempfile}" +#!/usr/bin/env bash + +tc() { + set \${*,,} + echo \${*^} +} + +for redirect in ${redirects}; do + IFS='^' read -r path ver <<<"\${redirect}" + echo -e "---\\nredirectURL: \"\${path/\/hugo\/content/}\"\\ntype: redirect\\nversioned: true\\n---\\n" > "\${path/\${ver}/_index.md}" +done + +for x in "${url_src_dst_vers}"; do + IFS='^' read -r _ _ dst _ <<<"\${x}" + + title="\${dst%/*}" + title="\$(tc \${title##*/})" + while [[ -n "\${dst}" ]]; do + if [[ ! -f "\${dst}/_index.md" ]]; then + echo -e "---title: \${title}\\n---\\n\\n# \${title}\\n\\n{{< section >}}" > "\${dst}/_index.md" + fi + dst="\${dst%/*}" + done +done + +if [[ -n "${WEBSITE_MOUNTS}" ]]; then + unset WEBSITE_SKIP_MOUNTS +fi + +${WEBSITE_EXEC} +EOF + chmod +x "${tempfile}" + volumes="${volumes} --volume=${tempfile}:/entrypoint" + readonly volumes + + IFS='' read -r cmd <&1\ + | sed -u \ + -e '/Web Server is available at http:\/\/localhost:3003\/ (bind address 0.0.0.0)/ d' \ + -e '/^hugo server/ d' \ + -e '/fatal: not a git repository (or any parent up to mount point \/)/ d' \ + -e '/Stopping at filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not set)./ d' \ + -e "/Makefile:[0-9]*: warning: overriding recipe for target 'docs'/ d" \ + -e "/docs.mk:[0-9]*: warning: ignoring old recipe for target 'docs'/ d" \ + -e '/\/usr\/bin\/make -j 2 proxy hserver-docs HUGO_PORT=3003/ d' \ + -e '/website-proxy/ d' \ + -e '/rm -rf dist*/ d' \ + -e '/Press Ctrl+C to stop/ d' \ + -e '/make/ d' \ + -e '/WARNING: The manual_mount source directory/ d' + fi + ;; +esac \ No newline at end of file diff --git a/docs/sources/_index.md b/docs/sources/_index.md new file mode 100644 index 00000000..0c5237c0 --- /dev/null +++ b/docs/sources/_index.md @@ -0,0 +1,86 @@ +--- +aliases: + - /docs/plugins/grafana-sentry-datasource/ +description: Guide for using the Sentry data source in Grafana to query and visualize Sentry issues, events, spans, and organization statistics. +keywords: + - grafana + - sentry + - data source + - error tracking + - application monitoring +labels: + products: + - cloud + - enterprise + - oss +menuTitle: Sentry +title: Sentry data source +weight: 1350 +review_date: "2026-04-07" +--- + +# Sentry data source + +The Sentry data source plugin lets you query and visualize [Sentry](https://sentry.io/) data within Grafana. You can display issues, events, spans, session metrics, and organization statistics in Grafana dashboards, giving you a unified view of application errors and performance alongside your other observability data. + +## Requirements + +- Grafana version 10.4.0 or later. +- A Sentry account (hosted at [sentry.io](https://sentry.io/) or self-hosted). +- A Sentry internal integration authentication token with **Read** access to **Project**, **Issue & Event**, and **Organization**. Refer to [Configure the Sentry data source](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/configure/) for setup instructions. + +## Supported features + +| Feature | Supported | +| ----------- | --------- | +| Metrics | Yes | +| Alerting | Yes | +| Annotations | Yes | + +## Supported query types + +The Sentry data source supports the following query types. For detailed field descriptions and examples, refer to the [query editor](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/query-editor/) documentation. + +| Query type | Description | +| ------------ | --------------------------------------------------------------------------------------------- | +| Issues | Query Sentry issues with filtering, sorting, and pagination. | +| Events | Query individual error and transaction events with custom fields. | +| Spans | Query span data for distributed tracing analysis. | +| Events Stats | Query time-series event data for trend analysis and visualization. | +| Spans Stats | Query time-series span data for performance trend analysis. | +| Metrics | Query session-based metrics such as crash rates and session health. | +| Stats | Query organization-level usage statistics such as event quotas and consumption. | + +## Get started + +The following documents help you set up and use the Sentry data source: + +- [Configure the Sentry data source](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/configure/) +- [Sentry query editor](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/query-editor/) +- [Template variables](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/template-variables/) +- [Annotations](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/annotations/) +- [Alerting](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/alerting/) +- [Troubleshooting](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/troubleshooting/) + +## Additional features + +After configuring the data source, you can: + +- Use [Explore](https://grafana.com/docs/grafana//explore/) to query Sentry data without building a dashboard. +- Add [Transformations](https://grafana.com/docs/grafana//panels-visualizations/query-transform-data/transform-data/) to manipulate query results. +- Create [Template variables](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/template-variables/) for dynamic, reusable dashboards. +- Add [Annotations](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/annotations/) to overlay Sentry issues on graphs. +- Set up [Alerting](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/alerting/) rules based on Sentry data. + +## Plugin updates + +Always ensure that your plugin version is up-to-date so you have access to all current features and improvements. Navigate to **Plugins and data** > **Plugins** to check for updates. Grafana recommends upgrading to the latest Grafana version, and this applies to plugins as well. + +{{< admonition type="note" >}} +Plugins are automatically updated in Grafana Cloud. +{{< /admonition >}} + +## Related resources + +- [Official Sentry documentation](https://docs.sentry.io/) +- [Grafana community forum](https://community.grafana.com/) diff --git a/docs/sources/alerting.md b/docs/sources/alerting.md new file mode 100644 index 00000000..aa132512 --- /dev/null +++ b/docs/sources/alerting.md @@ -0,0 +1,128 @@ +--- +aliases: + - /docs/plugins/grafana-sentry-datasource/alerting/ +description: Set up Grafana alerting with the Sentry data source to trigger notifications based on Sentry data. +keywords: + - grafana + - sentry + - alerting + - alert rules + - notifications +labels: + products: + - cloud + - enterprise + - oss +menuTitle: Alerting +title: Sentry alerting +weight: 400 +review_date: "2026-04-07" +--- + +# Sentry alerting + +You can configure Grafana alerting rules that query the Sentry data source to receive notifications when error rates, event counts, or other Sentry metrics cross defined thresholds. + +## Before you begin + +- [Configure the Sentry data source](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/configure/). +- Understand [Grafana Alerting](https://grafana.com/docs/grafana//alerting/). + +## Supported query types for alerting + +Alert rules work with Sentry query types that return numeric or time-series data. The following query types are compatible with alerting: + +| Query type | Compatible | Notes | +| ------------ | ---------- | ------------------------------------------------------------------------------------------------------------- | +| Issues | Yes | Returns tabular data. Use a **Count** rows expression to alert on the number of matching issues. | +| Events | Yes | Use aggregate fields like `count()` or `epm()` in **Fields**, or use a **Count** rows expression. | +| Events Stats | Yes | Returns time-series data. Best suited for alerting on event trends over time. | +| Spans | Yes | Returns tabular data. Use aggregate fields or a **Count** rows expression. | +| Spans Stats | Yes | Returns time-series data. Best suited for alerting on span performance trends. | +| Metrics | Yes | Returns time-series data. Alert on session metrics like crash rates or error rates. | +| Stats | Yes | Returns time-series data. Alert on organization-level usage statistics. | + +## Create an alert rule + +To create an alert rule using the Sentry data source: + +1. Navigate to **Alerting** > **Alert rules**. +1. Click **New alert rule**. +1. Enter a name for the alert rule. +1. Select the **Sentry** data source. +1. Select a query type and configure the query fields. For example, select **Events Stats** and set a **Y-axis** field such as `count()` to alert on event volume. +1. Define the alert condition using expressions. For example, use a **Reduce** expression to calculate the mean, then a **Threshold** expression to trigger when the value exceeds a limit. +1. Configure the evaluation interval and pending period. +1. Add labels and notifications as needed. +1. Click **Save rule and exit**. + +## Alert rule examples + +The following examples show common alerting scenarios with the Sentry data source. + +### Alert on high error event volume + +Monitor for spikes in error events across your projects: + +1. Select **Events Stats** as the query type. +1. Set **Y-axis** to `count()`. +1. Set **Query** to `event.type:error`. +1. Add a **Reduce** expression with function **Last**. +1. Add a **Threshold** expression to alert when the value is above your desired limit. + +### Alert on unresolved issue count + +Get notified when the number of unresolved issues exceeds a threshold: + +1. Select **Issues** as the query type. +1. Set **Query** to `is:unresolved`. +1. Set **Limit** high enough to capture all matching issues (for example, `100`). +1. Add a **Reduce** expression with function **Count** to count the number of returned rows. +1. Add a **Threshold** expression to alert when the count exceeds your limit. + +### Alert on slow transactions + +Monitor for p95 latency regressions in a specific transaction: + +1. Select **Events Stats** as the query type. +1. Set **Y-axis** to `p95()`. +1. Set **Query** to `event.type:transaction transaction:`. +1. Add a **Reduce** expression with function **Last**. +1. Add a **Threshold** expression to alert when the p95 value exceeds an acceptable duration in milliseconds. + +### Alert on crash rate changes + +Monitor session crash rates using the Metrics query type: + +1. Select **Metrics** as the query type. +1. Set **Field** to `session.crash_rate`. +1. Optionally set **Group By** to `project` to monitor per-project crash rates. +1. Add a **Reduce** expression with function **Last**. +1. Add a **Threshold** expression to alert when the crash rate exceeds an acceptable level (for example, `0.01` for 1%). + +### Alert on declining crash-free session rate + +Monitor when crash-free rates drop below a target: + +1. Select **Metrics** as the query type. +1. Set **Field** to `session.crash_free_rate`. +1. Add a **Reduce** expression with function **Last**. +1. Add a **Threshold** expression to alert when the value drops below your target (for example, `0.995` for 99.5%). + +### Alert on organization quota usage + +Monitor organization-level event consumption to avoid quota overages: + +1. Select **Stats** as the query type. +1. Set **Field** to `sum(quantity)`. +1. Set **Category Filter** to `error`. +1. Add a **Reduce** expression with function **Last**. +1. Add a **Threshold** expression to alert when usage approaches your quota limit. + +## Limitations + +- Alert evaluation depends on the Sentry API response time. If the Sentry API is slow or rate-limited, alert evaluation may be delayed. +- Sentry API rate limits apply to alert rule evaluations. Set evaluation intervals that avoid exceeding rate limits, especially when multiple alert rules query the same Sentry data source. +- Issues, Events, and Spans queries return tabular data. To create numeric alert conditions from these, use **Reduce** expressions with functions like **Count**, **Min**, **Max**, or **Mean**. + +For more information, refer to [Grafana Alerting](https://grafana.com/docs/grafana//alerting/). diff --git a/docs/sources/annotations.md b/docs/sources/annotations.md new file mode 100644 index 00000000..c1085714 --- /dev/null +++ b/docs/sources/annotations.md @@ -0,0 +1,111 @@ +--- +aliases: + - /docs/plugins/grafana-sentry-datasource/annotations/ +description: Use annotations to overlay Sentry issues on Grafana dashboard graphs. +keywords: + - grafana + - sentry + - annotations + - issues + - overlay +labels: + products: + - cloud + - enterprise + - oss +menuTitle: Annotations +title: Sentry annotations +weight: 350 +review_date: "2026-04-07" +--- + +# Sentry annotations + +Annotations let you overlay Sentry data on dashboard graphs, marking when issues were first or last seen directly on your time-series panels. This helps you correlate application errors with metrics from other data sources. + +## Before you begin + +- [Configure the Sentry data source](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/configure/). +- Understand [Grafana annotations](https://grafana.com/docs/grafana//dashboards/build-dashboards/annotate-visualizations/). + +## Supported query types for annotations + +All Sentry query types are available for annotations. The **Issues** and **Events** query types are best suited because they return discrete records with timestamps that map naturally to annotation markers. + +| Query type | Recommended | Notes | +| ------------ | ----------- | ------------------------------------------------------------------------------------------ | +| Issues | Yes | Uses `FirstSeen` and `LastSeen` timestamps. Best for marking when issues appeared. | +| Events | Yes | Uses event timestamps. Useful for marking individual error or transaction events. | +| Spans | Yes | Uses span timestamps. Useful for marking specific span occurrences. | +| Events Stats | No | Returns time-series data, which is less natural for annotation markers. | +| Spans Stats | No | Returns time-series data, which is less natural for annotation markers. | +| Metrics | No | Returns time-series data, which is less natural for annotation markers. | +| Stats | No | Returns time-series data, which is less natural for annotation markers. | + +## Create an annotation query + +To add Sentry annotations to a dashboard: + +1. Open the dashboard where you want to display annotations. +1. Navigate to **Dashboard settings** > **Annotations**. +1. Click **Add annotation query**. +1. Select the **Sentry** data source. +1. Select a **Query Type**. **Issues** is the most common choice for annotations. +1. (Optional) Filter by **Projects** to limit annotations to specific Sentry projects. +1. (Optional) Filter by **Environments** to limit annotations to specific environments. +1. (Optional) Enter a **Query** to filter which results appear as annotations. +1. (Optional) Set **Sort By** to control the order of results (for example, **Last Seen** or **Priority**). +1. (Optional) Set a **Limit** to control how many annotations display. +1. Click **Save dashboard**. + +## Annotation examples + +The following examples show common annotation configurations. + +### Overlay all unresolved issues + +Display all unresolved issues from a specific project: + +1. Set **Query Type** to **Issues**. +1. Select the target project in **Projects**. +1. Set **Query** to `is:unresolved`. + +### Overlay high-priority issues only + +Display only high-priority issues as annotations: + +1. Set **Query Type** to **Issues**. +1. Set **Query** to `is:unresolved priority:high`. + +### Overlay issues for a specific release + +Mark issues associated with a particular release: + +1. Set **Query Type** to **Issues**. +1. Set **Query** to `release:1.2.0`. + +### Overlay recent error events + +Mark individual error events on your graphs: + +1. Set **Query Type** to **Events**. +1. Set **Query** to `event.type:error`. +1. Set **Sort By** to **Last Seen** with **Descending** sort direction. +1. Set **Limit** to control how many events appear. + +### Overlay issues using template variables + +Use dashboard template variables to make annotations dynamic: + +1. Set **Query Type** to **Issues**. +1. Select `var: ${project}` in the **Projects** field. +1. Set **Query** to `is:unresolved`. + +When the user changes the project variable, the annotations update to show issues for the selected project. + +## Limitations + +- Annotations are filtered by the dashboard time range. Only data within the visible time range appears. +- Sentry API rate limits apply. If you have many matching results, set a **Limit** to reduce the number of API calls. + +For more information, refer to [Annotations](https://grafana.com/docs/grafana//dashboards/build-dashboards/annotate-visualizations/). diff --git a/docs/sources/configure.md b/docs/sources/configure.md new file mode 100644 index 00000000..48fcadea --- /dev/null +++ b/docs/sources/configure.md @@ -0,0 +1,170 @@ +--- +aliases: + - /docs/plugins/grafana-sentry-datasource/configure/ +description: Configure the Sentry data source in Grafana, including authentication setup and provisioning. +keywords: + - grafana + - sentry + - data source + - configuration + - authentication + - auth token + - provisioning +labels: + products: + - cloud + - enterprise + - oss +menuTitle: Configure +title: Configure the Sentry data source +weight: 100 +review_date: "2026-04-07" +--- + +# Configure the Sentry data source + +This document explains how to configure the Sentry data source in Grafana. + +## Before you begin + +Before configuring the data source, ensure you have: + +- **Grafana version:** Grafana 10.4.0 or later. +- **Grafana permissions:** Organization administrator role. Refer to [Permissions](https://grafana.com/docs/grafana//administration/roles-and-permissions/) for more information. +- **Sentry account:** An active Sentry account. +- **Sentry role:** The Admin, Manager, or Owner role in Sentry, required to create an internal integration token. + +## Get an authentication token from Sentry + +To configure the Sentry data source plugin, you need an internal integration token from Sentry: + +1. Go to `https://sentry.io`. +1. Navigate to **Settings** > **Developer Settings** > **Custom Integrations**. +1. Click **Create New Integration** and select **Internal Integration**. +1. Enter a valid name, such as _Grafana_. +1. Under **Permissions**, grant **Read** access to the required resources, such as **Project**, **Issue & Event**, and **Organization**. +1. Click **Save Changes**, then scroll down to **Tokens** and click **New Token**. +1. Copy the token for use in the **Sentry Auth Token** field when configuring the data source in Grafana. + +{{< admonition type="note" >}} +The Admin, Manager, or Owner role in Sentry is required to create internal integrations. +{{< /admonition >}} + +## Add the data source + +To add the Sentry data source in Grafana: + +1. Click **Connections** in the left-side menu. +1. Click **Add new connection**. +1. Type `Sentry` in the search bar. +1. Select **Sentry**. +1. Click **Add new data source**. + +## Configure settings + +The following table describes the available configuration settings. + +### Sentry settings + +| Setting | Description | +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Sentry URL** | (Required) The Sentry URL to connect to. Defaults to `https://sentry.io`. Set this to your self-hosted Sentry URL if you aren't using the hosted service. | +| **Sentry Org** | (Required) The Sentry organization slug. This is the last segment of your organization URL: `https://sentry.io/organizations/{organization_slug}/`. Enter only the slug, not the full URL. | +| **Sentry Auth Token** | (Required) The authentication token from Sentry. Create one from `https://sentry.io/settings/{organization_slug}/developer-settings/` using the steps in the previous section. | + +### Additional settings + +These optional settings provide more control over your data source connection. + +| Setting | Description | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| **Skip TLS Verify** | Skip TLS certificate verification. Use this option for self-hosted Sentry instances with self-signed certificates. | +| **Enable Secure Socks Proxy** | Enable proxying the data source connection through the secure socks proxy to a different network. Available in Grafana 10.0.0 and later when the proxy is enabled in Grafana configuration. | + +## Private data source connect + +{{< admonition type="note" >}} +Only for Grafana Cloud users. +{{< /admonition >}} + +Private data source connect, or PDC, allows you to establish a private, secured connection between a Grafana Cloud instance, or stack, and data sources secured within a private network. Click the drop-down to locate the URL for PDC. For more information regarding Grafana PDC, refer to [Private data source connect (PDC)](https://grafana.com/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/) and [Configure Grafana private data source connect (PDC)](https://grafana.com/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/configure-pdc/) for instructions on setting up a PDC connection. + +Click **Manage private data source connect** to open your PDC connection page and view your configuration details. + +## Verify the connection + +Click **Save & test** to verify the connection. A successful test displays the message: **plugin health check successful. N projects found.**, where _N_ is the number of projects accessible with the configured credentials. If the test fails, refer to [Troubleshoot Sentry data source issues](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/troubleshooting/) for common solutions. + +## Provision the data source + +You can define the Sentry data source in YAML files as part of Grafana's provisioning system. +For more information, refer to [Provisioning Grafana](https://grafana.com/docs/grafana//administration/provisioning/#data-sources). + +```yaml +apiVersion: 1 + +datasources: + - name: Sentry + type: grafana-sentry-datasource + access: proxy + jsonData: + url: https://sentry.io + orgSlug: + secureJsonData: + authToken: +``` + +The following table describes the provisioning keys. + +| Key | Description | +| --------------------------------- | ------------------------------------------------------------------------------------------------------ | +| `jsonData.url` | The Sentry URL. Defaults to `https://sentry.io`. | +| `jsonData.orgSlug` | The Sentry organization slug. | +| `jsonData.tlsSkipVerify` | Set to `true` to skip TLS certificate verification for self-hosted Sentry. | +| `jsonData.enableSecureSocksProxy` | Set to `true` to proxy the connection through the secure socks proxy. | +| `secureJsonData.authToken` | The Sentry authentication token. | + +## Provision the data source with Terraform + +You can provision the Sentry data source using the [Grafana Terraform provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs). Use the `grafana_data_source` resource to create and manage data source instances. + +### Basic Terraform provisioning + +```hcl +resource "grafana_data_source" "sentry" { + type = "grafana-sentry-datasource" + name = "Sentry" + + json_data_encoded = jsonencode({ + url = "https://sentry.io" + orgSlug = "" + }) + + secure_json_data_encoded = jsonencode({ + authToken = "" + }) +} +``` + +### Terraform provisioning for self-hosted Sentry + +The following example configures the data source for a self-hosted Sentry instance with TLS verification disabled: + +```hcl +resource "grafana_data_source" "sentry" { + type = "grafana-sentry-datasource" + name = "Sentry (self-hosted)" + + json_data_encoded = jsonencode({ + url = "https://sentry.example.com" + orgSlug = "" + tlsSkipVerify = true + }) + + secure_json_data_encoded = jsonencode({ + authToken = "" + }) +} +``` + +For more information about the Grafana Terraform provider, refer to the [provider documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/data_source). diff --git a/docs/sources/query-editor.md b/docs/sources/query-editor.md new file mode 100644 index 00000000..7684ccc0 --- /dev/null +++ b/docs/sources/query-editor.md @@ -0,0 +1,185 @@ +--- +aliases: + - /docs/plugins/grafana-sentry-datasource/query-editor/ +description: Use the Sentry query editor to query issues, events, spans, session metrics, and organization statistics. +keywords: + - grafana + - sentry + - query editor + - issues + - events + - spans + - events stats + - metrics + - organization stats +labels: + products: + - cloud + - enterprise + - oss +menuTitle: Query editor +title: Sentry query editor +weight: 200 +review_date: "2026-04-07" +--- + +# Sentry query editor + +This document explains how to use the Sentry query editor to build queries and visualize Sentry data in Grafana dashboards. + +## Before you begin + +- [Configure the Sentry data source](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/configure/). +- Verify your Sentry authentication token has the required read permissions. + +## Common fields + +Every query type includes the following shared fields. + +| Field | Description | +| ---------------- | ------------------------------------------------------------------------------------------------------------ | +| **Query Type** | The type of Sentry data to query. Select one of: Issues, Events, Spans, Events Stats, Spans Stats, Metrics, or Stats. | +| **Projects** | (Optional) Filter results by one or more Sentry projects. | +| **Environments** | (Optional) Filter results by one or more Sentry environments. Not available for Stats queries. | + +## Query types + +The query editor supports seven query types, each returning a different kind of Sentry data. + +### Issues + +Use the Issues query type to retrieve a list of Sentry issues. Results are filtered based on the dashboard time range. + +| Field | Description | +| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Query** | (Optional) A Sentry search query to filter results. Use the format `FIELD_NAME:FIELD_VALUE` to filter by issue fields. Run with Shift+Enter. | +| **Sort By** | (Optional) The order of results. Options: Last Seen, First Seen, Priority, Events, Users. | +| **Limit** | (Optional) The maximum number of results to return. Default: `100`. | + +#### Issue query examples + +- `is:unresolved` -- Show only unresolved issues. +- `is:unresolved assigned:me` -- Show unresolved issues assigned to you. +- `is:unresolved level:error` -- Show unresolved error-level issues. +- `is:unresolved first-seen:-24h` -- Show unresolved issues first seen in the last 24 hours. +- `is:unresolved times_seen:>100` -- Show unresolved issues seen more than 100 times. + +For more information about Sentry issues, refer to the [Sentry Issues documentation](https://docs.sentry.io/product/issues/). + +### Events + +Use the Events query type to retrieve a list of Sentry events. Results are filtered based on the dashboard time range. + +| Field | Description | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Query** | (Optional) A Sentry search query to filter results. Refer to the [Sentry search syntax documentation](https://docs.sentry.io/product/sentry-basics/search/) for details. Run with Shift+Enter. | +| **Fields** | The Sentry field names to fetch. Select from suggested fields or enter custom field names. Default fields: `id`, `title`, `project`, `project.id`, `release`, `count()`, `epm()`, `last_seen()`, `level`, `event.type`, `platform`. Tags are auto-completed. | +| **Sort By** | (Optional) The sort order for results. Options: Last Seen, Count, Events per minute, Failure rate, Level. You can also enter a custom sort field. | +| **Sort Direction** | (Optional) Ascending or Descending. Appears when a sort field is selected. | +| **Limit** | (Optional) The maximum number of results to return. Maximum: `100`. | + +#### Event query examples + +- `event.type:error` -- Show only error events. +- `event.type:error level:fatal` -- Show fatal error events. +- `event.type:transaction transaction.duration:>5000` -- Show transactions slower than 5 seconds. +- `release:1.2.0` -- Show events from a specific release. +- `tags[browser]:Chrome` -- Show events from Chrome browsers. + +For more information about Sentry events, refer to the [Sentry Discover documentation](https://docs.sentry.io/product/explore/discover-queries/). + +### Spans + +Use the Spans query type to retrieve span data from Sentry. This query type uses the same editor as Events but queries the Sentry spans API and provides span-specific field suggestions. + +| Field | Description | +| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | +| **Query** | (Optional) A Sentry search query to filter results. Run with Shift+Enter. | +| **Fields** | The span field names to fetch. Default fields: `id`, `span.op`, `span.description`, `count()`. Span attributes are auto-completed. | +| **Sort By** | (Optional) The sort order for results. You can also enter a custom sort field. | +| **Sort Direction** | (Optional) Ascending or Descending. Appears when a sort field is selected. | +| **Limit** | (Optional) The maximum number of results to return. Maximum: `100`. | + +#### Span query examples + +- `span.op:db` -- Show database spans. +- `span.op:http.client span.description:*api*` -- Show HTTP client spans with "api" in the description. + +### Events Stats + +Use the Events Stats query type to retrieve time-series data for Sentry events, suitable for graphing trends over time. Results are filtered based on the dashboard time range. + +| Field | Description | +| ----------- | ---------------------------------------------------------------------------------------------------------------- | +| **Query** | (Optional) A Sentry search query to filter results. Run with Shift+Enter. | +| **Y-axis** | (Required) One or more fields to plot on the y-axis. Enter field names and press Enter to add each one. | +| **Group** | (Optional) One or more fields or tags to group results by. Enter values and press Enter to add each one. | +| **Sort By** | (Optional) A field name to sort results by. | +| **Limit** | (Optional) The maximum number of result groups. Maximum: `10`. | + +#### Events Stats use cases + +- **Error trend monitoring:** Set **Y-axis** to `count()` and **Query** to `event.type:error` to graph error volume over time. +- **Error rate by release:** Set **Y-axis** to `count()`, **Query** to `event.type:error`, and **Group** to `release` to compare error rates across releases. +- **Transaction performance:** Set **Y-axis** to `p95(transaction.duration)` to track the 95th percentile response time. + +### Spans Stats + +Use the Spans Stats query type to retrieve time-series data for Sentry spans. This query type uses the same editor as Events Stats but queries the Sentry spans stats API. + +| Field | Description | +| ----------- | ---------------------------------------------------------------------------------------------------------------- | +| **Query** | (Optional) A Sentry search query to filter results. Run with Shift+Enter. | +| **Y-axis** | (Required) One or more fields to plot on the y-axis. Enter field names and press Enter to add each one. | +| **Group** | (Optional) One or more fields or tags to group results by. Enter values and press Enter to add each one. | +| **Sort By** | (Optional) A field name to sort results by. | +| **Limit** | (Optional) The maximum number of result groups. Maximum: `10`. | + +#### Spans Stats use cases + +- **Database performance:** Set **Y-axis** to `p95(span.duration)` and **Query** to `span.op:db` to track database query performance. +- **Slow HTTP calls by endpoint:** Set **Y-axis** to `avg(span.duration)`, **Query** to `span.op:http.client`, and **Group** to `span.description` to identify slow external calls. + +### Metrics + +Use the Metrics query type to retrieve session-based metrics from Sentry, such as crash rates, error rates, and session counts. + +| Field | Description | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Field** | (Required) The session metric to query. Options include: `session.crash_free_rate`, `session.crash_rate`, `session.crashed`, `session.errored`, `session.healthy`, `session.all`, `session.anr_rate`, `session.foreground_anr_rate`, `session.abnormal`, `count_unique(sentry.sessions.user)`, and user-specific variants. | +| **Query** | (Optional) A Sentry search query to filter results. Run with Shift+Enter. | +| **Group By** | (Optional) Group results by `environment`, `project`, `session.status`, or `release`. | +| **Sort By** | (Optional) Sort grouped results by a metric field or `release`. Appears only when a Group By value other than `session.status` is set. | +| **Order** | (Optional) Sort order: High to low or Low to high. Appears alongside Sort By. | +| **Limit** | (Optional) The maximum number of result groups. Default: `5`, maximum: `10`. Appears alongside Sort By. | + +#### Metrics use cases + +- **Crash-free rate monitoring:** Set **Field** to `session.crash_free_rate` and **Group By** to `release` to compare stability across releases. +- **Session health by environment:** Set **Field** to `session.healthy` and **Group By** to `environment` to compare session health across staging and production. +- **ANR rate tracking:** Set **Field** to `session.anr_rate` to monitor Application Not Responding rates on mobile apps. + +### Stats + +Use the Stats query type to retrieve organization-level usage statistics from Sentry, such as event counts and quotas. Results are filtered based on the dashboard time range. The Environments filter is not available for this query type. + +| Field | Description | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| **Field** | (Required) The statistic to trend. Options: `sum(quantity)` or `sum(times_seen)`. | +| **Category Filter** | (Required) The event category to filter by. Options: `error`, `transaction`, `attachment`, `default`, `session`, `security`. | +| **Group By** | (Optional) Group results by `outcome`, `reason`, or `category`. | +| **Outcome Filter** | (Optional) Filter by one or more outcomes: `accepted`, `filtered`, `invalid`, `rate_limited`, `client_discard`, `abuse`. | +| **Reason Filter** | (Optional) A comma-separated list of reasons to filter by. | +| **Interval** | (Optional) The time interval for grouping results. Format: `[number][unit]`, where unit is `m` (minutes), `h` (hours), `d` (days), or `w` (weeks). | + +#### Stats use cases + +- **Error quota monitoring:** Set **Field** to `sum(quantity)`, **Category Filter** to `error`, and **Group By** to `outcome` to track how many errors are accepted, filtered, or rate-limited. +- **Event consumption by project:** Set **Field** to `sum(quantity)`, **Category Filter** to `error`, and filter by specific projects to understand per-project quota usage. +- **Dropped event tracking:** Set **Field** to `sum(quantity)`, **Category Filter** to `error`, and **Outcome Filter** to `rate_limited` and `client_discard` to monitor events your organization is losing. + +For more information about organization statistics, refer to the [Sentry Org Stats documentation](https://docs.sentry.io/product/accounts/quotas/org-stats/). + +## Next steps + +- [Use template variables](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/template-variables/) diff --git a/docs/sources/template-variables.md b/docs/sources/template-variables.md new file mode 100644 index 00000000..ab6a9a24 --- /dev/null +++ b/docs/sources/template-variables.md @@ -0,0 +1,93 @@ +--- +aliases: + - /docs/plugins/grafana-sentry-datasource/template-variables/ +description: Use template variables with the Sentry data source for dynamic, reusable dashboards. +keywords: + - grafana + - sentry + - template variables + - dashboard variables + - projects + - environments + - teams +labels: + products: + - cloud + - enterprise + - oss +menuTitle: Template variables +title: Sentry template variables +weight: 300 +review_date: "2026-04-07" +--- + +# Sentry template variables + +Use template variables to create dynamic, reusable dashboards that let you switch between Sentry projects, environments, and teams without editing queries. + +## Before you begin + +- [Configure the Sentry data source](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/configure/). +- Understand [Grafana template variables](https://grafana.com/docs/grafana//dashboards/variables/). + +## Supported variable types + +The Sentry data source supports the following variable query types. + +| Variable query type | Display value | Actual value | Additional filters | +| ------------------- | -------------------------- | ------------ | ---------------------- | +| **Projects** | Project name and ID | Project ID | Optional team slug | +| **Environments** | Environment name | Environment name | Optional project IDs | +| **Teams** | Team name and slug | Team slug | None | + +## Create a query variable + +To create a query variable using the Sentry data source: + +1. Navigate to **Dashboard settings** > **Variables**. +1. Click **Add variable**. +1. Select **Query** as the variable type. +1. Select the **Sentry** data source. +1. In **Query Type**, select the type of Sentry entity you want to list: **Projects**, **Environments**, or **Teams**. +1. Configure additional filters based on the selected query type: + - **Projects:** Optionally select a **Team slug** to only list projects belonging to that team. The team selector shows all teams in your organization. + - **Environments:** Optionally select one or more **Project IDs** to list environments for those projects. If no project is selected, environments from all projects are listed. + - **Teams:** No additional configuration is needed. + +## Use variables in queries + +After creating template variables, you can use them in query editor fields. The **Projects** and **Environments** drop-downs in the query editor automatically include your dashboard variables as selectable options, prefixed with `var:`. + +For example, if you create a variable named `project` that lists Sentry projects, you can select `var: ${project}` in the **Projects** field of any Sentry query to dynamically filter by the selected project. + +## Variable examples + +The following examples show common template variable configurations. + +### Filter dashboards by project + +Create a variable that lets users select which Sentry project to display data for: + +1. Create a variable named `project` with **Query Type** set to **Projects**. +1. Set **Selection options** to **Multi-value** if you want users to select multiple projects. +1. In your dashboard queries, select `var: ${project}` in the **Projects** field. + +### Cascading project and environment variables + +Create linked variables where the environment list depends on the selected project: + +1. Create a variable named `project` with **Query Type** set to **Projects**. +1. Create a second variable named `environment` with **Query Type** set to **Environments**. +1. In the `environment` variable configuration, select `var: ${project}` in the **Project ID** selector. +1. When a user changes the project, the environment list updates automatically. + +### Filter projects by team + +Create a variable scoped to a specific team's projects: + +1. Create a variable named `team` with **Query Type** set to **Teams**. +1. Create a second variable named `project` with **Query Type** set to **Projects**. +1. In the `project` variable configuration, select `var: ${team}` in the **Team slug** selector. +1. When a user selects a team, only that team's projects appear in the project variable. + +For more information about using variables in queries, refer to [Variable syntax](https://grafana.com/docs/grafana//dashboards/variables/variable-syntax/). diff --git a/docs/sources/troubleshooting.md b/docs/sources/troubleshooting.md new file mode 100644 index 00000000..d4f95294 --- /dev/null +++ b/docs/sources/troubleshooting.md @@ -0,0 +1,295 @@ +--- +aliases: + - /docs/plugins/grafana-sentry-datasource/troubleshooting/ +description: Troubleshooting guide for the Sentry data source in Grafana. +keywords: + - grafana + - sentry + - troubleshooting + - errors + - authentication + - query + - annotations + - alerting +labels: + products: + - cloud + - enterprise + - oss +menuTitle: Troubleshooting +title: Troubleshoot Sentry data source issues +weight: 500 +review_date: "2026-04-07" +--- + +# Troubleshoot Sentry data source issues + +This document provides solutions to common issues you may encounter when configuring or using the Sentry data source. For configuration instructions, refer to [Configure the Sentry data source](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/configure/). + +## Authentication errors + +These errors occur when the Sentry authentication token is invalid, missing, or doesn't have the required permissions. + +### "401 Unauthorized" or "Invalid token" + +**Symptoms:** + +- Save & test fails with authorization errors +- Queries return access denied messages +- Project and environment drop-downs don't populate + +**Possible causes and solutions:** + +| Cause | Solution | +| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| Invalid or expired token | Generate a new authentication token in Sentry under **Settings** > **Developer Settings** > **Custom Integrations** and update the data source. | +| Insufficient permissions | Verify the internal integration has **Read** permissions for **Project**, **Issue & Event**, and **Organization** in Sentry. | +| Wrong organization slug | Verify the **Sentry Org** field matches the slug in your Sentry URL: `https://sentry.io/organizations/{slug}/`. | +| Token created with wrong integration type | Ensure you created an **Internal Integration**, not a public integration. Only internal integrations generate auth tokens suitable for this plugin. | + +### "0 projects found" on save and test + +**Symptoms:** + +- Save & test succeeds but reports "plugin health check successful. 0 projects found." +- No projects appear in the query editor drop-down + +**Solutions:** + +1. Verify the authentication token's integration has **Read** access to **Project** in Sentry. +1. Confirm the Sentry organization has at least one project. +1. Check that the **Sentry Org** slug matches the organization where projects exist. + +## Connection errors + +These errors occur when Grafana can't reach the Sentry API. + +### "Connection refused" or timeout errors + +**Symptoms:** + +- Data source test times out +- Queries fail with network errors + +**Possible causes and solutions:** + +| Cause | Solution | +| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Incorrect Sentry URL | Verify the **Sentry URL** field. For hosted Sentry, leave blank or use `https://sentry.io`. For self-hosted instances, enter your Sentry server URL. | +| Firewall blocking outbound HTTPS | Ensure firewall rules allow outbound HTTPS (port 443) from the Grafana server to the Sentry API endpoint. | +| Self-hosted TLS issues | For self-hosted Sentry with self-signed certificates, enable **Skip TLS Verify** in the data source's additional settings. | +| Network isolation | For Grafana Cloud accessing a private Sentry instance, configure [Private data source connect](https://grafana.com/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/). | + +## Query errors + +These errors occur when executing queries against Sentry. + +### "No data" or empty results + +**Symptoms:** + +- Query executes without error but returns no data +- Charts show "No data" message + +**Possible causes and solutions:** + +| Cause | Solution | +| ------------------------------ | -------------------------------------------------------------------------------------------------- | +| Time range doesn't contain data | Expand the dashboard time range or verify data exists in Sentry for the selected period. | +| Wrong project or environment | Verify you've selected the correct project and environment in the query editor. | +| Query filter too restrictive | Simplify or remove the query filter to verify data exists, then refine the filter. | +| Missing field permissions | Verify the authentication token has read access to the data type you're querying (issues, events). | + +### Query timeout + +**Symptoms:** + +- Query runs for a long time then fails +- Error mentions timeout or rate limits + +**Solutions:** + +1. Narrow the dashboard time range to reduce the volume of data returned. +1. Add project and environment filters to reduce the result set. +1. Reduce the **Limit** value in the query editor. +1. For Events Stats or Spans Stats queries, reduce the number of **Group** fields. + +### "unknown query type" error + +**Symptoms:** + +- Query fails with the message "unknown query type" + +**Solutions:** + +1. Select a valid query type in the **Query Type** drop-down. This error occurs when no query type is selected or the query configuration is corrupted. +1. If you're using a query type added in a newer plugin version (for example, Spans requires v2.2.0+, Metrics requires v1.8.0+), update the plugin to the required version. + +### "invalid or empty organization slug" error + +**Symptoms:** + +- Queries fail with "invalid or empty organization slug" +- Save & test may still succeed + +**Solutions:** + +1. Verify the **Sentry Org** field is set in the data source configuration. Refer to [Configure the Sentry data source](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/configure/). +1. Check that the slug doesn't contain extra spaces or the full URL — only enter the slug portion. + +### "404" errors on span queries + +**Symptoms:** + +- Spans or Spans Stats queries return 404 errors +- Other query types work correctly + +**Solutions:** + +1. Ensure you're running plugin version 2.2.4 or later, which includes a fix for 404 responses when querying spans with attribute aggregation. +1. Verify your Sentry plan includes access to the spans/tracing API. + +### "400" errors with detail message + +**Symptoms:** + +- Query fails with a message like "400 Bad Request" followed by a detail message from Sentry (for example, "400 Bad Request Invalid query") + +**Solutions:** + +1. Review the detail message for specific guidance. Common causes include invalid search syntax in the **Query** field or unsupported field names in **Fields** or **Y-axis**. +1. Test the same query directly in Sentry's Discover view to verify the syntax is valid. +1. For Events or Spans queries, verify the **Fields** values are valid Sentry field names. + +## Annotation errors + +These errors occur when using Sentry annotations on dashboards. + +### Annotations don't appear + +**Symptoms:** + +- Annotation query is configured but no annotations appear on the graph +- No error messages are displayed + +**Possible causes and solutions:** + +| Cause | Solution | +| --------------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| Time range doesn't contain data | Expand the dashboard time range. Annotations only display for data within the visible time range. | +| Query filter too restrictive | Simplify the **Query** filter or remove it temporarily to verify annotations appear. | +| Wrong project or environment | Verify the correct project and environment are selected in the annotation query. | +| Annotations disabled on panel | Verify annotations are enabled on the panel. Click the panel title and check that the annotation toggle is on. | + +### Too many annotations + +**Symptoms:** + +- Dashboard is slow or cluttered with annotations +- Browser performance degrades + +**Solutions:** + +1. Set a lower **Limit** value in the annotation query to reduce the number of returned results. +1. Add a more specific **Query** filter (for example, `is:unresolved level:error`) to reduce the number of matching issues. +1. Filter by **Projects** or **Environments** to narrow the scope. + +## Alerting errors + +These errors occur when using Grafana alerting with the Sentry data source. + +### Alert rule fails to evaluate + +**Symptoms:** + +- Alert rule status shows "Error" +- Alert notifications are not triggered + +**Possible causes and solutions:** + +| Cause | Solution | +| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| Sentry API rate limits | Increase the evaluation interval to reduce the frequency of API calls. Avoid evaluating more frequently than every 5 minutes. | +| Authentication token expired | Generate a new token and update the data source configuration. Refer to [Configure the Sentry data source](https://grafana.com/docs/plugins/grafana-sentry-datasource/latest/configure/). | +| Query returns no data | Verify the query returns data by running it in [Explore](https://grafana.com/docs/grafana//explore/) before creating an alert rule. | +| Missing Reduce expression | Issues, Events, and Spans queries return tabular data. Add a **Reduce** expression (for example, **Count**) to produce a numeric value for the alert condition. | + +### Alert condition not met despite matching data + +**Symptoms:** + +- Data appears in Explore but the alert doesn't fire +- Alert preview shows data but condition is never met + +**Solutions:** + +1. Verify the **Reduce** function matches your intent. For example, **Last** returns the most recent value, while **Mean** averages all values in the evaluation window. +1. Check the **Threshold** expression operator and value. Preview the alert rule to see the actual values being compared. +1. For Issues queries, verify the **Limit** is set high enough to capture all matching issues, since the **Count** expression only counts returned rows. + +## Template variable errors + +These errors occur when using template variables with the Sentry data source. + +### Variables return no values + +**Solutions:** + +1. Verify the data source connection is working by running **Save & test** in the data source settings. +1. For **Environments** variables, ensure the selected project IDs are valid and the projects have environments configured in Sentry. +1. For **Projects** variables filtered by team, verify the team slug is correct. +1. Check that the authentication token has **Read** permissions for the resources the variable queries. + +### Variables are slow to load + +**Solutions:** + +1. Set variable refresh to **On dashboard load** instead of **On time range change**. +1. For **Projects** variables, filter by team slug to reduce the number of results. + +## Performance issues + +These issues relate to slow queries or Sentry API limits. + +### API rate limit errors + +**Symptoms:** + +- "Rate limit exceeded" or throttling errors +- Dashboard panels intermittently fail to load + +**Solutions:** + +1. Reduce the frequency of dashboard auto-refresh. +1. Use larger time intervals in Stats queries to reduce the number of API calls. +1. Reduce the number of panels querying the same Sentry data source on a single dashboard. +1. Enable query caching in Grafana (available in Grafana Enterprise and Grafana Cloud). + +## Enable debug logging + +To capture detailed error information for troubleshooting: + +1. Set the Grafana log level to `debug` in the configuration file: + + ```ini + [log] + level = debug + ``` + +1. Review logs in `/var/log/grafana/grafana.log` (or your configured log location). +1. Look for entries containing `sentry` for request and response details. +1. Reset the log level to `info` after troubleshooting to avoid excessive log volume. + +## Get additional help + +If you've tried the solutions in this document and still encounter issues: + +1. Check the [Grafana community forums](https://community.grafana.com/) for similar issues. +1. Review the [Sentry data source GitHub issues](https://github.com/grafana/sentry-datasource/issues) for known bugs. +1. Consult the [Sentry documentation](https://docs.sentry.io/) for Sentry-specific guidance. +1. Contact Grafana Support if you're a Cloud Pro, Cloud Contracted, or Enterprise user. +1. When reporting issues, include: + - Grafana version and Sentry plugin version + - Error messages (redact sensitive information) + - Steps to reproduce + - Relevant configuration (redact credentials) diff --git a/docs/variables.mk b/docs/variables.mk new file mode 100644 index 00000000..644ffb58 --- /dev/null +++ b/docs/variables.mk @@ -0,0 +1,2 @@ +# List of projects to provide to the make-docs script. +PROJECTS := plugins/grafana-sentry-datasource