{"id":44164,"library":"zipkin-instrumentation-postgres","title":"Zipkin Postgres Instrumentation","description":"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.","status":"maintenance","version":"0.22.0","language":"javascript","source_language":"en","source_url":"https://github.com/openzipkin/zipkin-js","tags":["javascript"],"install":[{"cmd":"npm install zipkin-instrumentation-postgres","lang":"bash","label":"npm"},{"cmd":"yarn add zipkin-instrumentation-postgres","lang":"bash","label":"yarn"},{"cmd":"pnpm add zipkin-instrumentation-postgres","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core Zipkin tracing library","package":"zipkin","optional":false},{"reason":"PostgreSQL client to instrument","package":"pg","optional":false}],"imports":[{"note":"CommonJS require works, but ESM import is recommended.","wrong":"const instrumentPostgres = require('zipkin-instrumentation-postgres')","symbol":"instrumentPostgres","correct":"import { instrumentPostgres } from 'zipkin-instrumentation-postgres'"},{"note":"Default export is the same as named export `instrumentPostgres`; both can be used.","wrong":"const zipkinPostgres = require('zipkin-instrumentation-postgres').default","symbol":"default","correct":"import zipkinPostgres from 'zipkin-instrumentation-postgres'"},{"note":"Peer dependency required; import additional types as needed.","wrong":"const Tracer = require('zipkin').Tracer","symbol":"zipkin","correct":"import { Tracer } from 'zipkin'"}],"quickstart":{"code":"import { Tracer, BatchRecorder, jsonEncoder } from 'zipkin';\nimport { HttpLogger } from 'zipkin-transport-http';\nimport { instrumentPostgres } from 'zipkin-instrumentation-postgres';\nimport { Client } from 'pg';\n\nconst tracer = new Tracer({\n  recorder: new BatchRecorder({\n    logger: new HttpLogger({\n      endpoint: 'http://localhost:9411/api/v2/spans',\n      jsonEncoder: jsonEncoder.JSON_V2\n    })\n  }),\n  localServiceName: 'my-service'\n});\n\nconst pgClient = new Client({\n  connectionString: process.env.DATABASE_URL ?? ''\n});\n\nconst tracedClient = instrumentPostgres(pgClient, { tracer, remoteServiceName: 'postgres' });\n\nawait tracedClient.connect();\nconst res = await tracedClient.query('SELECT NOW()');\nconsole.log(res.rows);\nawait tracedClient.end();","lang":"typescript","description":"Initializes Zipkin tracer with HTTP transport, instruments a pg Client, and runs a traced query."},"warnings":[{"fix":"Upgrade Node.js to version 10 or later.","message":"Version 0.22.0 drops support for Node.js < 10.","severity":"breaking","affected_versions":">=0.22.0"},{"fix":"Migrate to OpenTelemetry JS with @opentelemetry/instrumentation-pg.","message":"The `zipkin-instrumentation-postgres` package is in maintenance mode; consider using OpenTelemetry for new projects.","severity":"deprecated","affected_versions":">=0.0.0"},{"fix":"Always pass `remoteServiceName` in the options object.","message":"The `remoteServiceName` option is required for span annotations; omitting it will produce incomplete traces.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use `instrumentPostgres` on each `Client` instance obtained from a Pool.","message":"Instrumentation only works with the `pg` library's `Client` class, not `Pool` directly. Instrument individual clients.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use `import { instrumentPostgres } from 'zipkin-instrumentation-postgres'`.","message":"Version 0.20.0 changed the import path from `zipkin-instrumentation-postgres/lib/instrumentation` to `zipkin-instrumentation-postgres`.","severity":"breaking","affected_versions":">=0.20.0"}],"env_vars":null,"search_vec":"'0.22.0':28 '2020':31 'aug':30 'automat':19 'base':81 'callback':77 'client':8,60 'compar':62 'current':24 'databas':7 'demand':48 'design':51 'distribut':10 'ecosystem':39 'enabl':9 'instanc':61 'instrument':3 'integr':68 'interceptor':4 'javascript':84 'js':38 'librari':73 'maintain':40 'middlewar':17 'on-demand':46 'openzipkin':42 'packag':15 'part':34 'pg':59,82 'postgr':2,6 'postgresql':21 'promis':80 'promise-bas':79 'provid':16 'publish':29 'queri':22 'releas':44 'requir':57 'seamless':69 'solut':66 'stabl':25 'support':75 'trace':11,20,65 'typic':45 'usag':83 'use':53 'version':26 'zipkin':1,13,37,55,72","created_at":"2026-06-05T17:03:17.158356+00:00","updated_at":"2026-06-05T17:03:17.158356+00:00","problems":[{"fix":"Ensure you pass a `pg.Client` instance, not a Pool or a non-object.","cause":"`pgClient` is not a valid Client instance or `instrumentPostgres` was called on a Pool.","error":"TypeError: Cannot read property 'query' of undefined"},{"fix":"Add `remoteServiceName: 'your-db-service-name'` to the options object.","cause":"Missing or undefined `remoteServiceName` option.","error":"Error: remoteServiceName is required"},{"fix":"Update package to >=0.20.0 and use `import { instrumentPostgres } from 'zipkin-instrumentation-postgres'`.","cause":"Incorrect import or older version (<0.20.0) that used a different export.","error":"UnhandledPromiseRejectionWarning: TypeError: instrumentPostgres is not a function"}],"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/openzipkin/zipkin-js#readme","github":"https://github.com/openzipkin/zipkin-js","docs":null,"changelog":null,"pypi":null,"npm":"zipkin-instrumentation-postgres","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"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}}