Skip to content

Add an opt-in port for GraphQL, the AI agent conversation API and the TTL lookup, apart from the agent ports - #14238

Merged
wu-sheng merged 1 commit into
masterfrom
feat/query-server-port
Nov 16, 2026
Merged

wu-sheng merged 1 commit into
masterfrom
feat/query-server-port

Conversation

@wu-sheng

@wu-sheng wu-sheng commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

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 reach 12800, so the query API is reachable wherever that SDK is. receiver-sharing-server could already move the receivers to their own ports; the query APIs had no way to move.

  • A new query-server module (oap-server/server-query-plugin/query-server-plugin) provides HTTPHandlerRegister. With SW_QUERY_SERVER_REST_PORT above 0 it 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 default 0 it forwards every handler to the core REST server, so nothing changes.
  • GraphQL (POST /graphql), the AI agent conversation view and files (/ai-agent/conversations/*), and /status/config/ttl register through it. The rest of /status/* stays on the admin server (17128).
  • Zipkin is left alone: upstream Zipkin serves collection and query on one port (9411), and OAP's Zipkin query already has its own port. PromQL, LogQL and TraceQL keep their own ports too.
  • Clients only change a URL. Horizon sends GraphQL and the conversation API to queryUrl, and its Data retention page reads the TTL through GraphQL (getRecordsTTL / getMetricsTTL); its management APIs already use the admin port. swctl sends GraphQL and the conversation view to the host of --base-url, and its admin commands, /status/config/ttl included, to the admin port. MCP's OAP query tools use GraphQL. The Helm chart gets an opt-in oap.ports.query (with receiver-grpc / receiver-rest) in Support OAP's separated receiver and query ports skywalking-helm#207.
  • The GraalVM distro registers and accepts its modules by hand (GraalVMOAPServerStartUp, AcceptedModules), so it needs the query-server module and provider and the query-server: block when it moves to this OAP.

Tests:

  • QueryServerModuleProviderTest: with port 0 a handler goes to the core REST register; with a port, a handler answers on that port and core REST is never looked up.
  • StatusModuleProviderTest.publicRestRegisterResolvesViaCoreModule is renamed publicRestRegisterResolvesViaQueryServerModule and mocks the query-server lookup instead of the core one, since the TTL handler now registers through it.
  • New e2e simple/query-port: agents report to the receiver port 11811, and ten swctl queries run on the query port 12810. A port check confirms GraphQL, the TTL lookup and the conversation view answer on 12810 and not on 12800 (POST /graphql on 12800 is 405, because no handler left there takes POST), and /healthcheck stays on 12800.
  • storage/expected/config-dump.yml gains the ten query-server.* keys of the default config.

Checked locally: checkstyle; install javadoc:javadoc -Pall on 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 CHANGES log.

🤖 Generated with Claude Code

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
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-plugin that either starts its own HTTP server (when restPort > 0) or forwards handler registration to the core REST server (when restPort == 0).
  • Migrates GraphQL, /status/config/ttl, and AI agent conversation HTTP handler registration to use QueryServerModule’s HTTPHandlerRegister.
  • 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

@wu-sheng wu-sheng added backend OAP backend related. feature New feature labels Nov 16, 2026
@wu-sheng wu-sheng added this to the 11.2.0 milestone Nov 16, 2026
… 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.
@wu-sheng
wu-sheng force-pushed the feat/query-server-port branch from 36b5349 to c165191 Compare November 16, 2026 06:53

@kezhenxu94 kezhenxu94 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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}
....

@wu-sheng
wu-sheng merged commit 6566fec into master Nov 16, 2026
492 of 495 checks passed
@wu-sheng
wu-sheng deleted the feat/query-server-port branch November 16, 2026 10:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backend OAP backend related. feature New feature

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants