This module provides automatic instrumentation for the pgmodule.
If total installation size is not constrained, it is recommended to use the @opentelemetry/auto-instrumentations-node bundle with @opentelemetry/sdk-node for the most seamless instrumentation experience.
Compatible with OpenTelemetry JS API and SDK 1.0+.
npm install --save @opentelemetry/instrumentation-pgconst { NodeSDK } = require('@opentelemetry/sdk-node');
const { PgInstrumentation } = require('@opentelemetry/instrumentation-pg');
const sdk = new NodeSDK({
instrumentations: [
new PgInstrumentation(),
],
});
sdk.start();
process.once('beforeExit', async () => { await sdk.shutdown(); });PgInstrumentation contains both pg and pg.Pool so it will be instrumented automatically.
This instrumentation creates the following span types:
| Span Name | Description | When Created |
|---|---|---|
pg.query:<OPERATION> <database> |
Database query execution | When client.query() is called |
pg.connect |
Client connection to database | When new Client().connect() is called directly |
pg-pool.connect |
Pool connection acquisition wait time | When acquiring a connection from pg-pool |
The pg-pool.connect spans measure the time spent waiting to acquire a connection from the pool. This can be valuable for identifying connection pool exhaustion or sizing issues. However, in high-throughput scenarios where connections are readily available, these spans may add noise with minimal diagnostic value. Consider using the requireParentSpan option or sampling strategies if pool connect spans become excessive.
PostgreSQL instrumentation has few options available to choose from. You can set the following:
| Options | Type | Description |
|---|---|---|
enhancedDatabaseReporting |
boolean |
If true, additional information about query parameters and results will be attached (as attributes) to spans representing database operations |
requestHook |
PgInstrumentationExecutionRequestHook (function) |
Function for adding custom span attributes using information about the query being issued and the db to which it's directed |
responseHook |
PgInstrumentationExecutionResponseHook (function) |
Function for adding custom span attributes from db response |
requireParentSpan |
boolean |
If true, requires a parent span to create new spans (default false) |
addSqlCommenterCommentToQueries |
boolean |
If true, adds sqlcommenter specification compliant comment to queries with tracing context (default false). NOTE: A comment will not be added to queries that already contain -- or /* ... */ in them, even if these are not actually part of comments |
ignoreConnectSpans |
boolean |
If true, pg.connect and pg-pool.connect spans will not be created. Query spans and pool metrics are still recorded (default false) |
The @opentelemetry/instrumentation-pg versions 0.72.0 and later emit the stable v1.34.0+ semantic conventions.
| Attribute | Short Description |
|---|---|
db.system.name |
The database management system (DBMS) product as identified by the client instrumentation. |
db.namespace |
The name of the database, fully qualified within the server address and port. |
db.query.text |
The database query being executed. |
db.operation.name |
The name of the operation or command being executed. |
server.address |
Remote hostname or similar. |
server.port |
Remote port number. |
error.type |
Describes a class of error the operation ended with. |
Metrics Exported:
- For more information on OpenTelemetry, visit: https://opentelemetry.io/
- For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
- For help or feedback on this project, join us in GitHub Discussions
Apache 2.0 - See LICENSE for more information.