Add query labels via sqlcommenter comment parsing

.github/workflows/ci-tap.yml

@@ -73,28 +73,19 @@ jobs:
           cmake --build build --parallel
           cmake --install build
 
-      - name: Start ClickHouse
+      - name: Start ClickHouse and OTel collector
         run: |
-          docker rm -f clickhouse-test 2>/dev/null || true
-          docker run -d --name clickhouse-test \
-            --network host \
-            clickhouse/clickhouse-server:26.1
-          # Wait for ClickHouse to be ready
-          for i in {1..30}; do
-            if curl -sf 'http://localhost:8123/' --data 'SELECT 1' >/dev/null 2>&1; then
-              echo "ClickHouse ready"
-              exit 0
+          docker compose -f docker/docker-compose.test.yml up -d --wait
+          docker compose -f docker/docker-compose.otel.yml up -d
+          # Poll OTel health endpoint (distroless image has no shell for healthcheck)
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:13133/ >/dev/null 2>&1; then
+              echo "OTel collector ready"
+              break
             fi
-            echo "Waiting for ClickHouse... ($i/30)"
+            echo "Waiting for OTel collector... ($i/30)"
             sleep 1
           done
-          echo "ClickHouse not ready after 30s"
-          docker logs clickhouse-test
-          exit 1
-
-      - name: Initialize ClickHouse schema
-        run: |
-          docker exec clickhouse-test clickhouse-client --multiquery < docker/init/00-schema.sql
 
       - name: Run TAP tests
         run: |
@@ -110,6 +101,8 @@ jobs:
           name: tap-test-logs
           path: t/tmp_check/
 
-      - name: Cleanup ClickHouse
+      - name: Cleanup
         if: always()
-        run: docker rm -f clickhouse-test 2>/dev/null || true
+        run: |
+          docker compose -f docker/docker-compose.test.yml down --volumes 2>/dev/null || true
+          docker compose -f docker/docker-compose.otel.yml down --volumes 2>/dev/null || true

.github/workflows/ci.yml

@@ -131,7 +131,7 @@ jobs:
             -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
 
       - name: Build
-        run: cmake --build build_unit --target hostname_test --parallel
+        run: cmake --build build_unit --parallel
 
       - name: Run unit tests
         run: ctest --test-dir build_unit --output-on-failure

CMakeLists.txt

@@ -79,6 +79,7 @@ target_include_directories(pg_stat_ch SYSTEM PRIVATE
   ${CMAKE_SOURCE_DIR}/third_party/opentelemetry-cpp/api/include
   ${CMAKE_SOURCE_DIR}/third_party/opentelemetry-cpp/sdk/include
   ${CMAKE_SOURCE_DIR}/third_party/opentelemetry-cpp/exporters/otlp/include
+  ${CMAKE_SOURCE_DIR}/third_party/opentelemetry-cpp/third_party/nlohmann-json/single_include
 )
 target_link_libraries(pg_stat_ch PRIVATE
   PostgreSQLServer::PostgreSQLServer
@@ -149,6 +150,19 @@ if(PSCH_BUILD_UNIT_TESTS)
   )
   pg_stat_ch_set_warnings(hostname_test)
 
+  add_executable(sqlcommenter_parse_test
+    test/unit/sqlcommenter_parse_test.cc
+    src/export/sqlcommenter_parse.cc
+  )
+  target_include_directories(sqlcommenter_parse_test PRIVATE src include)
+  target_include_directories(sqlcommenter_parse_test SYSTEM PRIVATE
+    ${CMAKE_SOURCE_DIR}/third_party/opentelemetry-cpp/third_party/nlohmann-json/single_include
+  )
+  target_compile_features(sqlcommenter_parse_test PRIVATE cxx_std_17)
+  target_link_libraries(sqlcommenter_parse_test PRIVATE GTest::gtest_main)
+  pg_stat_ch_set_warnings(sqlcommenter_parse_test)
+
   include(GoogleTest)
   gtest_discover_tests(hostname_test)
+  gtest_discover_tests(sqlcommenter_parse_test)
 endif()

docker/docker-compose.otel.yml

@@ -9,8 +9,5 @@ services:
       - "4317:4317"    # gRPC OTLP receiver (matches psch_otel_endpoint default)
       - "9091:9090"    # Prometheus metrics exporter (host:9091 → container:9090)
       - "13133:13133"  # Health check HTTP endpoint
-    healthcheck:
-      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:13133/"]
-      interval: 5s
-      timeout: 5s
-      retries: 10
+    # Note: no healthcheck — the contrib image is distroless (no shell/curl/wget).
+    # Use host-side polling (curl localhost:13133) to verify readiness.

docker/init/00-schema.sql

@@ -59,6 +59,8 @@ CREATE TABLE pg_stat_ch.events_raw
 
     query String COMMENT 'Full SQL query text (may be truncated). Used for debugging and query analysis.',
 
+    labels String DEFAULT '{}' COMMENT 'Query labels from sqlcommenter comments (key=value pairs in /* */ blocks). Access subpaths directly: labels.controller, labels.action. Empty {} when no labels present. See: https://google.github.io/sqlcommenter/',
+
     -- ========================================================================
     -- Shared buffer metrics (main buffer cache)
     -- ========================================================================

docker/migrations/001_add_labels_column.sql

@@ -0,0 +1,15 @@
+-- Migration 001: Add labels column for sqlcommenter support
+--
+-- This migration adds the `labels` column to `events_raw` for existing
+-- installations. New installations already include this column via
+-- docker/init/00-schema.sql.
+--
+-- Run with:
+--   clickhouse-client < docker/migrations/001_add_labels_column.sql
+--
+-- Safe to re-run: ALTER TABLE ADD COLUMN IF NOT EXISTS is idempotent.
+
+ALTER TABLE pg_stat_ch.events_raw
+    ADD COLUMN IF NOT EXISTS labels String DEFAULT '{}'
+    COMMENT 'Query labels from sqlcommenter comments (key=value pairs in /* */ blocks). Access subpaths directly: labels.controller, labels.action. Empty {} when no labels present. See: https://google.github.io/sqlcommenter/'
+    AFTER query;

docs/guides/clickhouse.md

@@ -80,6 +80,32 @@ Four materialized views provide pre-aggregated analytics:
 
 For view schemas, query patterns, and the `-State`/`-Merge` aggregation pattern, see [materialized views](/reference/materialized-views).
 
+## Schema migrations
+
+When upgrading pg_stat_ch, new columns or schema changes may be required. Migration scripts are provided in [`docker/migrations/`](https://github.com/ClickHouse/pg_stat_ch/tree/main/docker/migrations) and are safe to re-run (idempotent).
+
+Apply all pending migrations:
+
+```bash
+for f in docker/migrations/*.sql; do
+  clickhouse-client < "$f"
+done
+```
+
+Or apply a specific migration:
+
+```bash
+clickhouse-client < docker/migrations/001_add_labels_column.sql
+```
+
+| Migration | Version | Description |
+|---|---|---|
+| `001_add_labels_column.sql` | 0.2+ | Adds `labels JSON` column for [sqlcommenter](https://google.github.io/sqlcommenter/) query label support |
+
+<Note>
+New installations using `docker/init/00-schema.sql` already include all schema changes. Migrations are only needed for existing ClickHouse instances.
+</Note>
+
 ## Data retention
 
 The `events_raw` table has no TTL by default. To limit storage, add a TTL:

docs/reference/events-schema.mdx

@@ -30,6 +30,16 @@ The table is partitioned by date (`toDate(ts_start)`) and ordered by `ts_start`
 Query normalization replaces literals with placeholders (`$N`). This means `SELECT * FROM users WHERE id = 42` becomes `SELECT * FROM users WHERE id = $1`. No passwords, tokens, or PII are exported in query text.
 </Note>
 
+## Query labels
+
+| Column | Type | Description |
+|---|---|---|
+| `labels` | `String DEFAULT '{}'` | Key-value labels extracted from [sqlcommenter](https://google.github.io/sqlcommenter/) comments appended to the query. For example, `/* controller='users',action='show' */` produces `{"controller":"users","action":"show"}`. Access subpaths directly in ClickHouse: `labels.controller`, `labels.action`. Empty `{}` when no labels are present. |
+
+<Note>
+Labels are parsed from the **last** `/* */` comment block in the query text. The parser supports URL-encoded values and escaped single quotes per the sqlcommenter specification. Controlled by the [`pg_stat_ch.track_labels`](/reference/configuration) GUC (default: `true`).
+</Note>
+
 ## Shared buffer usage
 
 These columns show how queries interact with PostgreSQL's `shared_buffers` cache. The cache hit ratio for a query is `shared_blks_hit / (shared_blks_hit + shared_blks_read)`. Target above 99% for OLTP workloads.

include/config/guc.h

@@ -28,6 +28,7 @@ extern int psch_otel_log_batch_size;
 extern int psch_otel_log_max_bytes;
 extern int psch_otel_log_delay_ms;
 extern int psch_otel_metric_interval_ms;
+extern bool psch_track_labels;
 extern bool psch_debug_force_locked_overflow;
 
 // Initialize GUC variables

src/config/guc.cc

@@ -32,6 +32,7 @@ int psch_otel_log_batch_size = 8192;
 int psch_otel_log_max_bytes = 3 * 1024 * 1024;  // 3 MiB: gRPC default max is 4 MiB
 int psch_otel_log_delay_ms = 100;
 int psch_otel_metric_interval_ms = 5000;
+bool psch_track_labels = true;
 bool psch_debug_force_locked_overflow = false;
 
 // Log level options (matches PostgreSQL's server_message_level_options pattern)
@@ -307,6 +308,17 @@ void PschInitGuc(void) {
       PGC_SUSET,
       0,
       nullptr, nullptr, nullptr);
+  DefineCustomBoolVariable(
+      "pg_stat_ch.track_labels",
+      "Extract sqlcommenter labels from query comments.",
+      "When enabled, the background worker parses /* key='value' */ comments "
+      "and exports structured labels to ClickHouse (JSON) or OTel (attributes).",
+      &psch_track_labels,
+      true,
+      PGC_SIGHUP,
+      0,
+      nullptr, nullptr, nullptr);
+
   DefineCustomBoolVariable(
       "pg_stat_ch.debug_force_locked_overflow",
       "Force HandleOverflow in locked path (debug/test only).",

src/export/clickhouse_exporter.cc

@@ -75,10 +75,15 @@ class ClickHouseExporter : public StatsExporter {
   shared_ptr<Column<string>> DbOperationColumn() final { return TagString("cmd_type"); }
   shared_ptr<Column<string_view>> DbQueryTextColumn() final { return RecordString("query"); }
 
+  void AppendLabels(const ParseResult& labels) final {
+    labels_col_->Append(SerializeLabelsJson(labels));
+  }
+
   void BeginBatch() final {
     block = std::make_unique<clickhouse::Block>();
     columns.clear();
     exported_count = 0;
+    labels_col_ = Wrap<clickhouse::ColumnString, string_view>("labels");
   }
   void BeginRow() final { ++exported_count; }
   bool CommitBatch() final;
@@ -116,6 +121,7 @@ class ClickHouseExporter : public StatsExporter {
   std::unique_ptr<clickhouse::Client> client;
   std::unique_ptr<clickhouse::Block> block;
   std::vector<shared_ptr<BasicColumn>> columns;
+  shared_ptr<Column<string_view>> labels_col_;
   int consecutive_failures = 0;
   int exported_count = 0;
 };

src/export/exporter_interface.h

@@ -6,6 +6,8 @@
 #include <string>
 #include <string_view>
 
+#include "export/sqlcommenter_parse.h"
+
 class StatsExporter {
  protected:
   using string = std::string;
@@ -65,6 +67,10 @@ class StatsExporter {
   virtual shared_ptr<Column<string>> DbOperationColumn() = 0;
   // Query text. CH: RecordString "query"; OTel semconv: "db.query.text".
   virtual shared_ptr<Column<string_view>> DbQueryTextColumn() = 0;
+  // Query labels from sqlcommenter comments. Called inside the event loop.
+  // CH: serializes to JSON, appends to a String "labels" column;
+  // OTel: sets per-label attributes prefixed with "db.query.label.".
+  virtual void AppendLabels(const ParseResult& labels) = 0;
 
   virtual void BeginBatch() = 0;
   virtual void BeginRow() = 0;

src/export/otel_exporter.cc

@@ -129,6 +129,15 @@ class OTelExporter : public StatsExporter {
   shared_ptr<Column<string_view>> DbQueryTextColumn() final {
     return Wrap<RecordOnlyColumn<string_view>>("db.query.text");
   }
+  void AppendLabels(const ParseResult& labels) final {
+    for (int i = 0; i < labels.count; ++i) {
+      string attr_name = "db.query.label.";
+      attr_name.append(labels.labels[i].key.data(), labels.labels[i].key.size());
+      string val(labels.labels[i].value);
+      current_log_record->SetAttribute(attr_name, val);
+      current_row_tags[attr_name] = std::move(val);
+    }
+  }
 
   bool EstablishNewConnection() final;
   bool IsConnected() const final { return metrics_provider && log_provider; }