diff --git a/content/v2.0/visualize-data/visualization-types/gauge.md b/content/v2.0/visualize-data/visualization-types/gauge.md index c09b7a67f..62380f824 100644 --- a/content/v2.0/visualize-data/visualization-types/gauge.md +++ b/content/v2.0/visualize-data/visualization-types/gauge.md @@ -11,14 +11,25 @@ menu: parent: Visualization types --- -The **Gauge** view displays the single value most recent value for a time series in a gauge view. +The **Gauge** visualization displays the most recent value for a time series in a gauge. {{< img-hd src="/img/2-0-visualizations-gauge-example.png" alt="Gauge example" />}} -To select this view, select the **Gauge** option from the visualization dropdown in the upper right. +Select the **Gauge** option from the visualization dropdown in the upper right. -#### Gauge Controls +## Gauge behavior +The gauge visualization displays a single numeric data point within a defined spectrum (_default is 0-100_). +It uses the latest point in the first table (or series) returned by the query. +{{% note %}} +#### Queries should return one table +Flux does not guarantee the order in which tables are returned. +If a query returns multiple tables (or series), the table order can change between query executions +and result in the Gauge displaying inconsistent data. +For consistent results, the Gauge query should return a single table. +{{% /note %}} + +## Gauge Controls To view **Gauge** controls, click the settings icon ({{< icon "gear" >}}) next to the visualization dropdown in the upper right. @@ -32,3 +43,25 @@ the visualization dropdown in the upper right. - **Add a Threshold**: Change the color of the gauge based on the current value. - **Value is**: Enter the value at which the gauge should appear in the selected color. Choose a color from the dropdown menu next to the value. + +## Gauge examples +Gauge visualizations are useful for showing the current value of a metric and displaying +where it falls within a spectrum. + +### Steam pressure gauge +The following example queries sensor data that tracks the pressure of steam pipes +in a facility and displays it as a gauge. + +###### Query pressure data from a specific sensor +```js +from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => + r._measurement == "steam-sensors" and + r._field == "psi" + r.sensorID == "a211i" + ) +``` + +###### Visualization options for pressure gauge +{{< img-hd src="/img/2-0-visualizations-guage-pressure.jpg" alt="Pressure guage example" />}} diff --git a/content/v2.0/visualize-data/visualization-types/graph-single-stat.md b/content/v2.0/visualize-data/visualization-types/graph-single-stat.md index c9970e6b8..0c22695f9 100644 --- a/content/v2.0/visualize-data/visualization-types/graph-single-stat.md +++ b/content/v2.0/visualize-data/visualization-types/graph-single-stat.md @@ -10,6 +10,9 @@ menu: v2_0: name: Graph + Single Stat parent: Visualization types +related: + - /v2.0/visualize-data/visualization-types/graph + - /v2.0/visualize-data/visualization-types/single-stat --- The **Graph + Single Stat** view displays the specified time series in a line graph @@ -17,11 +20,24 @@ and overlays the single most recent value as a large numeric value. {{< img-hd src="/img/2-0-visualizations-line-graph-single-stat-example.png" alt="Line Graph + Single Stat example" />}} -To select this view, select the **Graph + Single Stat** option from the visualization -dropdown in the upper right. +Select the **Graph + Single Stat** option from the visualization dropdown in the upper right. -#### Graph + Single Stat Controls +## Graph + Single Stat behavior +The Graph visualization color codes each table (or series) in the queried data set. +When multiple series are present, it automatically assigns colors based on the selected [Line Colors option](#options). +The Single Stat visualization displays a single numeric data point. +It uses the latest point in the first table (or series) returned by the query. + +{{% note %}} +#### Queries should return one table +Flux does not guarantee the order in which tables are returned. +If a query returns multiple tables (or series), the table order can change between query executions +and result in the Single Stat visualization displaying inconsistent data. +For consistent Single Stat results, the query should return a single table. +{{% /note %}} + +## Graph + Single Stat Controls To view **Graph + Single Stat** controls, click the settings icon ({{< icon "gear" >}}) next to the visualization dropdown in the upper right. @@ -56,3 +72,22 @@ next to the visualization dropdown in the upper right. Choose a color from the dropdown menu next to the value. - **Colorization**: Choose **Text** for the single stat to change color based on the configured thresholds. Choose **Background** for the background of the graph to change color based on the configured thresholds. + +## Graph + Single Stat examples +The primary use case for the Graph + Single Stat visualization is to show the current or latest +value as well as historical values. + +### Show current value and historical values +The following example shows the current percentage of memory used as well as memory usage over time: + +###### Query memory usage percentage +```js +from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) +``` +###### Memory usage visualization +{{< img-hd src="/img/2-0-visualizations-graph-single-stat-mem.jpg" alt="Graph + Single Stat Memory Usage Example" />}} diff --git a/content/v2.0/visualize-data/visualization-types/graph.md b/content/v2.0/visualize-data/visualization-types/graph.md index 40fdab435..d5af696a9 100644 --- a/content/v2.0/visualize-data/visualization-types/graph.md +++ b/content/v2.0/visualize-data/visualization-types/graph.md @@ -11,15 +11,20 @@ menu: parent: Visualization types --- -There are several types of graphs you can create. - -To select this view, select the **Graph** option from the visualization dropdown -in the upper right. +The Graph visualization provides several types of graphs, each configured through +the [Graph options](#graph-options). {{< img-hd src="/img/2-0-visualizations-line-graph-example.png" alt="Line Graph example" />}} -#### Graph controls +Select the **Graph** option from the visualization dropdown in the upper right. +## Graph behavior +The Graph visualization color codes each table (or series) in the queried data set. +When multiple series are present, it automatically assigns colors based on the selected [Line Colors option](#options). + +When using a line graph, all points within a single table are connected. When multiple series are present, it automatically assigns colors based on the selected [Line Colors option](#options). + +## Graph controls To view **Graph** controls, click the settings icon ({{< icon "gear" >}}) next to the visualization dropdown in the upper right. @@ -47,22 +52,19 @@ to the visualization dropdown in the upper right. - **Min**: Minimum y-axis value. - **Max**: Maximum y-axis value. -##### Graph with linear interpolation +## Graph Examples +##### Graph with linear interpolation {{< img-hd src="/img/2-0-visualizations-line-graph-example.png" alt="Line Graph example" />}} ##### Graph with smooth interpolation - {{< img-hd src="/img/2-0-visualizations-line-graph-smooth-example.png" alt="Step-Plot Graph example" />}} ##### Graph with step interpolation - {{< img-hd src="/img/2-0-visualizations-line-graph-step-example.png" alt="Step-Plot Graph example" />}} diff --git a/content/v2.0/visualize-data/visualization-types/heatmap.md b/content/v2.0/visualize-data/visualization-types/heatmap.md index ba7bbbe20..755d6b1de 100644 --- a/content/v2.0/visualize-data/visualization-types/heatmap.md +++ b/content/v2.0/visualize-data/visualization-types/heatmap.md @@ -10,6 +10,8 @@ menu: v2_0: name: Heatmap parent: Visualization types +related: + - /v2.0/visualize-data/visualization-types/scatter --- A **Heatmap** displays the distribution of data on an x and y axes where color @@ -17,10 +19,16 @@ represents different concentrations of data points. {{< img-hd src="/img/2-0-visualizations-heatmap-example.png" alt="Heatmap example" />}} -To select this view, select the **Heatmap** option from the visualization dropdown in the upper right. +Select the **Heatmap** option from the visualization dropdown in the upper right. -#### Heatmap Controls +## Heatmap behavior +Heatmaps divide data points into "bins" – segments of the visualization with upper +and lower bounds for both [X and Y axes](#data). +The [Bin Size option](#options) determines the bounds for each bin. +The total number of points that fall within a bin determine the its value and color. +Warmer or brighter colors represent higher bin values or density of points within the bin. +## Heatmap Controls To view **Heatmap** controls, click the settings icon ({{< icon "gear" >}}) next to the visualization dropdown in the upper right. @@ -51,3 +59,57 @@ next to the visualization dropdown in the upper right. - **Custom**: Manually specify the value range of the y-axis. - **Min**: Minimum y-axis value. - **Max**: Maximum y-axis value. + +## Heatmap examples + +### Cross-measurement correlation +The following example explores possible correlation between CPU and Memory usage. +It uses data collected with the Telegraf [Mem](/v2.0/reference/telegraf-plugins/#mem) +and [CPU](/v2.0/reference/telegraf-plugins/#cpu) input plugins. + +###### Join CPU and memory usage +The following query joins CPU and memory usage on `_time`. +Each row in the output table contains `_value_cpu` and `_value_mem` columns. + +```js +cpu = from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) + +mem = from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + +join(tables: {cpu: cpu, mem: mem}, on: ["_time"], method: "inner") +``` + +###### Use a heatmap to visualize correlation +In the Heatmap visualization controls, `_value_cpu` is selected as the [X Column](#data) +and `_value_mem` is selected as the [Y Column](#data). +The domain for each axis is also customized to account for the scale difference +between column values. + +{{< img-hd src="/img/2-0-visualizations-heatmap-correlation.jpg" alt="Heatmap correlation example" />}} + + +## Important notes + +### Differences between a heatmap and a scatter plot +Heatmaps and [Scatter plots](/v2.0/visualize-data/visualization-types/scatter/) +both visualize the distribution of data points on X and Y axes. +However, in certain cases, heatmaps provide better visibility into point density. + +For example, the dashboard cells below visualize the same query results: + +{{< img-hd src="/img/2-0-visualizations-heatmap-vs-scatter.jpg" alt="Heatmap vs Scatter plot" />}} + +The heatmap indicates isolated high point density, which isn't visible in the scatter plot. +In the scatter plot visualization, points that share the same X and Y coordinates +appear as a single point. diff --git a/content/v2.0/visualize-data/visualization-types/histogram.md b/content/v2.0/visualize-data/visualization-types/histogram.md index c5abef006..3843778f4 100644 --- a/content/v2.0/visualize-data/visualization-types/histogram.md +++ b/content/v2.0/visualize-data/visualization-types/histogram.md @@ -3,7 +3,7 @@ title: Histogram visualization list_title: Histogram list_image: /img/2-0-visualizations-histogram-example.png description: > - A histogram is a way to view the distribution of data. Unlike column charts, histograms have no time axis. + A histogram is a way to view the distribution of data. The y-axis is dedicated to count, and the x-axis is divided into bins. weight: 204 menu: @@ -12,20 +12,32 @@ menu: parent: Visualization types --- -A histogram is a way to view the distribution of data. Unlike column charts, histograms have no time axis. -The y-axis is dedicated to count, and the x-axis is divided into bins. +A histogram is a way to view the distribution of data. +The y-axis is dedicated to count, and the X-axis is divided into bins. {{< img-hd src="/img/2-0-visualizations-histogram-example.png" alt="Histogram example" />}} -To select this view, select the **Histogram** option from the visualization dropdown in the upper right. +Select the **Histogram** option from the visualization dropdown in the upper right. -#### Histogram Controls +## Histogram behavior +The Histogram visualization is a bar graph that displays the number of data points +that fall within "bins" – segments of the X axis with upper and lower bounds. +Bin thresholds are determined by dividing the width of the X axis by the number +of bins set using the [Bins option](#options). +Data within bins can be further grouped or segmented by selecting columns in the +[Group By option](#options). +{{% note %}} +The Histogram visualization automatically bins, segments, and counts data. +To work properly, query results **should not** be structured as histogram data. +{{% /note %}} + +## Histogram Controls To view **Histogram** controls, click the settings icon ({{< icon "gear" >}}) next to the visualization dropdown in the upper right. ###### Data -- **Column**: The column to select data from. +- **X Column**: The column to select data from. - **Group By**: The column to group by. ###### Options @@ -43,3 +55,26 @@ to the visualization dropdown in the upper right. - **Custom**: Manually specify the value range of the x-axis. - **Min**: Minimum x-axis value. - **Max**: Maximum x-axis value. + +## Histogram examples + +### View error counts by severity over time +The following example uses the Histogram visualization to show the number of errors +"binned" by time and segmented by severity. +_It utilizes data from the [Telegraf Syslog plugin](/v2.0/reference/telegraf-plugins/#syslog)._ + +##### Query for errors by severity code +```js +from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "syslog" and + r._field == "severity_code" + ) +``` + +##### Histogram settings +In the Histogram visualization options, select `_time` as the [X Column](#data) +and `severity` as the [Group By](#data) option: + +{{< img-hd src="/img/2-0-visualizations-histogram-errors.jpg" alt="Errors histogram" />}} diff --git a/content/v2.0/visualize-data/visualization-types/scatter.md b/content/v2.0/visualize-data/visualization-types/scatter.md index 886b99f7f..bd45cdbef 100644 --- a/content/v2.0/visualize-data/visualization-types/scatter.md +++ b/content/v2.0/visualize-data/visualization-types/scatter.md @@ -9,21 +9,30 @@ menu: v2_0: name: Scatter parent: Visualization types +related: + - /v2.0/visualize-data/visualization-types/heatmap --- The **Scatter** view uses a scatter plot to display time series data. {{< img-hd src="/img/2-0-visualizations-scatter-example.png" alt="Scatter plot example" />}} -To select this view, select the **Scatter** option from the visualization dropdown in the upper right. +Select the **Scatter** option from the visualization dropdown in the upper right. -#### Scatter controls +## Scatter behavior +The scatter visualization maps each data point to X and Y coordinates. +X and Y axes are specified with the [X Column](#data) and [Y Column](#data) visualization options. +Each unique series is differentiated using fill colors and symbols. +Use the [Symbol Column](#data) and [Fill Column](#data) options to select columns +used to differentiate points in the visualization. + +## Scatter controls To view **Scatter** controls, click the settings icon ({{< icon "gear" >}}) next to the visualization dropdown in the upper right. ###### Data -- **Symbol column**: Define a column containing values that should be differentiated with symbols. -- **Fill column**: Define a column containing values that should be differentiated with fill color. +- **Symbol Column**: Define a column containing values that should be differentiated with symbols. +- **Fill Column**: Define a column containing values that should be differentiated with fill color. - **X Column**: Select a column to display on the x-axis. - **Y Column**: Select a column to display on the y-axis. @@ -42,3 +51,59 @@ to the visualization dropdown in the upper right. - **Custom**: Manually specify the value range of the y-axis. - **Min**: Minimum y-axis value. - **Max**: Maximum y-axis value. + +## Scatter examples + +### Cross-measurement correlation +The following example explores possible correlation between CPU and Memory usage. +It uses data collected with the Telegraf [Mem](/v2.0/reference/telegraf-plugins/#mem) +and [CPU](/v2.0/reference/telegraf-plugins/#cpu) input plugins. + +###### Query CPU and memory usage +The following query creates a union of CPU and memory usage. +It scales the CPU usage metric to better align with baseline memory usage. + +```js +cpu = from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) + // Scale CPU usage + |> map(fn: (r) => ({ + _value: r._value + 60.0, + _time: r._time + }) + ) + +mem = from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + +union(tables: [cpu, mem]) +``` + +###### Use a scatter plot to visualize correlation +In the Scatter visualization controls, points are differentiated based on their group keys. + +{{< img-hd src="/img/2-0-visualizations-scatter-correlation.jpg" alt="Heatmap correlation example" />}} + +## Important notes + +### Differences between a scatter plot and a heatmap +Scatter plots and [Heatmaps](/v2.0/visualize-data/visualization-types/heatmap/) +both visualize the distribution of data points on X and Y axes. +However, in certain cases, scatterplots can "hide" points if they share the same X and Y coordinates. + +For example, the dashboard cells below visualize the same query results: + +{{< img-hd src="/img/2-0-visualizations-heatmap-vs-scatter.jpg" alt="Heatmap vs Scatter plot" />}} + +The heatmap indicates isolated high point density, which isn't visible in the scatter plot. +In the scatter plot visualization, points that share the same X and Y coordinates +appear as a single point. diff --git a/content/v2.0/visualize-data/visualization-types/single-stat.md b/content/v2.0/visualize-data/visualization-types/single-stat.md index f5dafc906..ed70c9e01 100644 --- a/content/v2.0/visualize-data/visualization-types/single-stat.md +++ b/content/v2.0/visualize-data/visualization-types/single-stat.md @@ -15,10 +15,21 @@ The **Single Stat** view displays the most recent value of the specified time se {{< img-hd src="/img/2-0-visualizations-single-stat-example.png" alt="Single stat example" />}} -To select this view, select the **Single Stat** option from the visualization dropdown in the upper right. +Select the **Single Stat** option from the visualization dropdown in the upper right. -#### Single Stat Controls +## Single Stat behavior +The Single Stat visualization displays a single numeric data point. +It uses the latest point in the first table (or series) returned by the query. +{{% note %}} +#### Queries should return one table +Flux does not guarantee the order in which tables are returned. +If a query returns multiple tables (or series), the table order can change between query executions +and result in the Single Stat visualization displaying inconsistent data. +For consistent results, the Single Stat query should return a single table. +{{% /note %}} + +## Single Stat Controls To view **Single Stat** controls, click the settings icon ({{< icon "gear" >}}) next to the visualization dropdown in the upper right. @@ -34,3 +45,21 @@ next to the visualization dropdown in the upper right. Choose a color from the dropdown menu next to the value. - **Colorization**: Choose **Text** for the single stat to change color based on the configured thresholds. Choose **Background** for the background of the graph to change color based on the configured thresholds. + +## Single Stat examples + +### Show human-readable current value +The following example shows the current memory usage displayed has a human-readable percentage: + +###### Query memory usage percentage +```js +from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) +``` + +###### Memory usage as a single stat +{{< img-hd src="/img/2-0-visualizations-single-stat-memor.jpg" alt="Graph + Single Stat Memory Usage Example" />}} diff --git a/content/v2.0/visualize-data/visualization-types/table.md b/content/v2.0/visualize-data/visualization-types/table.md index 3449c2bb1..9af961887 100644 --- a/content/v2.0/visualize-data/visualization-types/table.md +++ b/content/v2.0/visualize-data/visualization-types/table.md @@ -1,6 +1,6 @@ --- title: Table visualization -list_title: Single stat +list_title: Table list_image: /img/2-0-visualizations-table-example.png description: > The Table option displays the results of queries in a tabular view, which is @@ -17,10 +17,16 @@ sometimes easier to analyze than graph views of data. {{< img-hd src="/img/2-0-visualizations-table-example.png" alt="Table example" />}} -To select this view, select the **Table** option from the visualization dropdown in the upper right. +Select the **Table** option from the visualization dropdown in the upper right. -#### Table Controls +## Table behavior +The table visualization renders queried data in structured, easy-to-read tables. +Columns and rows match those in the query output. +If query results contain multiple tables, only one table is shown at a time. +Select other output tables in the far left column of the table visualization. +Tables are identified by their [group key](/v2.0/query-data/get-started/#group-keys). +## Table Controls To view **Table** controls, click the settings icon ({{< icon "gear" >}}) next to the visualization dropdown in the upper right. @@ -51,3 +57,27 @@ the visualization dropdown in the upper right. - **Add a Threshold**: Change the color of the table based on the current value. - **Value is**: Enter the value at which the table should appear in the selected color. Choose a color from the dropdown menu next to the value. + +## Table examples +Tables are helpful when displaying many human-readable metrics in a dashboard +such as cluster statistics or log messages. + +### Human-readable cluster metrics +The following example queries the latest reported memory usage from a cluster of servers. + +###### Query the latest memory usage from each host +```js +from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + |> group(columns: ["host"]) + |> last() + |> group() + |> keep(columns: ["_value", "host"]) +``` + +###### Cluster metrics in a table +{{< img-hd src="/img/2-0-visualizations-table-human-readable.jpg" alt="Human readable metrics in a table" />}} diff --git a/static/img/2-0-visualizations-graph-single-stat-mem.jpg b/static/img/2-0-visualizations-graph-single-stat-mem.jpg new file mode 100644 index 000000000..1b66d2b93 Binary files /dev/null and b/static/img/2-0-visualizations-graph-single-stat-mem.jpg differ diff --git a/static/img/2-0-visualizations-guage-pressure.jpg b/static/img/2-0-visualizations-guage-pressure.jpg new file mode 100644 index 000000000..85a6f8aa7 Binary files /dev/null and b/static/img/2-0-visualizations-guage-pressure.jpg differ diff --git a/static/img/2-0-visualizations-heatmap-correlation.jpg b/static/img/2-0-visualizations-heatmap-correlation.jpg new file mode 100644 index 000000000..4f8b5369f Binary files /dev/null and b/static/img/2-0-visualizations-heatmap-correlation.jpg differ diff --git a/static/img/2-0-visualizations-heatmap-vs-scatter.jpg b/static/img/2-0-visualizations-heatmap-vs-scatter.jpg new file mode 100644 index 000000000..35ecfc820 Binary files /dev/null and b/static/img/2-0-visualizations-heatmap-vs-scatter.jpg differ diff --git a/static/img/2-0-visualizations-histogram-errors.jpg b/static/img/2-0-visualizations-histogram-errors.jpg new file mode 100644 index 000000000..74ee02f6a Binary files /dev/null and b/static/img/2-0-visualizations-histogram-errors.jpg differ diff --git a/static/img/2-0-visualizations-scatter-correlation.jpg b/static/img/2-0-visualizations-scatter-correlation.jpg new file mode 100644 index 000000000..9f7cd81bc Binary files /dev/null and b/static/img/2-0-visualizations-scatter-correlation.jpg differ diff --git a/static/img/2-0-visualizations-single-stat-memor.jpg b/static/img/2-0-visualizations-single-stat-memor.jpg new file mode 100644 index 000000000..852dd5e26 Binary files /dev/null and b/static/img/2-0-visualizations-single-stat-memor.jpg differ diff --git a/static/img/2-0-visualizations-table-human-readable.jpg b/static/img/2-0-visualizations-table-human-readable.jpg new file mode 100644 index 000000000..245b0bae5 Binary files /dev/null and b/static/img/2-0-visualizations-table-human-readable.jpg differ