feat: add sys.stack_trace system table to dump druid nodes threads

[FrankChen021]

Summary

• add the sys.stack_trace system table for collecting live Java platform-thread snapshots from explicitly selected Druid nodes
• add the /status/stack endpoint and a stateless collector with jstack-style formatting, CPU timing, lock, and deadlock information
• support the maxStackTraceFrameDepth SQL query context and HTTP parameter with a default of 100 and a valid range of 10–1000
• document the table, endpoint, conversion behavior, and virtual-thread limitation

Motivation

Expose targeted runtime diagnostics through SQL so operators and diagnostic AI agents can investigate thread contention, deadlocks, and CPU-heavy threads without collecting stack traces from an entire cluster unintentionally.

Validation

• StatusResourceTest (10 tests)
• SystemSchemaTest (28 tests)
• SystemStackTraceTableTest embedded HTTP/SQL coverage (7 tests)
• CalciteQueryTest#testInformationSchemaTables
• Checkstyle for server, sql, and embedded-tests
• documentation spellcheck
• git diff --check
• Tested on a test cluter

[Copilot]

Pull request overview

Adds a new operational diagnostics capability to Apache Druid by exposing live JVM platform-thread stack snapshots via both an HTTP status endpoint and a new sys.stack_trace SQL system table, enabling targeted investigation of contention/deadlocks/CPU-heavy threads on explicitly selected nodes.

Changes:

• Introduces /status/stack and a stateless StackTraceCollector that produces jstack-style formatted stack traces with optional CPU/lock/deadlock details and configurable frame depth.
• Adds sys.stack_trace system table with required server filter pushdown and support for maxStackTraceFrameDepth via SQL query context / HTTP parameter.
• Updates SQL metadata discovery tests and adds dedicated unit + embedded integration test coverage, plus user-facing documentation.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
website/.spelling	Adds new table/field terms to the website spellcheck allowlist.
sql/src/test/java/org/apache/druid/sql/calcite/schema/SystemSchemaTest.java	Extends system schema tests to include and validate the new stack_trace table behavior and context conversion.
sql/src/test/java/org/apache/druid/sql/calcite/CalciteQueryTest.java	Updates information-schema table enumeration to include sys.stack_trace.
sql/src/main/java/org/apache/druid/sql/calcite/schema/SystemStackTraceTable.java	Implements the sys.stack_trace system table, including server-filter requirement and HTTP collection from selected nodes.
sql/src/main/java/org/apache/druid/sql/calcite/schema/SystemSchema.java	Registers the new stack_trace system table in the system schema.
sql/src/main/java/org/apache/druid/sql/calcite/planner/PlannerContext.java	Propagates maxStackTraceFrameDepth from SQL query context into the Calcite DataContext.
server/src/test/java/org/apache/druid/server/StatusResourceTest.java	Adds unit tests for /status/stack response shape, validation, and formatting details.
server/src/main/java/org/apache/druid/server/StatusResource.java	Adds the /status/stack endpoint, guarded by state-read authorization and with query-param validation.
server/src/main/java/org/apache/druid/server/StackTraceCollector.java	New collector producing thread snapshot DTOs and jstack-style formatted stack output.
embedded-tests/src/test/java/org/apache/druid/testing/embedded/schema/SystemStackTraceTableTest.java	Adds embedded end-to-end coverage for the endpoint and the sys.stack_trace SQL table.
docs/querying/sql-metadata-tables.md	Documents the sys.stack_trace table, its required server filter, and frame-depth conversion semantics.
docs/api-reference/service-status-api.md	Documents the new /status/stack endpoint and its request/response behavior.

Suppressed comments (1)

server/src/main/java/org/apache/druid/server/StackTraceCollector.java:398

• These lock-related getters can return null (the backing fields are annotated @nullable), but the methods are not annotated @nullable. Aligning the nullability annotations on the getters makes the contract explicit to callers and matches the project’s typical JSON DTO style.

    @JsonProperty
    public String getLockName()
    {
      return lockName;
    }

---

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

[FrankChen021]

Severity	Findings
P0	0
P1	0
P2	1
P3	0
Total	1

Severity	Findings
P0	0
P1	0
P2	1
P3	0
Total	1

Reviewed 12 of 12 changed files. Found one cancellation and resource-lifecycle issue in the remote stack-trace request path.

---

This is an automated review by Codex GPT-5.6-Sol

[jtuglu1]

Can you outline the benefits of this approach compared to simply running perf, etc on the Druid process itself? Is this supposed to mirror: https://clickhouse.com/docs/reference/system-tables/trace_log?

[FrankChen021]

Can you outline the benefits of this approach compared to simply running perf, etc on the Druid process itself? Is this supposed to mirror: https://clickhouse.com/docs/reference/system-tables/trace_log?

It's not similar to the trace_log in clickhouse, but similar to the system.stack_trace table in clickhouse.
This provides an easier and simpler way to dump a stack trace to analyze thread usage/potential contention.
With this SQL support, AI agents can get thread dump to do the analysis for us.

[FrankChen021]

Severity	Findings
P0	0
P1	0
P2	1
P3	0
Total	1

Reviewed 12 of 12 changed files. Found one P2 issue: the updated code marks the future cancelled, but does not abort the production Netty HTTP exchange, so interrupted queries can retain transport resources.

---

This is an automated review by Codex GPT-5.6-Sol