[v11.2.x] [DOC] Update TraceQL query editor doc (#92491)
Co-authored-by: Isabel Matwawana <76437239+imatwawana@users.noreply.github.com> Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com>
This commit is contained in:
grafana-delivery-bot[bot]
co-authored by
Isabel Matwawana
Kim Nylander
Isabel Matwawana
Kim Nylander
parent
2a88694fd3
commit
a8aefb1386
@@ -23,19 +23,24 @@ 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](https://grafana.com/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 in Grafana **Explore** lets you search by trace ID and write TraceQL queries using autocomplete.
|
||||
|
||||
|
||||
|
||||
|
||||
## Enable the query editor
|
||||
## Before you begin
|
||||
|
||||
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](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/feature-toggles/).
|
||||
|
||||
If trying to query a self-managed Grafana Tempo or Grafana Enterprise Traces database with a gateway (e.g., nginx) in front of it from your hosted Grafana, that gateway (e.g., nginx) must allow gRPC connections. If it does not, streaming will not work and queries will fail to return results.
|
||||
### Streaming and gRPC
|
||||
|
||||
If you cannot configure your gateway to allow gRPC, open a support escalation to request streaming query results be disabled in your hosted Grafana.
|
||||
If you're trying to query a self-managed Grafana Tempo or Grafana Enterprise Traces database with a gateway, such as nginx, in front of it from your hosted Grafana, that gateway (for example, nginx) must allow gRPC connections.
|
||||
If it doesn't, streaming won't work and queries will fail to return results.
|
||||
|
||||
If you can't configure your gateway to allow gRPC, deactivate streaming in your hosted Grafana.
|
||||
In Grafana 11.2 and newer, you can deactivate the **Streaming** option in your Tempo data source settings from **Connections** > **Data sources** in the Grafana main menu.
|
||||
You can also open a support escalation to request streaming query results be disabled in your hosted Grafana.
|
||||
|
||||
## Write TraceQL queries using the query editor
|
||||
|
||||
@@ -44,13 +49,19 @@ The Tempo data source’s TraceQL query editor helps you query and display trace
|
||||
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. Select **Explore** from the main menu.
|
||||
1. Select a Tempo data source.
|
||||
1. 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](https://grafana.com/docs/tempo/latest/traceql/#construct-a-traceql-query).
|
||||
1. Optional: Use the Time picker drop-down to change the time and range for the query (refer to the [documentation for instructions](https://grafana.com/docs/grafana/latest/dashboards/use-dashboards/#set-dashboard-time-range)).
|
||||
1. Once you have finished your query, select **Run query**.
|
||||
|
||||
This video provides and example of creating a TraceQL query using the custom tag grouping.
|
||||
Optional: Select **Copy query from Search** to transfer a builder query to the editor.
|
||||
|
||||
1. Optional: Use the **Time picker** drop-down list to change the time and range for the query (refer to the [documentation for instructions](https://grafana.com/docs/grafana/latest/dashboards/use-dashboards/#set-dashboard-time-range)).
|
||||
1. Once you've finished your query, select **Run query**.
|
||||
|
||||
|
||||
|
||||
This video provides an example of creating a TraceQL query using the custom tag grouping.
|
||||
|
||||
{{< youtube id="fraepWra00Y" >}}
|
||||
|
||||
@@ -62,15 +73,15 @@ To query a particular trace by its trace ID:
|
||||
1. Enter the trace ID into the query field. For example: `41928b92edf1cdbe0ba6594baee5ae9`
|
||||
1. Click **Run query** or use the keyboard shortcut Shift + Enter.
|
||||
|
||||
|
||||
|
||||
|
||||
## 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's inside a spanset and provide attribute names, scopes, intrinsic names, logic operators, or attribute values from Tempo's API, depending on what's expected for the current situation.
|
||||
The editor detects spansets 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 the Tempo API, depending on what's expected for the current situation.
|
||||
|
||||
|
||||
|
||||
|
||||
To create a query using autocomplete, follow these steps:
|
||||
|
||||
@@ -84,17 +95,37 @@ To create a query using autocomplete, follow these steps:
|
||||
|
||||
## 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 results appear in a table, such as **Table - Traces**, under the query editor.
|
||||
Each span (and the trace it belongs to) matching the query conditions is returned by the query.
|
||||
If there are no filter conditions, all spans are matching and thus returned with their associated traces.
|
||||
|
||||
Selecting the trace ID from the returned results opens a trace diagram. Selecting a span from the returned results opens a trace diagram and reveals the relevant span in the trace diagram (the highlighted blue line).
|
||||
A query is performed against a defined time interval, relative (for example, the last 3 hours) or absolute (for example, from X date-time to Y date-time).
|
||||
The query response is also limited by the number of traces (**Limit**) and spans per spanset (**Span Limit**).
|
||||
|
||||
In the trace diagram, the bold text on the left side of each span indicates the service name, for example `mythical-requester: requester`, and it is hidden when subsequent spans have the same service name (nested spans).
|
||||
Each service has a color assigned to it, which is visible to the left of the name and timeline in the graph.
|
||||
Spans with the same color belong to the same service. The grey text to the right of the service name indicates the span name.
|
||||
|
||||
|
||||
|
||||
1. TraceQL query editor
|
||||
1. Query options: **Limit**, **Span Limit** and **Table Format** (Traces or Spans).
|
||||
1. Trace (by Trace ID). The **Name** and **Service** columns are displaying the trace root span name and associated service.
|
||||
1. Spans associated with the Trace.
|
||||
|
||||
### Streaming results
|
||||
Selecting the trace ID from the returned results opens a trace diagram.
|
||||
Selecting a span from the returned results opens a trace diagram and reveals the relevant span in the trace diagram.
|
||||
|
||||
For more information on span details, refer to [Traces in Explore](https://grafana.com/docs/grafana/latest/explore/trace-integration/#span-details).
|
||||
|
||||
|
||||
|
||||
### Focus on traces or spans
|
||||
|
||||
Under **Options**, you can choose to display the table as **Traces** or **Spans** focused.
|
||||
|
||||
When the **Table Type** option is set to **Spans**, the traces and spansets are flattened into a list of spans.
|
||||
The trace service and trace name are added to the row of each span to add context.
|
||||
|
||||
Using the **Spans** option makes it easier access the spans to apply transformations and plot them in dashboards.
|
||||
|
||||
### Stream results
|
||||
|
||||
The Tempo data source supports streaming responses to TraceQL queries so you can see partial query results as they come in without waiting for the whole query to finish.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user