{"id":43523,"library":"otel-instrumentation-postgres","title":"otel-instrumentation-postgres","description":"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.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/wataruoguchi/otel-instrumentation-postgres","tags":["javascript","postgresql","postgres.js","postgres","opentelemetry","instrumentation","tracing","typescript"],"install":[{"cmd":"npm install otel-instrumentation-postgres","lang":"bash","label":"npm"},{"cmd":"yarn add otel-instrumentation-postgres","lang":"bash","label":"yarn"},{"cmd":"pnpm add otel-instrumentation-postgres","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for OpenTelemetry API types and functions (tracer, meter, span, etc.)","package":"@opentelemetry/api","optional":false}],"imports":[{"note":"ESM-only package; CommonJS require may work but is not guaranteed.","wrong":"const { PostgresInstrumentation } = require('otel-instrumentation-postgres');","symbol":"PostgresInstrumentation","correct":"import { PostgresInstrumentation } from 'otel-instrumentation-postgres';"},{"note":"Named export, not default. Function wrapping the postgres.js client.","wrong":"import createOTELEmitter from 'otel-instrumentation-postgres';","symbol":"createOTELEmitter","correct":"import { createOTELEmitter } from 'otel-instrumentation-postgres';"},{"note":"TypeScript only; use for configuration options type.","symbol":"PostgresInstrumentationConfig","correct":"import type { PostgresInstrumentationConfig } from 'otel-instrumentation-postgres';"}],"quickstart":{"code":"import { NodeSDK } from '@opentelemetry/sdk-node';\nimport { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node';\nimport { ConsoleMetricExporter, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';\nimport { PostgresInstrumentation, createOTELEmitter } from 'otel-instrumentation-postgres';\nimport postgres from 'postgres';\n\nconst sdk = new NodeSDK({\n  traceExporter: new ConsoleSpanExporter(),\n  metricReader: new PeriodicExportingMetricReader({\n    exporter: new ConsoleMetricExporter(),\n  }),\n  instrumentations: [\n    new PostgresInstrumentation({\n      serviceName: 'my-app',\n      collectQueryParameters: true,\n    }),\n  ],\n});\nsdk.start();\n\nconst sql = postgres(process.env.DATABASE_URL ?? '');\nconst instrumentedSql = createOTELEmitter(sql);\n\nasync function main() {\n  const users = await instrumentedSql`SELECT * FROM users WHERE active = ${true}`;\n  console.log('Users:', users);\n  await sdk.shutdown();\n}\nmain().catch(console.error);","lang":"typescript","description":"Sets up OpenTelemetry SDK with ConsoleSpanExporter and ConsoleMetricExporter, instruments postgres.js client using PostgresInstrumentation and createOTELEmitter, then runs a query."},"warnings":[{"fix":"Ensure you have set up an OpenTelemetry SDK and called sdk.start() before instrumenting your postgres client.","message":"Requires a running OpenTelemetry SDK (e.g., @opentelemetry/sdk-node) before instrumentation can produce telemetry. Without SDK.start(), spans and metrics will not be exported.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Set DATABASE_URL or provide serverAddress, serverPort, databaseName in configuration.","message":"Environment variables for database connection (DATABASE_URL, PGHOST, PGPORT, PGDATABASE) must be set or explicitly provided in configuration options to avoid connection errors.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use 'pg' with @opentelemetry/instrumentation-pg or a dedicated pg instrumentation.","message":"This library instruments postgres.js (porsager/postgres), not the 'pg' package. Using it with 'pg' will not work and may cause confusing errors.","severity":"breaking","affected_versions":">=0.0.0"}],"env_vars":null,"search_vec":"'1.0.0':15 '1.9.0':60 'bucket':47 'captur':31 'client':11 'configur':45 'connect':26 'count':22,40 'databas':24 'depend':57 'detect':44 'durat':33 'histogram':21,46 'hook':52 'insight':29 'instrument':3,6,75 'javascript':70 'lifecycl':51 'metric':19 'name':38 'node.js':13 'opentelemetri':5,63,74 'opentelemetry/api':59 'oper':35 'otel':2 'otel-instrumentation-postgr':1 'paramet':39,48 'peer':56 'perform':28 'postgr':4,73 'postgres.js':8,72 'postgresql':10,71 'provid':16 'queri':25,32,43 'requir':61 'sanit':49 'sdk':64 'separ':69 'set':67 'ship':53 'slow':42 'span':20 'sql':34 'tabl':37 'trace':17,76 'type':36,55 'typescript':54,77 'version':14","created_at":"2026-06-05T17:00:13.046045+00:00","updated_at":"2026-06-05T17:00:13.046045+00:00","problems":[{"fix":"Run 'npm install otel-instrumentation-postgres' and ensure the import matches exactly.","cause":"Package not installed or typo in import path.","error":"Error: Cannot find module 'otel-instrumentation-postgres'"},{"fix":"Use import { createOTELEmitter } from 'otel-instrumentation-postgres';","cause":"Wrong import style (default vs named).","error":"TypeError: createOTELEmitter is not a function"},{"fix":"Use ESM import syntax (import { PostgresInstrumentation } from 'otel-instrumentation-postgres';) or check bundler configuration.","cause":"CommonJS require may not import ES module correctly.","error":"TypeError: PostgresInstrumentation is not a constructor"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/wataruoguchi/otel-instrumentation-postgres#readme","github":"https://github.com/wataruoguchi/otel-instrumentation-postgres","docs":null,"changelog":null,"pypi":null,"npm":"otel-instrumentation-postgres","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}