From fa4084f90ae075dd67d68aa58deaa2801291711d Mon Sep 17 00:00:00 2001 From: Marcus Olsson Date: Fri, 31 Jul 2020 16:07:03 +0200 Subject: [PATCH] Docs: Add plugins guide on error handling (#26518) --- docs/sources/developers/plugins/_index.md | 1 + .../developers/plugins/error-handling.md | 64 +++++++++++++++++++ docs/sources/menu.yaml | 2 + 3 files changed, 67 insertions(+) create mode 100644 docs/sources/developers/plugins/error-handling.md diff --git a/docs/sources/developers/plugins/_index.md b/docs/sources/developers/plugins/_index.md index bc32f45624a..15d7d7ebd0a 100644 --- a/docs/sources/developers/plugins/_index.md +++ b/docs/sources/developers/plugins/_index.md @@ -48,6 +48,7 @@ Improve an existing plugin with one of our guides: - [Add support for variables]({{< relref "add-support-for-variables.md" >}}) - [Build a logs data source plugin]({{< relref "build-a-logs-data-source-plugin.md" >}}) - [Build a streaming data source plugin]({{< relref "build-a-streaming-data-source-plugin.md" >}}) +- [Error handling]({{< relref "error-handling.md" >}}) ### Concepts diff --git a/docs/sources/developers/plugins/error-handling.md b/docs/sources/developers/plugins/error-handling.md new file mode 100644 index 00000000000..c381077b2d7 --- /dev/null +++ b/docs/sources/developers/plugins/error-handling.md @@ -0,0 +1,64 @@ ++++ +title = "Error handling" +type = "docs" ++++ + +# Error handling + +This guide explains how to handle errors in plugins. + +## Provide usable defaults + +Allow the user to learn your plugin in small steps. Provide a useful default configuration so that: + +- The user can get started right away. +- You can avoid unnecessary error messages. + +For example, by selecting the first field of an expected type, the panel can display a visualization without any user configuration. If a user explicitly selects a field, then use that one. Otherwise, default to the first field of type `string`: + +```ts +const numberField = frame.fields.find(field => + options.numberFieldName ? field.name === options.numberFieldName : field.type === FieldType.number +); +``` + +## Display error messages + +To display an error message to the user, `throw` an `Error` with the message you want to display: + +```ts +throw new Error('An error occurred'); +``` + +Grafana displays the error message in the top-left corner of the panel. + +{{< docs-imagebox img="/img/docs/panel_error.png" class="docs-image--no-shadow" max-width="850px" >}} + +Avoid displaying overly-technical error messages to the user. If you want to let technical users report an error, consider logging it instead. + +```ts +try { + failingFunction(); +} catch (err) { + console.error(err); + throw new Error('Something went wrong'); +} +``` + +> **Note:** Grafana displays the exception message in the UI as written, so we recommend using grammatically correct sentences. For more information, refer to the [Documentation style guide](https://github.com/grafana/grafana/blob/master/contribute/style-guides/documentation-style-guide.md). + +Here are some examples of situations where you might want to display an error to the user. + +### Invalid query response + +Users have full freedom when they create data source queries for panels. If your panel plugin requires a specific format for the query response, then use the panel canvas to guide the user. + +```ts +if (!numberField) { + throw new Error('Query result is missing a number field') +} + +if (frame.length === 0) { + throw new Error('Query returned an empty result') +} +``` diff --git a/docs/sources/menu.yaml b/docs/sources/menu.yaml index 3c3c9f7764c..59d58dbad73 100644 --- a/docs/sources/menu.yaml +++ b/docs/sources/menu.yaml @@ -462,6 +462,8 @@ name: Plugin protocol - link: /developers/plugins/backend/grafana-plugin-sdk-for-go/ name: Grafana plugin SDK for Go + - name: Error handling + link: /developers/plugins/error-handling/ - name: Legacy plugins children: - link: /developers/plugins/legacy/