Copilot commented on code in PR #833: URL: https://github.com/apache/skywalking-website/pull/833#discussion_r3055105944
########## 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 require Review Comment: Grammar: "Grafana Tempo require" should be "Grafana Tempo requires". ```suggestion `2a2e04e8d1114b14925c04a6321ca26c.38.17739924187687539`), while Grafana Tempo requires ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
