unbridled-41 opened a new issue, #4256:
URL: https://github.com/apache/rocketmq-dashboard/issues/4256
## Problem
The `rmq.message.query` and `rmq.message.trace` tools read their `cluster`
input into the instance-id slot: `MessageQueryToolHandler.java:48` and
`MessageTraceToolHandler.java:47` assign `String instanceId = (String)
input.get("cluster")` and pass it to `MessageService.queryMessages(instanceId,
...)` / `getMessageTrace(instanceId, ...)`, which resolve a registered instance
via `providerRegistry.byInstanceId` →
`RuntimeAdminClientResolver.resolveInstance` →
`instanceRepository.findByIdentifier` (unique instance name or numeric id,
`RuntimeAdminClientResolver.java:31-37`).
Meanwhile the consumers of these tools supply a **cluster** id, not an
instance identifier:
- The AI page's tool dialog prefills every field named `cluster` with the
selected cluster id (`web/src/pages/ai/index.tsx`, `buildToolInputTemplate` ←
`listClusters()` → `cluster.id`).
- `rmq.cluster.list` and every other catalog surface exposes cluster ids
only; no tool output contains an instance id.
- The catalog declares no `description` for the `cluster` property, so the
model gets no guidance either.
- `requiredCapabilities: []` means `ToolGatewayService.enforceCapabilities`
skips validation of the value entirely for these two tools.
## Evidence
1. Open the AI page, select a cluster and open the tool dialog for
`rmq.message.query`: the JSON template is pre-filled with `"cluster":
"<clusterId>"`.
2. Fill a topic and execute: the handler passes the cluster id where
`findByIdentifier` expects an instance name → `404 Instance not found:
<clusterId>`.
3. The same routing failure for the two list tools was fixed in commit
206314b9 (#4115), whose description records the exact failure mode ("404
Instance not found: DefaultCluster on every call") — the two message handlers
kept the pre-fix pattern.
A second data point: the handlers' own unit tests
(`MessageQueryToolHandlerTest`) pin instance-identifier semantics (`"cluster":
"instance-a"`), so the field name, the tool description ("Query messages in a
RocketMQ instance…") and the runtime resolution disagree.
## Impact
Both message tools are unusable from the manual tool dialog (every run fails
with a misleading 404 naming a cluster id), and chat runs fail whenever the
model follows the field name instead of guessing an instance identifier. No
silent wrong-instance queries occur — the failure is always loud.
## Possible directions (need a maintainer decision)
1. Make the two runtime tools instance-addressed: rename the input to
`instance` and relax `ToolCatalog.validateClusterConvention`
(ToolCatalog.java:141-146) to accept `cluster` or `instance` as the declared
target field. Note `enforceCapabilities` hardcodes `input.get("cluster")` and
would need to read the declared field if `requiredCapabilities` is ever added
to these tools.
2. Keep `cluster` and resolve it to an instance server-side — needs a
resolution policy (metadata-DB lookup by
`rmq_topic.cluster_id`/`rmq_consumer_group.cluster_id` with silent gaps for
unsynchronized inventory; default-instance assumption; per-instance
`discoverClusters` probing).
3. Minimal documentation stopgap: describe the field as an instance
identifier in the catalog and stop the UI from blanket-prefilling it.
## Related work
- #4115 (merged) fixed the identical routing defect for `rmq.topic.list` /
`rmq.group.list` by routing into their cluster-scoped branches; the message
tools have no cluster-scoped branch to route into.
- Open PR #4148 adds paging/`includeBody`/`traceTopic` to these same two
tools but does not touch the target-id routing.
- The framework currently has no cluster→instance resolution mechanism;
`ClusterVO` carries no instance id.
--
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]
