feat(webapp): per-client database pool metrics that survive the driver adapter by ericallam · Pull Request #4541 · triggerdotdev/trigger.dev

ericallam · 2026-08-08T21:59:45Z

What

Follow-up to #4539. The driver-adapter work is inert until a client flips to the pg driver adapter, but the moment one does, our database observability degrades: the OTel metrics pipeline reads pool stats from Prisma's $metrics, which is owned by the Rust engine's quaint pool. Under the adapter, pg.Pool owns the pool, so those gauges read zero. The pipeline also only ever scraped a single client (the control-plane writer singleton).

This PR makes database metrics driver-agnostic and per-client:

Every configured client registers a metrics source: control-plane writer/replica, run-ops writer/replica, legacy writer/replica. Previously only the control-plane writer singleton was scraped.
Each OTel instrument is observed per client with db_client and db_driver (quaint | pg-adapter) attributes. db_client uses our canonical datasource-role labels (control-plane-writer, control-plane-replica, run-ops-writer, run-ops-replica, legacy-run-ops-writer, legacy-run-ops-replica) — the same strings used for the db.datasource span attribute, so a metric and a trace point at the same pool.
Pool figures come from the authoritative source per driver:
- pg-adapter: pg.Pool (totalCount/idleCount/waitingCount, plus cumulative opened/closed from connect/remove events).
- quaint: the Rust engine's $metrics pool gauges/counters, exactly as before.
Query counters and duration histograms still come from $metrics for both drivers (the Rust engine executes queries in both cases).
New db.pool.connections.waiting gauge (pg.Pool exposes this; quaint reports 0).
Stops exporting Prisma metrics from the Prometheus /metrics route. Pool observability now lives entirely in the OTel pipeline, per driver, per client.

Why

So we can flip any client (including the control-plane writer, the primary desync-fix target) to the driver adapter without losing pool visibility. Existing dashboards keyed on the same metric names keep working; they gain a per-client dimension.

Testing

Unit (apps/webapp/app/utils/databaseMetrics.server.test.ts): the pure normalizer — quaint reads pool from $metrics; adapter reads pool from pg.Pool and keeps engine query metrics; busy never goes negative; graceful zeroing when $metrics is unavailable (adapter still reports live pool figures).

Live smoke test against a prod-shaped local stack: three physically-distinct Postgres DBs (control-plane, run-ops, legacy) behind dual PgBouncers, split mode on, with a mix of adapter and quaint clients. Reading the actual emitted OTel metrics, every pool shows up as its own series:

db.pool.connections.total{db_client="control-plane-writer",  db_driver="pg-adapter"} = 1
db.pool.connections.total{db_client="control-plane-replica", db_driver="quaint"}     = 1
db.pool.connections.total{db_client="run-ops-writer",        db_driver="pg-adapter"} = 1
db.pool.connections.total{db_client="run-ops-replica",       db_driver="quaint"}     = 1
db.pool.connections.total{db_client="legacy-run-ops-writer", db_driver="quaint"}     = 1
db.pool.connections.total{db_client="legacy-run-ops-replica",db_driver="quaint"}     = 1
db.client.queries.total{db_client="control-plane-writer",db_driver="pg-adapter"} = incrementing
db.client.queries.duration.count{db_client="control-plane-writer",db_driver="pg-adapter"} = incrementing

Confirms: metrics are attributed per pool with the correct driver; adapter pools' figures come from pg.Pool; and query counters/duration histograms keep incrementing under the pg adapter. Also verified /metrics (Prometheus) now returns zero prisma_* series while still serving the app's own metrics.

pnpm run typecheck --filter webapp passes.

Notes

/metrics (Prometheus) no longer includes prisma_* series. Anything scraping that endpoint for Prisma metrics should read the equivalent db.* metrics from the OTel exporter instead.
PgBouncer + ?schema= gotcha (separate from this PR, worth flagging for rollout): since feat(webapp,database): opt-in per-client Prisma driver adapters #4539 parses ?schema= from the DSN and passes { schema } to the adapter, node-postgres sends search_path as a startup parameter. A transaction-mode PgBouncer rejects that with FATAL: unsupported startup parameter: search_path. Our prod control-plane DSNs use the default public schema with no ?schema= param, so this is latent, but any client we flip to the adapter must not carry ?schema= in its DSN (or the pooler needs ignore_startup_parameters = search_path).

…r adapter Report Prisma pool and query metrics for every configured client (control-plane writer/replica, run-ops writer/replica, legacy writer/replica) instead of only the control-plane writer, tagged with db_client and db_driver attributes. Pool figures come from the authoritative source per driver: pg.Pool (totalCount/idleCount/waitingCount + connect/remove counters) for driver-adapter clients, and the Rust engine metrics for quaint clients. Query counters and duration histograms come from prisma metrics for both. Adds a db.pool.connections.waiting gauge. Stops exporting Prisma metrics from the Prometheus /metrics route; pool observability now lives entirely in the OTel pipeline. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KHjfL7qXHia5DTnxi1RePS

changeset-bot · 2026-08-08T21:59:50Z

⚠️ No Changeset found

Latest commit: 5d964b2

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2026-08-08T22:01:57Z

Observability map

As of 5d964b2.

18/100 over 413 measured of 429 entry points (base 18, no change)

What this PR changed
No entry point this PR touches changed its score.

FIX FIRST

/api/v1/projects/:projectRef/envvars (sensitive) - auth-boundary, request-context
/auth/sso (sensitive) - auth-boundary, request-context
/_app/orgs/:organizationSlug/settings/team (sensitive) - error-classification, auth-scope, request-context

AUDIT 3 of 50 sensitive mutations record an actor. 47 without one.
CONTEXT 11 of 413 entry points name a tenant on a failure path. 325 appear only here, 39 of them sensitive, in the JSON rather than the fix list.

What the score is made of

CHECKS
  error-classification  168 applicable,  94 pass,   0 sole, global without it 10
  auth-boundary          62 applicable,  57 pass,   0 sole, global without it 15
  auth-scope             19 applicable,  17 pass,   0 sole, global without it 18
  request-context       413 applicable,  11 pass, 223 sole, global without it 64
  audit-trail            50 applicable,   3 pass,   0 sole, not in the score

The score and findings here are report-only and never gate the merge. Separately, a required test suite keeps this tool's symbol and route lists in sync with the code they name, and can fail a pull request that renames or removes a symbol they reference, or that adds the first route with a segment they anticipate. Each failure names the list to edit. The rules and their reasons: internal-packages/observability-map/README.md.

coderabbitai · 2026-08-08T22:02:16Z

Walkthrough

The change adds a shared database metrics registry and normalization layer. Standard Prisma and driver-adapter clients register pool, connection, query, and histogram sources. The tracer collects metrics for every registered client and records client and driver attributes, including waiting connections. The metrics route now serves the shared metrics register without separate Prisma collection. Tests cover normalization, pool statistics, histograms, fallback values, and nonnegative busy counts.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely describes the main change: per-client database pool metrics that work with driver adapters.
Description check	✅ Passed	The description clearly explains the change, rationale, implementation details, testing, and rollout notes; some template headings are omitted.

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

Create stacked PR
Commit on current branch

🛠️ Fix failing CI checks 💡

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/db-pool-metrics-per-client

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 1

🧹 Nitpick comments (6)

apps/webapp/app/utils/databaseMetrics.server.ts (2)
88-113: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

The driver label can disagree with the pool source.

If usesDriverAdapter is true and pool is undefined, line 89 falls through to the Prisma-gauge branch, but line 113 still reports driver: "pg-adapter". A driver-adapter client returns no prisma_pool_connections_* gauges, so the series reports zeros under a pg-adapter label. Current callers in db.server.ts always pass pool together with usesDriverAdapter: true, so this is a latent contract gap rather than an active bug.

Consider deriving driver from the same condition used to select the pool source.
♻️ Proposed change
   let pool: NormalizedPoolMetrics;
-  if (source.usesDriverAdapter && source.pool) {
+  const usesAdapterPool = source.usesDriverAdapter && source.pool !== undefined;
+  if (usesAdapterPool && source.pool) {
-    driver: source.usesDriverAdapter ? "pg-adapter" : "quaint",
+    driver: usesAdapterPool ? "pg-adapter" : "quaint",
Alternatively, model the source as a discriminated union so pool is required when usesDriverAdapter is true.
131-143: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Silent catch hides repeated $metrics failures.

The empty catch discards the error. For a quaint client, the result is a full set of zeroed pool and query series, which is indistinguishable from a genuinely idle pool. Operators cannot tell that collection failed.

Note that $metrics requires the metrics preview feature. If it is not enabled, every scrape reports zeros with no signal.

Consider logging at debug level with the clientType, and consider omitting query metrics when json is undefined instead of reporting zeros.
apps/webapp/app/utils/databaseMetrics.server.test.ts (1)
100-119: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Cover collectDatabaseClientMetrics with a rejecting client.

This test passes undefined directly, so it verifies normalizeDatabaseMetrics only. The try/catch in collectDatabaseClientMetrics is the code that converts a rejected $metrics.json() into undefined, and no test exercises it. registerDatabaseMetricsSource and resetDatabaseMetricsSources are also untested.

Consider adding a test that registers a source whose $metrics.json() rejects, then asserts that collectDatabaseClientMetrics resolves and that one failing client does not fail the other clients.
💚 Proposed test
+  it("resolves when one client's $metrics rejects", async () => {
+    resetDatabaseMetricsSources();
+    registerDatabaseMetricsSource({
+      clientType: "writer",
+      usesDriverAdapter: false,
+      client: { $metrics: { json: async () => Promise.reject(new Error("boom")) } },
+    });
+    registerDatabaseMetricsSource({
+      clientType: "reader",
+      usesDriverAdapter: false,
+      client: stubClient,
+    });
+
+    const results = await collectDatabaseClientMetrics();
+
+    expect(results).toHaveLength(2);
+    expect(results[0]?.counters.queriesTotal).toBe(0);
+    expect(results[1]?.counters.queriesTotal).toBe(100);
+  });
The registry is module-level state, so call resetDatabaseMetricsSources() in an afterEach to keep tests isolated.
apps/webapp/app/db.server.ts (2)
441-488: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

buildDriverAdapterPool changes look correct.

connect fires when the pool establishes a new physical connection, and remove fires when the pool discards one, so opened and closed are valid monotonic counters. Returning the pool alongside the adapter gives the normalizer an authoritative totalCount/idleCount/waitingCount source.

One note: disposeExternalPool: true means the adapter owns pool teardown. The returned pool reference is retained by the metrics registry for the process lifetime. If a client is ever torn down and rebuilt, the stale pool stays registered. See the related comment on the registry in apps/webapp/app/utils/databaseMetrics.server.ts.

587-597: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Extract the repeated registerDatabaseMetricsSource call into a helper. The same ternary that builds a DatabaseMetricsSource from driverPool appears four times in apps/webapp/app/db.server.ts. Only the client variable differs. The shared root cause is a missing helper next to buildDriverAdapterPool.

Add the helper once:
function registerClientMetrics(
  clientType: string,
  client: PrismaClient | RunOpsPrismaClient,
  driverPool: DriverAdapterPool | undefined
) {
  registerDatabaseMetricsSource(
    driverPool
      ? {
          clientType,
          usesDriverAdapter: true,
          client,
          pool: driverPool.pool,
          poolCounters: driverPool.poolCounters,
        }
      : { clientType, usesDriverAdapter: false, client }
  );
}
apps/webapp/app/db.server.ts#L587-L597: replace the block in buildWriterClient with registerClientMetrics(clientType, client, driverPool);.

apps/webapp/app/db.server.ts#L771-L781: replace the block in buildReplicaClient with registerClientMetrics(clientType, replicaClient, driverPool);.

apps/webapp/app/db.server.ts#L897-L907: replace the block in buildRunOpsWriterClient with registerClientMetrics(clientType, client, driverPool);.

apps/webapp/app/db.server.ts#L994-L1004: replace the block in buildRunOpsReplicaClient with registerClientMetrics(clientType, client, driverPool);.
apps/webapp/app/v3/tracer.server.ts (1)

520-534: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Plan for series-shape changes on deployment.

Adding db_client and db_driver labels changes each emitted series from one unlabelled series per metric into one series per registered client. Update external queries and alerts on rollout, or aggregate with sum by (...) before comparison.

Both labels are bounded, so this does not introduce high-cardinality attributes.

Source: Coding guidelines

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 45a6ca06-928e-4618-9b24-a2c992b9b404

📥 Commits

Reviewing files that changed from the base of the PR and between 90e8bd5 and c71c46b.

📒 Files selected for processing (6)

.server-changes/db-pool-metrics-per-client.md
apps/webapp/app/db.server.ts
apps/webapp/app/routes/metrics.ts
apps/webapp/app/utils/databaseMetrics.server.test.ts
apps/webapp/app/utils/databaseMetrics.server.ts
apps/webapp/app/v3/tracer.server.ts

📜 Review details

🧰 Additional context used

📓 Path-based instructions (13)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

**/*.{ts,tsx}: Use types over interfaces for TypeScript
Avoid using enums; prefer string unions or const objects instead

**/*.{ts,tsx}: Prefer static imports over dynamic import(); use dynamic imports only for unresolvable circular dependencies, genuine performance code splitting, or conditional runtime loading.
Import Trigger.dev tasks from @trigger.dev/sdk; never use @trigger.dev/sdk/v3 or deprecated client.defineJob.
Add agentcrumbs while writing code using approved namespaces; mark lines with // @Crumbs or blocks with `// `#region` `@crumbs, and strip them before merging.

Files:

apps/webapp/app/utils/databaseMetrics.server.test.ts
apps/webapp/app/routes/metrics.ts
apps/webapp/app/utils/databaseMetrics.server.ts
apps/webapp/app/v3/tracer.server.ts
apps/webapp/app/db.server.ts

{packages/core,apps/webapp}/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Use zod for validation in packages/core and apps/webapp

Files:

apps/webapp/app/utils/databaseMetrics.server.test.ts
apps/webapp/app/routes/metrics.ts
apps/webapp/app/utils/databaseMetrics.server.ts
apps/webapp/app/v3/tracer.server.ts
apps/webapp/app/db.server.ts

**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Use function declarations instead of default exports

Files:

apps/webapp/app/utils/databaseMetrics.server.test.ts
apps/webapp/app/routes/metrics.ts
apps/webapp/app/utils/databaseMetrics.server.ts
apps/webapp/app/v3/tracer.server.ts
apps/webapp/app/db.server.ts

**/*.{test,spec}.{ts,tsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Use vitest for all tests in the Trigger.dev repository

**/*.{test,spec}.{ts,tsx}: Use Vitest exclusively and never mock dependencies; use Testcontainers for integration dependencies.
Place test files next to the source files they test.

Files:

apps/webapp/app/utils/databaseMetrics.server.test.ts

**/*.ts

📄 CodeRabbit inference engine (.cursor/rules/otel-metrics.mdc)

**/*.ts: When creating or editing OTEL metrics (counters, histograms, gauges), ensure metric attributes have low cardinality by using only enums, booleans, bounded error codes, or bounded shard IDs
Do not use high-cardinality attributes in OTEL metrics such as UUIDs/IDs (envId, userId, runId, projectId, organizationId), unbounded integers (itemCount, batchSize, retryCount), timestamps (createdAt, startTime), or free-form strings (errorMessage, taskName, queueName)
When exporting OTEL metrics via OTLP to Prometheus, be aware that the exporter automatically adds unit suffixes to metric names (e.g., 'my_duration_ms' becomes 'my_duration_ms_milliseconds', 'my_counter' becomes 'my_counter_total'). Account for these transformations when writing Grafana dashboards or Prometheus queries

Files:

apps/webapp/app/utils/databaseMetrics.server.test.ts
apps/webapp/app/routes/metrics.ts
apps/webapp/app/utils/databaseMetrics.server.ts
apps/webapp/app/v3/tracer.server.ts
apps/webapp/app/db.server.ts

apps/webapp/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/webapp.mdc)

apps/webapp/**/*.{ts,tsx}: Access environment variables through the env export of env.server.ts instead of directly accessing process.env
Use subpath exports from @trigger.dev/core package instead of importing from the root @trigger.dev/core path

Do not reintroduce the removed v1 execution path; RunEngineVersion.V1 branches may only reject or finalize gracefully so v3 clients receive a clean 4xx, never a 5xx.

Files:

apps/webapp/app/utils/databaseMetrics.server.test.ts
apps/webapp/app/routes/metrics.ts
apps/webapp/app/utils/databaseMetrics.server.ts
apps/webapp/app/v3/tracer.server.ts
apps/webapp/app/db.server.ts

apps/webapp/**/*.test.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/webapp.mdc)

Do not import env.server.ts directly or indirectly into test files; instead pass environment-dependent values through options/parameters to make code testable

Files:

apps/webapp/app/utils/databaseMetrics.server.test.ts

apps/**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

For apps, use typecheck for verification and never use build as the correctness check.

Files:

apps/webapp/app/utils/databaseMetrics.server.test.ts
apps/webapp/app/routes/metrics.ts
apps/webapp/app/utils/databaseMetrics.server.ts
apps/webapp/app/v3/tracer.server.ts
apps/webapp/app/db.server.ts

apps/webapp/app/**/*.{ts,tsx}