Learn the basics of using Grafana.
- }}" class="nav-cards__item nav-cards__item--guide"> -Learn basic observability.
}}" class="nav-cards__item nav-cards__item--guide">Review the configuration and setup options.
- }}" class="nav-cards__item nav-cards__item--guide"> + }}" class="nav-cards__item nav-cards__item--guide">Learn about time series data.
diff --git a/docs/sources/basics/exemplars/_index.md b/docs/sources/basics/exemplars/_index.md deleted file mode 100644 index d11ae5ca917..00000000000 --- a/docs/sources/basics/exemplars/_index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -aliases: - - /docs/grafana/latest/basics/exemplars/ -description: Exemplars -keywords: - - grafana - - concepts - - exemplars - - prometheus -title: Exemplars -weight: 400 ---- - -# Introduction to exemplars - -An exemplar is a specific trace representative of measurement taken in a given time interval. While metrics excel at giving you an aggregated view of your system, traces give you a fine grained view of a single request; exemplars are a way to link the two. - -Suppose your company website is experiencing a surge in traffic volumes. While more than eighty percent of the users are able to access the website in under two seconds, some users are experiencing a higher than normal response time resulting in bad user experience. - -To identify the factors that are contributing to the latency, you must compare a trace for a fast response against a trace for a slow response. Given the vast amount of data in a typical production environment, it will be extremely laborious and time-consuming effort. - -Use exemplars to help isolate problems within your data distribution by pinpointing query traces exhibiting high latency within a time interval. Once you localize the latency problem to a few exemplar traces, you can combine it with additional system based information or location properties to perform a root cause analysis faster, leading to quick resolutions to performance issues. - -Support for exemplars is available for the Prometheus data source only. Once you enable the functionality, exemplars data is available by default. For more information on exemplar configuration and how to enable exemplars, refer to [configuring exemplars in Prometheus data source]({{< relref "../../datasources/prometheus/#configuring-exemplars" >}}). - -Grafana shows exemplars alongside a metric in the Explore view and in dashboards. Each exemplar displays as a highlighted star. You can hover your cursor over an exemplar to view the unique traceID, which is a combination of a key value pair. To investigate further, click the blue button next to the `traceID` property. - -{{< figure src="/static/img/docs/v74/exemplars.png" class="docs-image--no-shadow" max-width= "750px" caption="Screenshot showing the detail window of an Exemplar" >}} - -Refer to [View exemplar data]({{< relref "view-exemplars/" >}}) for instructions on how to drill down and view exemplar trace details from metrics and logs. To know more about exemplars, refer to the blogpost [Intro to exemplars, which enable Grafana Tempo’s distributed tracing at massive scale](https://grafana.com/blog/2021/03/31/intro-to-exemplars-which-enable-grafana-tempos-distributed-tracing-at-massive-scale/). diff --git a/docs/sources/developers/plugins/data-frames.md b/docs/sources/developers/plugins/data-frames.md index d9eb7bfb96e..ceaed7b90c4 100644 --- a/docs/sources/developers/plugins/data-frames.md +++ b/docs/sources/developers/plugins/data-frames.md @@ -74,7 +74,7 @@ A data transformation is any function that accepts a data frame as input, and re A data frame with at least one time field is considered a _time series_. -For more information on time series, refer to our [Introduction to time series]({{< relref "../../basics/timeseries/" >}}). +For more information on time series, refer to our [Introduction to time series]({{< relref "../../fundamentals/timeseries/" >}}). ### Wide format diff --git a/docs/sources/basics/_index.md b/docs/sources/fundamentals/_index.md similarity index 82% rename from docs/sources/basics/_index.md rename to docs/sources/fundamentals/_index.md index 2c67abb9305..6637aa7cbd7 100644 --- a/docs/sources/basics/_index.md +++ b/docs/sources/fundamentals/_index.md @@ -1,11 +1,12 @@ --- aliases: - /docs/grafana/latest/basics/ -title: Grafana basics -weight: 15 + - /docs/grafana/latest/fundamentals/ +title: Fundamentals +weight: 8 --- -# Grafana basics +# Fundamentals This section provides basic information about observability topics in general and Grafana in particular. These topics will help people who are just starting out with observability and monitoring. diff --git a/docs/sources/basics/exemplars/view-exemplars.md b/docs/sources/fundamentals/exemplars/index.md similarity index 62% rename from docs/sources/basics/exemplars/view-exemplars.md rename to docs/sources/fundamentals/exemplars/index.md index 0aa4ba68816..55615d34665 100644 --- a/docs/sources/basics/exemplars/view-exemplars.md +++ b/docs/sources/fundamentals/exemplars/index.md @@ -1,21 +1,41 @@ --- aliases: + - /docs/grafana/latest/basics/exemplars/ - /docs/grafana/latest/basics/exemplars/view-exemplars/ + - /docs/grafana/latest/fundamentals/exemplars/ description: Exemplars keywords: - grafana - concepts - exemplars - prometheus -title: View exemplar data +title: Exemplars weight: 400 --- -# View exemplar data +# Introduction to exemplars + +An exemplar is a specific trace representative of measurement taken in a given time interval. While metrics excel at giving you an aggregated view of your system, traces give you a fine grained view of a single request; exemplars are a way to link the two. + +Suppose your company website is experiencing a surge in traffic volumes. While more than eighty percent of the users are able to access the website in under two seconds, some users are experiencing a higher than normal response time resulting in bad user experience. + +To identify the factors that are contributing to the latency, you must compare a trace for a fast response against a trace for a slow response. Given the vast amount of data in a typical production environment, it will be extremely laborious and time-consuming effort. + +Use exemplars to help isolate problems within your data distribution by pinpointing query traces exhibiting high latency within a time interval. Once you localize the latency problem to a few exemplar traces, you can combine it with additional system based information or location properties to perform a root cause analysis faster, leading to quick resolutions to performance issues. + +Support for exemplars is available for the Prometheus data source only. Once you enable the functionality, exemplars data is available by default. For more information on exemplar configuration and how to enable exemplars, refer to [configuring exemplars in Prometheus data source]({{< relref "../../datasources/prometheus/#configuring-exemplars" >}}). + +Grafana shows exemplars alongside a metric in the Explore view and in dashboards. Each exemplar displays as a highlighted star. You can hover your cursor over an exemplar to view the unique traceID, which is a combination of a key value pair. To investigate further, click the blue button next to the `traceID` property. + +{{< figure src="/static/img/docs/v74/exemplars.png" class="docs-image--no-shadow" max-width= "750px" caption="Screenshot showing the detail window of an Exemplar" >}} + +Refer to [View exemplar data]({{< relref "#view-exemplar-data" >}}) for instructions on how to drill down and view exemplar trace details from metrics and logs. To know more about exemplars, refer to the blogpost [Intro to exemplars, which enable Grafana Tempo’s distributed tracing at massive scale](https://grafana.com/blog/2021/03/31/intro-to-exemplars-which-enable-grafana-tempos-distributed-tracing-at-massive-scale/). + +## View exemplar data When support for exemplar support is enabled for a Prometheus data source, you can view exemplar data either in the Explore view or from the Loki log details. -## In Explore +### In Explore Explore visualizes exemplar traces as highlighted stars alongside metrics data. For more information on how Explore visualizes trace data, refer to [Tracing in Explore]({{< relref "../../explore/trace-integration/" >}}). @@ -31,7 +51,7 @@ To examine the details of an exemplar trace: For more information on how to drill down and analyze the trace and span details, refer to the [Analyze trace and span details](#analyze-trace-and-spans) section. -## In logs +### In logs You can also view exemplar trace details from the Loki logs in Explore. Use regex within the Derived fields links for Loki to extract the `traceID` information. Now when you expand Loki logs, you can see a `traceID` property under the **Detected fields** section. To learn more about how to extract a part of a log message into an internal or external link, refer to [using derived fields in Loki]({{< relref "../../explore/logs-integration/" >}}). @@ -45,7 +65,7 @@ To view the details of an exemplar trace: For more information on how to drill down and analyze the trace and span details, refer to the [Analyze trace and span details](#analyze-trace-and-spans) section. -## Analyze trace and spans +### Analyze trace and spans This panel shows the details of the trace in different segments. diff --git a/docs/sources/basics/glossary.md b/docs/sources/fundamentals/glossary/index.md similarity index 99% rename from docs/sources/basics/glossary.md rename to docs/sources/fundamentals/glossary/index.md index 1fd9828ed8a..f7192b86aea 100644 --- a/docs/sources/basics/glossary.md +++ b/docs/sources/fundamentals/glossary/index.md @@ -3,6 +3,7 @@ aliases: - /docs/grafana/latest/basics/glossary/ - /docs/grafana/latest/getting-started/glossary/ - /docs/grafana/latest/guides/glossary/ + - /docs/grafana/latest/fundamentals/glossary/ description: Grafana glossary keywords: - grafana diff --git a/docs/sources/basics/intro-histograms.md b/docs/sources/fundamentals/intro-histograms/index.md similarity index 93% rename from docs/sources/basics/intro-histograms.md rename to docs/sources/fundamentals/intro-histograms/index.md index 4e82edc7c37..0164a439bb5 100644 --- a/docs/sources/basics/intro-histograms.md +++ b/docs/sources/fundamentals/intro-histograms/index.md @@ -2,6 +2,7 @@ aliases: - /docs/grafana/latest/basics/intro-histograms/ - /docs/grafana/latest/getting-started/intro-histograms/ + - /docs/grafana/latest/fundamentals/intro-histograms/ description: An introduction to histograms and heatmaps keywords: - grafana @@ -32,7 +33,7 @@ Here is an example showing height distribution of people. {{< figure src="/static/img/docs/histogram-panel/histogram-example-v8-0.png" max-width="625px" caption="Bar chart example" >}} -For more information about histogram visualization options, refer to [Histogram]({{< relref "../panels-visualizations/visualizations/histogram/" >}}). +For more information about histogram visualization options, refer to [Histogram]({{< relref "../../panels-visualizations/visualizations/histogram/" >}}). Histograms only look at _value distributions_ over a specific time range. The problem with histograms is that you cannot see any trends or changes in the distribution over time. This is where heatmaps become useful. @@ -44,7 +45,7 @@ In this example, you can clearly see what values are more common and how they tr  -For more information about heatmap visualization options, refer to [Heatmap]({{< relref "../panels-visualizations/visualizations//heatmap/" >}}). +For more information about heatmap visualization options, refer to [Heatmap]({{< relref "../../panels-visualizations/visualizations/heatmap/" >}}). ## Pre-bucketed data diff --git a/docs/sources/basics/timeseries-dimensions.md b/docs/sources/fundamentals/timeseries-dimensions/index.md similarity index 96% rename from docs/sources/basics/timeseries-dimensions.md rename to docs/sources/fundamentals/timeseries-dimensions/index.md index af607ae0456..2eb878687e3 100644 --- a/docs/sources/basics/timeseries-dimensions.md +++ b/docs/sources/fundamentals/timeseries-dimensions/index.md @@ -3,6 +3,7 @@ aliases: - /docs/grafana/latest/basics/timeseries-dimensions/ - /docs/grafana/latest/getting-started/timeseries-dimensions/ - /docs/grafana/latest/guides/timeseries-dimensions/ + - /docs/rafana/latest/fundamentals/timeseries-dimensions/ description: time series dimensions keywords: - grafana @@ -91,4 +92,4 @@ In this case the labels that represent the dimensions will have two keys based o In the case of SQL-like data sources, more than one numeric column can be selected, with or without additional string columns to be used as dimensions. For example, `AVG(Temperature) AS AvgTemp, MAX(Temperature) AS MaxTemp`. This, if combined with multiple dimensions, can result in a lot of series. Selecting multiple values is currently only designed to be used with visualization. -Additional technical information on tabular time series formats and how dimensions are extracted can be found in [the developer documentation on data frames as time series]({{< relref "../developers/plugins/data-frames/#data-frames-as-time-series" >}}). +Additional technical information on tabular time series formats and how dimensions are extracted can be found in [the developer documentation on data frames as time series]({{< relref "../../developers/plugins/data-frames/#data-frames-as-time-series" >}}). diff --git a/docs/sources/basics/timeseries.md b/docs/sources/fundamentals/timeseries/index.md similarity index 99% rename from docs/sources/basics/timeseries.md rename to docs/sources/fundamentals/timeseries/index.md index a9f61abe6a6..56cedfd48a4 100644 --- a/docs/sources/basics/timeseries.md +++ b/docs/sources/fundamentals/timeseries/index.md @@ -1,6 +1,7 @@ --- aliases: - /docs/grafana/latest/basics/timeseries/ + - /docs/grafana/latest/fundamentals/timeseries/ description: Introduction to time series keywords: - grafana diff --git a/docs/sources/getting-started/_index.md b/docs/sources/getting-started/_index.md index 9248619cfcf..9b887f3adea 100644 --- a/docs/sources/getting-started/_index.md +++ b/docs/sources/getting-started/_index.md @@ -3,7 +3,7 @@ aliases: - /docs/grafana/latest/getting-started/ - /docs/grafana/latest/guides/what-is-grafana/ title: Get started -weight: 15 +weight: 9 --- # Get started diff --git a/docs/sources/panels-visualizations/query-transform-data/expression-queries/index.md b/docs/sources/panels-visualizations/query-transform-data/expression-queries/index.md index d869682229b..0da0dbfc22f 100644 --- a/docs/sources/panels-visualizations/query-transform-data/expression-queries/index.md +++ b/docs/sources/panels-visualizations/query-transform-data/expression-queries/index.md @@ -29,7 +29,7 @@ Expressions are meant to augment data sources by enabling queries from different > **Note:** When possible, you should do data processing inside the data source. Copying data from storage to the Grafana server for processing is inefficient, so expressions are targeted at lightweight data processing. -Expressions work with data source queries that return time series or number data. They also operate on [multiple-dimensional data]({{< relref "../../../basics/timeseries-dimensions/" >}}). For example, a query that returns multiple series, where each series is identified by labels or tags. +Expressions work with data source queries that return time series or number data. They also operate on [multiple-dimensional data]({{< relref "../../../fundamentals/timeseries-dimensions/" >}}). For example, a query that returns multiple series, where each series is identified by labels or tags. An individual expression takes one or more queries or other expressions as input and adds data to the result. Each individual expression or query is represented by a variable that is a named identifier known as its RefID (e.g., the default letter `A` or `B`). @@ -42,7 +42,7 @@ Expressions work with two types of data. - A collection of time series. - A collection of numbers, where each number is an item. -Each collection is returned from a single data source query or expression and represented by the RefID. Each collection is a set, where each item in the set is uniquely identified by its dimensions which are stored as [labels]({{< relref "../../../basics/timeseries-dimensions/#labels" >}}) or key-value pairs. +Each collection is returned from a single data source query or expression and represented by the RefID. Each collection is a set, where each item in the set is uniquely identified by its dimensions which are stored as [labels]({{< relref "../../../fundamentals/timeseries-dimensions/#labels" >}}) or key-value pairs. ### Data source queries diff --git a/docs/sources/panels-visualizations/visualizations/heatmap/index.md b/docs/sources/panels-visualizations/visualizations/heatmap/index.md index a806614d499..91302a2f8f9 100644 --- a/docs/sources/panels-visualizations/visualizations/heatmap/index.md +++ b/docs/sources/panels-visualizations/visualizations/heatmap/index.md @@ -15,7 +15,7 @@ weight: 600 # Heatmap -The Heatmap panel visualization allows you to view histograms over time. For more information about histograms, refer to [Introduction to histograms and heatmaps]({{< relref "../../../basics/intro-histograms/" >}}). +The Heatmap panel visualization allows you to view histograms over time. For more information about histograms, refer to [Introduction to histograms and heatmaps]({{< relref "../../../fundamentals/intro-histograms/" >}}).  diff --git a/docs/sources/whatsnew/whats-new-in-v7-4.md b/docs/sources/whatsnew/whats-new-in-v7-4.md index 150ca28004a..688805d0955 100644 --- a/docs/sources/whatsnew/whats-new-in-v7-4.md +++ b/docs/sources/whatsnew/whats-new-in-v7-4.md @@ -85,7 +85,7 @@ Grafana graphs now support Prometheus _exemplars_. They are displayed as diamond {{< figure src="/static/img/docs/v74/exemplars.png" max-width="900px" caption="Exemplar example" >}} -For more information, refer to [Exemplars]({{< relref "../datasources/prometheus/#exemplars" >}}). +For more information, refer to [Exemplars]({{< relref "../fundamentals/exemplars/" >}}). ### Trace to logs @@ -102,7 +102,7 @@ The following topics were updated as a result of this feature: _Server-side expressions_ is an experimental feature that allows you to manipulate data returned from backend data source queries. Expressions allow you to manipulate data with math and other operations when the data source is a backend data source or a **--Mixed--** data source. -The main use case is for [multi-dimensional]({{< relref "../basics/timeseries-dimensions/" >}}) data sources used with the upcoming next generation alerting, but expressions can be used with backend data sources and visualization as well. +The main use case is for [multi-dimensional]({{< relref "../fundamentals/timeseries-dimensions/" >}}) data sources used with the upcoming next generation alerting, but expressions can be used with backend data sources and visualization as well. > **Note:** Queries built with this feature might break with minor version upgrades until Grafana 8 is released. This feature does not work with the current Grafana Alerting. diff --git a/docs/sources/whatsnew/whats-new-in-v9-1.md b/docs/sources/whatsnew/whats-new-in-v9-1.md index cf298d211f4..f2b267a3b62 100644 --- a/docs/sources/whatsnew/whats-new-in-v9-1.md +++ b/docs/sources/whatsnew/whats-new-in-v9-1.md @@ -85,7 +85,7 @@ As part of the upcoming improvements to Grafana's navigation, you can now direct #### Heatmap improvements The beta heatmap announced in version 9.0 is now used throughout Grafana. -Its performance is improved, and it now supports [exemplars]({{< relref "../basics/exemplars/" >}}). +Its performance is improved, and it now supports [exemplars]({{< relref "../fundamentals/exemplars/" >}}). To learn more about the heatmap panel, see the [documentation]({{< relref "../panels-visualizations/visualizations/heatmap/" >}}). {{< figure src="/static/img/docs/panels/heatmap-panel-9-1.png" max-width="750px" caption="A heatmap panel" >}}