From 6ef632a6b71524f5ae64d835035c65eb71c546c3 Mon Sep 17 00:00:00 2001 From: Isabel Matwawana <76437239+imatwawana@users.noreply.github.com> Date: Mon, 9 Dec 2024 12:50:14 -0500 Subject: [PATCH] [v11.0.x] Docs: state timeline visualization refactor (#97693) --- .../visualizations/state-timeline/index.md | 93 ++++++++++--------- 1 file changed, 48 insertions(+), 45 deletions(-) diff --git a/docs/sources/panels-visualizations/visualizations/state-timeline/index.md b/docs/sources/panels-visualizations/visualizations/state-timeline/index.md index 76d81fc06eb..d6c6f2b960d 100644 --- a/docs/sources/panels-visualizations/visualizations/state-timeline/index.md +++ b/docs/sources/panels-visualizations/visualizations/state-timeline/index.md @@ -34,7 +34,7 @@ A state timeline visualization displays data in a way that shows state changes o For example, if you're monitoring the CPU usage of a server, you can use a state timeline to visualize the different states, such as “LOW,” “NORMAL,” “HIGH,” or “CRITICAL,” over time. Each state is represented by a different color and the lengths represent the duration of time that the server remained in that state: -{{< figure src="/static/img/docs/state-timeline-panel/state-timeline-panel.png" max-width="1025px" alt="A state timeline visualization showing CPU usage" >}} +![A state timeline visualization showing CPU usage](/media/docs/grafana/panels-visualizations/screenshot-state-timeline-v11.4.png) The state timeline visualization is useful when you need to monitor and analyze changes in states or statuses of various entities over time. You can use one when you need to: @@ -58,11 +58,9 @@ The state timeline visualization works best if you have data capturing the vario Each state ends when the next state begins or when there is a `null` value. -### Examples +### Example 1 -The following tables are examples of the type of data you need for a state timeline visualization and how it should be formatted. - -#### Single time column with null values +The following example has a single time column and includes null values: | Timestamps | Server A | Server B | | ------------------- | -------- | -------- | @@ -76,11 +74,13 @@ The following tables are examples of the type of data you need for a state timel | 2024-02-29 10:00:00 | Down | Down | | 2024-02-29 10:30:00 | Warning | Down | -The data is converted as follows, with the [null and empty values visualized as gaps](https://grafana.com/docs/grafana/latest/panels-visualizations/visualizations/state-timeline/#connect-null-values) in the state timeline: +The data is converted as follows, with the [null and empty values visualized as gaps](#connect-null-values) in the state timeline: {{< figure src="/static/img/docs/state-timeline-panel/state-timeline-with-null-values.png" max-width="1025px" alt="A state timeline visualization with null values showing the status of two servers" >}} -#### Two time columns without null values +### Example 2 + +The following example has two time columns and doesn't include any null values: | Start time | End time | Server A | Server B | | ------------------- | ------------------- | -------- | -------- | @@ -97,74 +97,77 @@ The data is converted as follows: If your query results aren't in a table format like the preceding examples, especially for time-series data, you can apply specific [transformations](https://stackoverflow.com/questions/68887416/grafana-state-timeline-panel-with-values-states-supplied-by-label) to achieve this. -## Panel options +### Time series data + +You can also create a state timeline visualization using time series data. To do this, add [thresholds](#thresholds), which turn the time series into discrete colored state regions. + +![State timeline with time series](/media/docs/grafana/panels-visualizations/screenshot-state-timeline-time-series-v11.4.png) + +## Configuration options + +{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="" >}} + +### Panel options {{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="" >}} -## State timeline options +### State timeline options Use these options to refine the visualization. -### Merge equal consecutive values + -Controls whether Grafana merges identical values if they are next to each other. +| Option | Description | +| ------ | ----------------------------------------------------------------------------------------------- | +| Merge equal consecutive values | Controls whether Grafana merges identical values if they are next to each other. | +| Show values | Controls whether values are rendered inside the state regions. Choose from **Auto**, **Always**, and **Never**. **Auto** renders values if there is sufficient space. | +| Align values | Controls value alignment inside state regions. Choose from **Left**, **Center**, and **Right**. | +| Row height | Controls how much space between rows there are. 1 = no space = 0.5 = 50% space. | +| [Page size](#page-size-enable-pagination) | The **Page size** option lets you paginate the state timeline visualization to limit how many series are visible at once. | +| Line width | Controls line width of state regions. | +| Fill opacity | Controls value alignment inside state regions. | +| [Connect null values](#connect-null-values) | Choose how null values, which are gaps in the data, appear on the graph. | +| [Disconnect null values](#disconnect-values) | Choose whether to set a threshold above which values in the data should be disconnected. | -### Show values + -Controls whether values are rendered inside the state regions. Auto will render values if there is sufficient space. +{{< docs/shared lookup="visualizations/connect-null-values.md" source="grafana" version="" leveloffset="+1" >}} -### Align values +{{< docs/shared lookup="visualizations/disconnect-values.md" source="grafana" version="" leveloffset="+1" >}} -Controls value alignment inside state regions. +### Legend options -### Row height +{{< docs/shared lookup="visualizations/legend-options-2.md" source="grafana" version="" leveloffset="+1" >}} -Controls how much space between rows there are. 1 = no space = 0.5 = 50% space. +### Tooltip options -### Line width +Tooltip options control the information overlay that appears when you hover over data points in the visualization. -Controls line width of state regions. +#### Tooltip mode -### Fill opacity +When you hover your cursor over the visualization, Grafana can display tooltips. Choose how tooltips behave. -Controls the opacity of state regions. +- **Single -** The hover tooltip shows only a single series, the one that you are hovering over on the visualization. +- **Hidden -** Do not display the tooltip when you interact with the visualization. -{{< docs/shared lookup="visualizations/connect-null-values.md" source="grafana" version="" >}} +Use an override to hide individual series from the tooltip. -{{< docs/shared lookup="visualizations/disconnect-values.md" source="grafana" version="" >}} - -## Time series data with thresholds - -The visualization can be used with time series data as well. In this case, the thresholds are used to turn the time series into discrete colored state regions. - -{{< figure src="/static/img/docs/v8/state_timeline_time_series.png" max-width="1025px" caption="state timeline with time series" >}} - -## Standard options +### Standard options {{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="" >}} -## Legend options - -{{< docs/shared lookup="visualizations/legend-options-2.md" source="grafana" version="" >}} - -## Tooltip options - -{{< docs/shared lookup="visualizations/tooltip-options-1.md" source="grafana" version="" >}} - -## Data links +### Data links {{< docs/shared lookup="visualizations/datalink-options.md" source="grafana" version="" >}} -## Value mappings +### Value mappings {{< docs/shared lookup="visualizations/value-mappings-options.md" source="grafana" version="" >}} -{{< figure src="/static/img/docs/v8/value_mappings_side_editor.png" max-width="300px" caption="Value mappings side editor" >}} - -## Thresholds +### Thresholds {{< docs/shared lookup="visualizations/thresholds-options-2.md" source="grafana" version="" >}} -## Field overrides +### Field overrides {{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="" >}}