feat(instrumentation-pg): add skipConnectSpans option (open-telemetry#3280)

Co-authored-by: Claude <noreply@anthropic.com>

Author: jtomaszewski

packages/instrumentation-pg/README.md

@@ -62,6 +62,7 @@ PostgreSQL instrumentation has few options available to choose from. You can set
 | `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](https://github.com/open-telemetry/opentelemetry-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) |
 
 ## Semantic Conventions
 

packages/instrumentation-pg/src/instrumentation.ts

@@ -249,7 +249,12 @@ export class PgInstrumentation extends InstrumentationBase<PgInstrumentationConf
     const plugin = this;
     return (original: PgClientConnect) => {
       return function connect(this: pgTypes.Client, callback?: Function) {
-        if (utils.shouldSkipInstrumentation(plugin.getConfig())) {
+        const config = plugin.getConfig();
+
+        if (
+          utils.shouldSkipInstrumentation(config) ||
+          config.ignoreConnectSpans
+        ) {
           return original.call(this, callback);
         }
 
@@ -571,7 +576,16 @@ export class PgInstrumentation extends InstrumentationBase<PgInstrumentationConf
     const plugin = this;
     return (originalConnect: typeof pgPoolTypes.prototype.connect) => {
       return function connect(this: PgPoolExtended, callback?: PgPoolCallback) {
-        if (utils.shouldSkipInstrumentation(plugin.getConfig())) {
+        const config = plugin.getConfig();
+
+        if (utils.shouldSkipInstrumentation(config)) {
+          return originalConnect.call(this, callback as any);
+        }
+
+        // Still set up event listeners for metrics even when skipping spans
+        plugin._setPoolConnectEventListeners(this);
+
+        if (config.ignoreConnectSpans) {
           return originalConnect.call(this, callback as any);
         }
 
@@ -584,8 +598,6 @@ export class PgInstrumentation extends InstrumentationBase<PgInstrumentationConf
           ),
         });
 
-        plugin._setPoolConnectEventListeners(this);
-
         if (callback) {
           const parentSpan = trace.getSpan(context.active());
           callback = utils.patchCallbackPGPool(

packages/instrumentation-pg/src/types.ts

@@ -79,4 +79,12 @@ export interface PgInstrumentationConfig extends InstrumentationConfig {
    * the tracing context, following the {@link https://github.com/open-telemetry/opentelemetry-sqlcommenter sqlcommenter} format
    */
   addSqlCommenterCommentToQueries?: boolean;
+
+  /**
+   * If true, `pg.connect` and `pg-pool.connect` spans will not be created.
+   * Query spans and pool metrics are still recorded.
+   *
+   * @default false
+   */
+  ignoreConnectSpans?: boolean;
 }

packages/instrumentation-pg/test/pg-pool.test.ts

@@ -327,6 +327,77 @@ describe('pg-pool', () => {
       const spans = memoryExporter.getFinishedSpans();
       assert.strictEqual(spans.length, 0);
     });
+
+    it('should not create connect spans when ignoreConnectSpans=true', async () => {
+      const newPool = new pgPool(CONFIG);
+      create({
+        ignoreConnectSpans: true,
+      });
+      const span = provider.getTracer('test-pg-pool').startSpan('test span');
+      await context.with(trace.setSpan(context.active(), span), async () => {
+        const client = await newPool.connect();
+        try {
+          await client.query('SELECT NOW()');
+        } finally {
+          client.release();
+        }
+      });
+      await newPool.end();
+
+      const spans = memoryExporter.getFinishedSpans();
+      const poolConnectSpans = spans.filter(s => s.name === 'pg-pool.connect');
+      const clientConnectSpans = spans.filter(s => s.name === 'pg.connect');
+      const querySpans = spans.filter(s => s.name.startsWith('pg.query'));
+
+      assert.strictEqual(
+        poolConnectSpans.length,
+        0,
+        'Expected no pg-pool.connect spans'
+      );
+      assert.strictEqual(
+        clientConnectSpans.length,
+        0,
+        'Expected no pg.connect spans'
+      );
+      assert.ok(querySpans.length > 0, 'Expected query spans to be created');
+
+      // Reset config for subsequent tests
+      create({});
+    });
+
+    it('should still record pool metrics when ignoreConnectSpans=true', async () => {
+      const metricReader = testUtils.initMeterProvider(instrumentation);
+      const newPool = new pgPool(CONFIG);
+      create({
+        ignoreConnectSpans: true,
+      });
+
+      const client = await newPool.connect();
+      try {
+        await client.query('SELECT NOW()');
+      } finally {
+        client.release();
+      }
+
+      const { resourceMetrics, errors } = await metricReader.collect();
+      assert.deepEqual(
+        errors,
+        [],
+        'expected no errors during metric collection'
+      );
+
+      const metrics = resourceMetrics.scopeMetrics[0].metrics;
+      assert.strictEqual(
+        metrics[1].descriptor.name,
+        METRIC_DB_CLIENT_CONNECTION_COUNT,
+        'Expected connection count metric'
+      );
+
+      await newPool.end();
+
+      // Reset config for subsequent tests
+      create({});
+    });
   });
 
   describe('#pool.query()', () => {