feat: Trilogy semantic convention stability migration

instrumentation/trilogy/Appraisals

@@ -4,6 +4,15 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-appraise 'trilogy-2' do
-  gem 'trilogy', '~> 2.3'
+# 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]
+
+semconv_stability.each do |mode|
+  appraise "trilogy-2-#{mode}" do
+    gem 'trilogy', '~> 2.3'
+  end
 end

instrumentation/trilogy/README.md

@@ -83,3 +83,19 @@ The `opentelemetry-instrumentation-trilogy` gem is distributed under the Apache
 [slack-channel]: https://cloud-native.slack.com/archives/C01NWKKMKMY
 [discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions
 [opentelemetry-mysql]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation/mysql2
+
+## Database semantic convention stability
+
+In the OpenTelemetry ecosystem, database semantic conventions have now reached a stable state. However, the initial Trilogy 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, Trilogy instrumentation code comes in three patch versions: `dup`, `old`, and `stable`. These versions are identical except for the attributes they send. Any changes to Trilogy 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/).

instrumentation/trilogy/lib/opentelemetry/instrumentation/trilogy/instrumentation.rb

@@ -10,8 +10,9 @@ module Trilogy
       # The Instrumentation class contains logic to detect and install the Trilogy instrumentation
       class Instrumentation < OpenTelemetry::Instrumentation::Base
         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
 
@@ -33,12 +34,45 @@ class Instrumentation < OpenTelemetry::Instrumentation::Base
 
         private
 
-        def require_dependencies
-          require_relative 'patches/client'
+        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/client'
+        end
+
+        def require_dependencies_stable
+          require_relative 'patches/stable/client'
+        end
+
+        def require_dependencies_old
+          require_relative 'patches/old/client'
         end
 
         def patch_client
-          ::Trilogy.prepend(Patches::Client)
+          ::Trilogy.prepend(Patches::Dup::Client)
+        end
+
+        def patch_client_stable
+          ::Trilogy.prepend(Patches::Stable::Client)
+        end
+
+        def patch_client_old
+          ::Trilogy.prepend(Patches::Old::Client)
+        end
+
+        def patch_client_dup
+          ::Trilogy.prepend(Patches::Dup::Client)
         end
 
         def configure_propagator(config)

instrumentation/trilogy/lib/opentelemetry/instrumentation/trilogy/patches/dup/client.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry-helpers-mysql'
+require 'opentelemetry-helpers-sql-obfuscation'
+
+module OpenTelemetry
+  module Instrumentation
+    module Trilogy
+      module Patches
+        module Dup
+          # Module to prepend to Trilogy for instrumentation
+          module Client
+            def initialize(options = {})
+              @connection_options = options # This is normally done by Trilogy#initialize
+
+              tracer.in_span(
+                'connect',
+                attributes: client_attributes.merge!(OpenTelemetry::Instrumentation::Trilogy.attributes),
+                kind: :client
+              ) do
+                super
+              end
+            end
+
+            def ping(...)
+              tracer.in_span(
+                'ping',
+                attributes: client_attributes.merge!(OpenTelemetry::Instrumentation::Trilogy.attributes),
+                kind: :client
+              ) do
+                super
+              end
+            end
+
+            def query(sql)
+              tracer.in_span(
+                OpenTelemetry::Helpers::MySQL.database_span_name(
+                  sql,
+                  OpenTelemetry::Instrumentation::Trilogy.attributes[
+                    'db.operation.name'
+                  ],
+                  database_name,
+                  config
+                ),
+                attributes: client_attributes(sql).merge!(
+                  OpenTelemetry::Instrumentation::Trilogy.attributes
+                ),
+                kind: :client
+              ) do |_span, context|
+                if propagator && sql.frozen?
+                  sql = +sql
+                  propagator.inject(sql, context: context)
+                  sql.freeze
+                elsif propagator
+                  propagator.inject(sql, context: context)
+                end
+
+                super
+              end
+            end
+
+            private
+
+            def client_attributes(sql = nil)
+              attributes = {
+                ::OpenTelemetry::SemanticConventions::Trace::DB_SYSTEM => 'mysql',
+                ::OpenTelemetry::SemanticConventions::Trace::NET_PEER_NAME => connection_options&.fetch(:host, 'unknown sock') || 'unknown sock',
+                'db.system.name' => 'mysql',
+                'server.address' => connection_options&.fetch(:host, 'unknown sock') || 'unknown sock'
+              }
+
+              attributes[::OpenTelemetry::SemanticConventions::Trace::DB_NAME] = database_name if database_name
+              attributes['db.namespace'] = database_name if database_name
+              attributes[::OpenTelemetry::SemanticConventions::Trace::DB_USER] = database_user if database_user
+              attributes[::OpenTelemetry::SemanticConventions::Trace::PEER_SERVICE] = config[:peer_service] unless config[:peer_service].nil?
+              attributes['db.instance.id'] = @connected_host unless @connected_host.nil?
+
+              if sql
+                case config[:db_statement]
+                when :obfuscate
+                  attributes[::OpenTelemetry::SemanticConventions::Trace::DB_STATEMENT] =
+                    OpenTelemetry::Helpers::SqlObfuscation.obfuscate_sql(sql, obfuscation_limit: config[:obfuscation_limit], adapter: :mysql)
+                  attributes['db.query.text'] =
+                    OpenTelemetry::Helpers::SqlObfuscation.obfuscate_sql(sql, obfuscation_limit: config[:obfuscation_limit], adapter: :mysql)
+                when :include
+                  attributes[::OpenTelemetry::SemanticConventions::Trace::DB_STATEMENT] = sql
+                  attributes['db.query.text'] = sql
+                end
+              end
+
+              attributes
+            end
+
+            def database_name
+              connection_options[:database]
+            end
+
+            def database_user
+              connection_options[:username]
+            end
+
+            def tracer
+              Trilogy::Instrumentation.instance.tracer
+            end
+
+            def config
+              Trilogy::Instrumentation.instance.config
+            end
+
+            def propagator
+              Trilogy::Instrumentation.instance.propagator
+            end
+          end
+        end
+      end
+    end
+  end
+end