Registry / database / otel-instrumentation-postgres

otel-instrumentation-postgres

library1.0.0jsnpmunverified

OpenTelemetry instrumentation for postgres.js (the PostgreSQL client for Node.js). Version 1.0.0 provides tracing and metrics (spans, histograms, counts) for database queries, connections, and performance insights. It captures query duration, SQL operation type, table names, parameter counts, and slow query detection. Configurable histogram buckets, parameter sanitization, and lifecycle hooks. Ships TypeScript types. Peer dependency on @opentelemetry/api ^1.9.0. Requires an OpenTelemetry SDK to be set up separately.

database devops

npm install otel-instrumentation-postgres

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OTEL-INSTRUMENTATI

otel-instrumentation-postgres

databasejavascriptv1.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PostgresInstrumentation

✓ import { PostgresInstrumentation } from 'otel-instrumentation-postgres';

✗ const { PostgresInstrumentation } = require('otel-instrumentation-postgres');

ESM-only package; CommonJS require may work but is not guaranteed.

createOTELEmitter

✓ import { createOTELEmitter } from 'otel-instrumentation-postgres';

✗ import createOTELEmitter from 'otel-instrumentation-postgres';

Named export, not default. Function wrapping the postgres.js client.

PostgresInstrumentationConfig

✓ import type { PostgresInstrumentationConfig } from 'otel-instrumentation-postgres';

TypeScript only; use for configuration options type.

Sets up OpenTelemetry SDK with ConsoleSpanExporter and ConsoleMetricExporter, instruments postgres.js client using PostgresInstrumentation and createOTELEmitter, then runs a query.

import { NodeSDK } from '@opentelemetry/sdk-node'; import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node'; import { ConsoleMetricExporter, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics'; import { PostgresInstrumentation, createOTELEmitter } from 'otel-instrumentation-postgres'; import postgres from 'postgres'; const sdk = new NodeSDK({ traceExporter: new ConsoleSpanExporter(), metricReader: new PeriodicExportingMetricReader({ exporter: new ConsoleMetricExporter(), }), instrumentations: [ new PostgresInstrumentation({ serviceName: 'my-app', collectQueryParameters: true, }), ], }); sdk.start(); const sql = postgres(process.env.DATABASE_URL ?? ''); const instrumentedSql = createOTELEmitter(sql); async function main() { const users = await instrumentedSql`SELECT * FROM users WHERE active = ${true}`; console.log('Users:', users); await sdk.shutdown(); } main().catch(console.error);

Debug

Known issues

gotchaRequires a running OpenTelemetry SDK (e.g., @opentelemetry/sdk-node) before instrumentation can produce telemetry. Without SDK.start(), spans and metrics will not be exported.

fix

Ensure you have set up an OpenTelemetry SDK and called sdk.start() before instrumenting your postgres client.

affects: >=0.0.0

gotchaEnvironment variables for database connection (DATABASE_URL, PGHOST, PGPORT, PGDATABASE) must be set or explicitly provided in configuration options to avoid connection errors.

fix

Set DATABASE_URL or provide serverAddress, serverPort, databaseName in configuration.

affects: >=0.0.0

breakingThis library instruments postgres.js (porsager/postgres), not the 'pg' package. Using it with 'pg' will not work and may cause confusing errors.

fix

Use 'pg' with @opentelemetry/instrumentation-pg or a dedicated pg instrumentation.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Cannot find module 'otel-instrumentation-postgres'

Package not installed or typo in import path.

fix

Run 'npm install otel-instrumentation-postgres' and ensure the import matches exactly.

TypeError: createOTELEmitter is not a function

Wrong import style (default vs named).

fix

Use import { createOTELEmitter } from 'otel-instrumentation-postgres';

TypeError: PostgresInstrumentation is not a constructor

CommonJS require may not import ES module correctly.

fix

Use ESM import syntax (import { PostgresInstrumentation } from 'otel-instrumentation-postgres';) or check bundler configuration.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

@opentelemetry/apirequiredPeer dependency for OpenTelemetry API types and functions (tracer, meter, span, etc.)

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/wataruoguchi/otel-instrumentation-postgres ↗

packageotel-instrumentation-postgres ↗

homepagehttps://github.com/wataruoguchi/otel-instrumentation-postgres#readme ↗