From ee8b79a68f100d78ac3dfaa44e647bdc127ea9cb Mon Sep 17 00:00:00 2001 From: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> Date: Thu, 7 Sep 2023 09:26:18 -0400 Subject: [PATCH] [DOC] Share query editor doc for traces (#74239) * Share query editor doc for traces * Updates to included content * Update docs/sources/datasources/tempo/query-editor/index.md * Update docs/sources/datasources/tempo/query-editor/index.md * Update docs/sources/datasources/tempo/query-editor/index.md * Fixed duplicate text --- .../query-editor/{index.md => _index.md} | 48 +++++++---- .../tempo/query-editor/traceql-editor.md | 23 +++++ .../tempo/query-editor/traceql-search.md | 38 +++++++++ .../datasources/tempo-editor-traceql.md | 83 +++++++++++++++++++ 4 files changed, 176 insertions(+), 16 deletions(-) rename docs/sources/datasources/tempo/query-editor/{index.md => _index.md} (72%) create mode 100644 docs/sources/datasources/tempo/query-editor/traceql-editor.md create mode 100644 docs/sources/datasources/tempo/query-editor/traceql-search.md create mode 100644 docs/sources/shared/datasources/tempo-editor-traceql.md diff --git a/docs/sources/datasources/tempo/query-editor/index.md b/docs/sources/datasources/tempo/query-editor/_index.md similarity index 72% rename from docs/sources/datasources/tempo/query-editor/index.md rename to docs/sources/datasources/tempo/query-editor/_index.md index d4ef81f81dc..14c9f364a80 100644 --- a/docs/sources/datasources/tempo/query-editor/index.md +++ b/docs/sources/datasources/tempo/query-editor/_index.md @@ -24,7 +24,38 @@ The Tempo data source's query editor helps you query and display traces from Tem This topic explains configuration and queries specific to the Tempo data source. For general documentation on querying data sources in Grafana, see [Query and transform data][query-transform-data]. -## Query by search +To add TraceQL panels to your dashboard, refer to the [Traces panel documentation](/docs/grafana/latest/panels-visualizations/visualizations/traces/). + +To learn more about Grafana dashboards, refer to the [Use dashboards documentation](/docs/grafana/latest/dashboards/use-dashboards/). + +## Write TraceQL queries in Grafana + +You can compose TraceQL queries in Grafana and Grafana Cloud using **Explore** and a Tempo data source. You can use either the **Query type** > **Search** (the TraceQL query builder) or the **TraceQL** tab (the TraceQL query editor). +Both of these methods let you build queries and drill-down into result sets. + +To learn more about how to query by TraceQL, refer to the [TraceQL documentation](/docs/tempo/latest/traceql). + +### TraceQL query builder + +The TraceQL query builder, located on the **Explore** > **Query type** > **Search** in Grafana, provides drop-downs and text fields to help you write a query. + +Refer to the [Search using the TraceQL query builder documentation]({{< relref "./traceql-search" >}}) to learn more about creating queries using convenient drop-down menus. + +![The TraceQL query builder](/static/img/docs/tempo/screenshot-traceql-query-type-search-v10.png) + +### TraceQL query editor + +The TraceQL query editor, located on the **Explore** > **TraceQL** tab in Grafana, lets you search by trace ID and write TraceQL queries using autocomplete. + +Refer to the [TraceQL query editor documentation]({{< relref "./traceql-editor" >}}) to learn more about constructing queries using a code-editor-like experience. + +![The TraceQL query editor](/static/img/docs/tempo/screenshot-traceql-query-editor-v10.png) + +## Query by search (deprecated) + +{{% admonition type="caution" %}} +Starting with Grafana v10.2, this query type has been deprecated. It will be removed in Grafana v10.3. +{{% /admonition %}} Use this to search for traces by service name, span name, duration range, or process-level attributes that are included in your application's instrumentation, such as HTTP status code and customer ID. @@ -68,21 +99,6 @@ To query a particular trace: {{< figure src="/static/img/docs/tempo/query-editor-traceid.png" class="docs-image--no-shadow" max-width="750px" caption="Screenshot of the Tempo TraceID query type" >}} -## Query by TraceQL - -Inspired by PromQL and LogQL, TraceQL is a query language designed for selecting traces. -The default traces search reviews the whole trace. -TraceQL provides a method for formulating precise queries so you can zoom in to the data you need. -Query results are returned faster because the queries limit what is searched. - -To learn more about how to query by TraceQL, refer to the [TraceQL documentation](/docs/tempo/latest/traceql). - -You can create TraceQL queries using the Query editor or using **Search** query type. - -[//]: # 'Include content for preview of Search tab featuring TraceQL query builder' - -{{< docs/shared source="grafana" lookup="datasources/tempo-search-traceql.md" leveloffset="+1" version="" >}} - ## Query Loki for traces To find traces to visualize, you can use the [Loki query editor]({{< relref "../../loki#loki-query-editor" >}}). diff --git a/docs/sources/datasources/tempo/query-editor/traceql-editor.md b/docs/sources/datasources/tempo/query-editor/traceql-editor.md new file mode 100644 index 00000000000..d572ce066ae --- /dev/null +++ b/docs/sources/datasources/tempo/query-editor/traceql-editor.md @@ -0,0 +1,23 @@ +--- +description: Learn how to create TraceQL queries in Grafana using the query editor. +keywords: + - grafana + - tempo + - traces + - queries +labels: + products: + - cloud + - enterprise + - oss +menuTitle: Write TraceQL queries +title: Write TraceQL queries with the editor +weight: 300 +--- + +# Write TraceQL queries with the editor + +[//]: # 'Shared content for the TraceQL query editor' +[//]: # 'This content is located in /docs/sources/shared/datasources/tempo-editor-traceql.md' + +{{< docs/shared source="grafana" lookup="datasources/tempo-editor-traceql.md" version="" >}} diff --git a/docs/sources/datasources/tempo/query-editor/traceql-search.md b/docs/sources/datasources/tempo/query-editor/traceql-search.md new file mode 100644 index 00000000000..390c166f227 --- /dev/null +++ b/docs/sources/datasources/tempo/query-editor/traceql-search.md @@ -0,0 +1,38 @@ +--- +description: Learn how to create TraceQL queries in Grafana using Explore > Search. +keywords: + - grafana + - tempo + - traces + - queries +labels: + products: + - cloud + - enterprise + - oss +menuTitle: Search traces +title: Search traces using TraceQL query builder +weight: 300 +--- + +# Search traces using TraceQL query builder + +Inspired by PromQL and LogQL, TraceQL is a query language designed for selecting traces. +TraceQL provides a method for formulating precise queries so you can zoom in to the data you need. +Query results are returned faster because the queries limit what is searched. + +To learn more about how to query by TraceQL, refer to the [TraceQL documentation](/docs/tempo/latest/traceql). + +The TraceQL query builder, located on the **Explore** > **Query type** > **Search** in Grafana, provides drop-downs and text fields to help you write a query. + +![The TraceQL query builder](/static/img/docs/tempo/screenshot-traceql-query-type-search-v10.png) + +## Enable Search with the query builder + +This feature is automatically available in Grafana 10 (and newer) and Grafana Cloud. + +To enable the TraceQL query builder in self-hosted Grafana through version 10.1, [enable the `traceqlSearch` feature toggle](/docs/grafana/latest/setup-grafana/configure-grafana/feature-toggles/). + +[//]: # 'Shared content for the Search - TraceQL query builder' + +{{< docs/shared source="grafana" lookup="datasources/tempo-search-traceql.md" leveloffset="+1" version="" >}} diff --git a/docs/sources/shared/datasources/tempo-editor-traceql.md b/docs/sources/shared/datasources/tempo-editor-traceql.md new file mode 100644 index 00000000000..485682ceba4 --- /dev/null +++ b/docs/sources/shared/datasources/tempo-editor-traceql.md @@ -0,0 +1,83 @@ +--- +headless: true +labels: + products: + - enterprise + - oss +--- + +[//]: # 'This file documents the TraceQL query editor for the Tempo data source.' +[//]: # 'This shared file is included in these locations:' +[//]: # '/grafana/docs/sources/datasources/tempo/query-editor/traceql-editor.md' +[//]: # '/website/docs/grafana-cloud/data-configuration/traces/traces-query-editor.md' +[//]: # '/tempo/docs/sources/tempo/traceql/query_editor.md' +[//]: # +[//]: # 'If you make changes to this file, verify that the meaning and content are not changed in any place where the file is included.' +[//]: # 'Any links should be fully qualified and not relative: /docs/grafana/ instead of ../grafana/.' + + + +Inspired by PromQL and LogQL, TraceQL is a query language designed for selecting traces. +TraceQL provides a method for formulating precise queries so you can zoom in to the data you need. +Query results are returned faster because the queries limit what is searched. + +To learn more about how to query by TraceQL, refer to the [TraceQL documentation](/docs/tempo/latest/traceql). + +The TraceQL query editor, located on the **Explore** > **TraceQL** tab in Grafana, lets you search by trace ID and write TraceQL queries using autocomplete. + +![The TraceQL query editor](/static/img/docs/tempo/screenshot-traceql-query-editor-v10.png) + +## Enable the query editor + +This feature is automatically available in Grafana 10 (and newer) and Grafana Cloud. + +To use the TraceQL query editor in self-hosted Grafana 9.3.2 and older, you need to [enable the `traceqlEditor` feature toggle](/docs/grafana/latest/setup-grafana/configure-grafana/feature-toggles/). + +## Write TraceQL queries using the query editor + +The Tempo data source’s TraceQL query editor helps you query and display traces from Tempo in **Explore**. + +To access the query editor, follow these steps: + +1. Sign into Grafana or Grafana Cloud. +1. Select your Tempo data source. +1. From the menu, choose **Explore** and select the **TraceQL** tab. +1. Start your query on the text line by entering `{`. For help with TraceQL syntax, refer to the [Construct a TraceQL query documentation]({{< relref "./_index.md" >}}). +1. Optional: Use the Time picker drop-down to change the time and range for the query (refer to the [documentation for instructions](/docs/grafana/latest/dashboards/use-dashboards#set-dashboard-time-range)). +1. Once you have finished your query, select **Run query**. + +## Query by TraceID + +To query a particular trace by its trace ID: + +1. From the menu, choose **Explore**, select the desired Tempo data source, and navigate to the **TraceQL** tab. +1. Enter the trace ID into the query field. For example: `41928b92edf1cdbe0ba6594baee5ae9` +1. Click **Run query** or use the keyboard shortcut Shift + Enter. + +![Search for a trace ID using the TraceQL query editor](/static/img/docs/tempo/screenshot-traceql-editor-traceID.png) + +## Use autocomplete to write queries + +You can use the query editor’s autocomplete suggestions to write queries. +The editor detects span sets to provide relevant autocomplete options. +It uses regular expressions (regex) to detect where it is inside a spanset and provide attribute names, scopes, intrinsic names, logic operators, or attribute values from Tempo's API, depending on what is expected for the current situation. + +![Query editor showing the auto-complete feature](/static/img/docs/tempo/screenshot-traceql-query-editor-auto-complete-v10.png) + +To create a query using autocomplete, follow these steps: + +1. Use the steps above to access the query editor and begin your query. + +1. Enter your query. As you type your query, autocomplete suggestions appear as a drop-down. Each letter you enter refines the autocomplete options to match. + +1. Use your mouse or arrow keys to select any option you wish. When the desired option is highlighted, press Tab on your keyboard to add the selection to your query. + +1. Once your query is complete, select **Run query** to perform the query. + +## View query results + +Query results for both the editor and the builder are returned in a table. Selecting the Trace ID or Span ID provides more detailed information. + +![Query editor showing span results](/static/img/docs/tempo/screenshot-traceql-query-editor-results-v10.png) + +Selecting the trace ID from the returned results will open a trace diagram. Selecting a span from the returned results opens a trace diagram and reveals the relevant span in the trace diagram (above, the highlighted blue line).