Send and verify events with node-postgres pool and query telemetry
Use node-postgres pool and query telemetry where your app knows the final result. Collect only the fields you need, then verify a test event before building charts.
- 1
Choose the outcome
Postgres connection-pool monitoring
- 2
Define the contract
query_fingerprint, service, database_name, status, and duration_ms
- 3
Log the final result
Pass an approved operation fingerprint from the call site instead of deriving it from raw SQL.
- 4
Check the stored event
Exercise a known fixture, then inspect database_query_completed for one correctly typed terminal row.
Before you start
Before you start
- The pg package with a shared Pool
- Application-owned operation fingerprints
- A server-side TELEMETRY_API_KEY
- A server-side runtime with fetch and AbortSignal.timeout
Delivery setup
Install and initialize server-side
This server-side example sends events through the Log API with a server-side key and a bounded fetch request; no Telemetry SDK initialization is needed. Keep ingestion credentials out of browser bundles, client-visible environment variables, source control, logs, and exception messages.
npm installation
npm install pg- 1Create one reusable server-side client. Set its timeout and retry limit.
- 2Log an event when the operation succeeds, fails, retries, or times out.
- 3Send test events with known results and inspect the stored rows before enabling an alert.
Snippet
Start with one structured event
Add this shape where the workflow completes, fails, or retries. Then build the dashboard from real fields.
node-postgres pool and query telemetry event
import { Pool } from "pg";
async function emitDatabaseOutcome(data) {
try {
const delivery = await fetch("https://api.telemetry.sh/log", {
method: "POST",
headers: {
Authorization: process.env.TELEMETRY_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ table: "database_query_completed", data }),
signal: AbortSignal.timeout(1000),
});
if (!delivery.ok) throw new Error("telemetry_delivery_unconfirmed");
} catch {
try { console.warn("Telemetry delivery unconfirmed"); } catch {}
}
}
const pool = new Pool({ max: 10 });
const SAFE_DATABASE_ERROR_CODES = new Set(["40001", "40P01", "55P03", "57014"]);
function classifyDatabaseError(error) {
return error && typeof error === "object" &&
"code" in error &&
SAFE_DATABASE_ERROR_CODES.has(String(error.code))
? String(error.code)
: "database_error";
}
async function runDatabaseOperation({
queryFingerprint,
text,
values,
}) {
const acquireStartedAt = performance.now();
let client;
let acquisitionWaitMs;
let queryStartedAt;
let outcome;
try {
client = await pool.connect();
acquisitionWaitMs = performance.now() - acquireStartedAt;
queryStartedAt = performance.now();
const result = await client.query(text, values);
outcome = {
query_fingerprint: queryFingerprint,
service: "checkout-api",
database_name: "app_production",
status: "success",
phase: "query",
operation_duration_ms: Math.round(performance.now() - acquireStartedAt),
duration_ms: Math.round(performance.now() - queryStartedAt),
acquisition_wait_ms: Math.round(acquisitionWaitMs),
rows_returned: result.rowCount ?? result.rows.length,
active_connections: pool.totalCount - pool.idleCount,
idle_connections: pool.idleCount,
max_connections: pool.options.max ?? 10,
waiting_count: pool.waitingCount,
release: process.env.APP_RELEASE,
environment: process.env.NODE_ENV,
};
return result;
} catch (error) {
outcome = {
query_fingerprint: queryFingerprint,
service: "checkout-api",
database_name: "app_production",
status: "failed",
phase: queryStartedAt === undefined ? "acquire" : "query",
duration_ms: queryStartedAt === undefined ? undefined : Math.round(performance.now() - queryStartedAt),
acquisition_wait_ms: Math.round(acquisitionWaitMs ?? (performance.now() - acquireStartedAt)),
operation_duration_ms: Math.round(performance.now() - acquireStartedAt),
error_type: classifyDatabaseError(error),
active_connections: pool.totalCount - pool.idleCount,
idle_connections: pool.idleCount,
max_connections: pool.options.max ?? 10,
waiting_count: pool.waitingCount,
release: process.env.APP_RELEASE,
environment: process.env.NODE_ENV,
};
throw error;
} finally {
client?.release();
if (outcome) await emitDatabaseOutcome(outcome);
}
}Event schema
query_fingerprint, service, database_name, status, and duration_ms
active_connections, idle_connections, max_connections, and waiting_count
acquisition_wait_ms, operation_duration_ms, phase, rows_returned, error_type, release, and environment
Check your setup
Checkpoint 1
Pass an approved operation fingerprint from the call site instead of deriving it from raw SQL.
Checkpoint 2
Measure connection acquisition separately from query execution so pool contention is not mistaken for database work.
Checkpoint 3
Record driver error codes through an allowlist and never forward connection strings, query parameters, or raw database messages.
Checkpoint 4
Release the acquired database client before exporting the outcome. A one-second cooperative Log API timeout and guarded diagnostics keep delivery failure from replacing the database result or error.
Checkpoint 5
Record acquisition_wait_ms separately from duration_ms for query execution. On acquisition failure, omit query duration; operation_duration_ms includes both phases. Pool counts are captured before release.
Checkpoint 6
This example does not implement transactions, durable export, retries, or shutdown draining. Configure database connection/query limits and background pool error handling in the application.
Verification
Prove the event arrived
Run this after exercising known success and failure cases. Replace the fallback table name if your final event contract differs from the snippet.
node-postgres pool and query telemetry verification query
SELECT *
FROM database_query_completed
ORDER BY timestamp_utc DESC
LIMIT 20;Implementation references
Review the event contract, data-safety guidance, and upstream primary documentation before enabling a new production path.
Where to log
Keep the outcome event small and recoverable
This pattern provides
- Record the outcome as an event you can query with SQL.
- Stable fields for dashboards, alerts, and cross-event correlation.
- Test events for checking success, failure, retries, and timeouts.
This pattern does not provide
- An OTLP exporter, automatic collection pipeline, or replacement for detailed traces and diagnostic logs.
- Exactly-once delivery merely because the payload contains an event ID.
- Permission to collect raw provider payloads, user content, credentials, or regulated data.
Example event schemas
Event schemas for this workflow
Check what each event records, when to send it, and which field types it needs. Review the example payload and privacy checklist before using it in production.
Use these queries in Telemetry
Learn about SQL query API
Run read-only DataFusion SQL over structured-event tables and reuse the result.
Related SQL recipes
More SQL recipes
Run the query using this workflow's event fields and check the example result. Save the result to a dashboard or set up an alert.
Find slow database queries by fingerprint
Which database operations are consistently slow enough to investigate?
Open recipeRank database queries by total time impact
Which database operation consumes the most cumulative request time?
Open recipeMeasure database connection-pool saturation
Which application pools are making callers wait for a database connection?
Open recipeMeasure database connection timeouts and churn
Which services and regions show unhealthy database connection churn?
Open recipeCalculate database transaction rollback rate
Which services roll back an unusual share of database transactions?
Open recipeMeasure long-running database transactions
Which application transaction classes remain open the longest?
Open recipeFind database lock waits and deadlocks
Which database operations create the most serious lock contention?
Open recipeAnalyze database errors by SQLSTATE and release
Which database error classes increased after an application release?
Open recipeMeasure database replication and CDC lag
Which replicas or CDC consumers are falling behind their source database?
Open recipeMeasure database replica staleness by region
Which replica regions are serving stale or failed reads?
Open recipeTrack database migration failures by release
Which releases contain failed or rolled-back database migrations?
Open recipeBrowse by implementation family
Compare related integration patterns
Templates to pair with this integration
More integrations
Prisma ORM database telemetry
Measure Prisma operation fingerprints, model and method latency, failures, result counts, releases, and database-dependent workflows without collecting raw query parameters.
Open guideMySQL query and pool telemetry
Track normalized MySQL operations, pool wait, transaction outcomes, controlled error categories, and release regressions without storing raw SQL or parameters.
Open guideMongoDB operation telemetry
Track named MongoDB operations, latency, result counts, retries, transaction outcomes, and release regressions without collecting documents or query values.
Open guide