Registry / database / zipkin-instrumentation-postgres

zipkin-instrumentation-postgres

library0.22.0jsnpmunverified

Interceptor for postgres database clients, enabling distributed tracing with Zipkin. This package provides middleware to automatically trace PostgreSQL queries. The current stable version is 0.22.0 (published Aug 2020). It is part of the Zipkin JS ecosystem, maintained by OpenZipkin, with releases typically on-demand. It is designed for use with `zipkin` and requires a `pg` client instance. Compared to other tracing solutions, it integrates seamlessly with the Zipkin library and supports both callback and promise-based `pg` usage.

database

npm install zipkin-instrumentation-postgres

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ZIPKIN-INSTRUMENTA

zipkin-instrumentation-postgres

databasejavascriptv0.22.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.

instrumentPostgres

✓ import { instrumentPostgres } from 'zipkin-instrumentation-postgres'

✗ const instrumentPostgres = require('zipkin-instrumentation-postgres')

CommonJS require works, but ESM import is recommended.

default

✓ import zipkinPostgres from 'zipkin-instrumentation-postgres'

✗ const zipkinPostgres = require('zipkin-instrumentation-postgres').default

Default export is the same as named export `instrumentPostgres`; both can be used.

zipkin

✓ import { Tracer } from 'zipkin'

✗ const Tracer = require('zipkin').Tracer

Peer dependency required; import additional types as needed.

Initializes Zipkin tracer with HTTP transport, instruments a pg Client, and runs a traced query.

import { Tracer, BatchRecorder, jsonEncoder } from 'zipkin'; import { HttpLogger } from 'zipkin-transport-http'; import { instrumentPostgres } from 'zipkin-instrumentation-postgres'; import { Client } from 'pg'; const tracer = new Tracer({ recorder: new BatchRecorder({ logger: new HttpLogger({ endpoint: 'http://localhost:9411/api/v2/spans', jsonEncoder: jsonEncoder.JSON_V2 }) }), localServiceName: 'my-service' }); const pgClient = new Client({ connectionString: process.env.DATABASE_URL ?? '' }); const tracedClient = instrumentPostgres(pgClient, { tracer, remoteServiceName: 'postgres' }); await tracedClient.connect(); const res = await tracedClient.query('SELECT NOW()'); console.log(res.rows); await tracedClient.end();

Debug

Known issues

breakingVersion 0.22.0 drops support for Node.js < 10.

fix

Upgrade Node.js to version 10 or later.

affects: >=0.22.0

deprecatedThe `zipkin-instrumentation-postgres` package is in maintenance mode; consider using OpenTelemetry for new projects.

fix

Migrate to OpenTelemetry JS with @opentelemetry/instrumentation-pg.

affects: >=0.0.0

gotchaThe `remoteServiceName` option is required for span annotations; omitting it will produce incomplete traces.

fix

Always pass `remoteServiceName` in the options object.

affects: >=0.0.0

gotchaInstrumentation only works with the `pg` library's `Client` class, not `Pool` directly. Instrument individual clients.

fix

Use `instrumentPostgres` on each `Client` instance obtained from a Pool.

affects: >=0.0.0

breakingVersion 0.20.0 changed the import path from `zipkin-instrumentation-postgres/lib/instrumentation` to `zipkin-instrumentation-postgres`.

fix

Use `import { instrumentPostgres } from 'zipkin-instrumentation-postgres'`.

affects: >=0.20.0

Errors

Common errors & fixes

TypeError: Cannot read property 'query' of undefined

`pgClient` is not a valid Client instance or `instrumentPostgres` was called on a Pool.

fix

Ensure you pass a `pg.Client` instance, not a Pool or a non-object.

Error: remoteServiceName is required

Missing or undefined `remoteServiceName` option.

fix

Add `remoteServiceName: 'your-db-service-name'` to the options object.

UnhandledPromiseRejectionWarning: TypeError: instrumentPostgres is not a function

Incorrect import or older version (<0.20.0) that used a different export.

fix

Update package to >=0.20.0 and use `import { instrumentPostgres } from 'zipkin-instrumentation-postgres'`.

Upgrade

Version history

0.22.0latest on npm

Audit

Dependencies

zipkinrequiredCore Zipkin tracing library

pgrequiredPostgreSQL client to instrument

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/openzipkin/zipkin-js ↗

packagezipkin-instrumentation-postgres ↗

homepagehttps://github.com/openzipkin/zipkin-js#readme ↗