mirror of
https://github.com/grafana/grafana.git
synced 2025-07-28 16:12:22 +08:00
84 lines
4.5 KiB
Markdown
84 lines
4.5 KiB
Markdown
---
|
||
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/.'
|
||
|
||
<!-- # Write TraceQL queries using the query editor -->
|
||
|
||
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](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.
|
||
|
||
|
||
|
||
## 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](https://grafana.com/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](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**.
|
||
|
||
## 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.
|
||
|
||
|
||
|
||
## 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.
|
||
|
||
|
||
|
||
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.
|
||
|
||
|
||
|
||
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).
|