Feature: add pg_query_state runtime API to gp_stats_collector

.github/workflows/gpsc-ci.yaml

@@ -0,0 +1,316 @@
+# --------------------------------------------------------------------
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed
+# with this work for additional information regarding copyright
+# ownership. The ASF licenses this file to You under the Apache
+# License, Version 2.0 (the "License"); you may not use this file
+# except in compliance with the License. You may obtain a copy of the
+# License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied. See the License for the specific language governing
+# permissions and limitations under the License.
+#
+# --------------------------------------------------------------------
+# gp_stats_collector CI Workflow
+#
+# Builds Cloudberry with --with-gp-stats-collector (the default in
+# configure-cloudberry.sh), stands up a demo cluster with the extension
+# preloaded, and runs the gp_stats_collector regression suites.
+#
+# Scoped to changes that can affect the extension or the core patches it
+# depends on, so it does not run on every unrelated push.
+# --------------------------------------------------------------------
+name: GPSC CI Pipeline
+
+on:
+  push:
+    branches:
+      - 'pgqs-**'
+  pull_request:
+    paths:
+      - 'gpcontrib/gp_stats_collector/**'
+      - '.github/workflows/gpsc-ci.yaml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+
+  test-gpsc:
+    name: Build and Test gp_stats_collector (${{ matrix.os }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu22.04
+            image: apache/incubator-cloudberry:cbdb-build-ubuntu22.04-latest
+          - os: rocky8
+            image: apache/incubator-cloudberry:cbdb-build-rocky8-latest
+          - os: rocky9
+            image: apache/incubator-cloudberry:cbdb-build-rocky9-latest
+    container:
+      image: ${{ matrix.image }}
+      options: >-
+        --user root
+        -h cdw
+
+    steps:
+      - name: Checkout Cloudberry source
+        uses: actions/checkout@v4
+        with:
+          # Init/build scripts hardcode a "cloudberry" source dir name
+          # (e.g. create-cloudberry-demo-cluster.sh uses ${SRC_DIR}/../cloudberry),
+          # so the checkout path must be "cloudberry", not the repo name.
+          path: cloudberry
+          submodules: recursive
+
+      - name: Cloudberry Environment Initialization
+        shell: bash
+        env:
+          SRC_DIR: ${{ github.workspace }}/cloudberry
+        run: |
+          set -eo pipefail
+          if ! su - gpadmin -c "/tmp/init_system.sh"; then
+            echo "::error::Container initialization failed"
+            exit 1
+          fi
+          mkdir -p "${SRC_DIR}/build-logs"
+          chown -R gpadmin:gpadmin .
+          chmod -R 755 .
+
+      - name: Configure
+        shell: bash
+        env:
+          SRC_DIR: ${{ github.workspace }}/cloudberry
+        run: |
+          set -eo pipefail
+          chmod +x "${SRC_DIR}"/devops/build/automation/cloudberry/scripts/configure-cloudberry.sh
+          if ! time su - gpadmin -c "cd ${SRC_DIR} && SRC_DIR=${SRC_DIR} ${SRC_DIR}/devops/build/automation/cloudberry/scripts/configure-cloudberry.sh"; then
+            echo "::error::Configure failed"
+            exit 1
+          fi
+
+      - name: Build
+        shell: bash
+        env:
+          SRC_DIR: ${{ github.workspace }}/cloudberry
+        run: |
+          set -eo pipefail
+          chmod +x "${SRC_DIR}"/devops/build/automation/cloudberry/scripts/build-cloudberry.sh
+          if ! time su - gpadmin -c "cd ${SRC_DIR} && SRC_DIR=${SRC_DIR} ${SRC_DIR}/devops/build/automation/cloudberry/scripts/build-cloudberry.sh"; then
+            echo "::error::Build failed"
+            exit 1
+          fi
+
+      - name: Create demo cluster (gp_stats_collector preloaded)
+        shell: bash
+        env:
+          SRC_DIR: ${{ github.workspace }}/cloudberry
+        run: |
+          set -eo pipefail
+          chmod +x "${SRC_DIR}"/devops/build/automation/cloudberry/scripts/create-cloudberry-demo-cluster.sh
+          if ! time su - gpadmin -c "cd ${SRC_DIR} && SRC_DIR=${SRC_DIR} ${SRC_DIR}/devops/build/automation/cloudberry/scripts/create-cloudberry-demo-cluster.sh"; then
+            echo "::error::Demo cluster creation failed"
+            exit 1
+          fi
+          # pg_query_state requires the module in shared_preload_libraries.
+          su - gpadmin -c "cd ${SRC_DIR} && \
+            source /usr/local/cloudberry-db/cloudberry-env.sh && \
+            source gpAux/gpdemo/gpdemo-env.sh && \
+            gpconfig -c shared_preload_libraries -v 'gp_stats_collector' && \
+            gpstop -ra"
+
+      - name: Run gp_stats_collector regression suite
+        shell: bash
+        env:
+          SRC_DIR: ${{ github.workspace }}/cloudberry
+        run: |
+          set -eo pipefail
+          chmod +x "${SRC_DIR}"/devops/build/automation/cloudberry/scripts/test-cloudberry.sh
+          # Capture make output to an artifact file: the raw job log gets
+          # truncated by the huge Build step, so tail it here on failure.
+          if ! time su - gpadmin -c "cd ${SRC_DIR} && \
+            source /usr/local/cloudberry-db/cloudberry-env.sh && \
+            source gpAux/gpdemo/gpdemo-env.sh && \
+            SRC_DIR=${SRC_DIR} \
+            PGOPTIONS='' \
+            MAKE_NAME='GPSC Regress' \
+            MAKE_TARGET=installcheck \
+            MAKE_DIRECTORY=--directory=${SRC_DIR}/gpcontrib/gp_stats_collector \
+            ${SRC_DIR}/devops/build/automation/cloudberry/scripts/test-cloudberry.sh \
+              > ${SRC_DIR}/build-logs/gpsc-regress-make.log 2>&1"; then
+            echo "::error::gp_stats_collector installcheck failed"
+            echo "===== gpsc-regress-make.log (tail) ====="
+            tail -120 ${SRC_DIR}/build-logs/gpsc-regress-make.log 2>/dev/null || true
+            echo "===== regression.diffs ====="
+            cat ${SRC_DIR}/gpcontrib/gp_stats_collector/regression.diffs 2>/dev/null || true
+            exit 1
+          fi
+
+      - name: Run pg_query_state suite
+        shell: bash
+        env:
+          SRC_DIR: ${{ github.workspace }}/cloudberry
+        run: |
+          set -eo pipefail
+          if ! time su - gpadmin -c "cd ${SRC_DIR} && \
+            source /usr/local/cloudberry-db/cloudberry-env.sh && \
+            source gpAux/gpdemo/gpdemo-env.sh && \
+            SRC_DIR=${SRC_DIR} \
+            PGOPTIONS='' \
+            MAKE_NAME='GPSC pg_query_state' \
+            MAKE_TARGET=installcheck \
+            MAKE_DIRECTORY=--directory=${SRC_DIR}/gpcontrib/gp_stats_collector/test \
+            ${SRC_DIR}/devops/build/automation/cloudberry/scripts/test-cloudberry.sh \
+              > ${SRC_DIR}/build-logs/gpsc-pqs-make.log 2>&1"; then
+            echo "::error::pg_query_state suite failed"
+            echo "===== gpsc-pqs-make.log (tail) ====="
+            tail -120 ${SRC_DIR}/build-logs/gpsc-pqs-make.log 2>/dev/null || true
+            echo "===== test/regression.diffs ====="
+            cat ${SRC_DIR}/gpcontrib/gp_stats_collector/test/regression.diffs 2>/dev/null || true
+            exit 1
+          fi
+
+      - name: Upload regression artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: gpsc-results-${{ matrix.os }}
+          path: |
+            cloudberry/gpcontrib/gp_stats_collector/regression.out
+            cloudberry/gpcontrib/gp_stats_collector/regression.diffs
+            cloudberry/gpcontrib/gp_stats_collector/results/
+            cloudberry/gpcontrib/gp_stats_collector/test/results/
+            cloudberry/gpcontrib/gp_stats_collector/test/regression.diffs
+            cloudberry/build-logs/
+          retention-days: 7
+
+  # Runs the pg_query_state isolation2 suite (multi-session / happy-path checks
+  # that plain pg_regress cannot express).  The fault injector (gp_inject_fault)
+  # is enabled by default (--enable-faultinjector=yes), so no debug build is
+  # needed.
+  test-gpsc-isolation2:
+    name: pg_query_state multi-session (gp_stats_collector)
+    runs-on: ubuntu-latest
+    container:
+      image: apache/incubator-cloudberry:cbdb-build-ubuntu22.04-latest
+      options: >-
+        --user root
+        -h cdw
+
+    steps:
+      - name: Checkout Cloudberry source
+        uses: actions/checkout@v4
+        with:
+          path: cloudberry
+          submodules: recursive
+
+      - name: Cloudberry Environment Initialization
+        shell: bash
+        env:
+          SRC_DIR: ${{ github.workspace }}/cloudberry
+        run: |
+          set -eo pipefail
+          if ! su - gpadmin -c "/tmp/init_system.sh"; then
+            echo "::error::Container initialization failed"
+            exit 1
+          fi
+          mkdir -p "${SRC_DIR}/build-logs"
+          chown -R gpadmin:gpadmin .
+          chmod -R 755 .
+
+      - name: Configure
+        shell: bash
+        env:
+          SRC_DIR: ${{ github.workspace }}/cloudberry
+        run: |
+          set -eo pipefail
+          chmod +x "${SRC_DIR}"/devops/build/automation/cloudberry/scripts/configure-cloudberry.sh
+          if ! time su - gpadmin -c "cd ${SRC_DIR} && SRC_DIR=${SRC_DIR} ${SRC_DIR}/devops/build/automation/cloudberry/scripts/configure-cloudberry.sh"; then
+            echo "::error::Configure failed"
+            exit 1
+          fi
+
+      - name: Build
+        shell: bash
+        env:
+          SRC_DIR: ${{ github.workspace }}/cloudberry
+        run: |
+          set -eo pipefail
+          chmod +x "${SRC_DIR}"/devops/build/automation/cloudberry/scripts/build-cloudberry.sh
+          if ! time su - gpadmin -c "cd ${SRC_DIR} && SRC_DIR=${SRC_DIR} ${SRC_DIR}/devops/build/automation/cloudberry/scripts/build-cloudberry.sh"; then
+            echo "::error::Build failed"
+            exit 1
+          fi
+
+      - name: Build isolation2 harness
+        shell: bash
+        env:
+          SRC_DIR: ${{ github.workspace }}/cloudberry
+        run: |
+          set -eo pipefail
+          if ! time su - gpadmin -c "cd ${SRC_DIR} && \
+            source /usr/local/cloudberry-db/cloudberry-env.sh && \
+            make -C src/test/isolation2 install"; then
+            echo "::error::isolation2 harness build failed"
+            exit 1
+          fi
+
+      - name: Create demo cluster (gp_stats_collector preloaded)
+        shell: bash
+        env:
+          SRC_DIR: ${{ github.workspace }}/cloudberry
+        run: |
+          set -eo pipefail
+          chmod +x "${SRC_DIR}"/devops/build/automation/cloudberry/scripts/create-cloudberry-demo-cluster.sh
+          if ! time su - gpadmin -c "cd ${SRC_DIR} && SRC_DIR=${SRC_DIR} ${SRC_DIR}/devops/build/automation/cloudberry/scripts/create-cloudberry-demo-cluster.sh"; then
+            echo "::error::Demo cluster creation failed"
+            exit 1
+          fi
+          su - gpadmin -c "cd ${SRC_DIR} && \
+            source /usr/local/cloudberry-db/cloudberry-env.sh && \
+            source gpAux/gpdemo/gpdemo-env.sh && \
+            gpconfig -c shared_preload_libraries -v 'gp_stats_collector' && \
+            gpstop -ra"
+
+      - name: Run pg_query_state isolation2 suite
+        shell: bash
+        env:
+          SRC_DIR: ${{ github.workspace }}/cloudberry
+        run: |
+          set -eo pipefail
+          if ! su - gpadmin -c "cd ${SRC_DIR} && \
+            source /usr/local/cloudberry-db/cloudberry-env.sh && \
+            source gpAux/gpdemo/gpdemo-env.sh && \
+            make -C gpcontrib/gp_stats_collector/test/isolation2 installcheck \
+              > ${SRC_DIR}/build-logs/gpsc-iso2.log 2>&1"; then
+            echo "::error::pg_query_state isolation2 suite failed"
+            echo "===== gpsc-iso2.log (tail) ====="
+            tail -100 ${SRC_DIR}/build-logs/gpsc-iso2.log 2>/dev/null || true
+            echo "===== isolation2 regression.diffs ====="
+            cat ${SRC_DIR}/gpcontrib/gp_stats_collector/test/isolation2/regression.diffs 2>/dev/null || true
+            exit 1
+          fi
+
+      - name: Upload isolation2 artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: gpsc-iso2-results
+          path: |
+            cloudberry/gpcontrib/gp_stats_collector/test/isolation2/results/
+            cloudberry/gpcontrib/gp_stats_collector/test/isolation2/regression.diffs
+            cloudberry/build-logs/
+          retention-days: 7

LICENSE

@@ -200,6 +200,28 @@
    See the License for the specific language governing permissions and
    limitations under the License.
 
+================================================================================
+This product includes software derived from pg_query_state
+(https://github.com/postgrespro/pg_query_state), under the PostgreSQL License:
+
+   Copyright (c) 2016-2025, Postgres Professional
+
+   Permission to use, copy, modify, and distribute this software and its
+   documentation for any purpose, without fee, and without a written agreement
+   is hereby granted, provided that the above copyright notice and this
+   paragraph and the following two paragraphs appear in all copies.
+
+   IN NO EVENT SHALL POSTGRES PROFESSIONAL BE LIABLE TO ANY PARTY FOR DIRECT,
+   INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST
+   PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN
+   IF POSTGRES PROFESSIONAL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+   POSTGRES PROFESSIONAL SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT
+   NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+   PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS,
+   AND POSTGRES PROFESSIONAL HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT,
+   UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
+
 ================================================================================
 This product includes software from PostgreSQL, under the PostgreSQL License:
 

gpcontrib/gp_stats_collector/Makefile

@@ -3,14 +3,15 @@ EXTENSION  = gp_stats_collector
 DATA       = $(wildcard *--*.sql)
 REGRESS    = gpsc_cursors gpsc_dist gpsc_select gpsc_utf8_trim gpsc_utility gpsc_guc_cache gpsc_uds gpsc_locale
 
-PROTO_BASES = gpsc_plan gpsc_metrics gpsc_set_service
+PROTO_BASES = gpsc_plan gpsc_metrics gpsc_set_service yagpcc_metrics yagpcc_plan yagpcc_set_per_node
 PROTO_OBJS  = $(patsubst %,src/protos/%.pb.o,$(PROTO_BASES))
 
 C_OBJS   = $(patsubst %.c,%.o,$(wildcard src/*.c src/*/*.c))
 CPP_OBJS = $(patsubst %.cpp,%.o,$(wildcard src/*.cpp src/log/*.cpp src/memory/*.cpp))
 OBJS     = $(C_OBJS) $(CPP_OBJS) $(PROTO_OBJS)
 
 PG_CXXFLAGS += -Werror -Wall -Wno-unused-but-set-variable -std=c++17 -Isrc/protos -Isrc -Iinclude -DGPBUILD
+PG_CPPFLAGS += -I$(libpq_srcdir) -Isrc/protos -Isrc -Iinclude
 SHLIB_LINK += -lprotobuf -lstdc++
 EXTRA_CLEAN = src/protos
 

gpcontrib/gp_stats_collector/README.md

@@ -45,3 +45,25 @@ An extension for collecting query execution metrics and reporting them to an ext
 -   **User Filtering:** To exclude activity from certain roles, add them to the comma-separated list in `gpsc.ignored_users_list`.
 -   **Trimming plans:** Query texts and execution plans are trimmed based on `gpsc.max_text_size` and `gpsc.max_plan_size` (default: 1024KB). For now, it is not recommended to set these GUCs higher than 1024KB.
 -   **Analyze collection:** Analyze is sent if execution time exceeds `gpsc.min_analyze_time`, which is 10 seconds by default. Analyze is collected if `gpsc.enable_analyze` is true.
+
+### Runtime Query State (`pg_query_state`)
+
+On-demand inspection of the live execution state of another running backend. The target's active plan tree is walked across the coordinator (QD) and every segment (QE), collecting per-node instrumentation, without waiting for the query to finish. This is the signal-only variant: per-node samples are written to the server log rather than sent to the UDS sink.
+
+The functions live in the `gpsc` schema (extension version 1.2).
+
+#### 1. `pg_query_state(pid)`
+-   **What:** Triggers runtime per-node collection for the query running on backend `pid`. Fans a poll out to every participating QE and to the QD; each backend walks its plan tree and logs a per-node snapshot. Fire-and-forget: returns `void`.
+-   **GUC:** `pg_query_state.enable`.
+
+#### 2. `pg_query_state_backends(pid)`
+-   **What:** Lists the QE backends participating in the query running on backend `pid`, as `(segid, pid)` rows. Returns an empty set when the target is not running a query or has the module disabled.
+-   **GUC:** `pg_query_state.enable`.
+
+#### 3. `cbdb_mpp_query_state(gp_segment_pid[])`
+-   **What:** QE-side dispatch target used internally by `pg_query_state()`; not intended for direct use.
+
+### Runtime Query State Configuration
+-   **Enable:** `pg_query_state.enable` (default `on`) turns the executor hooks and signal handling on or off. Additional GUCs `pg_query_state.enable_timing` and `pg_query_state.enable_buffers` control the level of instrumentation collected.
+-   **Permissions:** The functions are granted to `PUBLIC`, but access is checked in the server: a caller may poll a backend only if it is a superuser or owns the target query. This lets monitoring agents run under a non-superuser role while still preventing one role from observing another's queries.
+-   **Preload:** The module registers custom signal handlers at startup, so `gp_stats_collector` must be listed in `shared_preload_libraries`.