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-website.git
The following commit(s) were added to refs/heads/master by this push:
new 0acd6d7d65b Add TraceQL blog (#833)
0acd6d7d65b is described below
commit 0acd6d7d65b55e11e5ba4e86cd6ed0c9df3090be
Author: Wan Kai <[email protected]>
AuthorDate: Thu Apr 9 11:26:41 2026 +0800
Add TraceQL blog (#833)
---
.../grafana-tempo-datasource-streaming.png | Bin 0 -> 63176 bytes
.../grafana-tempo-skywalking-datasource.png | Bin 0 -> 102613 bytes
.../grafana-tempo-skywalking-explore.png | Bin 0 -> 292672 bytes
.../grafana-tempo-skywalking-panel.png | Bin 0 -> 369078 bytes
.../grafana-tempo-skywalking-trace-detail.png | Bin 0 -> 233164 bytes
.../grafana-tempo-skywalking-trace-list.png | Bin 0 -> 268657 bytes
.../grafana-tempo-skywalking-variables.png | Bin 0 -> 75972 bytes
.../grafana-tempo-zipkin-datasource.png | Bin 0 -> 96952 bytes
.../grafana-tempo-zipkin-trace-detail.png | Bin 0 -> 264844 bytes
.../grafana-tempo-zipkin-trace-list.png | Bin 0 -> 345678 bytes
content/blog/2026-04-08-traceql/index.md | 319 +++++++++++++++++++++
.../grafana-tempo-datasource-streaming.png | Bin 0 -> 63176 bytes
.../grafana-tempo-skywalking-datasource.png | Bin 0 -> 102613 bytes
.../grafana-tempo-skywalking-explore.png | Bin 0 -> 292672 bytes
.../grafana-tempo-skywalking-panel.png | Bin 0 -> 369078 bytes
.../grafana-tempo-skywalking-trace-detail.png | Bin 0 -> 233164 bytes
.../grafana-tempo-skywalking-trace-list.png | Bin 0 -> 268657 bytes
.../grafana-tempo-skywalking-variables.png | Bin 0 -> 75972 bytes
.../grafana-tempo-zipkin-datasource.png | Bin 0 -> 96952 bytes
.../grafana-tempo-zipkin-trace-detail.png | Bin 0 -> 264844 bytes
.../grafana-tempo-zipkin-trace-list.png | Bin 0 -> 345678 bytes
content/zh/2026-04-08-traceql/index.md | 314 ++++++++++++++++++++
22 files changed, 633 insertions(+)
diff --git
a/content/blog/2026-04-08-traceql/grafana-tempo-datasource-streaming.png
b/content/blog/2026-04-08-traceql/grafana-tempo-datasource-streaming.png
new file mode 100644
index 00000000000..3887643b190
Binary files /dev/null and
b/content/blog/2026-04-08-traceql/grafana-tempo-datasource-streaming.png differ
diff --git
a/content/blog/2026-04-08-traceql/grafana-tempo-skywalking-datasource.png
b/content/blog/2026-04-08-traceql/grafana-tempo-skywalking-datasource.png
new file mode 100644
index 00000000000..bfa50edee9b
Binary files /dev/null and
b/content/blog/2026-04-08-traceql/grafana-tempo-skywalking-datasource.png differ
diff --git
a/content/blog/2026-04-08-traceql/grafana-tempo-skywalking-explore.png
b/content/blog/2026-04-08-traceql/grafana-tempo-skywalking-explore.png
new file mode 100644
index 00000000000..0d7d24aa6ac
Binary files /dev/null and
b/content/blog/2026-04-08-traceql/grafana-tempo-skywalking-explore.png differ
diff --git a/content/blog/2026-04-08-traceql/grafana-tempo-skywalking-panel.png
b/content/blog/2026-04-08-traceql/grafana-tempo-skywalking-panel.png
new file mode 100644
index 00000000000..4a3754aad41
Binary files /dev/null and
b/content/blog/2026-04-08-traceql/grafana-tempo-skywalking-panel.png differ
diff --git
a/content/blog/2026-04-08-traceql/grafana-tempo-skywalking-trace-detail.png
b/content/blog/2026-04-08-traceql/grafana-tempo-skywalking-trace-detail.png
new file mode 100644
index 00000000000..a3cfde36f09
Binary files /dev/null and
b/content/blog/2026-04-08-traceql/grafana-tempo-skywalking-trace-detail.png
differ
diff --git
a/content/blog/2026-04-08-traceql/grafana-tempo-skywalking-trace-list.png
b/content/blog/2026-04-08-traceql/grafana-tempo-skywalking-trace-list.png
new file mode 100644
index 00000000000..ad31240face
Binary files /dev/null and
b/content/blog/2026-04-08-traceql/grafana-tempo-skywalking-trace-list.png differ
diff --git
a/content/blog/2026-04-08-traceql/grafana-tempo-skywalking-variables.png
b/content/blog/2026-04-08-traceql/grafana-tempo-skywalking-variables.png
new file mode 100644
index 00000000000..d69e1bddac0
Binary files /dev/null and
b/content/blog/2026-04-08-traceql/grafana-tempo-skywalking-variables.png differ
diff --git
a/content/blog/2026-04-08-traceql/grafana-tempo-zipkin-datasource.png
b/content/blog/2026-04-08-traceql/grafana-tempo-zipkin-datasource.png
new file mode 100644
index 00000000000..9d5d3de51a4
Binary files /dev/null and
b/content/blog/2026-04-08-traceql/grafana-tempo-zipkin-datasource.png differ
diff --git
a/content/blog/2026-04-08-traceql/grafana-tempo-zipkin-trace-detail.png
b/content/blog/2026-04-08-traceql/grafana-tempo-zipkin-trace-detail.png
new file mode 100644
index 00000000000..0fa241bf500
Binary files /dev/null and
b/content/blog/2026-04-08-traceql/grafana-tempo-zipkin-trace-detail.png differ
diff --git
a/content/blog/2026-04-08-traceql/grafana-tempo-zipkin-trace-list.png
b/content/blog/2026-04-08-traceql/grafana-tempo-zipkin-trace-list.png
new file mode 100644
index 00000000000..94ae9c36fb7
Binary files /dev/null and
b/content/blog/2026-04-08-traceql/grafana-tempo-zipkin-trace-list.png differ
diff --git a/content/blog/2026-04-08-traceql/index.md
b/content/blog/2026-04-08-traceql/index.md
new file mode 100644
index 00000000000..884054606b2
--- /dev/null
+++ b/content/blog/2026-04-08-traceql/index.md
@@ -0,0 +1,319 @@
+---
+title: "Query SkyWalking and Zipkin Traces with TraceQL and Visualize in
Grafana"
+author: "Kai Wan"
+date: 2026-04-08
+description: "SkyWalking 10.4 introduces TraceQL support, implementing Grafana
Tempo's HTTP query APIs so that Grafana can query and visualize traces stored
in SkyWalking."
+tags:
+- TraceQL
+- Grafana
+- Tempo
+- Tracing
+- Zipkin
+---
+
+# Query SkyWalking and Zipkin Traces with TraceQL and Visualize in Grafana
+
+Apache SkyWalking introduced **TraceQL** support in version **10.4.0**,
implementing
+[Grafana Tempo's HTTP query
APIs](https://grafana.com/docs/tempo/v2.10.x/api_docs/) so that
+Grafana can query and visualize traces stored in SkyWalking without any
additional plugins.
+This means you can now use the familiar Grafana Tempo data source to search,
filter, and
+drill into both **SkyWalking native traces** and **Zipkin-compatible traces**
— all served
+by your existing SkyWalking OAP server.
+
+## Architecture Overview
+
+```
+┌────────────────────┐ Tempo HTTP API
┌─────────────────────────────┐
+│ │ ──── /skywalking/api/search ──► │ SkyWalking Native
Backend │
+│ Grafana │ │ (Query Traces V2
API) │
+│ (Tempo Data Src) │
├─────────────────────────────┤
+│ │ ──── /zipkin/api/search ──────► │ Zipkin-Compatible
Backend │
+└────────────────────┘
└──────────┬──────────────────┘
+ │
+
┌──────────▼──────────────────┐
+ │ SkyWalking OAP
Server │
+ │
┌───────────────────────┐ │
+ │ │ TraceQL Service
│ │
+ │ │ (port 3200)
│ │
+ │
└───────────────────────┘ │
+ │
┌───────────────────────┐ │
+ │ │ Storage
(BanyanDB / │ │
+ │ │ Elasticsearch /
…) │ │
+ │
└───────────────────────┘ │
+
└─────────────────────────────┘
+```
+
+The TraceQL Service sits inside the OAP server and exposes the
Tempo-compatible HTTP API on
+port `3200` (default). It converts traces from their native format into
+[Tempo's
format](https://github.com/grafana/tempo/blob/main/pkg/tempopb/tempo.proto),
+where the trace detail part (`Trace` message) reuses OTLP `Trace` definitions.
+
+## Limitations and Supported TraceQL Features
+
+TraceQL is a rich query language, but SkyWalking currently implements a
practical subset.
+The following features are **supported**:
+
+| Feature | Examples
|
+|----------------------|--------------------------------------------------------|
+| Spanset filter | `{resource.service.name="frontend"}`
|
+| Resource attributes | `resource.service.name`
|
+| Span attributes | `span.http.method`, `span.http.status_code`
|
+| Intrinsic fields | `duration`, `name`, `status`
|
+| Comparison operators | `=`, `>`, `>=`, `<`, `<=`
|
+| Compound conditions | `{resource.service.name="frontend" &&
duration>100ms}` |
+| Duration units | `us`/`µs`, `ms`, `s`, `m`, `h`
|
+
+The following features are **not yet supported**:
+
+- Spanset logical operations (`{...} AND {...}`, `{...} OR {...}`)
+- Pipeline operations (`|` operator)
+- Aggregate functions (`count()`, `avg()`, `max()`, `min()`, `sum()`)
+- Regular expression matching (`=~`, `!~`)
+- `event` and `link` scopes
+- `kind` intrinsic field
+- Streaming mode (must be disabled in the Grafana Tempo data source settings)
+
+> **Important**: SkyWalking native trace support in TraceQL is based on the
+> [Query Traces V2
API](https://skywalking.apache.org/docs/main/next/en/api/query-protocol/#trace-v2).
+> Currently, only **BanyanDB** storage implements this API. Other storage
backends
+> (e.g., Elasticsearch, MySQL, PostgreSQL) do not support SkyWalking native
trace queries via TraceQL.
+> Zipkin-compatible traces are **not** subject to this restriction.
+
+## Trace Format Conversion
+
+Since the trace detail part of Tempo's format reuses
+[OTLP Trace](https://opentelemetry.io/docs/reference/specification/protocol/)
definitions,
+the conversion descriptions below refer to OTLP field names (e.g., span kind,
status code).
+
+### SkyWalking Native Trace
+
+#### Trace ID Encoding
+
+SkyWalking native trace IDs are arbitrary strings (e.g.,
+`2a2e04e8d1114b14925c04a6321ca26c.38.17739924187687539`), while Grafana Tempo
requires
+pure hex-encoded trace IDs. The TraceQL Service encodes each UTF-8 byte of the
original trace
+ID as two lowercase hex characters:
+
+```
+Original: 2a2e04e8d1114b14925c04a6321ca26c.38.17739924187687539
+Encoded:
32613265303465386431313134623134393235633034613633323163613236632e33382e3137373339393234313837363837353339
+```
+
+This encoded hex trace ID is what appears in all API responses and in Grafana.
When you click a
+trace ID in Grafana, the TraceQL Service automatically decodes it back to the
original SkyWalking
+trace ID for the internal query.
+
+#### Span Kind Mapping
+
+| SkyWalking Span Type | OTLP Span Kind |
+|----------------------|----------------------|
+| `Entry` | `SPAN_KIND_SERVER` |
+| `Exit` | `SPAN_KIND_CLIENT` |
+| `Local` | `SPAN_KIND_INTERNAL` |
+
+#### Status Mapping
+
+| SkyWalking `isError` | OTLP Status Code |
+|----------------------|---------------------|
+| `true` | `STATUS_CODE_ERROR` |
+| `false` | `STATUS_CODE_OK` |
+
+#### SpanAttachedEvents
+SkyWalking
[SpanAttachedEvents](https://skywalking.apache.org/docs/main/next/en/concepts-and-designs/event/)
are converted to OTLP span events,
+with `tags` mapped as string attributes and `summary` mapped as numeric
attributes (serialized as strings).
+
+### Zipkin Trace
+
+#### Span Kind Mapping
+
+| Zipkin Span Kind | OTLP Span Kind |
+|------------------|----------------------|
+| `CLIENT` | `SPAN_KIND_CLIENT` |
+| `SERVER` | `SPAN_KIND_SERVER` |
+| `PRODUCER` | `SPAN_KIND_PRODUCER` |
+| `CONSUMER` | `SPAN_KIND_CONSUMER` |
+
+#### Status Mapping
+1. If the `otel.status_code` tag is present, it is used directly.
+2. Otherwise, if the `error` tag equals `true`, the status is
`STATUS_CODE_ERROR`.
+3. If neither tag is present, the status defaults to `STATUS_CODE_UNSET`.
+
+#### Endpoint and Annotation Mapping
+Zipkin endpoint fields are mapped to OTLP attributes (e.g.,
`localEndpoint.ipv4` → `net.host.ip`),
+and Zipkin annotations are converted to OTLP span events.
+
+For the full conversion details, see the [TraceQL Service
documentation](https://skywalking.apache.org/docs/main/next/en/api/traceql-service/).
+
+## How to Enable TraceQL
+
+### Step 1: Enable the TraceQL Module
+
+By default, the TraceQL module is **disabled** (`selector: ${SW_TRACEQL:-}`).
To enable it, set
+the selector to `default`:
+
+```yaml
+# In application.yml
+traceQL:
+ selector: ${SW_TRACEQL:default}
+ default:
+ enableDatasourceSkywalking: ${SW_TRACEQL_ENABLE_DATASOURCE_SKYWALKING:true}
+ enableDatasourceZipkin: ${SW_TRACEQL_ENABLE_DATASOURCE_ZIPKIN:true}
+```
+
+Or via environment variables:
+
+```bash
+export SW_TRACEQL=default
+export SW_TRACEQL_ENABLE_DATASOURCE_SKYWALKING=true
+export SW_TRACEQL_ENABLE_DATASOURCE_ZIPKIN=true
+```
+
+### Step 2: Enable the Zipkin Receiver (for Zipkin traces only)
+
+If you want to query Zipkin traces, you also need to enable the Zipkin
receiver so that
+SkyWalking can ingest Zipkin trace data:
+
+```yaml
+# In application.yml
+receiver-zipkin:
+ selector: ${SW_RECEIVER_ZIPKIN:default}
+ default:
+ searchableTracesTags: ${SW_ZIPKIN_SEARCHABLE_TAG_KEYS:http.method}
+ sampleRate: ${SW_ZIPKIN_SAMPLE_RATE:10000}
+ restHost: ${SW_RECEIVER_ZIPKIN_REST_HOST:0.0.0.0}
+ restPort: ${SW_RECEIVER_ZIPKIN_REST_PORT:9411}
+```
+
+Or via environment variable:
+
+```bash
+export SW_RECEIVER_ZIPKIN=default
+```
+
+### Full Configuration Reference
+
+For the complete list of all configuration options and their default values,
see the
+[Configuration section of the TraceQL Service
documentation](https://skywalking.apache.org/docs/main/next/en/api/traceql-service/#configuration).
+
+## Configuring Grafana Tempo Data Source
+
+> **Prerequisite**: Grafana **12 or later** is required.
+
+Each trace backend (SkyWalking native / Zipkin) needs its own Tempo data
source in Grafana,
+because each is served under a different context path.
+
+### Context Paths
+
+The two backends are served under separate context paths on the same port:
+
+| Backend | Default Context Path | Env Variable
| Full Default URL |
+|-------------------|----------------------|-------------------------------------------|-------------------------------------|
+| SkyWalking native | `/skywalking` |
`SW_TRACEQL_REST_CONTEXT_PATH_SKYWALKING` | `http://<oap-host>:3200/skywalking`
|
+| Zipkin | `/zipkin` |
`SW_TRACEQL_REST_CONTEXT_PATH_ZIPKIN` | `http://<oap-host>:3200/zipkin`
|
+
+### Setting Up the SkyWalking Data Source
+
+1. In Grafana, go to **Configuration → Data Sources → Add data source**.
+2. Choose **Tempo**.
+3. Set the URL to `http://<oap-host>:3200/skywalking`.
+4. **Disable the Streaming option** (SkyWalking does not support streaming
mode).
+
+
+
+5. Save and test the data source.
+
+
+
+### Setting Up the Zipkin Data Source
+
+Same as above, but set the URL to `http://<oap-host>:3200/zipkin`.
+
+
+
+## Configuring Trace List Result Tags
+
+When you search for traces in Grafana, the trace list panel shows a summary of
each trace.
+The `tracesListResultTags` configuration controls **which span tags are
included in the search
+result** and displayed as columns in the trace list.
+
+| Env Variable | Default Value
| Purpose
|
+|-------------------------------------------------|------------------------------------------------------------------------------------------------|----------------------------------|
+| `SW_TRACEQL_ZIPKIN_TRACES_LIST_RESULT_TAGS` | `http.method,error`
| Tags
shown for Zipkin traces |
+| `SW_TRACEQL_SKYWALKING_TRACES_LIST_RESULT_TAGS` |
`http.method,http.status_code,rpc.status_code,db.type,db.instance,mq.queue,mq.topic,mq.broker`
| Tags shown for SkyWalking traces |
+
+Note that `service.name` and `span.kind` are **always included** regardless of
this setting.
+
+These tags appear as attribute columns in the Grafana Tempo trace search
results, making it
+easier to identify and group traces at a glance:
+
+**SkyWalking native trace list:**
+
+
+
+**Zipkin trace list:**
+
+
+
+You can customize these tags based on your application's instrumentation. For
example, if your
+services heavily use messaging, you might add `mq.destination` or
`messaging.system` to the list.
+
+## Building a Trace Dashboard in Grafana
+
+### SkyWalking Native Trace Dashboard
+
+#### Step 1: Explore and Save
+
+1. Go to the **Explore** page in Grafana.
+2. Select the Tempo data source you configured for SkyWalking (e.g.,
`SkyWalkingTraceQL`).
+3. Run a test query, then click **Add to dashboard** and save it as
`SkyWalking Trace`.
+
+
+
+#### Step 2: Configure Variables
+
+Add dashboard variables so users can filter traces dynamically (e.g., by
service name):
+
+
+
+#### Step 3: Add a Trace Panel
+
+1. Choose a **Table** chart (or edit the panel you saved).
+2. Set **Query type** to `Search`.
+3. Set the **Service Name** query condition to the variable `$Service`.
+4. Add other query conditions as needed (e.g., duration, span name, tags).
+5. Test and save.
+
+
+
+#### Step 4: View Trace Details
+
+Click any trace ID in the trace panel to jump to the Explore page showing the
full trace
+waterfall view with all spans, tags, and events:
+
+
+
+### Zipkin Trace Dashboard
+
+The setup for Zipkin traces is identical to SkyWalking native traces — just
use the Zipkin
+Tempo data source you configured (e.g., `ZipkinTraceQL`).
+
+**Zipkin trace detail view:**
+
+
+
+## Summary
+
+With TraceQL support in SkyWalking 10.4.0, you can now leverage Grafana's
powerful Tempo
+data source to query and visualize both SkyWalking native traces and
Zipkin-compatible traces.
+The key points to remember:
+
+1. **Enable the TraceQL module** by setting `SW_TRACEQL=default` and enabling
the desired backends.
+2. **Configure separate Tempo data sources** in Grafana for each backend
(`/skywalking` and `/zipkin`).
+3. **Disable the Streaming option** in the Grafana Tempo data source settings.
+4. **Customize result tags** via
`SW_TRACEQL_SKYWALKING_TRACES_LIST_RESULT_TAGS` and
`SW_TRACEQL_ZIPKIN_TRACES_LIST_RESULT_TAGS` to control what's shown in search
results.
+5. **SkyWalking native trace queries require BanyanDB** storage (Zipkin traces
work with all storage backends).
+
+For the complete API reference and conversion details, see the
+[TraceQL Service
documentation](https://skywalking.apache.org/docs/main/next/en/api/traceql-service/).
+For Grafana integration details, see
+[Use Grafana As The
UI](https://skywalking.apache.org/docs/main/next/en/setup/backend/ui-grafana/#use-grafana-as-the-ui).
diff --git
a/content/zh/2026-04-08-traceql/grafana-tempo-datasource-streaming.png
b/content/zh/2026-04-08-traceql/grafana-tempo-datasource-streaming.png
new file mode 100644
index 00000000000..3887643b190
Binary files /dev/null and
b/content/zh/2026-04-08-traceql/grafana-tempo-datasource-streaming.png differ
diff --git
a/content/zh/2026-04-08-traceql/grafana-tempo-skywalking-datasource.png
b/content/zh/2026-04-08-traceql/grafana-tempo-skywalking-datasource.png
new file mode 100644
index 00000000000..bfa50edee9b
Binary files /dev/null and
b/content/zh/2026-04-08-traceql/grafana-tempo-skywalking-datasource.png differ
diff --git a/content/zh/2026-04-08-traceql/grafana-tempo-skywalking-explore.png
b/content/zh/2026-04-08-traceql/grafana-tempo-skywalking-explore.png
new file mode 100644
index 00000000000..0d7d24aa6ac
Binary files /dev/null and
b/content/zh/2026-04-08-traceql/grafana-tempo-skywalking-explore.png differ
diff --git a/content/zh/2026-04-08-traceql/grafana-tempo-skywalking-panel.png
b/content/zh/2026-04-08-traceql/grafana-tempo-skywalking-panel.png
new file mode 100644
index 00000000000..4a3754aad41
Binary files /dev/null and
b/content/zh/2026-04-08-traceql/grafana-tempo-skywalking-panel.png differ
diff --git
a/content/zh/2026-04-08-traceql/grafana-tempo-skywalking-trace-detail.png
b/content/zh/2026-04-08-traceql/grafana-tempo-skywalking-trace-detail.png
new file mode 100644
index 00000000000..a3cfde36f09
Binary files /dev/null and
b/content/zh/2026-04-08-traceql/grafana-tempo-skywalking-trace-detail.png differ
diff --git
a/content/zh/2026-04-08-traceql/grafana-tempo-skywalking-trace-list.png
b/content/zh/2026-04-08-traceql/grafana-tempo-skywalking-trace-list.png
new file mode 100644
index 00000000000..ad31240face
Binary files /dev/null and
b/content/zh/2026-04-08-traceql/grafana-tempo-skywalking-trace-list.png differ
diff --git
a/content/zh/2026-04-08-traceql/grafana-tempo-skywalking-variables.png
b/content/zh/2026-04-08-traceql/grafana-tempo-skywalking-variables.png
new file mode 100644
index 00000000000..d69e1bddac0
Binary files /dev/null and
b/content/zh/2026-04-08-traceql/grafana-tempo-skywalking-variables.png differ
diff --git a/content/zh/2026-04-08-traceql/grafana-tempo-zipkin-datasource.png
b/content/zh/2026-04-08-traceql/grafana-tempo-zipkin-datasource.png
new file mode 100644
index 00000000000..9d5d3de51a4
Binary files /dev/null and
b/content/zh/2026-04-08-traceql/grafana-tempo-zipkin-datasource.png differ
diff --git
a/content/zh/2026-04-08-traceql/grafana-tempo-zipkin-trace-detail.png
b/content/zh/2026-04-08-traceql/grafana-tempo-zipkin-trace-detail.png
new file mode 100644
index 00000000000..0fa241bf500
Binary files /dev/null and
b/content/zh/2026-04-08-traceql/grafana-tempo-zipkin-trace-detail.png differ
diff --git a/content/zh/2026-04-08-traceql/grafana-tempo-zipkin-trace-list.png
b/content/zh/2026-04-08-traceql/grafana-tempo-zipkin-trace-list.png
new file mode 100644
index 00000000000..94ae9c36fb7
Binary files /dev/null and
b/content/zh/2026-04-08-traceql/grafana-tempo-zipkin-trace-list.png differ
diff --git a/content/zh/2026-04-08-traceql/index.md
b/content/zh/2026-04-08-traceql/index.md
new file mode 100644
index 00000000000..19b34d08852
--- /dev/null
+++ b/content/zh/2026-04-08-traceql/index.md
@@ -0,0 +1,314 @@
+---
+title: "使用 TraceQL 查询 SkyWalking 和 Zipkin 链路追踪数据并在 Grafana 中可视化"
+author: "万凯"
+date: 2026-04-08
+description: "SkyWalking 10.4 引入了 TraceQL 支持，实现了 Grafana Tempo 的 HTTP 查询 API，使
Grafana 可以直接查询和可视化 SkyWalking 中存储的链路追踪数据。"
+tags:
+- TraceQL
+- Grafana
+- Tempo
+- Tracing
+- Zipkin
+---
+
+# 使用 TraceQL 查询 SkyWalking 和 Zipkin 链路追踪数据并在 Grafana 中可视化
+
+Apache SkyWalking 在 **10.4.0** 版本中引入了 **TraceQL** 支持，实现了
+[Grafana Tempo 的 HTTP 查询
API](https://grafana.com/docs/tempo/v2.10.x/api_docs/)，使
+Grafana 无需任何额外插件即可查询和可视化 SkyWalking 中存储的链路追踪数据。
+这意味着你现在可以使用熟悉的 Grafana Tempo 数据源来搜索、过滤和深入分析
+**SkyWalking 原生链路追踪**和 **Zipkin 兼容链路追踪** —— 所有数据都由现有的 SkyWalking OAP 服务器提供。
+
+## 架构概览
+
+```
+┌────────────────────┐ Tempo HTTP API
┌─────────────────────────────┐
+│ │ ──── /skywalking/api/search ──► │ SkyWalking Native
Backend │
+│ Grafana │ │ (Query Traces V2
API) │
+│ (Tempo Data Src) │
├─────────────────────────────┤
+│ │ ──── /zipkin/api/search ──────► │ Zipkin-Compatible
Backend │
+└────────────────────┘
└──────────┬──────────────────┘
+ │
+
┌──────────▼──────────────────┐
+ │ SkyWalking OAP
Server │
+ │
┌───────────────────────┐ │
+ │ │ TraceQL Service
│ │
+ │ │ (port 3200)
│ │
+ │
└───────────────────────┘ │
+ │
┌───────────────────────┐ │
+ │ │ Storage
(BanyanDB / │ │
+ │ │ Elasticsearch /
…) │ │
+ │
└───────────────────────┘ │
+
└─────────────────────────────┘
+```
+
+TraceQL Service 位于 OAP 服务器内部，在端口 `3200`（默认）上暴露 Tempo 兼容的 HTTP API。
+它将链路追踪数据从原生格式转换为
+[Tempo
的格式](https://github.com/grafana/tempo/blob/main/pkg/tempopb/tempo.proto)，
+其中链路追踪详情部分（`Trace` 消息）复用了 OTLP `Trace` 定义。
+
+## 支持的 TraceQL 特性与限制
+
+TraceQL 是一种功能丰富的查询语言，但 SkyWalking 目前实现了一个实用的子集。
+以下特性**已支持**：
+
+| Feature | Examples
|
+|----------------------|--------------------------------------------------------|
+| Spanset filter | `{resource.service.name="frontend"}`
|
+| Resource attributes | `resource.service.name`
|
+| Span attributes | `span.http.method`, `span.http.status_code`
|
+| Intrinsic fields | `duration`, `name`, `status`
|
+| Comparison operators | `=`, `>`, `>=`, `<`, `<=`
|
+| Compound conditions | `{resource.service.name="frontend" &&
duration>100ms}` |
+| Duration units | `us`/`µs`, `ms`, `s`, `m`, `h`
|
+
+以下特性**暂不支持**：
+
+- Spanset logical operations (`{...} AND {...}`, `{...} OR {...}`)
+- Pipeline operations (`|` operator)
+- Aggregate functions (`count()`, `avg()`, `max()`, `min()`, `sum()`)
+- Regular expression matching (`=~`, `!~`)
+- `event` and `link` scopes
+- `kind` intrinsic field
+- Streaming mode (must be disabled in the Grafana Tempo data source settings)
+
+> **重要提示**：TraceQL 中的 SkyWalking 原生链路追踪支持基于
+> [Query Traces V2
API](https://skywalking.apache.org/docs/main/next/en/api/query-protocol/#trace-v2)。
+> 目前只有 **BanyanDB** 存储实现了该 API。其他存储后端
+> （如 Elasticsearch、MySQL、PostgreSQL）不支持通过 TraceQL 查询 SkyWalking 原生链路追踪数据。
+> Zipkin 兼容链路追踪**不受**此限制。
+
+## Trace 格式转换
+
+由于 Tempo 格式的链路追踪详情部分复用了
+[OTLP Trace](https://opentelemetry.io/docs/reference/specification/protocol/)
定义，
+以下转换描述使用 OTLP 字段名称（如 span kind、status code）。
+
+### SkyWalking 原生链路追踪
+
+#### Trace ID 编码
+
+SkyWalking 原生 trace ID 是任意字符串（例如
+`2a2e04e8d1114b14925c04a6321ca26c.38.17739924187687539`），而 Grafana Tempo 要求
+纯十六进制编码的 trace ID。TraceQL Service 将原始 trace ID 的每个 UTF-8 字节编码为两个小写十六进制字符：
+
+```
+原始值: 2a2e04e8d1114b14925c04a6321ca26c.38.17739924187687539
+编码后:
32613265303465386431313134623134393235633034613633323163613236632e33382e3137373339393234313837363837353339
+```
+
+编码后的十六进制 trace ID 会出现在所有 API 响应和 Grafana 中。当你在 Grafana 中点击
+trace ID 时，TraceQL Service 会自动将其解码回原始的 SkyWalking trace ID 进行内部查询。
+
+#### Span Kind 映射
+
+| SkyWalking Span Type | OTLP Span Kind |
+|----------------------|----------------------|
+| `Entry` | `SPAN_KIND_SERVER` |
+| `Exit` | `SPAN_KIND_CLIENT` |
+| `Local` | `SPAN_KIND_INTERNAL` |
+
+#### 状态映射
+
+| SkyWalking `isError` | OTLP Status Code |
+|----------------------|---------------------|
+| `true` | `STATUS_CODE_ERROR` |
+| `false` | `STATUS_CODE_OK` |
+
+#### SpanAttachedEvents
+SkyWalking
[SpanAttachedEvents](https://skywalking.apache.org/docs/main/next/en/concepts-and-designs/event/)
被转换为 OTLP span events，
+其中 `tags` 映射为字符串属性，`summary` 映射为数值属性（序列化为字符串）。
+
+### Zipkin 链路追踪
+
+#### Span Kind 映射
+
+| Zipkin Span Kind | OTLP Span Kind |
+|------------------|----------------------|
+| `CLIENT` | `SPAN_KIND_CLIENT` |
+| `SERVER` | `SPAN_KIND_SERVER` |
+| `PRODUCER` | `SPAN_KIND_PRODUCER` |
+| `CONSUMER` | `SPAN_KIND_CONSUMER` |
+
+#### 状态映射
+1. 如果存在 `otel.status_code` 标签，则直接使用。
+2. 否则，如果 `error` 标签等于 `true`，则状态为 `STATUS_CODE_ERROR`。
+3. 如果以上标签都不存在，则状态默认为 `STATUS_CODE_UNSET`。
+
+#### Endpoint 与 Annotation 映射
+Zipkin endpoint 字段被映射为 OTLP 属性（例如 `localEndpoint.ipv4` → `net.host.ip`），
+Zipkin annotations 被转换为 OTLP span events。
+
+完整的转换详情请参阅 [TraceQL Service
文档](https://skywalking.apache.org/docs/main/next/en/api/traceql-service/)。
+
+## 如何启用 TraceQL
+
+### 步骤 1：启用 TraceQL 模块
+
+默认情况下，TraceQL 模块是**禁用的**（`selector: ${SW_TRACEQL:-}`）。要启用它，将 selector
+设置为 `default`：
+
+```yaml
+# 在 application.yml 中
+traceQL:
+ selector: ${SW_TRACEQL:default}
+ default:
+ enableDatasourceSkywalking: ${SW_TRACEQL_ENABLE_DATASOURCE_SKYWALKING:true}
+ enableDatasourceZipkin: ${SW_TRACEQL_ENABLE_DATASOURCE_ZIPKIN:true}
+```
+
+或通过环境变量设置：
+
+```bash
+export SW_TRACEQL=default
+export SW_TRACEQL_ENABLE_DATASOURCE_SKYWALKING=true
+export SW_TRACEQL_ENABLE_DATASOURCE_ZIPKIN=true
+```
+
+### 步骤 2：启用 Zipkin 接收器（仅用于 Zipkin 链路追踪）
+
+如果你需要查询 Zipkin 链路追踪数据，还需要启用 Zipkin 接收器，以便 SkyWalking 能够接收
+Zipkin 链路追踪数据：
+
+```yaml
+# 在 application.yml 中
+receiver-zipkin:
+ selector: ${SW_RECEIVER_ZIPKIN:default}
+ default:
+ searchableTracesTags: ${SW_ZIPKIN_SEARCHABLE_TAG_KEYS:http.method}
+ sampleRate: ${SW_ZIPKIN_SAMPLE_RATE:10000}
+ restHost: ${SW_RECEIVER_ZIPKIN_REST_HOST:0.0.0.0}
+ restPort: ${SW_RECEIVER_ZIPKIN_REST_PORT:9411}
+```
+
+或通过环境变量设置：
+
+```bash
+export SW_RECEIVER_ZIPKIN=default
+```
+
+### 完整配置参考
+
+所有配置选项及其默认值的完整列表，请参阅
+[TraceQL Service
文档的配置章节](https://skywalking.apache.org/docs/main/next/en/api/traceql-service/#configuration)。
+
+## 配置 Grafana Tempo 数据源
+
+> **前提条件**：需要 Grafana **12 或更高版本**。
+
+每个链路追踪后端（SkyWalking 原生 / Zipkin）需要在 Grafana 中配置各自独立的 Tempo 数据源，
+因为它们分别在不同的上下文路径下提供服务。
+
+### 上下文路径
+
+两个后端在同一端口上使用不同的上下文路径提供服务：
+
+| Backend | Default Context Path | Env Variable
| Full Default URL |
+|-------------------|----------------------|-------------------------------------------|-------------------------------------|
+| SkyWalking native | `/skywalking` |
`SW_TRACEQL_REST_CONTEXT_PATH_SKYWALKING` | `http://<oap-host>:3200/skywalking`
|
+| Zipkin | `/zipkin` |
`SW_TRACEQL_REST_CONTEXT_PATH_ZIPKIN` | `http://<oap-host>:3200/zipkin`
|
+
+### 配置 SkyWalking 数据源
+
+1. 在 Grafana 中，前往 **Configuration → Data Sources → Add data source**。
+2. 选择 **Tempo**。
+3. 将 URL 设置为 `http://<oap-host>:3200/skywalking`。
+4. **禁用 Streaming 选项**（SkyWalking 不支持流式模式）。
+
+
+
+5. 保存并测试数据源。
+
+
+
+### 配置 Zipkin 数据源
+
+与上述步骤相同，但将 URL 设置为 `http://<oap-host>:3200/zipkin`。
+
+
+
+## 配置链路追踪列表结果标签
+
+在 Grafana 中搜索链路追踪时，链路追踪列表面板会显示每条追踪的摘要信息。
+`tracesListResultTags` 配置控制**哪些 span 标签会包含在搜索结果中**并作为列显示在追踪列表中。
+
+| Env Variable | Default Value
| Purpose
|
+|-------------------------------------------------|------------------------------------------------------------------------------------------------|----------------------------------|
+| `SW_TRACEQL_ZIPKIN_TRACES_LIST_RESULT_TAGS` | `http.method,error`
| Tags
shown for Zipkin traces |
+| `SW_TRACEQL_SKYWALKING_TRACES_LIST_RESULT_TAGS` |
`http.method,http.status_code,rpc.status_code,db.type,db.instance,mq.queue,mq.topic,mq.broker`
| Tags shown for SkyWalking traces |
+
+注意，无论此设置如何，`service.name` 和 `span.kind` **始终包含**在结果中。
+
+这些标签在 Grafana Tempo 链路追踪搜索结果中显示为属性列，方便快速识别和分组追踪数据：
+
+**SkyWalking 原生追踪列表：**
+
+
+
+**Zipkin 追踪列表：**
+
+
+
+你可以根据应用程序的埋点情况自定义这些标签。例如，如果你的服务大量使用消息队列，
+可以在列表中添加 `mq.destination` 或 `messaging.system`。
+
+## 在 Grafana 中构建链路追踪仪表板
+
+### SkyWalking 原生追踪仪表板
+
+#### 步骤 1：探索并保存
+
+1. 前往 Grafana 的 **Explore** 页面。
+2. 选择你为 SkyWalking 配置的 Tempo 数据源（例如 `SkyWalkingTraceQL`）。
+3. 运行一个测试查询，然后点击 **Add to dashboard** 并保存为 `SkyWalking Trace`。
+
+
+
+#### 步骤 2：配置变量
+
+添加仪表板变量，以便用户可以动态过滤追踪数据（例如按服务名称过滤）：
+
+
+
+#### 步骤 3：添加追踪面板
+
+1. 选择 **Table** 图表（或编辑你保存的面板）。
+2. 将 **Query type** 设置为 `Search`。
+3. 将 **Service Name** 查询条件设置为变量 `$Service`。
+4. 根据需要添加其他查询条件（如 duration、span name、tags）。
+5. 测试并保存。
+
+
+
+#### 步骤 4：查看追踪详情
+
+点击追踪面板中的任意 trace ID，即可跳转到 Explore 页面，查看完整的追踪瀑布图，
+包含所有 span、标签和事件：
+
+
+
+### Zipkin 追踪仪表板
+
+Zipkin 追踪的设置与 SkyWalking 原生追踪完全相同 —— 只需使用你配置的 Zipkin Tempo 数据源
+（例如 `ZipkinTraceQL`）。
+
+**Zipkin 追踪详情视图：**
+
+
+
+## 总结
+
+通过 SkyWalking 10.4.0 中的 TraceQL 支持，你现在可以利用 Grafana 强大的 Tempo 数据源
+来查询和可视化 SkyWalking 原生链路追踪和 Zipkin 兼容链路追踪数据。
+需要记住的要点：
+
+1. **启用 TraceQL 模块**：设置 `SW_TRACEQL=default` 并启用所需的后端。
+2. **在 Grafana 中配置独立的 Tempo 数据源**：为每个后端分别配置（`/skywalking` 和 `/zipkin`）。
+3. **禁用 Streaming 选项**：在 Grafana Tempo 数据源设置中关闭流式模式。
+4. **自定义结果标签**：通过 `SW_TRACEQL_SKYWALKING_TRACES_LIST_RESULT_TAGS` 和
`SW_TRACEQL_ZIPKIN_TRACES_LIST_RESULT_TAGS` 控制搜索结果中显示的内容。
+5. **SkyWalking 原生追踪查询需要 BanyanDB** 存储（Zipkin 追踪支持所有存储后端）。
+
+完整的 API 参考和转换详情，请参阅
+[TraceQL Service
文档](https://skywalking.apache.org/docs/main/next/en/api/traceql-service/)。
+Grafana 集成详情，请参阅
+[使用 Grafana 作为
UI](https://skywalking.apache.org/docs/main/next/en/setup/backend/ui-grafana/#use-grafana-as-the-ui)。
