This is an automated email from the ASF dual-hosted git repository. wankai pushed a commit to branch sw-traceql in repository https://gitbox.apache.org/repos/asf/skywalking.git
commit 4b59a345bfbaf1c6774e2d781f603c101ce0faeb Author: wankai123 <[email protected]> AuthorDate: Mon Mar 30 09:24:29 2026 +0800 add docs --- .github/workflows/skywalking.yaml | 2 + docs/en/api/traceql-service.md | 46 ++++++++++++++++------ docs/en/changes/changes.md | 2 +- docs/en/setup/backend/configuration-vocabulary.md | 12 ++++++ .../promql/handler/PromQLApiHandlerTest.java | 26 ++++-------- .../src/main/resources/application.yml | 2 +- 6 files changed, 59 insertions(+), 31 deletions(-) diff --git a/.github/workflows/skywalking.yaml b/.github/workflows/skywalking.yaml index fcc2a11b7b..5b966775fe 100644 --- a/.github/workflows/skywalking.yaml +++ b/.github/workflows/skywalking.yaml @@ -653,6 +653,8 @@ jobs: config: test/e2e-v2/cases/logql/e2e.yaml - name: TraceQL Service Zipkin config: test/e2e-v2/cases/traceql/zipkin/e2e.yaml + - name: TraceQL Service SkyWalking + config: test/e2e-v2/cases/traceql/skywalking/e2e.yaml - name: AWS API Gateway config: test/e2e-v2/cases/aws/api-gateway/e2e.yaml - name: Redis Prometheus and Log Collecting diff --git a/docs/en/api/traceql-service.md b/docs/en/api/traceql-service.md index e9d0c8fe0f..513a26bbbb 100644 --- a/docs/en/api/traceql-service.md +++ b/docs/en/api/traceql-service.md @@ -5,6 +5,10 @@ Third-party systems or visualization platforms that already support Tempo and Tr SkyWalking supports two types of traces: SkyWalking native traces and Zipkin-compatible traces. The TraceQL Service converts both trace formats to OpenTelemetry Protocol (OTLP) format to provide compatibility with Grafana Tempo and TraceQL queries. +> **Note**: SkyWalking native trace support in TraceQL is based on the [Query Traces V2 API](../../../oap-server/server-query-plugin/query-graphql-plugin/src/main/resources/query-protocol/trace-v2.graphqls) (`queryTraces` / `hasQueryTracesV2Support`). +> Currently, only **BanyanDB** storage implements this API. Other storage backends (e.g. Elasticsearch, MySQL, PostgreSQL) do not support it. +> Zipkin-compatible traces are not subject to this restriction. + ## Details Of Supported TraceQL The following doc describes the details of the supported protocol and compared it to the TraceQL official documentation. If not mentioned, it will not be supported by default. @@ -250,16 +254,16 @@ Search for traces matching the given TraceQL criteria. GET /api/search ``` -| Parameter | Definition | Optional | -|-------------|-------------------------------------|---------------| -| q | TraceQL query | yes | -| tags | Deprecated tag query format | yes | -| minDuration | Minimum trace duration | yes | -| maxDuration | Maximum trace duration | yes | -| limit | Maximum number of traces to return | yes | -| start | Start timestamp (seconds) | yes | -| end | End timestamp (seconds) | yes | -| spss | Spans per span set | not supported | +| Parameter | Definition | Optional | +|-------------|-------------------------------------------------|----------------| +| q | TraceQL query | yes | +| tags | Deprecated tag query format | yes | +| minDuration | Minimum trace duration | yes | +| maxDuration | Maximum trace duration | yes | +| limit | Maximum number of traces to return. Default: 20 | yes | +| start | Start timestamp (seconds) | yes | +| end | End timestamp (seconds) | yes | +| spss | Spans per span set | not supported | **Example**: ```text @@ -716,6 +720,26 @@ version: "0.1.0" When using the SkyWalking native backend, the following conversions are applied: +### Trace ID Encoding + +SkyWalking native trace IDs are arbitrary strings that may contain characters outside the hexadecimal alphabet +(for example, `2a2e04e8d1114b14925c04a6321ca26c.38.17739924187687539` includes `.` separators). +OTLP and Grafana Tempo require trace IDs to be pure hex strings. + +To satisfy this constraint, every SkyWalking trace ID is encoded by converting each UTF-8 byte of the +original string to two lowercase hex characters: + +``` +Original: 2a2e04e8d1114b14925c04a6321ca26c.38.17739924187687539 +Encoded: 32613265303465386431313134623134393235633034613633323163613236632e33382e3137373339393234313837363837353339 +``` + +- **Encoding**: `traceId.getBytes(UTF-8)` → each byte formatted as `%02x` → concatenated lowercase hex string. +- **Decoding**: hex string → byte array → `new String(bytes, UTF-8)` → original SkyWalking trace ID. + +The encoded trace ID is what appears in all API responses (e.g., the `traceID` field in [Search Traces](#search-traces)). +When calling [Query Trace by ID](#query-trace-by-id-v1), use the encoded hex form as the `{traceId}` path parameter. + ### Span Kind Mapping SkyWalking span types are mapped to OTLP span kinds: @@ -835,5 +859,5 @@ traceQL: ## See Also - [Grafana Tempo TraceQL Documentation](https://grafana.com/docs/tempo/latest/traceql/) - [OpenTelemetry Protocol Specification](https://opentelemetry.io/docs/reference/specification/protocol/) -- [SkyWalking Trace Query](https://skywalking.apache.org/docs/main/next/en/api/query-protocol/) +- [SkyWalking Trace Query](https://skywalking.apache.org/docs/main/next/en/api/query-protocol/#trace) diff --git a/docs/en/changes/changes.md b/docs/en/changes/changes.md index ecab15648e..7c2b664ce9 100644 --- a/docs/en/changes/changes.md +++ b/docs/en/changes/changes.md @@ -161,7 +161,7 @@ * Bump up netty to 4.2.10.Final. * Bump up log4j to 2.25.3 and jackson to 2.18.5. * Remove PowerMock dependency. Replace `Whitebox` with `ReflectUtil` (standard Java reflection + `sun.misc.Unsafe` for final fields) across all modules to support JDK 25+. -* Support TraceQL and Tempo API for Zipkin trace query. +* Support TraceQL and Tempo API for Zipkin and SkyWalking native trace query. * Remove `initExp` from MAL configuration. It was an internal Groovy startup validation mechanism, not an end-user feature. The v2 ANTLR4 compiler performs fail-fast validation at startup natively. * Update hierarchy rule documentation: `auto-matching-rules` in `hierarchy-definition.yml` no longer use Groovy scripts. Rules now use a dedicated expression grammar supporting property access, String methods, if/else, comparisons, and logical operators. All shipped rules are fully compatible. * Activate `otlp-traces` handler in `receiver-otel` by default. diff --git a/docs/en/setup/backend/configuration-vocabulary.md b/docs/en/setup/backend/configuration-vocabulary.md index 1654a83148..a1ef39c2aa 100644 --- a/docs/en/setup/backend/configuration-vocabulary.md +++ b/docs/en/setup/backend/configuration-vocabulary.md @@ -271,6 +271,18 @@ It divided into several modules, each of which has its own settings. The followi | - | - | buildInfoBuildUser | Mock build user for API buildInfo [...] | - | - | buildInfoBuildDate | Mock build date for API buildInfo [...] | - | - | buildInfoGoVersion | Mock go version for API buildInfo [...] +| traceQL | default | - | This module provides the Grafana Tempo-compatible TraceQL query API. It supports both Zipkin and SkyWalking native data sources. See [TraceQL Service](../../api/traceql-service.md) for more details. [...] +| - | - | restHost | Binding IP of RESTful services. [...] +| - | - | restPort | Binding port of RESTful services. Default is Grafana Tempo's native port. [...] +| - | - | enableDatasourceZipkin | Enables the Zipkin data source for the TraceQL API. When `true`, the Zipkin-based handler is mounted at `restContextPathZipkin`. Requires the `receiver-zipkin` module to be enabled. [...] +| - | - | enableDatasourceSkywalking | Enables the SkyWalking native data source for the TraceQL API. When `true`, the SkyWalking-native handler is mounted at `restContextPathSkywalking`. [...] +| - | - | restContextPathZipkin | Web context path for the Zipkin data source endpoint. [...] +| - | - | restContextPathSkywalking | Web context path for the SkyWalking native data source endpoint. [...] +| - | - | restIdleTimeOut | Connector idle timeout of RESTful services (in milliseconds). [...] +| - | - | restAcceptQueueSize | ServerSocketChannel Backlog of RESTful services. [...] +| - | - | lookback | If the query does not provide a start time (default end time is current), this is the default look-back duration for traces and autocomplete tag queries (in milliseconds). [...] +| - | - | zipkinTracesListResultTags | Span tag keys included in the trace list result for the Zipkin data source. These tags are used for trace grouping and shown in the trace list panel. Multiple values are separated by commas. [...] +| - | - | skywalkingTracesListResultTags | Span tag keys included in the trace list result for the SkyWalking native data source. These tags are used for trace grouping and shown in the trace list panel. Multiple values are separated by commas. [...] | alarm | default | - | Read [alarm doc](backend-alarm.md) for more details. [...] | telemetry | - | - | Read [telemetry doc](backend-telemetry.md) for more details. [...] | - | none | - | No op implementation. [...] diff --git a/oap-server/server-query-plugin/promql-plugin/src/test/java/org/apache/skywalking/promql/handler/PromQLApiHandlerTest.java b/oap-server/server-query-plugin/promql-plugin/src/test/java/org/apache/skywalking/promql/handler/PromQLApiHandlerTest.java index f6784f5d10..ce0cfb6f3b 100644 --- a/oap-server/server-query-plugin/promql-plugin/src/test/java/org/apache/skywalking/promql/handler/PromQLApiHandlerTest.java +++ b/oap-server/server-query-plugin/promql-plugin/src/test/java/org/apache/skywalking/promql/handler/PromQLApiHandlerTest.java @@ -18,10 +18,7 @@ package org.apache.skywalking.promql.handler; -import java.time.Instant; import java.time.OffsetDateTime; -import java.time.format.DateTimeFormatter; -import java.time.temporal.TemporalAccessor; import org.apache.skywalking.oap.query.promql.handler.PromQLApiHandler; import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.Test; @@ -38,25 +35,18 @@ public class PromQLApiHandlerTest { "2026-01-20T11:27:18+08:00", "2026-01-20T11:27:18.0+08:00", "2026-01-20T11:27:18.123+08:00", - // "2026-01-20T11:27:18+0800", - // "2026-01-20T11:27:18.0+0800", - // "2026-01-20T11:27:18.123+0800", - // "2026-01-19T19:27:18-08:00", + "2026-01-20T11:27:18+0800", + "2026-01-20T11:27:18.0+0800", + "2026-01-20T11:27:18.123+0800", + "2026-01-19T19:27:18-08:00", "2026-01-19T19:27:18.0-08:00", "2026-01-19T19:27:18.123-08:00", - // "2026-01-19T19:27:18-0800", - // "2026-01-19T19:27:18.0-0800", - // "2026-01-19T19:27:18.123-0800", - // "2026-01-20T03:27:18" + "2026-01-19T19:27:18-0800", + "2026-01-19T19:27:18.0-0800", + "2026-01-19T19:27:18.123-0800", + "2026-01-20T03:27:18" }; - for (String str : testCases) { - DateTimeFormatter.ISO_OFFSET_DATE_TIME.parse(str); - TemporalAccessor t = DateTimeFormatter.ISO_OFFSET_DATE_TIME.parse(str); - - Assertions.assertEquals(1768879638, Instant.from(t).getEpochSecond()); - } - for (String str : testCases) { OffsetDateTime odt = OffsetDateTime.parse(str, PromQLApiHandler.RFC3339_FORMATTER); Assertions.assertEquals(1768879638, odt.toEpochSecond()); diff --git a/oap-server/server-starter/src/main/resources/application.yml b/oap-server/server-starter/src/main/resources/application.yml index 0fd09dcda1..436887690a 100644 --- a/oap-server/server-starter/src/main/resources/application.yml +++ b/oap-server/server-starter/src/main/resources/application.yml @@ -509,7 +509,7 @@ traceQL: restContextPathSkywalking: ${SW_TRACEQL_REST_CONTEXT_PATH_SKYWALKING:/skywalking} restIdleTimeOut: ${SW_TRACEQL_REST_IDLE_TIMEOUT:30000} restAcceptQueueSize: ${SW_TRACEQL_REST_QUEUE_SIZE:0} - # If query not provide the start time, the default look back for traces and autocompleteTags, 1 day in millis + # If query not provide the start time (the default end time is current), the default look back for traces and autocompleteTags, 1 day in millis lookback: ${SW_TRACEQL_LOOKBACK:86400000} # The tags in the list result of traces query, which would be used for trace grouping and shown in the trace list page. zipkinTracesListResultTags: ${SW_TRACEQL_ZIPKIN_TRACES_LIST_RESULT_TAGS:http.method,error}
