@Rocky we wanna use query detail api v2 on starrocks 3.5.16 and it returns 404

For StarRocks version 3.5.16, if the Query Detail API v2 (

/api/v2/query_detail

) is returning a 404 Not Found, it is likely due to one of the following reasons: 1. Version Compatibility While the Query Detail API v2 is documented for the 3.5 release line, it was introduced in later patches or is sometimes listed in documentation that covers upcoming 4.0/4.1 features. * Check v1 first: Verify if the v1 endpoint works:

GET /api/query_detail?event_time=0

. If v1 works but v2 returns 404, the v2 route is likely not available in your specific build (3.5.16). * Note: In some versions of StarRocks, the v2 endpoints were added starting from 3.4.x or 3.5.x patches. If you are on an early 3.5 patch, it might be missing. 2. Configuration Prerequisite The Query Detail API (both v1 and v2) will not function unless query collection is enabled in the FE configuration. * Action: Run the following command in your SQL client to ensure it is enabled:

sql
    ADMIN SET FRONTEND CONFIG ("enable_collect_query_detail_info" = "true");

Note: While disabling this usually returns an empty result rather than a 404, some internal routing might behave differently depending on the deployment. 3. Correct Endpoint and Port Ensure you are using the FE HTTP Port (default is

8030

) and the correct path: * Path:

/api/v2/query_detail

(underscore, not hyphen). * Example Call:

bash
    curl -u root:password "http://<FE_IP>:8030/api/v2/query_detail?event_time=0&is_request_all_frontend=true"

_The

is_request_all_frontend

parameter is exclusive to v2 and allows the current FE to aggregate details from other FEs._ 4. Authentication Ensure you are providing basic authentication (

-u user:password

). While authentication failures typically return 401 or 403, some proxy or security configurations may mask endpoints with a 404 if the user is not recognized. Troubleshooting Steps 1. Test v1:

curl -u root: "http://<FE_IP>:8030/api/query_detail?event_time=0"

2. Verify Config:

SHOW FRONTEND CONFIG LIKE '%enable_collect_query_detail_info%';

3. Check FE Logs: Look at

fe.log

or

fe.warn.log

on the FE node. If the endpoint is unregistered, there might be no log, but if there's a routing error, it will appear there. 4. Leader FE: Ensure you are hitting the Leader FE or that

is_request_all_frontend=true

is used (if supported). If v1 works but v2 consistently returns 404 on 3.5.16, it is highly probable that the v2 endpoint was not yet backported to that specific patch level. You may need to upgrade to a later 3.5 patch (like 3.5.17+) or 4.x to use the v2 features. References • administration/http_interface/query_detail.md • sql-reference/http_sql_api.md

@Rocky v1 works and config is enabled. why there is v2 mentioned in 3.5 doc if there is no support for query detail api v2?

The Query Detail API v2 (

/api/v2/query_detail

) was introduced to support cross-FE query collection (the

is_request_all_frontend

parameter) and to provide a more standard JSON response structure. If you are seeing a 404 Not Found on version 3.5.16 even though v1 works, the reason is likely a mismatch between the current documentation and your specific patch version: 1. Version Availability While the StarRocks 3.5 documentation (Stable) includes the v2 API, this feature was added to the 3.5 branch in a later patch version. * The v2 API and the underlying logic to aggregate query details across FEs (related to PR #61345) were primary features of the 4.0 release line and were backported to the 3.5 stable branch later. * In version 3.5.16, the v2 endpoint may not have been backported yet. It is typically available starting from StarRocks 3.5.18+ or 4.0.0+. 2. Documentation vs. Build The official StarRocks documentation usually reflects the latest state of a minor version branch (e.g., the latest 3.5.x patch). If the v2 API was merged into the

branch-3.5

code recently, the "3.5" docs will show it, even if your specific installation (3.5.16) is slightly behind that change. Recommendation * Continue using v1: For version 3.5.16, the v1 endpoint (

/api/query_detail

) is the stable and supported route. Note that v1 only returns queries that hit the specific FE you are calling; it does not support aggregating results from other FEs. * Upgrade for v2: If you require the v2 features (like

is_request_all_frontend

), you should upgrade to at least StarRocks 3.5.18 or move to the 4.0/4.1 release line. * Verify Endpoint: Just to be sure, confirm you are hitting the FE HTTP port (default

8030

) and that the path is exactly

/api/v2/query_detail

. If you decide to upgrade, you can check the specific release notes for 3.5.18 or 3.5.19 on the StarRocks Releases page to confirm the exact patch where the backport landed. References • administration/http_interface/query_detail.md • release_notes/release-3.5.md

@Rocky there is no 3.5.18 the latest is 3.5.17 and we use 3.5.16

The reason you are seeing a 404 Not Found for the Query Detail API v2 on StarRocks 3.5.16 is that this specific endpoint was not yet included in that patch, despite being mentioned in the 3.5 documentation. Why is it in the 3.5 doc? StarRocks documentation for a minor version branch (like 3.5) typically reflects the latest state of that branch's code. The Query Detail API v2 was a major enhancement (introducing the

is_request_all_frontend

capability) that was primarily targeted for the 4.x release line. While the documentation for the 3.5 branch has been updated to include v2, the actual code for this endpoint is usually backported in a later patch. Based on the release timelines: * StarRocks 3.5.16/3.5.17: These patches focus primarily on stability, security (like OAuth 2.0/JWT), and data lake improvements. The v2 endpoint logic was likely not present in the 3.5.16 build. * Release Discrepancy: Since 3.5.17 is currently the latest version and still does not appear to feature the v2 endpoint, the documentation is likely showing "ahead-of-release" content or features that are only confirmed for the 4.0.x and 4.1.x lines. Solution / Next Steps 1. Use v1 for now: On 3.5.16, you must use

GET /api/query_detail

. Note that v1 only returns queries executed on the specific FE you are calling; it cannot aggregate queries from other FEs. 2. Upgrade to 4.x for v2: If you specifically need the v2 features (such as

is_request_all_frontend

or the wrapped JSON response), you will need to upgrade to StarRocks 4.0.0 or higher. 3. Check Future Patches: If you cannot upgrade to 4.x, keep an eye on the release notes for 3.5.18+. If it is backported to the 3.5 branch, it will be explicitly listed as an "Improvement" or "New Feature" in the release notes. To verify the current status of your FE endpoints, you can check the FE logs (

fe.log

) at startup to see which HTTP routes are being registered. If

/api/v2/query_detail

is missing from that list, the binary simply does not support it. References • administration/http_interface/query_detail.md • release_notes/release-3.5.md References • administration/http_interface/query_detail.md • administration/management/FE_configuration.md

@Rocky If I run that not on specific fe ip but on the service it still gets running queries from the specific fe?

Yes, that is correct. In version 3.5.16, where you are limited to the v1 API (

/api/query_detail

), you will only see queries from the specific FE node that handles the HTTP request. Here is how it works on your version: * Local Cache Only: Each FE maintains its own local memory cache for query details. A query's details are only stored on the FE that acted as the coordinator for that specific query. * Service/Load Balancer Behavior: When you call the API via a service address or load balancer, your request is routed to one of the available FEs. That FE will return only the queries it has in its local memory. * No Aggregation: The v1 API does not have the logic to "reach out" to other FEs to gather their data. The

is_request_all_frontend

parameter, which enables cluster-wide aggregation, is exclusive to the v2 API. How to get all queries in 3.5.16 Since v2 is not available to automate this for you, you have two options: 1. Manual Aggregation: You must iterate through every FE in your cluster (get the list via

SHOW FRONTENDS

) and call the v1 API on each specific FE IP individually, then merge the JSON results in your own script. 2. External Monitoring: Use a tool like Prometheus/Grafana or StarRocks' Audit Loader to export query metadata to a centralized table or external system where you can view the entire cluster's activity in one place. The 404 you are seeing for v2 is because the documentation you're looking at covers the latest state of the 3.5 branch, but the code for that specific endpoint was likely backported in a patch later than 3.5.16 (it is fully supported in 4.0+). References • administration/http_interface/query_detail.md • administration/management/FE_configuration.md References • administration/http_interface/query_detail.md • administration/management/FE_configuration.md

@Rocky is query detal api enabled by default in version 4.0?

No, the Query Detail API is not fully enabled by default in StarRocks version 4.0. While the HTTP endpoint code exists in version 4.0 (unlike in your current 3.5.16 version where it results in a 404), the background collection of query data is disabled by default to save memory and CPU. To use it in version 4.0, you must set the following FE configuration: Required Configuration You must set

enable_collect_query_detail_info

to

true

. * Parameter:

enable_collect_query_detail_info

* Default:

false

* Type: Boolean (Mutable) You can enable it dynamically without restarting the FE by running:

sql
ADMIN SET FRONTEND CONFIG ("enable_collect_query_detail_info" = "true");

Why it's "off" by default * Data Collection: If this is

false

, the FEs will not record query details into their memory cache. The API will return an empty list or

code: 0

with no results. * Resource Usage: Collecting every query's detail (including the plan and profile) consumes FE memory. StarRocks leaves this off so you can decide if the overhead is acceptable for your production environment. Summary of version 4.0 improvements In version 4.0, once you enable the collection: 1. v2 is supported: You can use

GET /api/v2/query_detail

. 2. Cluster-wide view: You can pass

is_request_all_frontend=true

to get a unified view of all queries across all FEs from a single API call. 3. Standard JSON: The response format is standardized with a

result

wrapper. References • administration/http_interface/query_detail.md • administration/management/FE_configuration.md References • administration/http_interface/query_detail.md • release_notes/release-4.0.md • administration/management/FE_configuration.md

@Rocky can I add filters when using query detail api? for instance if I want only isQuery = true?

No, the Query Detail API does not support a server-side filter for

isQuery

. According to the documentation, the API only supports the following query parameters for filtering: 1.

event_time

(Required): A lower bound filter. You must pass a timestamp (or

0

to get all cached items). 2.

user

(Optional): Filters the results to a specific username (case-insensitive). 3.

is_request_all_frontend

(Optional, v2 only): Aggregates results from all FEs. How to filter for

isQuery

While

isQuery

is a field returned in the JSON response for each query, you cannot pass it in the URL (e.g.,

?isQuery=true

will be ignored by the server). To get only actual queries (and exclude other statements), you must filter the results on the client side after receiving the JSON response. Example using

curl

and `jq`: If you want to filter for

isQuery: true

from the command line:

bash
# For v1 (your current version)
curl -u root: "http://<FE_IP>:<FE_HTTP_PORT>/api/query_detail?event_time=0" | jq '.[] | select(.isQuery == true)'

# For v2 (version 4.0+)
curl -u root: "http://<FE_IP>:<FE_HTTP_PORT>/api/v2/query_detail?event_time=0&is_request_all_frontend=true" | jq '.result[] | select(.isQuery == true)'

Summary of what you can filter via URL: Parameter | Support | Description

event_time

| Yes | Returns items newer than this internal timestamp.

user

| Yes | Returns items for a specific user.

isQuery

| No | Must be filtered in your application/script.

state

| No | Must be filtered in your application/script. References • administration/http_interface/query_detail.md References • administration/http_interface/query_detail.md • administration/management/FE_configuration.md

@Rocky so can I connect that query detail api to some monitoring framework?

Yes, you can connect the Query Detail API to monitoring frameworks, but it is typically used for real-time/live dashboards rather than long-term historical analysis. Depending on your monitoring stack, here are the three most common ways to integrate it: 1. Grafana (Direct Connection) If you use Grafana, you can visualize the Query Detail API results without a middleman: * Plugin: Install the JSON API Datasource for Grafana. * Setup: Configure the URL to

http://<FE_IP>:8030/api/v2/query_detail?event_time=0&is_request_all_frontend=true

. * Benefit: You can create a table in Grafana that shows currently running queries, their latency, and the SQL text in real-time. 2. Custom Prometheus Exporter Since Prometheus expects metrics (numbers) rather than JSON logs, you cannot point Prometheus directly at the Query Detail API. * The Approach: Write a small script (Python/Go) that calls the API, counts items (e.g., "number of queries with latency > 1s"), and exports them as Prometheus gauges. * Note: For standard metrics like "Queries Per Second" or "CPU Usage," you should use the built-in StarRocks

/metrics

endpoint instead, which is natively supported by Prometheus. 3. The "Standard" Alternative: Audit Loader (Recommended) If your goal is to monitor query performance, StarRocks experts typically recommend the Audit Loader plugin instead of polling the API. * How it works: It automatically sinks every query's detail (user, SQL, execution time, memory used) into a StarRocks table (e.g.,

starrocks_audit_db*.starrocks_audit_tbl*

). * Monitoring: You then point Grafana at that table using the standard MySQL/StarRocks connector. * Why use this over the API? * Persistence: The API only holds a limited number of queries in memory. The Audit Loader table stores history for days or weeks. * Scalability: Querying a table is more efficient for large-scale analysis than parsing large JSON blobs from an HTTP API. Summary: Which one should you choose? * Use the Query Detail API if you want to build a "Top" or "Live Activity" dashboard to see what is running right now. * Use the Audit Loader if you want to monitor trends, find the slowest queries from yesterday, or see which users are consuming the most resources over time. References • administration/management/audit_loader.md • administration/http_interface/query_detail.md • administration/management/monitoring/Monitor_and_Alert.md References • administration/management/audit_loader.md • administration/http_interface/query_detail.md • administration/management/monitoring/Monitor_and_Alert.md • administration/management/monitoring/metrics.md References • administration/http_interface/query_detail.md • administration/management/audit_loader.md • administration/management/monitoring/Monitor_and_Alert.md • administration/management/monitoring/metrics.md

@Rocky AuditLoader catches finished queries not currently runnings right? if I want currently running ones I should use query detail api?

Correct. Your understanding is spot on: * Audit Loader writes data only after a query has finished. It is the best tool for historical analysis, such as "How much data did we scan yesterday?" or "Which user ran the most queries last week?" * Query Detail API captures queries in real-time. It can show queries that are still in the

RUNNING

state. If you are looking to monitor currently running queries, here are your best options: 1. Query Detail API (Best for JSON/HTTP Monitoring) As you noted, this API includes queries that haven't finished yet. * State field: In the JSON response, the

state

field will be

RUNNING

. * Unfinished indicators: For running queries,

endTime

and

latency

will be

-1

. 2. SQL Commands (Best for Manual or SQL-based Monitoring) If you prefer to stay within a SQL interface (or use a monitoring tool that speaks MySQL/JDBC), you can use these commands: *

show proc '/global_current_queries'

: (Recommended for v3.4+) Shows all queries currently running across the entire cluster. *

show proc '/current_queries'

: Shows queries running only on the FE node you are currently connected to. *

SHOW PROCESSLIST

: The classic way to see active connections and their current state. Comparison Table Feature | Audit Loader | Query Detail API |

global_current_queries

Status | Finished queries only | Running & Finished | Running only Persistence | Long-term (Table-based) | Short-term (Memory cache) | Instantaneous (Live) Format | SQL Table | JSON via HTTP | SQL Table Best Use Case | Historical reporting | Real-time monitoring | Quick manual check Recommendation: For a "Live Dashboard" in a monitoring framework like Grafana, the Query Detail API (with the JSON API datasource) or

show proc '/global_current_queries'

(with the StarRocks datasource) are your best bets. References • administration/http_interface/query_detail.md • using_starrocks/running_queries.md • administration/management/audit_loader.md References • administration/http_interface/query_detail.md • using_starrocks/running_queries.md • administration/management/audit_loader.md • sql-reference/sql-statements/cluster-management/nodes_processes/SHOW_RUNNING_QUERIES.md References • using_starrocks/running_queries.md • administration/management/resource_management/query_queues.md • sql-reference/sql-statements/cluster-management/nodes_processes/SHOW_RUNNING_QUERIES.md • administration/management/monitor_manage_big_queries.md