Repository navigation
Add an opt-in port for GraphQL, the AI agent conversation API and the TTL lookup, apart from the agent ports - #14238
Conversation
There was a problem hiding this comment.
Warning
Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.
Copilot review overview
5 open issues
This module compiles againstorg.apache.skywalking.oap.server.core.*types (e.g.,CoreModule,… · NewrestAcceptQueueSizeis wired toHTTPServerConfig.acceptQueueSize(...), which typically controls… · New WhenrestPort == 0, the registeredHTTPHandlerRegisterimplementation dereferences… · New This 'find a free port by binding to 0 and closing' pattern is inherently racy: another… · New The e2e assertsPOST /graphqlon the core REST port returns405. If the route is removed… · New
What changed in this PR
Adds a new opt-in query-server module to allow serving native query APIs (GraphQL, AI agent conversation endpoints, and TTL lookup) on a dedicated HTTP port, separate from agent/receiver ports, while preserving current behavior by default.
Changes:
- Introduces
query-server-pluginthat either starts its own HTTP server (whenrestPort > 0) or forwards handler registration to the core REST server (whenrestPort == 0). - Migrates GraphQL,
/status/config/ttl, and AI agent conversation HTTP handler registration to useQueryServerModule’sHTTPHandlerRegister. - Adds docs + e2e coverage for the separated query port, and updates CI to run the new e2e case.
| File | Description |
|---|---|
| test/e2e-v2/cases/storage/expected/config-dump.yml | Adds expected default query-server.* config keys to config dump snapshot |
| test/e2e-v2/cases/simple/query-port/expected/query-port-ok.yml | Adds sentinel expected output for the new query-port e2e case |
| test/e2e-v2/cases/simple/query-port/e2e.yaml | Adds e2e scenario validating query APIs move to the query port |
| test/e2e-v2/cases/simple/query-port/docker-compose.yml | Configures OAP/query/receiver ports for the new e2e case |
| oap-server/server-tools/data-generator/src/main/resources/application.yml | Adds query-server config section to data-generator config |
| oap-server/server-starter/src/main/resources/application.yml | Documents and introduces query-server configuration keys |
| oap-server/server-query-plugin/query-server-plugin/src/test/java/org/apache/skywalking/oap/query/server/QueryServerModuleProviderTest.java | Adds unit tests for forwarding vs dedicated-port behavior |
| oap-server/server-query-plugin/query-server-plugin/src/main/resources/META-INF/services/org.apache.skywalking.oap.server.library.module.ModuleProvider | Registers QueryServerModuleProvider via SPI |
| oap-server/server-query-plugin/query-server-plugin/src/main/resources/META-INF/services/org.apache.skywalking.oap.server.library.module.ModuleDefine | Registers QueryServerModule via SPI |
| oap-server/server-query-plugin/query-server-plugin/src/main/java/org/apache/skywalking/oap/query/server/QueryServerModuleProvider.java | Implements query-server provider (dedicated HTTP server or forward-to-core) |
| oap-server/server-query-plugin/query-server-plugin/src/main/java/org/apache/skywalking/oap/query/server/QueryServerModule.java | Declares the new query-server module and services |
| oap-server/server-query-plugin/query-server-plugin/src/main/java/org/apache/skywalking/oap/query/server/QueryServerConfig.java | Adds config model for query-server HTTP settings + TLS |
| oap-server/server-query-plugin/query-server-plugin/pom.xml | Adds new Maven module for query-server plugin |
| oap-server/server-query-plugin/query-graphql-plugin/src/main/java/org/apache/skywalking/oap/query/graphql/GraphQLQueryProvider.java | Moves GraphQL HTTP handler registration from core REST to query-server |
| oap-server/server-query-plugin/query-graphql-plugin/pom.xml | Adds dependency on the new query-server plugin |
| oap-server/server-query-plugin/pom.xml | Registers query-server-plugin as a submodule |
| oap-server/server-admin/status/src/test/java/org/apache/skywalking/oap/server/admin/status/StatusModuleProviderTest.java | Updates status unit test to resolve public REST register via query-server |
| oap-server/server-admin/status/src/main/java/org/apache/skywalking/oap/server/admin/status/StatusModuleProvider.java | Binds /status/config/ttl via query-server register and updates docs/comments |
| oap-server/server-admin/status/pom.xml | Adds dependency on query-server plugin to bind TTL handler to query server |
| oap-server/analyzer/ai-agent-conversation/src/main/java/org/apache/skywalking/oap/server/ai/agent/conversation/AIAgentConversationProvider.java | Moves AI agent conversation HTTP handler registration to query-server |
| oap-server/analyzer/ai-agent-conversation/pom.xml | Adds dependency on query-server plugin |
| docs/en/setup/backend/configuration-vocabulary.md | Documents query-server configuration vocabulary and clarifies TTL binding |
| docs/en/setup/backend/backend-expose.md | Documents how to expose query APIs via the separated query server |
| docs/en/setup/backend/admin-api/status.md | Updates status API docs to reference query-server for TTL binding/discovery |
| docs/en/setup/backend/admin-api/readme.md | Updates admin docs to mention query-server as the query surface alternative |
| docs/en/setup/backend/admin-api/inspect.md | Updates discovery guidance to prefer query-server host/port when enabled |
| docs/en/security/README.md | Documents security implications and port separation (query vs receiver) |
| docs/en/changes/changes.md | Adds changelog entry for query-server feature |
| .github/workflows/skywalking.yaml | Adds the new query-port e2e scenario to CI matrix |
Review effort: Lite
… TTL lookup, apart from the agent ports The core REST port (12800) serves GraphQL next to the HTTP receivers, so a client that reports over HTTP, such as the browser monitoring SDK, reaches the same port as the query API. receiver-sharing-server could already move the receivers off; the query side had no way to move. The new query-server module exposes HTTPHandlerRegister. With SW_QUERY_SERVER_REST_PORT above 0 it starts its own HTTP server, with its own host, context path and TLS settings; with the default 0 it forwards every handler to the core REST server, so nothing changes. GraphQL, the AI agent conversation view and files, and /status/config/ttl register through it.
36b5349 to
c165191
Compare
kezhenxu94
left a comment
There was a problem hiding this comment.
LGTM. Checked the module wiring: every module that now resolves HTTPHandlerRegister from query-server (GraphQL, ai-agent-conversation, status) declares QueryServerModule.NAME in requiredModules(), so the lazy coreRESTRegister in the port-0 fallback is always resolved before any addHandler call. The fallback path keeps the old behaviour, and the new jar reaches oap-libs transitively through query-graphql-plugin. Every in-repo application.yml that boots GraphQL has the new block. One note inline about upgrades.
| * BanyanDB: fix dropping a measure, as removing a runtime rule or changing a metric's function with `allowStorageChange` does, leaving its pre-built TopN aggregations behind on the dropped measure. The drop deleted a TopN aggregation named after the measure, but each is named after its `bydb-topn.yml` rule, so none was deleted, and a measure created again under the same name found the old ones in place and kept their old definition. It now deletes every TopN aggregation whose source is the dropped measure, and when one fails to delete it stops before the measure, so the removal fails and is tried again instead of leaving that aggregation behind. | ||
| * Fix the trace and Zipkin queries putting an event of eBPF profiling on the wrong span, or losing it. A server-side event (a request read, or a response written, on the server, attached to the client's span through its trace context) belongs on the server's span, while the client-side events of that span stay on it; but the span an event went to was remembered by the span the event named alone, so every event of a span followed its first one. On a Zipkin trace, a span that took both its own events and the server-side events of its client span was also rebuilt twice, keeping only one of the two sets. Each event now goes to the span of its own side. | ||
| * Fix span-attached events of eBPF profiling overwriting each other. An event's storage ID was its segment ID, start time and name. Rover sends a Zipkin event with an empty segment ID, so two Zipkin events with the same name and start time, in any two traces, had one ID, and so could two SkyWalking events on different spans of one segment. Elasticsearch kept only the one written last, and JDBC, whose row key is the same ID, cannot hold both. The ID now also carries the trace ID and span ID. | ||
| * Add the `query-server` module, so the native query APIs can have their own port, apart from the ports agents report to. Set `SW_QUERY_SERVER_REST_PORT` to a port greater than 0, and GraphQL (`/graphql`), the AI agent conversation view and files (`/ai-agent/conversations/*`), and `/status/config/ttl` move from the core REST port (default `12800`) to it, with their own host, context path and TLS settings (`SW_QUERY_SERVER_REST_*`). Point the UI's `queryUrl`, `swctl --base-url` and other GraphQL clients at the new port. With the default `0`, nothing changes. Together with `receiver-sharing-server`, no agent or query traffic is left on the core ports. |
There was a problem hiding this comment.
"With the default 0, nothing changes" holds only for the shipped application.yml. GraphQL, status and ai-agent-conversation now list query-server in requiredModules(), so an operator who mounts their own application.yml from an earlier release (no query-server: block) will see OAP fail at boot with ModuleNotFoundException (BootstrapFlow). Setting SW_QUERY_SERVER=- fails the same way. Could you add a sentence saying a custom application.yml needs the new query-server: block?
There was a problem hiding this comment.
I am following the existing module config style. @wankai123 asked the same.
receiver-sharing-server:
selector: ${SW_RECEIVER_SHARING_SERVER:default}
default:
# For HTTP server
restHost: ${SW_RECEIVER_SHARING_REST_HOST:0.0.0.0}
restPort: ${SW_RECEIVER_SHARING_REST_PORT:0}
....


Give the native query APIs a port of their own
By default the core REST port (
core.restPort,12800) serves GraphQL next to the HTTP receivers. A client that reports over HTTP, such as the browser monitoring SDK running in end users' browsers, has to reach12800, so the query API is reachable wherever that SDK is.receiver-sharing-servercould already move the receivers to their own ports; the query APIs had no way to move.query-servermodule (oap-server/server-query-plugin/query-server-plugin) providesHTTPHandlerRegister. WithSW_QUERY_SERVER_REST_PORTabove0it starts its own HTTP server, with its own host, context path, idle timeout, connection limit, request-header limit and TLS settings (SW_QUERY_SERVER_REST_*). With the default0it forwards every handler to the core REST server, so nothing changes.POST /graphql), the AI agent conversation view and files (/ai-agent/conversations/*), and/status/config/ttlregister through it. The rest of/status/*stays on the admin server (17128).9411), and OAP's Zipkin query already has its own port. PromQL, LogQL and TraceQL keep their own ports too.queryUrl, and its Data retention page reads the TTL through GraphQL (getRecordsTTL/getMetricsTTL); its management APIs already use the admin port.swctlsends GraphQL and the conversation view to the host of--base-url, and its admin commands,/status/config/ttlincluded, to the admin port. MCP's OAP query tools use GraphQL. The Helm chart gets an opt-inoap.ports.query(withreceiver-grpc/receiver-rest) in Support OAP's separated receiver and query ports skywalking-helm#207.GraalVMOAPServerStartUp,AcceptedModules), so it needs thequery-servermodule and provider and thequery-server:block when it moves to this OAP.Tests:
QueryServerModuleProviderTest: with port0a handler goes to the core REST register; with a port, a handler answers on that port and core REST is never looked up.StatusModuleProviderTest.publicRestRegisterResolvesViaCoreModuleis renamedpublicRestRegisterResolvesViaQueryServerModuleand mocks thequery-serverlookup instead of the core one, since the TTL handler now registers through it.simple/query-port: agents report to the receiver port11811, and tenswctlqueries run on the query port12810. A port check confirms GraphQL, the TTL lookup and the conversation view answer on12810and not on12800(POST /graphqlon12800is405, because no handler left there takesPOST), and/healthcheckstays on12800.storage/expected/config-dump.ymlgains the tenquery-server.*keys of the default config.Checked locally: checkstyle;
install javadoc:javadoc -Pallon JDK 11 (0 javadoc errors); the full unit-test suite (8296 tests, 0 failures, 0 errors); a live boot with and without the port; the new e2e case (11/11 passed).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 #.
Update the
CHANGESlog.🤖 Generated with Claude Code