From ae3be459f0bc92883ffa269d2a60273a992f37e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Piotr=20Jamr=C3=B3z?= Date: Tue, 28 Mar 2023 21:53:17 +0200 Subject: [PATCH] Docs: Clean up Explore documentation (#64908) * Remove the info about custom Prometheus Query Editor as it's not relevant since #60020 * Update basic Explore documentation * Change graphs and tables to visualizations as Explore supports different types of visualization * Make clear "Starred" refers to a tab * Update how to select start/end date for query history * Remove Prometheus specific section as it's no longer relevant. Prometheus query editor is documented in https://grafana.com/docs/grafana/latest/datasources/prometheus/query-editor/#metrics-browser * Add informational log level (added in #30942) * Use more direct language * Fix a link * Make headers more consistent * Minor tweaks * Update docs/sources/explore/explore-inspector.md Co-authored-by: Eve Meelan <81647476+Eve832@users.noreply.github.com> * Do not enumerate bullet points * Fix incorrect header type * Update tracing headers * Link to more info about Mixed data source * Use "data source" instead of "datasource" * Fix tracing headers * Fix more log headers * Update docs/sources/explore/explore-inspector.md Co-authored-by: J Stickler --------- Co-authored-by: Eve Meelan <81647476+Eve832@users.noreply.github.com> Co-authored-by: J Stickler --- docs/sources/explore/_index.md | 12 ++++++--- docs/sources/explore/explore-inspector.md | 2 +- docs/sources/explore/logs-integration.md | 9 ++++--- docs/sources/explore/query-management.md | 30 ++--------------------- docs/sources/explore/trace-integration.md | 20 +++++++-------- 5 files changed, 26 insertions(+), 47 deletions(-) diff --git a/docs/sources/explore/_index.md b/docs/sources/explore/_index.md index 244628dfcc7..5cf8d1ee52a 100644 --- a/docs/sources/explore/_index.md +++ b/docs/sources/explore/_index.md @@ -44,12 +44,14 @@ To access Explore: {{< figure src="/static/img/docs/explore/panel_dropdown-7-4.png" class="docs-image--no-shadow" max-width= "650px" caption="Screenshot of the new Explore option in the panel menu" >}} -1. Choose your data source from the dropdown in the top left. [Prometheus](https://grafana.com/oss/prometheus/) has a custom Explore implementation, the other data sources use their standard query editor. -1. In the query field, write your query to explore your data. There are three buttons beside the query field, a clear button (X), an add query button (+) and the remove query button (-). Just like the normal query editor, you can add and remove multiple queries. +1. Choose your data source from the dropdown in the top left. +1. Write the query using a query editor provided by the selected data source. Please check [data sources documentation]({{< relref "../datasources" >}}) to see how to use various query editors. +1. For general documentation on querying data sources in Grafana, see [Query and transform data]({{< relref "../panels-visualizations/query-transform-data" >}}). +1. Run the query using the button in the top right corner. ## Split and compare -The split view provides an easy way to compare graphs and tables side-by-side or to look at related data together on one page. +The split view provides an easy way to compare visualizations side-by-side or to look at related data together on one page. To open the split view: @@ -73,4 +75,6 @@ The Share shortened link capability allows you to create smaller and simpler URL ### exploreMixedDatasource -Disabled by default, allows users in Explore to have different datasources for different queries. If compatible, results will be combined. +Disabled by default, allows users in Explore to have different data sources for different queries. If compatible, results will be combined. + +Learn more about how to use [Mixed data source]({{< relref "../datasources/#special-data-sources" >}}). diff --git a/docs/sources/explore/explore-inspector.md b/docs/sources/explore/explore-inspector.md index c0d57bc5e4f..261d9e543c4 100644 --- a/docs/sources/explore/explore-inspector.md +++ b/docs/sources/explore/explore-inspector.md @@ -43,7 +43,7 @@ For multiple queries or for queries multiple nodes, there are additional options Grafana generates a CSV file in your default browser download location. You can open it in the viewer of your choice. -1. In the **Inspector** tab, raw query results following instructions in (### Inspect raw query results). +1. In the **Inspector** tab, get raw query results by following the instructions [described in Inspect raw query results](#inspect-raw-query-results). 1. Refine query settings until you can see the raw data that you want to export. 1. Click **Download CSV**. diff --git a/docs/sources/explore/logs-integration.md b/docs/sources/explore/logs-integration.md index 6703a3da95f..e41a0c1a013 100644 --- a/docs/sources/explore/logs-integration.md +++ b/docs/sources/explore/logs-integration.md @@ -53,6 +53,7 @@ For logs where a level label is specified, we use the value of the label to dete | warning | warning | yellow | | info | info | green | | information | info | green | +| informational | info | green | | notice | info | green | | dbug | debug | blue | | debug | debug | blue | @@ -99,7 +100,7 @@ You can change the order of received logs from the default descending order (new ## Labels and detected fields -Each log row has an extendable area with its labels and detected fields, for more robust interaction. For all labels we have added the ability to filter for (positive filter) and filter out (negative filter) selected labels. Each field or label also has a stats icon to display ad-hoc statistics in relation to all displayed logs. +Each log row has an extendable area with its labels and detected fields, for more robust interaction. You can filter for (positive filter) and filter out (negative filter) selected labels. Each field or label also has a stats icon to display ad-hoc statistics in relation to all displayed logs. ## Escaping newlines @@ -112,12 +113,12 @@ To automatically fix incorrectly escaped sequences that Explore has detected: Explore replaces these sequences. When it does so, the option will change from "Escape newlines" to "Remove escaping". Evaluate the changes as the parsing may not be accurate based on the input received. You can revert the replacements by clicking "Remove escaping". -### Data links +## Data links By using data links, you can turn any part of a log message into an internal or external link. The created link is visible as a button in the **Links** section inside the **Log details** view. {{< figure src="/static/img/docs/explore/data-link-9-4.png" max-width="800px" caption="Data link in Explore" >}} -### Toggle field visibility +## Toggle field visibility Expand a log line and click the eye icon to show or hide fields. @@ -141,7 +142,7 @@ after switching to the Logs data source, the query changes to: This will return a chunk of logs in the selected time range that can be grepped/text searched. -## Logs sample +### Logs sample If the selected data source implements logs sample, and supports both log and metric queries, then for metric queries you will be able to automatically see samples of log lines that contributed to visualized metrics. This feature is currently supported by Loki data sources. diff --git a/docs/sources/explore/query-management.md b/docs/sources/explore/query-management.md index 5a482667cea..f360286c11b 100644 --- a/docs/sources/explore/query-management.md +++ b/docs/sources/explore/query-management.md @@ -33,7 +33,7 @@ Query history lets you view the history of your querying. For each individual qu ### Manage favorite queries -All queries that have been starred in the Query history tab are displayed in the Starred. This allows you to access your favorite queries faster and to reuse these queries without typing them from scratch. +All queries that have been starred in the Query history tab are displayed in the Starred tab. This allows you to access your favorite queries faster and to reuse these queries without typing them from scratch. ### Sort query history @@ -54,7 +54,7 @@ Filter query history in Query history and Starred tab by data source name: In **Query history** tab it is also possible to filter queries by date using the slider: - Use vertical slider to filter queries by date. -- By dragging top handle, adjust start date. +- By dragging bottom handle, adjust start date. - By dragging top handle, adjust end date. ### Search in query history @@ -73,29 +73,3 @@ You can customize the query history in the Settings tab. Options are described i | Change the default active tab | Query history tab | > **Note:** Query history settings are global, and applied to both panels in split mode. - -## Prometheus-specific Features - -The first version of Explore features a custom querying experience for Prometheus. When a query is executed, it actually executes two queries, a normal Prometheus query for the graph and an Instant Query for the table. An Instant Query returns the last value for each time series which shows a good summary of the data shown in the graph. - -### Metrics explorer - -On the left side of the query field, click **Metrics** to open the Metric Explorer. This shows a hierarchical menu with metrics grouped by their prefix. For example, all Alertmanager metrics are grouped under the `alertmanager` prefix. This is a good starting point if you just want to explore which metrics are available. - -{{< figure src="/static/img/docs/v65/explore_metric_explorer.png" class="docs-image--no-shadow" max-width= "800px" caption="Screenshot of the new Explore option in the panel menu" >}} - -### Query field - -The Query field supports autocomplete for metric names and functions, comparable to the standard Prometheus query editor. Press the Enter key to create a new line and Shift+Enter to execute a query. - -The autocomplete menu can be triggered by pressing Ctrl+Space. The Autocomplete menu contains a new History section with a list of recently executed queries. - -Suggestions can appear under the query field - click on them to update your query with the suggested change. - -- For counters (monotonically increasing metrics), a rate function will be suggested. -- For buckets, a histogram function will be suggested. -- For recording rules, possible to expand the rules. - -### Table filters - -Click on the filter button in the "label" column of a Table panel to add filters to the query expression. You can add filters for multiple queries as well - the filter is added for all the queries. diff --git a/docs/sources/explore/trace-integration.md b/docs/sources/explore/trace-integration.md index f7c3f42d2ca..e8e6ac3b6b5 100644 --- a/docs/sources/explore/trace-integration.md +++ b/docs/sources/explore/trace-integration.md @@ -20,9 +20,9 @@ Supported data sources are: For information on how to configure queries for the data sources listed above, refer to the documentation for specific data source. -## Trace View explanation +## Trace View -This section explains the elements of the Trace View dashboard. +This section explains the elements of the Trace View. {{< figure src="/static/img/docs/explore/explore-trace-view-full-8-0.png" class="docs-image--no-shadow" max-width= "900px" caption="Screenshot of the trace view" >}} @@ -63,12 +63,6 @@ Clicking anywhere on the span row shows span details. - Process metadata: Metadata about the process that logged this span. - Logs: List of logs logged by this span and associated key values. In case of Zipkin logs section shows Zipkin annotations. -### Node graph - -You can optionally expand the node graph for the displayed trace. Depending on the data source, this can show spans of the trace as nodes in the graph, or as some additional context like service graph based on the current trace. - -![Node graph](/static/img/docs/explore/explore-trace-view-node-graph-8-0.png 'Node graph') - ### Trace to logs > **Note:** Available in Grafana 7.4 and later versions. @@ -79,9 +73,15 @@ You can navigate from a span in a trace view directly to logs relevant for that Click the document icon to open a split view in Explore with the configured data source and query relevant logs for the span. -## Service Graph view +## Node Graph -The Service Graph view visualizes the span metrics (traces data for rates, error rates, and durations (RED)) and service graphs. +You can optionally expand the node graph for the displayed trace. Depending on the data source, this can show spans of the trace as nodes in the graph, or as some additional context like service graph based on the current trace. + +![Node graph](/static/img/docs/explore/explore-trace-view-node-graph-8-0.png 'Node graph') + +## Service Graph + +The Service Graph visualizes the span metrics (traces data for rates, error rates, and durations (RED)) and service graphs. Once the requirements are set up, this pre-configured view is immediately available. For more information, refer to the [Service Graph view table section](https://grafana.com/docs/grafana/latest/datasources/tempo/#service-graph-view-table) of the Tempo data source page and the [service graph view page](https://grafana.com/docs/tempo/latest/metrics-generator/service-graph-view/) in the Tempo documentation.