Telemetry
Integration guide

MySQL Query and Pool Telemetry

Track normalized MySQL operations, pool wait, transaction outcomes, controlled error categories, and release regressions without storing raw SQL or parameters.

Reviewed by the Telemetry product team on . Instrumentation contract, privacy boundaries, and implementation guidance. Review standards and ownership

Get an API keyView snippet
Useful for
  • Slow-query analysis
  • Connection-pool saturation
  • Transaction reliability
Implementation evidence

MySQL Query and Pool Telemetry: from boundary to verified row

Use MySQL Query and Pool Telemetry at a controlled application boundary, keep the event contract small, and verify a known outcome before building aggregate views.

  1. 1

    Choose the outcome

    Slow-query analysis

  2. 2

    Define the contract

    database_system, operation, query_fingerprint, pool_name, and release

  3. 3

    Instrument the boundary

    Measure the application boundary so the event can distinguish pool acquisition time from execution time.

  4. 4

    Verify the evidence

    Exercise a known fixture, then inspect mysql_query_completed for one correctly typed terminal row.

Before you start

Prerequisites and boundaries

  • A server-side MySQL client such as mysql2 and telemetry-sh
  • An allowlisted operation-name or query-fingerprint function owned by the application
  • Reviewed handling for SQLSTATE values, timeouts, transactions, and pool acquisition

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.

mysql-install

npm installation

bash
npm install telemetry-sh
  1. 1Prepare one reusable server-side delivery client with bounded network behavior.
  2. 2Add the outcome event at the success, failure, retry, or timeout boundary.
  3. 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.

mysql

MySQL Query and Pool Telemetry event

javascript
await telemetry.log("mysql_query_completed", {
  database_system: "mysql",
  operation: "account_entitlements.select",
  query_fingerprint: "account_entitlements_by_account_v2",
  pool_name: "primary",
  status: "success",
  wait_ms: poolAcquiredAt - startedAt,
  duration_ms: completedAt - startedAt,
  rows_affected: result.length,
  transaction_status: "not_started",
  route_template: "/api/accounts/:accountId/entitlements",
  release: process.env.APP_RELEASE,
});

Event contract

database_system, operation, query_fingerprint, pool_name, and release

status, duration_ms, wait_ms, rows_affected, and transaction_status

controlled_sqlstate, retry_count, route_template, job_name, and account_id

Implementation checkpoints

Checkpoint 1

Measure the application boundary so the event can distinguish pool acquisition time from execution time.

Checkpoint 2

Prefer an application-owned operation name or reviewed digest; never send raw SQL, bound values, connection strings, returned rows, or unrestricted error text.

Checkpoint 3

Use MySQL Performance Schema for database-native diagnostics and Telemetry for the compact application outcome and customer-impact join.

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.

mysql-verification

MySQL Query and Pool Telemetry verification query

sql
SELECT *
FROM mysql_query_completed
ORDER BY timestamp_utc DESC
LIMIT 20;
Confirm one terminal row per logical outcome, with the expected status, identifiers, units, and UTC time.
Inspect the inferred schema and verify that retries do not change field types or generate a new logical event ID.
Search the stored fields for credentials, raw payloads, prompts, private content, and unbounded error messages.
Exercise a provider timeout, ingestion rejection, and process shutdown before treating the dashboard as complete.

Implementation references

Review the event contract, data-safety guidance, and upstream primary documentation before enabling a new production path.

Database reliability monitoringSlow-query SQLDatabase reliability templateMySQL Performance SchemaMySQL statement digests

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.
Delivery and idempotencyBatching and shutdownTroubleshoot ingestion

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.

Database reliability9 fields

database_operation_completed

One completed application-owned database operation.

Inspect contract

Related product capability

Continue this workflow in SQL query API

Run read-only DataFusion SQL over structured-event tables and reuse the result.

Explore SQL query APIReview customer evidence

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.

Browse all recipes
Database reliabilityBeginner

Find Slow Database Queries by Fingerprint

Which database operations are consistently slow enough to investigate?

Open recipe
Database reliabilityBeginner

Measure Database Connection-Pool Saturation

Which application pools are making callers wait for a database connection?

Open recipe
Database reliabilityIntermediate

Calculate Database Transaction Rollback Rate

Which services roll back an unusual share of database transactions?

Open recipe
Database reliabilityBeginner

Analyze Database Errors by SQLSTATE and Release

Which database error classes increased after an application release?

Open recipe
Database reliabilityBeginner

Rank Database Queries by Total Time Impact

Which database operation consumes the most cumulative request time?

Open recipe
Complete collectionsDatabase reliability SQL

Browse by implementation family

Compare related integration patterns

Database and Data-System Telemetry Integrations

Templates to pair with this integration

Database Reliability Monitoring Template

Instrument slow operation fingerprints, pool contention, transaction rollbacks, locks, replication lag, and migration outcomes with safe structured events.

Open template

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 guide

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 guide

MongoDB Operation Telemetry

Track named MongoDB operations, latency, result counts, retries, transaction outcomes, and release regressions without collecting documents or query values.

Open guide