mirror of
https://github.com/grafana/grafana.git
synced 2024-11-30 04:34:23 -06:00
[DOC] Tracing: Add doc for Tempo Search query (#68923)
* Add doc for Tempo Search query * Updates for wording and images * Add note to Explore about query editor for tracing * Fix prettier * Apply suggestions from code review Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Update docs/sources/shared/datasources/tempo-search-traceql.md * Changes from prettier * Update docs/sources/shared/datasources/tempo-search-traceql.md * Update docs/sources/shared/datasources/tempo-search-traceql.md * Updates from prettier --------- Co-authored-by: Jack Baldry <jack.baldry@grafana.com>
This commit is contained in:
Kim Nylander
GitHub
parent
07dd90b5a8
commit
34ba2ddd84
@ -58,15 +58,25 @@ To configure your Tempo data source to use this feature, refer to the [Tempo doc
|
||||
|
||||
To query a particular trace:
|
||||
|
||||
1. Select the **TraceID** query type.
|
||||
1. Enter the trace's ID into the **Trace ID** field.
|
||||
1. Select the **TraceQL** query type.
|
||||
1. Enter the trace's ID into the query field.
|
||||
|
||||
{{< 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 tab (preview feature).
|
||||
|
||||
[//]: # 'Include content for preview of Search tab featuring TraceQL query builder'
|
||||
|
||||
{{< docs/shared source="grafana" lookup="datasources/tempo-search-traceql.md" leveloffset="+1" >}}
|
||||
|
||||
## Query Loki for traces
|
||||
|
||||
To find traces to visualize, you can use the [Loki query editor]({{< relref "../../loki#loki-query-editor" >}}).
|
||||
|
||||
@ -9,7 +9,7 @@ weight: 20
|
||||
|
||||
# Tracing in Explore
|
||||
|
||||
Explore allows you to visualize traces from tracing data sources. This is available in Grafana v7.0+.
|
||||
You can use Explore to query and visualize traces from tracing data sources.
|
||||
|
||||
Supported data sources are:
|
||||
|
||||
@ -20,6 +20,18 @@ 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.
|
||||
|
||||
## Query editor
|
||||
|
||||
You can query and search tracing data using a data source's query editor.
|
||||
|
||||
Each data source can have it's own query editor. The query editor for the Tempo data source is slightly different than the query editor for the Jaegar data source.
|
||||
|
||||
For information on querying each data source, refer to their documentation:
|
||||
|
||||
- [Tempo query editor]({{< relref "../datasources/tempo/query-editor" >}})
|
||||
- [Jaeger query editor]({{< relref "../datasources/jaeger/#query-the-data-source" >}})
|
||||
- [Zipkin query editor]({{< relref "../datasources/zipkin/#query-the-data-source" >}})
|
||||
|
||||
## Trace View
|
||||
|
||||
This section explains the elements of the Trace View.
|
||||
|
||||
102
docs/sources/shared/datasources/tempo-search-traceql.md
Normal file
102
docs/sources/shared/datasources/tempo-search-traceql.md
Normal file
@ -0,0 +1,102 @@
|
||||
---
|
||||
headless: true
|
||||
---
|
||||
|
||||
[//]: # 'This file documents the Search query type for the Tempo data source. It is available as a public preview.'
|
||||
[//]: # 'This shared file is included in these locations:'
|
||||
[//]: # '/grafana/docs/sources/datasources/tempo/query-editor/index.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/.'
|
||||
|
||||
# Create TraceQL queries using Search
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
This new Search query type is available as an experimental feature. This feature is under active development and is not production ready. To try this feature, enable the `traceqlSearch` feature flag in Grafana (read [documentation](/docs/grafana/latest/setup-grafana/configure-grafana/feature-toggles/)). Grafana Cloud users should contact Grafana Support to enable this feature.
|
||||
{{% /admonition %}}
|
||||
|
||||
Using the Search tab in Explore, you can use the query builder’s drop-downs to compose TraceQL queries. The selections you make automatically generate a [TraceQL query](/docs/tempo/latest/traceql).
|
||||
|
||||
To access **Search**, select your Tempo data source, and then choose **Explore** and select **Query type** > **Search**.
|
||||
You can use the query builder to search trace data by resource service name, span name, duration, and one or more tags. The examples on this page use the default filters.
|
||||
|
||||
In addition, you can add query builder blocks, view the query history, and use the **Inspector** to see details.
|
||||
|
||||
{{< figure src="/static/img/docs/queries/screenshot-tempods-query-search.png" class="docs-image--no-shadow" max-width="750px" caption="Screenshot of the Tempo Search query type" >}}
|
||||
|
||||
## Perform a search
|
||||
|
||||
To perform a search, you need to select filters and/or tags and then run the query. The results appear underneath the query builder.
|
||||
The screenshot below identifies the areas used to perform a search.
|
||||
|
||||
{{< figure src="/static/img/docs/queries/screenshot-tempods-query-search-parts.png" class="docs-image--no-shadow" max-width="750px" caption="Parts of Tempo Search query type" >}}
|
||||
|
||||
| Number | Name | Action | Comment |
|
||||
| :----- | :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 1 | Data source | Use the data source drop-down to select a Tempo data source. | Each data source has its own version of search. This Search is specific to the Tempo data source. |
|
||||
| 2 | Query type tab | Select Search. | |
|
||||
| 3 | Choose filter | Choose whether to filter using **Resource Service Name**, **Span Name**, and/or **Duration**. | Optional. You can execute an empty query in the Search tab. In TraceQL, `{}` is a valid query and is the default query until you choose options. |
|
||||
| 4 | Filters conditions | Select options for one or more filters. For example, you can define a filter where **Resource Service Name** (`resource.service.name`) equals (`=`) `cloud-logs-archiver`. | Optional. At least one tag or filter must be defined. |
|
||||
| 5 | Tags | Add tags for span, resource, or unscoped and define their conditions. | Optional. |
|
||||
| 6 | TraceQL query | Displays the TraceQL query constructed by your selections. | This TraceQL query is executed when you select **Run query**. |
|
||||
|
||||
Every query searches the data for the selected time frame.
|
||||
By default, queries run against data from the last hour.
|
||||
Select Time range to the left of Run query to choose the time range for the data your query runs against.
|
||||
Read the [dashboard time range](/docs/grafana/latest/dashboards/use-dashboards/#set-dashboard-time-range) documentation to learn more.
|
||||
|
||||
To access Search, use the following steps:
|
||||
|
||||
1. Sign into Grafana.
|
||||
1. Select your Tempo data source.
|
||||
1. From the menu, choose Explore and select Query type > Search.
|
||||
|
||||
## Define filters
|
||||
|
||||
Using filters, you refine the data returned from the query by selecting Resource Service Name, Span Name, or Duration. The **Duration** represents span time, calculated by subtracting the end time from the start time of the span.
|
||||
|
||||
Grafana administrators can change the default filters using the Tempo data source configuration.
|
||||
Filters can be limited by the operators. The available operators are determined by the field type.
|
||||
For example, **Span Name** and **Resource Service Name** are string fields so the comparison operators are equals (`=`), not equal (`!=`), or regular expressions (`=~`).
|
||||
**Duration** is a duration field type and uses range selections (`>`, `>=`, `<`, `<=`).
|
||||
|
||||
When you select multiple values for the same filter, Grafana automatically changes the operator to the regex operator `=~` and concatenates the values with a `|`. This capability only applies to fields with drop-down value selection.
|
||||
|
||||
For example, if you choose **Span Name** `= get` and then **Span Name** `= log_results_cache,` operator drop-down changes from `=` to `=~` and both `get` and `log_results_cache` are listed in the **Span Name** field. The resulting query is updated with this:
|
||||
|
||||
`{duration>5ms && duration<10ms && name=~"get|log_results_cache"}`
|
||||
|
||||
To define filters, follow these steps:
|
||||
|
||||
1. Choose one of the filters.
|
||||
1. Select a comparison operator from the drop-down.
|
||||
1. **Resource Service Name** and **Span Name** only: Select one or more values from the drop-down.
|
||||
1. **Duration** only: Enter values and units for the range and choose comparison operators for the drop-downs. Units can be nanoseconds (`ns`), milliseconds (`ms`), seconds (`s`), minutes (`m`), and hours (`h`).
|
||||
|
||||
You can either select **Run query** to execute the query or define tags and then run the query.
|
||||
|
||||
## Define tags
|
||||
|
||||
You can add any tags to your query. Tags can be selected by scoped (span or resource) or unscoped. If you select unscoped, then all tags are searched for matches.
|
||||
|
||||
To add a tag, follow these steps:
|
||||
|
||||
1. Select span, resource, or unscoped.
|
||||
1. Select a tag from the **Select tag** drop-down.
|
||||
1. Select a comparison operator.
|
||||
1. Select a value from the **Select value** drop-down. This field is populated based upon the tag.
|
||||
1. Optional: Select **+** to add an additional tag.
|
||||
|
||||
### Optional: Add queries
|
||||
|
||||
Using **Add query**, you can have successive queries that run in sequential order.
|
||||
For example, query A runs and then query B.
|
||||
You can reorder the queries by dragging and dropping them above or below other queries.
|
||||
Select **+ Add query** to add another query block.
|
||||
|
||||
### Run queries and view results
|
||||
|
||||
Select **Run query** to run the TraceQL query (1 in the screenshot).
|
||||
|
||||
Queries can take a little while to return results. The results appear in a table underneath the query builder. Selecting a Trace ID (2 in the screenshot) displays more detailed information (3 in the screenshot).
|
||||
|
||||
{{< figure src="/static/img/docs/queries/screenshot-tempods-query-results.png" class="docs-image--no-shadow" max-width="750px" caption="Tempo Search query type results" >}}
|
||||
Loading…
Reference in New Issue
Block a user