mirror of
https://github.com/grafana/grafana.git
synced 2025-01-07 22:53:56 -06:00
Docs: Document new value mappings (#35067)
* Update value-mappings.md * Update value-mappings.md * Update whats-new-in-v8-0.md * Update add-authentication-for-data-source-plugins.md * Update _index.md * updates * Update docs/sources/panels/value-mappings.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> * Update value-mappings.md * Update value-mappings.md * Update panel-editor.md * Update panel-editor.md * Update docs/sources/panels/value-mappings.md Co-authored-by: Torkel Ödegaard <torkel@grafana.org> * Update value-mappings.md * Update value-mappings.md * Update value-mappings.md * Update value-mappings.md * Update value-mappings.md * Update value-mappings.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> Co-authored-by: Torkel Ödegaard <torkel@grafana.org>
This commit is contained in:
Diana Payton
GitHub
parent
406f0458b2
commit
d50b7c526b
@ -64,8 +64,8 @@ aliases = ["/docs/grafana/v1.1", "/docs/grafana/latest/guides/reference/admin",
|
||||
<h4>Provisioning</h4>
|
||||
<p>Learn how to automate your Grafana configuration.</p>
|
||||
</a>
|
||||
<a href="{{< relref "whatsnew/whats-new-in-v7-5.md" >}}" class="nav-cards__item nav-cards__item--guide">
|
||||
<h4>What's new in v7.5</h4>
|
||||
<a href="{{< relref "whatsnew/whats-new-in-v8-0.md" >}}" class="nav-cards__item nav-cards__item--guide">
|
||||
<h4>What's new in v8.0</h4>
|
||||
<p>Explore the features and enhancements in the latest release.</p>
|
||||
</a>
|
||||
|
||||
|
||||
@ -286,7 +286,7 @@ func (ds *dataSource) QueryData(ctx context.Context, req *backend.QueryDataReque
|
||||
|
||||
If your data source uses the same OAuth provider as Grafana itself, for example using [Generic OAuth Authentication]({{< relref "../../auth/generic-oauth.md" >}}), your data source plugin can reuse the access token for the logged-in Grafana user.
|
||||
|
||||
To allow Grafana to pass the access token to the plugin, the user needs to enable **Forward OAuth Identity** on the data source configuration page. This tells Grafana to pass the token to the plugin in a Authorization header. Note that your plugin needs to use the [DataSourceHttpSettings]({{< relref "https://developers.grafana.com/ui/latest/index.html?path=/story/data-source-datasourcehttpsettings--basic" >}}) component in the configuration editor to expose the setting for your data source plugin.
|
||||
To allow Grafana to pass the access token to the plugin, the user needs to enable **Forward OAuth Identity** on the data source configuration page. This tells Grafana to pass the token to the plugin in a Authorization header. Note that your plugin needs to use the [DataSourceHttpSettings](https://developers.grafana.com/ui/latest/index.html?path=/story/data-source-datasourcehttpsettings--basic) component in the configuration editor to expose the setting for your data source plugin.
|
||||
|
||||
The Authorization header is available on the `DataQuery` object on the query data request in your backend data source.
|
||||
|
||||
|
||||
@ -19,12 +19,6 @@ There are several ways to access the panel editor, also called the **Edit Panel*
|
||||
- Click the title of an existing panel and then click **Edit**. The panel opens in edit mode.
|
||||
- Click anywhere on an existing panel and then press **e** on your keyboard. The panel opens in edit mode.
|
||||
|
||||
## Resize panel editor sections
|
||||
|
||||
Drag to resize sections of the panel editor. If the side pane becomes too narrow, then the Panel, Field, and Overrides tabs change to a dropdown list.
|
||||
|
||||
{{< figure src="/static/img/docs/panel-editor/resize-panel-editor-panels-7-0.gif" class="docs-image--no-shadow" max-width="600px" >}}
|
||||
|
||||
## Parts of the panel editor
|
||||
|
||||
This section describes the parts of the panel editor screen and a bit about fields, options, or tasks associated with each part. Some sections in this page link to pages where sections or tasks are documented more fully.
|
||||
@ -46,8 +40,9 @@ On the right side of the header are the following options:
|
||||
|
||||
The visualization preview section contains viewing options, time range controls, the visualization preview, and (if applicable) the panel title, axes, and legend.
|
||||
|
||||
{{< figure src="/static/img/docs/panel-editor/visualization-preview-7-0.png" class="docs-image--no-shadow" max-width="1200px" >}}
|
||||
{{< figure src="/static/img/docs/panel-editor/visualization-preview-8-0.png" class="docs-image--no-shadow" max-width="1200px" >}}
|
||||
|
||||
- **Table view -** Convert any visualization to a table so that you can see the data. Useful for troubleshooting.
|
||||
- **Fill -** The visualization preview will fill the available space in the preview part. If you change the width of the side pane or height of the bottom pane the visualization will adapt to fill whatever space is available.
|
||||
- **Fit -** The visualization preview will fill the available space in but preserve the aspect ratio of the panel.
|
||||
- **Exact -** The visualization preview will have the exact size as the size on the dashboard. If not enough space is available, the visualization will scale down preserving the aspect ratio.
|
||||
@ -57,7 +52,7 @@ The visualization preview section contains viewing options, time range controls,
|
||||
|
||||
The section contains tabs where you enter queries, transform your data, and create alert rules (if applicable).
|
||||
|
||||
{{< figure src="/static/img/docs/panel-editor/data-section-7-0.png" class="docs-image--no-shadow" max-width="1200px" >}}
|
||||
{{< figure src="/static/img/docs/panel-editor/data-section-8-0.png" class="docs-image--no-shadow" max-width="1200px" >}}
|
||||
|
||||
- **Query tab -** Select your data source and enter queries here. For more information, refer to [Queries]({{< relref "queries.md" >}}).
|
||||
- **Transform tab -** Apply data transformations. For more information, refer to [Transformations]({{< relref "transformations/_index.md" >}}).
|
||||
|
||||
@ -3,14 +3,138 @@ title = "Value mappings"
|
||||
weight = 600
|
||||
+++
|
||||
|
||||
## Value mappings
|
||||
# Value mappings
|
||||
|
||||
Value mappings come in different types.
|
||||
Value mapping concept allow you to replace values or ranges in your visualizations with words or emojis.
|
||||
|
||||
* **Range** maps numerical ranges to a display text and color.
|
||||
* **Value** maps text values to a color or different display text.
|
||||
* **Special** maps special values like `Null`, `NaN` and boolean values like `true` and `false` to a display text and color.
|
||||
Values mapped via value mappings will skip the unit formatting. This means that a text value mapped to a numerical value will not be formatted using the configured unit.
|
||||
|
||||
The display text and color are both optional. If you only want to assign colors to text values you can leave the display text empty and the original value will be used for display.
|
||||
|
||||
|
||||
Values mapped via value mappings will skip the unit formatting. This means that a text value mapped to a numerical value will not be formatted using the configured unit.
|
||||
If value mappings are present in a panel, then Grafana displays a summary in the side pane of the panel editor.
|
||||
|
||||
> **Note:** The new value mappings are not compatible with some visualizations, such as Graph (old), Text, and Heatmap.
|
||||
|
||||
## Value mapping examples
|
||||
|
||||
Value mappings are displayed differently in different visualizations.
|
||||
|
||||
### Time series example
|
||||
|
||||
Here's an example showing a Time series visualization with value mappings. Value mapping colors are not applied to this visualization, but the display text is shown on the axis.
|
||||
|
||||
|
||||
|
||||
### Stat example
|
||||
|
||||
Here's an example showing a Stat visualization with value mappings. You might want to hide the sparkline so it doesn't interfere with the values. Value mapping text colors are applied.
|
||||
|
||||
|
||||
|
||||
### Bar gauge example
|
||||
|
||||
Here's an example showing a Bar gauge visualization with value mappings. The value mapping colors are applied to the text but not the gauges.
|
||||
|
||||
|
||||
|
||||
### Table example
|
||||
|
||||
Here's an example showing a Table visualization with value mappings. If you want value mapping colors displayed on the table, then set the cell display mode to **Color text** or **Color background**.
|
||||
|
||||
|
||||
|
||||
## Value mappings fields
|
||||
|
||||
This section describes options in the Value mappings user interface.
|
||||
|
||||
> **Note:** Display text and Color are both optional. If you want to only assign colors to the text values, then you can leave the display text empty and the original value is displayed.
|
||||
|
||||
### Condition
|
||||
|
||||
This column lists the type of condition a value mapping is triggered by and the values.
|
||||
|
||||
You can map values to three different conditions:
|
||||
|
||||
- **Value** maps text values to a color or different display text. For example, if a value is `10`, I want Grafana to display **Perfection!** rather than the number.
|
||||
- **Range** maps numerical ranges to a display text and color. For example, if a value is within a certain range, I want Grafana to display **Low** or **High** rather than the number.
|
||||
- **Special** maps special values like `Null`, `NaN` (not a number), and boolean values like `true` and `false` to a display text and color. For example, if Grafana encounters a `null`, I want Grafana to display **N/A**.
|
||||
|
||||
You can also use the dots on the left as a "handle" to drag and reorder value mappings in the list.
|
||||
|
||||
### Display text
|
||||
|
||||
The _display text_ is what Grafana displays instead of a number when the listed condition is met.
|
||||
|
||||
You can enter any Ascii character or emoji in this field.
|
||||
|
||||
### Color
|
||||
|
||||
You can select a color to for Grafana to display the value mapping text in.
|
||||
|
||||
- **Set color -** Click **Set color** to see a range of recommended colors. Click **Custom** to choose your own color.
|
||||
- **Text color -** The primary text color for the current theme, i.e. white in dark theme and black in light theme.
|
||||
- **Transparent -** Makes the color transparent so that the value mapping color shows whatever color is behind it, such as a panel background color.
|
||||
|
||||
|
||||
|
||||
### Copy icon
|
||||
|
||||
Click the copy icon in the value mapping row that you want to copy.
|
||||
|
||||
### Trash icon
|
||||
|
||||
Click the trash can icon to delete a value mapping. Once deleted, you cannot recover it.
|
||||
|
||||
## Map a value
|
||||
|
||||
Create a mapping for a single value.
|
||||
|
||||
|
||||
|
||||
1. [Open the panel editor]({{< relref "./panel-editor.md#open-the-panel-editor" >}}).
|
||||
1. In the Value mappings section of the side pane, click **Add value mappings**.
|
||||
1. Click **Add a new mapping** and then select **Value**.
|
||||
1. Enter the exact value for Grafana to match.
|
||||
1. (Optional) Enter display text.
|
||||
1. (Optional) Set the color.
|
||||
1. Click **Update** to save the value mapping.
|
||||
|
||||
## Map a range
|
||||
|
||||
Create a mapping for a range of values.
|
||||
|
||||
|
||||
|
||||
1. [Open the panel editor]({{< relref "./panel-editor.md#open-the-panel-editor" >}}).
|
||||
1. In the Value mappings section of the side pane, click **Add value mappings**.
|
||||
1. Click **Add a new mapping** and then select **Range**.
|
||||
1. Enter the beginning and ending values in the range for Grafana to match.
|
||||
1. (Optional) Enter display text.
|
||||
1. (Optional) Set the color.
|
||||
1. Click **Update** to save the value mapping.
|
||||
|
||||
## Map a special value
|
||||
|
||||
Create a mapping for a special value.
|
||||
|
||||
|
||||
|
||||
1. [Open the panel editor]({{< relref "./panel-editor.md#open-the-panel-editor" >}}).
|
||||
1. In the Value mappings section of the side pane, click **Add value mappings**.
|
||||
1. Click **Add a new mapping** and then select **Special**.
|
||||
1. Select the special value for Grafana to match. Options include:
|
||||
- Null
|
||||
- NaN (Not a Number)
|
||||
- Null + NaN
|
||||
- True
|
||||
- False
|
||||
- Empty
|
||||
1. (Optional) Enter display text.
|
||||
1. (Optional) Set the color.
|
||||
1. Click **Update** to save the value mapping.
|
||||
|
||||
## Edit a value mapping
|
||||
|
||||
1. [Open the panel editor]({{< relref "./panel-editor.md#open-the-panel-editor" >}}).
|
||||
1. In the Value mappings section of the side pane, click **Edit value mappings**.
|
||||
1. Make any necessary changes in the fields and then click **Update**.
|
||||
|
||||
@ -94,7 +94,7 @@ Lots of panel editor improvements, heavily informed by user research and communi
|
||||
|
||||
- All options are now shown in a single pane.
|
||||
- You can now search panel options.
|
||||
- Value mapping has been completely redesigned.
|
||||
- The Value mappings feature has been completely redesigned. For more information, refer to [Value mappings]({{< relref "../panels/value-mappings.md" >}}).
|
||||
- New **Table view** option is always available.
|
||||
|
||||
The [Panels]({{< relref "../panels/_index.md" >}}) section has been updated to reflect these changes.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user