Prisma ORM Database Telemetry: from boundary to verified row
Use Prisma ORM Database Telemetry at a controlled application boundary, keep the event contract small, and verify a known outcome before building aggregate views.
- 1
Choose the outcome
Prisma operation latency
- 2
Define the contract
query_fingerprint, prisma_model, prisma_operation, and workflow
- 3
Instrument the boundary
Wrap product-level Prisma calls with an explicit fingerprint such as User.findMany.active instead of forwarding emitted SQL.
- 4
Verify the evidence
Exercise a known fixture, then inspect database_query_completed for one correctly typed terminal row.
Before you start
Prerequisites and boundaries
- Prisma Client initialized on the server
- Stable operation names chosen at application call sites
- A server-side TELEMETRY_API_KEY
Delivery setup
Install and initialize server-side
Import telemetry-sh in server-only code and initialize it once with process.env.TELEMETRY_API_KEY. Keep ingestion credentials out of browser bundles, client-visible environment variables, source control, logs, and exception messages.
npm installation
npm install telemetry-sh- 1Prepare one reusable server-side delivery client with bounded network behavior.
- 2Add the outcome event at the success, failure, retry, or timeout boundary.
- 3Send controlled fixtures 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.
Prisma ORM Database Telemetry event
import telemetry from "telemetry-sh";
const SAFE_DATABASE_ERROR_CODES = new Set(["P2024", "P2034"]);
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 observePrismaOperation({
queryFingerprint,
model,
operation,
workflow,
run,
}) {
const startedAt = performance.now();
try {
const result = await run();
await telemetry.log("database_query_completed", {
query_fingerprint: queryFingerprint,
prisma_model: model,
prisma_operation: operation,
workflow,
database_name: "app_production",
status: "success",
duration_ms: Math.round(performance.now() - startedAt),
rows_returned: Array.isArray(result) ? result.length : 1,
release: process.env.APP_RELEASE,
environment: process.env.NODE_ENV,
});
return result;
} catch (error) {
await telemetry.log("database_query_completed", {
query_fingerprint: queryFingerprint,
prisma_model: model,
prisma_operation: operation,
workflow,
database_name: "app_production",
status: "failed",
duration_ms: Math.round(performance.now() - startedAt),
error_type: classifyDatabaseError(error),
release: process.env.APP_RELEASE,
environment: process.env.NODE_ENV,
});
throw error;
}
}
const users = await observePrismaOperation({
queryFingerprint: "User.findMany.active",
model: "User",
operation: "findMany",
workflow: "account_directory",
run: () => prisma.user.findMany({ where: { active: true } }),
});Event contract
query_fingerprint, prisma_model, prisma_operation, and workflow
status, duration_ms, rows_returned, controlled error_type, and account_id
database_name, release, environment, and safe correlation identifiers
Implementation checkpoints
Checkpoint 1
Wrap product-level Prisma calls with an explicit fingerprint such as User.findMany.active instead of forwarding emitted SQL.
Checkpoint 2
Keep model, operation, and workflow separate so a database regression can be connected to customer-visible behavior.
Checkpoint 3
Prisma query events expose SQL and parameters; do not send either field to Telemetry.
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.
Prisma ORM Database 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.
Production boundary
Keep the outcome event small and recoverable
This pattern provides
- A bounded, SQL-ready outcome beside the upstream workflow.
- Stable fields for dashboards, alerts, and cross-event correlation.
- A fixture-driven path for validating success, failure, retry, and timeout behavior.
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.
Event schema starting points
Event contracts for this workflow
Review the row grain, emit boundary, required types, privacy classes, example payload, and validation checklist before adapting a query or snippet to production.
Related product capability
Continue this workflow in SQL query API
Run read-only DataFusion SQL over structured-event tables and reuse the result.
Related SQL recipes
Answer the next question with SQL
Run the query against the structured fields from this workflow, inspect the example result, and turn a useful answer into a dashboard or 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 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 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
node-postgres Pool and Query Telemetry
Instrument node-postgres query fingerprints, connection acquisition, pool pressure, timeouts, transaction outcomes, and database errors without logging SQL 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 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 guide