(skywalking) branch master updated: Add TraceQL configuration in docs ui-grafana.md (#13803)

[wusheng]

This is an automated email from the ASF dual-hosted git repository.

wusheng pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/skywalking.git


The following commit(s) were added to refs/heads/master by this push:
     new acb63379cd Add TraceQL configuration in docs ui-grafana.md (#13803)
acb63379cd is described below

commit acb63379cdaa80837a2c02835be837b12afb06a8
Author: Wan Kai <wankai...@foxmail.com>
AuthorDate: Tue Apr 7 17:38:11 2026 +0800

    Add TraceQL configuration in docs ui-grafana.md (#13803)
---
 docs/en/api/traceql-service.md      | 14 ++----------
 docs/en/setup/backend/ui-grafana.md | 44 +++++++++++++++++++++++++++++++++----
 2 files changed, 42 insertions(+), 16 deletions(-)

diff --git a/docs/en/api/traceql-service.md b/docs/en/api/traceql-service.md
index eb4d96ed75..6a72fdaf30 100644
--- a/docs/en/api/traceql-service.md
+++ b/docs/en/api/traceql-service.md
@@ -835,18 +835,8 @@ traceQL:
 ```
 
 ## Integration with Grafana
-
-### Add Tempo Data Source
-1. In Grafana, go to Configuration → Data Sources
-2. Add a new Tempo data source
-3. Set the URL to: `http://<oap-host>:<port>/zipkin` (for Zipkin-compatible 
traces) or `http://<oap-host>:<port>/skywalking` (for SkyWalking native traces)
-4. **Important**: Disable the "Streaming" option as it is not currently 
supported
-5. Save and test the connection
-
-### Query Traces
-- Use TraceQL queries in Grafana Explore
-- View trace details with OTLP visualization
-- Search traces by service, span, duration, status and tags
+***Notice:*** The feature requires version `Grafana 12 or later`.
+For more details, refer to [Use Grafana As The 
UI](../setup/backend/ui-grafana.md).
 
 ## Limitations
 - Pipeline operations (`|` operator) are not supported
diff --git a/docs/en/setup/backend/ui-grafana.md 
b/docs/en/setup/backend/ui-grafana.md
index 3be7c8fe3e..19173b5d64 100644
--- a/docs/en/setup/backend/ui-grafana.md
+++ b/docs/en/setup/backend/ui-grafana.md
@@ -1,5 +1,5 @@
 # Use Grafana As The UI
-SkyWalking provides [PromQL Service](../../api/promql-service.md) and [LogQL 
Service](../../api/logql-service.md). You can choose 
[Grafana](https://grafana.com/) 
+SkyWalking provides [PromQL Service](../../api/promql-service.md), [LogQL 
Service](../../api/logql-service.md) and [TraceQL 
Service](../../api/traceql-service.md). You can choose 
[Grafana](https://grafana.com/) 
 as the SkyWalking UI. About the installation and how to use please refer to 
the [official document](https://grafana.com/docs/grafana/v9.3/).
 
 Notice <1>, Gafana is [AGPL-3.0 
license](https://github.com/grafana/grafana/blob/main/LICENSE), which is very 
different from Apache 2.0.
@@ -10,18 +10,32 @@ Grafana UI is an extension on our support of PromQL APIs. 
We don't maintain or p
 
 ## Configure Data Source
 ### Prometheus Data Source
-In the data source config panel, chose the `Prometheus` and set the url to the 
OAP server address, the default port is `9090`.
+In the data source config panel, choose the `Prometheus` and set the url to 
the OAP server address, the default port is `9090`.
 <img 
src="https://skywalking.apache.org/screenshots/9.6.0/promql/grafana-datasource.jpg"/>
 
 ### SkyWalking Data Source
 Before you start, please install the [SkyWalking data source 
plugin](https://github.com/apache/skywalking-grafana-plugins).
-In the data source config panel, chose the `SkyWalking` and set the url to the 
OAP server `graphql` service address, the default port is `12800`.
+In the data source config panel, choose the `SkyWalking` and set the url to 
the OAP server `graphql` service address, the default port is `12800`.
 <img 
src="https://skywalking.apache.org/screenshots/9.7.0/promql/grafana-skywalking-datasource.jpg"/>
 
 ### Loki Data Source
-In the data source config panel, chose the `Loki` and set the url to the OAP 
server address, the default port is `3100`.
+In the data source config panel, choose the `Loki` and set the url to the OAP 
server address, the default port is `3100`.
 <img 
src="https://skywalking.apache.org/screenshots/9.6.0/logql/grafana-loki-datasource.jpg"/>
 
+### Tempo Data Source
+In the data source config panel, choose the `Tempo` and set the url to the 
full OAP trace API address, including the context path. The default port is 
`3200`, for example `http://<oap-host>:3200/skywalking` for SkyWalking native 
trace or `http://<oap-host>:3200/zipkin` for Zipkin trace.
+The SkyWalking native trace API context path is `/skywalking`, and the Zipkin 
trace API context path is `/zipkin`.
+You can customize them via `SW_TRACEQL_REST_CONTEXT_PATH_SKYWALKING` and 
`SW_TRACEQL_REST_CONTEXT_PATH_ZIPKIN` respectively. If you customize either 
path, use the customized path in the Grafana Tempo data source URL.
+
+***Notice:*** The feature requires version `Grafana 12 or later`. And require 
disabling the Streaming option for the Tempo data source in the following 
configuration.
+<img 
src="https://skywalking.apache.org/screenshots/10.4.0/traceql/grafana-tempo-datasource-streaming.png"/>
+
+#### SkyWalking Native Trace
+<img 
src="https://skywalking.apache.org/screenshots/10.4.0/traceql/grafana-tempo-skywalking-datasource.png"/>
+
+#### Zipkin Trace
+<img 
src="https://skywalking.apache.org/screenshots/10.4.0/traceql/grafana-tempo-zipkin-datasource.png"/>
+
 ## Configure Metric Dashboards
 
 ### Dashboards Settings
@@ -118,6 +132,28 @@ For endpoint relation scope, extra set `Endpoint` and 
`Dest Endpoint`.
 4. Test query and save the panel.
 <img 
src="https://skywalking.apache.org/screenshots/10.1.0/promql/grafana-relation-panel.png"/>
 
+## Configure Trace Dashboard
+### SkyWalking Native Trace
+#### Dashboards Settings
+The following steps are an example of configuring a `Trace` dashboard for 
SkyWalking native trace:
+1. Go to the `Explore` page, select the `Tempo` data source named 
`SkyWalkingTraceQL` (the name you configured). Add it to the dashboard and save 
it as `SkyWalking Trace`.
+<img 
src="https://skywalking.apache.org/screenshots/10.4.0/traceql/grafana-tempo-skywalking-explore.png"/>
+2. Configure variables for the dashboard:
+<img 
src="https://skywalking.apache.org/screenshots/10.4.0/traceql/grafana-tempo-skywalking-variables.png"/>
+
+#### Add Trace Panel
+The following steps show how to add a trace panel for SkyWalking native trace.
+1. Choose `Table` chart or edit your saved panel.
+2. Set `Query type` to `Search` and set the query condition `Service Name` to 
variable `$Service`.
+3. Set other query conditions if needed.
+4. Test query and save the panel.
+<img 
src="https://skywalking.apache.org/screenshots/10.4.0/traceql/grafana-tempo-skywalking-panel.png"/>
+5. If you click the trace ID on the trace panel, it will jump to the explore 
page and show the trace details.
+<img 
src="https://skywalking.apache.org/screenshots/10.4.0/traceql/grafana-tempo-skywalking-trace-detail.png"/>
+
+### Zipkin Trace
+Same as the SkyWalking native trace, but use the Zipkin Tempo data source you 
configured.
+
 ## Preview on demo.skywalking.a.o
 SkyWalking community provides a preview site for services of `General` and 
`Service Mesh` layers from the demo environment.
 You could take a glance through [**Preview metrics on 
Grafana**](https://skywalking.apache.org/#demo) of the demo deployment.