Support TraceQL and Tempo API for Zipkin trace query.

[wankai123]

• If this is non-trivial feature, paste the links/URLs to the design doc.
• Update the documentation to include this new feature.
• Tests(including UT, IT, E2E) are added to verify the new feature.
• If it's UI related, attach the screenshots below.

• If this pull request closes/resolves/fixes an existing issue, replace the issue number. Closes [Feature] Support Grafana TraceQL for OTEL and Zipkin traces #13563.
• Update the CHANGES log.

The SkyWalking native trace adaptation will be in the next PR.

[Copilot]

Pull request overview

Adds a new TraceQL/Tempo-compatible HTTP API surface to SkyWalking OAP (focused on Zipkin traces for now), including a new traceql-plugin, path-prefixed handler registration, E2E coverage, and documentation/CHANGELOG updates for the feature introduced in #13563.

Changes:

• Introduce traceql-plugin with Tempo-like endpoints, OTLP conversion utilities, and supporting entities/grammars/proto.
• Extend the shared HTTPServer to support registering handlers under a configurable path prefix (e.g., /zipkin, /skywalking).
• Add E2E cases and expected outputs for Zipkin TraceQL/Tempo API behavior, plus docs/menu/changes updates.

Reviewed changes

Copilot reviewed 46 out of 46 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
test/e2e-v2/script/prepare/setup-e2e-shell/install-jq.sh	Adds jq installation for E2E shell environment.
test/e2e-v2/cases/traceql/zipkin/traceql-cases.yaml	Defines Zipkin TraceQL/Tempo API E2E HTTP queries and validations.
test/e2e-v2/cases/traceql/zipkin/expected/trace-by-id-protobuf-header.yml	Expected content-type header for protobuf trace-by-id response.
test/e2e-v2/cases/traceql/zipkin/expected/trace-by-id-json.yml	Expected OTLP-JSON-like trace-by-id payload structure.
test/e2e-v2/cases/traceql/zipkin/expected/tag-values-status.yml	Expected tag-values response for status.
test/e2e-v2/cases/traceql/zipkin/expected/tag-values-service.yml	Expected tag-values response for service names.
test/e2e-v2/cases/traceql/zipkin/expected/tag-values-http-method.yml	Expected tag-values response for http.method.
test/e2e-v2/cases/traceql/zipkin/expected/search-traces-complex.yml	Expected search response structure for a complex TraceQL query.
test/e2e-v2/cases/traceql/zipkin/expected/search-traces-by-service.yml	Expected search response structure filtered by service.
test/e2e-v2/cases/traceql/zipkin/expected/search-traces-by-duration.yml	Expected search response structure filtered by duration.
test/e2e-v2/cases/traceql/zipkin/expected/search-tags-v2.yml	Expected tag listing response for v2 tags endpoint.
test/e2e-v2/cases/traceql/zipkin/expected/search-tags-v1.yml	Expected tag listing response for v1 tags endpoint.
test/e2e-v2/cases/traceql/zipkin/expected/buildinfo.yml	Expected buildinfo response shape.
test/e2e-v2/cases/traceql/zipkin/e2e.yaml	New E2E scenario wiring (compose env + tool install + verify).
test/e2e-v2/cases/traceql/zipkin/docker-compose.yml	Compose environment enabling Zipkin receiver/query and TraceQL service.
oap-server/server-starter/src/main/resources/application.yml	Adds traceQL module configuration and defaults (host/port/context paths).
oap-server/server-starter/pom.xml	Adds traceql-plugin dependency to OAP starter.
oap-server/server-query-plugin/zipkin-query-plugin/src/main/java/org/apache/skywalking/oap/query/zipkin/handler/ZipkinQueryHandler.java	Refactors ZipkinQueryHandler to expose internal methods for reuse (service/span/trace/traces).
oap-server/server-query-plugin/traceql-plugin/src/test/java/org/apache/skywalking/oap/query/tempo/parser/TraceQLQueryParserTest.java	Adds unit tests for extracting parameters from TraceQL.
oap-server/server-query-plugin/traceql-plugin/src/main/resources/META-INF/services/org.apache.skywalking.oap.server.library.module.ModuleProvider	Registers TraceQL module provider.
oap-server/server-query-plugin/traceql-plugin/src/main/resources/META-INF/services/org.apache.skywalking.oap.server.library.module.ModuleDefine	Registers TraceQL module define.
oap-server/server-query-plugin/traceql-plugin/src/main/proto/tempopb/tempo.proto	Adds Tempo protobuf definitions used for OTLP/protobuf responses.
oap-server/server-query-plugin/traceql-plugin/src/main/java/org/apache/skywalking/oap/query/traceql/handler/ZipkinTraceQLApiHandler.java	Implements Zipkin-backed Tempo/TraceQL endpoints and response formatting (JSON/protobuf).
oap-server/server-query-plugin/traceql-plugin/src/main/java/org/apache/skywalking/oap/query/traceql/handler/TraceQLApiHandler.java	Defines the abstract Tempo-like HTTP API surface (buildinfo/search/tags/trace, etc.).
oap-server/server-query-plugin/traceql-plugin/src/main/java/org/apache/skywalking/oap/query/traceql/handler/SkyWalkingTraceQLApiHandler.java	Stub handler for SkyWalking-native traces (planned for later PR).
oap-server/server-query-plugin/traceql-plugin/src/main/java/org/apache/skywalking/oap/query/traceql/entity/TagValuesResponse.java	Response model for tag-values endpoint.
oap-server/server-query-plugin/traceql-plugin/src/main/java/org/apache/skywalking/oap/query/traceql/entity/TagNamesV2Response.java	Response model for v2 tag listing (scoped tags).
oap-server/server-query-plugin/traceql-plugin/src/main/java/org/apache/skywalking/oap/query/traceql/entity/TagNamesResponse.java	Response model for v1 tag listing.
oap-server/server-query-plugin/traceql-plugin/src/main/java/org/apache/skywalking/oap/query/traceql/entity/SearchResponse.java	Response model for trace search results.
oap-server/server-query-plugin/traceql-plugin/src/main/java/org/apache/skywalking/oap/query/traceql/entity/QueryResponse.java	Base class for TraceQL HTTP JSON responses.
oap-server/server-query-plugin/traceql-plugin/src/main/java/org/apache/skywalking/oap/query/traceql/entity/OtlpTraceResponse.java	JSON model for OTLP-like trace-by-id response.
oap-server/server-query-plugin/traceql-plugin/src/main/java/org/apache/skywalking/oap/query/traceql/entity/BuildInfoResponse.java	JSON model for Tempo buildinfo endpoint.
oap-server/server-query-plugin/traceql-plugin/src/main/java/org/apache/skywalking/oap/query/traceql/converter/ZipkinOTLPConverter.java	Converts Zipkin spans/traces into OTLP protobuf and JSON models.
oap-server/server-query-plugin/traceql-plugin/src/main/java/org/apache/skywalking/oap/query/traceql/TraceQLProvider.java	Starts a dedicated HTTP server and registers Zipkin/SkyWalking handlers under path prefixes.
oap-server/server-query-plugin/traceql-plugin/src/main/java/org/apache/skywalking/oap/query/traceql/TraceQLModule.java	Declares new traceQL module.
oap-server/server-query-plugin/traceql-plugin/src/main/java/org/apache/skywalking/oap/query/traceql/TraceQLConfig.java	Adds TraceQL module configuration properties.
oap-server/server-query-plugin/traceql-plugin/src/main/antlr4/org/apache/skywalking/oap/query/tempo/grammar/TraceQLParser.g4	Adds ANTLR parser grammar for TraceQL.
oap-server/server-query-plugin/traceql-plugin/src/main/antlr4/org/apache/skywalking/oap/query/tempo/grammar/TraceQLLexer.g4	Adds ANTLR lexer grammar for TraceQL.
oap-server/server-query-plugin/traceql-plugin/pom.xml	New module build: protobuf + ANTLR generation + dependencies.
oap-server/server-query-plugin/status-query-plugin/src/main/java/org/apache/skywalking/oap/query/debug/DebuggingHTTPHandler.java	Updates debugging endpoints to use renamed ZipkinQueryHandler HTTP methods.
oap-server/server-query-plugin/pom.xml	Adds traceql-plugin as a query-plugin module.
oap-server/server-library/library-server/src/main/java/org/apache/skywalking/oap/server/library/server/http/HTTPServer.java	Adds handler registration with a configurable path prefix.
docs/menu.yml	Adds “TraceQL APIs” to docs navigation.
docs/en/changes/changes.md	Adds changelog entry for TraceQL/Tempo API support for Zipkin queries.
docs/en/api/traceql-service.md	Adds TraceQL service documentation and API descriptions.

Comments suppressed due to low confidence (4)

oap-server/server-query-plugin/traceql-plugin/src/main/java/org/apache/skywalking/oap/query/traceql/handler/ZipkinTraceQLApiHandler.java:279

• The fallback branch returns HttpResponse.ofJson("Unsupported tag value query") with HTTP 200 and a plain JSON string, which doesn't match the documented Tempo tag-values response shape ({"tagValues": [...]}). Consider returning an error status (e.g., 400) with a structured error payload, or an empty TagValuesResponse to keep the response schema stable for clients like Grafana.

            }
        }
        return HttpResponse.ofJson("Unsupported tag value query");
    }

oap-server/server-query-plugin/traceql-plugin/src/main/proto/tempopb/tempo.proto:6

• tempo.proto is missing the ASF license header comment that other .proto files in this repository include. Add the standard Apache license header to keep licensing consistent across the codebase.

syntax = "proto3";

package tempopb;

option java_package = "io.grafana.tempo.tempopb";
option java_multiple_files = true;

oap-server/server-query-plugin/traceql-plugin/src/main/java/org/apache/skywalking/oap/query/traceql/TraceQLProvider.java:95

• This provider registers the /skywalking TraceQL handler even though SkyWalkingTraceQLApiHandler is currently a stub returning "Not implemented yet". Given the PR description says SkyWalking native adaptation will be in the next PR, consider not binding this handler until it is functional (or return 501/404) to avoid exposing a broken endpoint surface to users.

        // Register SkyWalking-compatible Tempo API handler with /skywalking context path
        httpServer.addHandler(
            new SkyWalkingTraceQLApiHandler(getManager()),
            Arrays.asList(HttpMethod.POST, HttpMethod.GET),
            config.getRestContextPathSkywalking()
        );

docs/en/api/traceql-service.md:7

• The doc claims SkyWalking native traces are supported by TraceQL Service, but the implementation currently returns "Not implemented yet" for the /skywalking endpoints. Either adjust the documentation to clearly mark SkyWalking support as pending (next PR) or implement/disable the SkyWalking handler so the docs match actual behavior.

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.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.