feat: PG semantic convention stability migration

instrumentation/pg/Appraisals

@@ -1,11 +1,22 @@
 # frozen_string_literal: true
 
+# To facilitate database semantic convention stability migration, we are using
+# appraisal to test the different semantic convention modes along with different
+# gem versions. For more information on the semantic convention modes, see:
+# https://opentelemetry.io/docs/specs/semconv/non-normative/db-migration/
+
+semconv_stability = %w[old stable dup]
+
 %w[1.6.0].each do |version|
-  appraise "pg-#{version}" do
-    gem 'pg', "~> #{version}"
+  semconv_stability.each do |stability|
+    appraise "pg-#{version.tr('.', '_')}-#{stability}" do
+      gem 'pg', "~> #{version}"
+    end
   end
 end
 
-appraise 'pg-latest' do
-  gem 'pg'
+semconv_stability.each do |stability|
+  appraise "pg-latest-#{stability}" do
+    gem 'pg'
+  end
 end

instrumentation/pg/README.md

@@ -72,6 +72,22 @@ The OpenTelemetry Ruby gems are maintained by the OpenTelemetry Ruby special int
 
 The `opentelemetry-instrumentation-pg` gem is distributed under the Apache 2.0 license. See [LICENSE][license-github] for more information.
 
+## Database semantic convention stability
+
+In the OpenTelemetry ecosystem, database semantic conventions have now reached a stable state. However, the initial PG instrumentation was introduced before this stability was achieved, which resulted in database attributes being based on an older version of the semantic conventions.
+
+To facilitate the migration to stable semantic conventions, you can use the `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable. This variable allows you to opt-in to the new stable conventions, ensuring compatibility and future-proofing your instrumentation.
+
+When setting the value for `OTEL_SEMCONV_STABILITY_OPT_IN`, you can specify which conventions you wish to adopt:
+
+- `database` - Emits the stable database and networking conventions and ceases emitting the old conventions previously emitted by the instrumentation.
+- `database/dup` - Emits both the old and stable database and networking conventions, enabling a phased rollout of the stable semantic conventions.
+- Default behavior (in the absence of either value) is to continue emitting the old database and networking conventions the instrumentation previously emitted.
+
+During the transition from old to stable conventions, PG instrumentation code comes in three patch versions: `dup`, `old`, and `stable`. These versions are identical except for the attributes they send. Any changes to PG instrumentation should consider all three patches.
+
+For additional information on migration, please refer to our [documentation](https://opentelemetry.io/docs/specs/semconv/non-normative/db-migration/).
+
 [pg-home]: https://github.com/ged/ruby-pg
 [bundler-home]: https://bundler.io
 [repo-github]: https://github.com/open-telemetry/opentelemetry-ruby

instrumentation/pg/lib/opentelemetry/instrumentation/pg/instrumentation.rb

@@ -12,8 +12,9 @@ class Instrumentation < OpenTelemetry::Instrumentation::Base
         MINIMUM_VERSION = Gem::Version.new('1.1.0')
 
         install do |config|
-          require_dependencies
-          patch_client
+          patch_type = determine_semconv
+          send(:"require_dependencies_#{patch_type}")
+          send(:"patch_client_#{patch_type}")
           configure_propagator(config)
         end
 
@@ -38,13 +39,44 @@ def gem_version
           Gem::Version.new(::PG::VERSION)
         end
 
-        def require_dependencies
-          require_relative 'patches/connection'
+        def determine_semconv
+          stability_opt_in = ENV.fetch('OTEL_SEMCONV_STABILITY_OPT_IN', '')
+          values = stability_opt_in.split(',').map(&:strip)
+
+          if values.include?('database/dup')
+            'dup'
+          elsif values.include?('database')
+            'stable'
+          else
+            'old'
+          end
+        end
+
+        def require_dependencies_dup
+          require_relative 'patches/dup/connection'
+        end
+
+        def require_dependencies_old
+          require_relative 'patches/old/connection'
+        end
+
+        def require_dependencies_stable
+          require_relative 'patches/stable/connection'
+        end
+
+        def patch_client_dup
+          ::PG::Connection.prepend(Patches::Dup::Connection)
+          ::PG::Connection.singleton_class.prepend(Patches::Dup::Connect)
+        end
+
+        def patch_client_old
+          ::PG::Connection.prepend(Patches::Old::Connection)
+          ::PG::Connection.singleton_class.prepend(Patches::Old::Connect)
         end
 
-        def patch_client
-          ::PG::Connection.prepend(Patches::Connection)
-          ::PG::Connection.singleton_class.prepend(Patches::Connect)
+        def patch_client_stable
+          ::PG::Connection.prepend(Patches::Stable::Connection)
+          ::PG::Connection.singleton_class.prepend(Patches::Stable::Connect)
         end
 
         def configure_propagator(config)