aws_advanced_ruby_driver_wrapper 1.0.1 → 1.1.0

data/lib/aws_advanced_ruby_driver_wrapper/utils/parser/sql_parser.rb

@@ -39,28 +39,34 @@ module AwsAdvancedRubyDriverWrapper
         MAX_CACHE_ENTRIES = 1000
 
         def initialize(driver_dialect)
-          @analyzer = resolve_analyzer(driver_dialect)
+          @pg = pg_dialect?(driver_dialect)
+          @analyzer = resolve_analyzer
           # A parser belongs to one connection, which is used by one thread at a time, so this plain
           # hash needs no lock. Insertion order is used as the eviction order (least-recently-used).
           @cache = {}
         end
 
         # Returns the analysis for +sql+, parsing it only on the first sight of a given statement and
-        # serving repeats from a bounded cache. The result is a pure function of the SQL for this
-        # parser's dialect, so caching by the SQL string is safe.
+        # serving repeats from a bounded cache. The result is a pure function of the SQL and the
+        # server version for this parser's dialect, so caching by the two of them is safe. The version
+        # is part of the key because a connection can reach a server of another version after a
+        # failover or a blue/green switchover.
         #
+        # @param server_version [Integer, nil] the MySQL server's version, which decides whether a
+        #   versioned +/*!+ comment is part of the statement; ignored on PostgreSQL
         # @raise [StandardError] whatever the underlying analyzer raises on SQL it cannot read
-        def analyze_sql(sql)
+        def analyze_sql(sql, server_version: nil)
           return empty_result unless sql.is_a?(String) && !sql.strip.empty?
 
-          cached = @cache.delete(sql)
+          key = [sql, server_version]
+          cached = @cache.delete(key)
           unless cached.nil?
-            @cache[sql] = cached # re-insert so it counts as most-recently-used
+            @cache[key] = cached # re-insert so it counts as most-recently-used
             return cached
           end
 
-          result = build_analysis(sql)
-          @cache[sql] = result
+          result = build_analysis(sql, server_version)
+          @cache[key] = result
           @cache.shift if @cache.size > MAX_CACHE_ENTRIES # evict the least-recently-used entry
           result
         end
@@ -72,17 +78,18 @@ module AwsAdvancedRubyDriverWrapper
         # the callers that must not write a value they cannot place look at the analysis itself.
         #
         # @param sql [String, nil]
+        # @param server_version [Integer, nil] see {#analyze_sql}
         # @return [Hash{Integer => String}]
-        def column_parameter_mapping(sql)
-          analyze_sql(sql).parameter_column_names
+        def column_parameter_mapping(sql, server_version: nil)
+          analyze_sql(sql, server_version: server_version).parameter_column_names
         rescue StandardError
           {}
         end
 
         private
 
-        def build_analysis(sql)
-          analysis = @analyzer.analyze(sql)
+        def build_analysis(sql, server_version)
+          analysis = @pg ? @analyzer.analyze(sql) : @analyzer.analyze(sql, server_version: server_version)
           SqlAnalysisResult.new(
             query_type: analysis.query_type,
             affected_tables: analysis.tables.to_set { |table_name| strip_schema_prefix(table_name) },
@@ -109,8 +116,8 @@ module AwsAdvancedRubyDriverWrapper
           end
         end
 
-        def resolve_analyzer(driver_dialect)
-          if pg_dialect?(driver_dialect)
+        def resolve_analyzer
+          if @pg
             require_relative 'pg_statement_analyzer'
             # Loaded now rather than on the first statement, so a missing pg_query gem is reported
             # when the parser is created instead of in the middle of a query.

data/lib/aws_advanced_ruby_driver_wrapper/utils/retry_util.rb

@@ -137,7 +137,8 @@ module AwsAdvancedRubyDriverWrapper
 
       def select_candidate(hosts, role, strategy)
         @host_service.select_host(hosts, role, strategy)
-      rescue StandardError
+      rescue StandardError => e
+        logger.warn("Failed to select a host using the '#{strategy}' host selection strategy: #{e.message}")
         nil
       end
 

data/lib/aws_advanced_ruby_driver_wrapper/utils/saml_utils.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+require 'digest'
+require 'net/http'
+require 'openssl'
+require 'uri'
+require_relative '../errors'
+
+module AwsAdvancedRubyDriverWrapper
+  module Utils
+    # Shared helpers for the SAML-based authentication plugins (AD FS, Okta):
+    # URL validation, the cache-key principal fingerprint, and a small Net::HTTP
+    # client used to talk to the identity provider's HTTP endpoints (there is no
+    # AWS SDK for these calls).
+    module SamlUtils
+      module_function
+
+      HTTPS_URL_PATTERN = %r{\Ahttps://[-a-zA-Z0-9+&@#/%?=~_!:,.']*[-a-zA-Z0-9+&@#/%=~_']}
+
+      # The regex the IdP sign-in response is scraped with for the SAML assertion,
+      # shared by the AD FS and Okta flows.
+      SAML_RESPONSE_PATTERN = /SAMLResponse\W+value="([^"]+)"/
+
+      # Rejects anything that is not a well-formed https:// URL, guarding the IdP
+      # requests against being redirected to a non-TLS or malformed endpoint.
+      #
+      # @raise [Errors::SamlAuthError] when the URL is not a valid https URL
+      def validate_url!(url)
+        uri = URI.parse(url)
+        return if uri.is_a?(URI::HTTPS) && url.match?(HTTPS_URL_PATTERN)
+
+        raise Errors::SamlAuthError, "Invalid HTTPS URL: #{url}"
+      rescue URI::InvalidURIError
+        raise Errors::SamlAuthError, "Invalid HTTPS URL: #{url}"
+      end
+
+      # A short, stable fingerprint of the AWS principal a SAML connection assumes,
+      # for the token cache key. The principal is fully determined by the STS
+      # inputs iam_role_arn + iam_idp_arn, so two connections that assume different
+      # roles (or trust different identity providers) never share a cached token.
+      # No secret is included, and the federated username is intentionally excluded:
+      # once the role is assumed the database authority is the role.
+      #
+      # @param parts [Array<String, nil>] role_arn, idp_arn
+      # @return [String] 16 hex characters
+      def principal_fingerprint(*parts)
+        Digest::SHA256.hexdigest(parts.join("\0"))[0, 16]
+      end
+
+      # Performs an HTTP request against an IdP endpoint, following redirects and
+      # carrying cookies across them (AD FS and Okta both rely on this). Only
+      # https URLs are allowed; each hop is validated.
+      #
+      # @param method [Symbol] :get or :post
+      # @param url [String] the https URL to request
+      # @param body [String, nil] request body for :post
+      # @param headers [Hash] request headers
+      # @param ssl_insecure [Boolean] skip TLS verification when true
+      # @param open_timeout_sec [Float] connect timeout in seconds
+      # @param read_timeout_sec [Float] socket timeout in seconds
+      # @param cookies [Hash] a cookie jar, keyed by host then cookie name, shared across the
+      #   calls of one sign-on flow and mutated in place. Cookies are only sent back to the host
+      #   that set them, so following a redirect to another host cannot leak them.
+      # @return [Net::HTTPResponse]
+      def http_request(method:, url:, body: nil, headers: {}, ssl_insecure: false,
+                       open_timeout_sec: 60.0, read_timeout_sec: 60.0, max_redirects: 3, cookies: {})
+        redirects = 0
+        loop do
+          validate_url!(url)
+          uri = URI.parse(url)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+          http.verify_mode = ssl_insecure ? OpenSSL::SSL::VERIFY_NONE : OpenSSL::SSL::VERIFY_PEER
+          http.open_timeout = open_timeout_sec
+          http.read_timeout = read_timeout_sec
+
+          request = build_request(method, uri, body, headers, cookies)
+          response = http.request(request)
+          merge_cookies!(cookies, uri.host, response)
+
+          if response.is_a?(Net::HTTPRedirection) && response['location'] && redirects < max_redirects
+            url = absolute_redirect(uri, response['location'])
+            method = :get
+            body = nil
+            redirects += 1
+            next
+          end
+
+          return response
+        end
+      end
+
+      def build_request(method, uri, body, headers, cookies)
+        request =
+          case method
+          when :post then Net::HTTP::Post.new(uri)
+          else Net::HTTP::Get.new(uri)
+          end
+        headers.each { |k, v| request[k] = v }
+        request.body = body if body
+        host_jar = cookies[uri.host]
+        request['Cookie'] = host_jar.map { |k, v| "#{k}=#{v}" }.join('; ') if host_jar && !host_jar.empty?
+        request
+      end
+
+      def merge_cookies!(cookies, host, response)
+        jar = (cookies[host] ||= {})
+        Array(response.get_fields('set-cookie')).each do |raw|
+          pair = raw.split(';', 2).first.to_s.split('=', 2)
+          jar[pair[0].strip] = pair[1] if pair.length == 2
+        end
+      end
+
+      def absolute_redirect(uri, location)
+        URI.join(uri, location).to_s
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/utils/storage/storage_service.rb

@@ -63,9 +63,11 @@ module AwsAdvancedRubyDriverWrapper
         # Retrieves an item. Returns nil if absent or expired.
         # @param name [Symbol] registered cache name.
         # @param key [Object] item key.
-        # @param register_access [Boolean] whether to publish a DataAccessEvent.
+        # @param register_access [Boolean] whether to publish a DataAccessEvent, which extends the expiration of
+        #   any monitor registered with this cache name as its produced_data_type. Pass true only when this read
+        #   should keep that monitor alive.
         # @return [Object, nil]
-        def get(name, key, register_access: true)
+        def get(name, key, register_access: false)
           value = fetch_cache!(name).get(key)
           return nil unless value
 
@@ -80,9 +82,11 @@ module AwsAdvancedRubyDriverWrapper
         # plugin configuration (e.g. a plugin reading a cache owned by another, optional plugin).
         # @param name [Symbol] cache name (need not be registered).
         # @param key [Object] item key.
-        # @param register_access [Boolean] whether to publish a DataAccessEvent.
+        # @param register_access [Boolean] whether to publish a DataAccessEvent, which extends the expiration of
+        #   any monitor registered with this cache name as its produced_data_type. Pass true only when this read
+        #   should keep that monitor alive.
         # @return [Object, nil]
-        def get_if_registered(name, key, register_access: true)
+        def get_if_registered(name, key, register_access: false)
           cache = @caches[name]
           return nil if cache.nil?
 
@@ -99,7 +103,7 @@ module AwsAdvancedRubyDriverWrapper
         # @param key [Object] item key.
         # @return [Boolean]
         def exists?(name, key)
-          !get(name, key, register_access: false).nil?
+          !get(name, key).nil?
         end
 
         # Removes an item.

data/lib/aws_advanced_ruby_driver_wrapper/utils/telemetry/null_telemetry.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+module AwsAdvancedRubyDriverWrapper
+  module Utils
+    module Telemetry
+      # Stands in for a context when no span is recorded, so callers never have to check for nil.
+      class NullTelemetryContext
+        INSTANCE = new.freeze
+
+        def name
+          'null'
+        end
+
+        def success=(_success); end
+
+        def set_attribute(_key, _value); end
+
+        def record_exception(_exception); end
+
+        def close; end
+      end
+
+      class NullTelemetryCounter
+        INSTANCE = new.freeze
+
+        def name
+          'null'
+        end
+
+        def add(_value); end
+
+        def inc; end
+      end
+
+      class NullTelemetryGauge
+        INSTANCE = new.freeze
+
+        def name
+          'null'
+        end
+      end
+
+      # The factory used when telemetry is disabled.
+      class NullTelemetryFactory
+        def open_telemetry_context(_name, _trace_level)
+          NullTelemetryContext::INSTANCE
+        end
+
+        def in_context(_name, _trace_level, record_result: false, record_failure: false)
+          yield NullTelemetryContext::INSTANCE
+        end
+
+        def post_copy(_context, _trace_level); end
+
+        def create_counter(_name)
+          NullTelemetryCounter::INSTANCE
+        end
+
+        def create_gauge(_name, &)
+          NullTelemetryGauge::INSTANCE
+        end
+
+        def in_use?
+          false
+        end
+
+        def traces_in_use?
+          false
+        end
+
+        INSTANCE = new.freeze
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/utils/telemetry/open_telemetry_context.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+require_relative '../../logging'
+require_relative 'telemetry_const'
+
+module AwsAdvancedRubyDriverWrapper
+  module Utils
+    module Telemetry
+      # A span, made the current one for as long as the context is open. Contexts must be closed in
+      # the reverse order they were opened, which {TelemetryFactory#in_context} guarantees.
+      class OpenTelemetryContext
+        include Logging
+
+        attr_reader :name
+
+        # @param start_timestamp [Time, nil] when the span started; now when nil
+        # @param links [Array<OpenTelemetry::Trace::Link>] spans the new span is linked to
+        def initialize(tracer, name, trace_level, start_timestamp: nil, links: [])
+          @name = name
+          @tracer = tracer
+          parent = OpenTelemetry::Trace.current_span.context
+          in_trace = parent.valid?
+          trace_level = TraceLevel::NO_TRACE if trace_level == TraceLevel::NESTED && !in_trace
+
+          case trace_level
+          when TraceLevel::FORCE_TOP_LEVEL, TraceLevel::TOP_LEVEL
+            # A top-level span starts a trace of its own. When there was a trace in progress, the new
+            # one is linked to it and records its ID, so the two can still be found together.
+            links += [OpenTelemetry::Trace::Link.new(parent)] if in_trace
+            @span = tracer.start_root_span(name, links: links.empty? ? nil : links, start_timestamp: start_timestamp)
+            set_attribute(TelemetryConst::PARENT_TRACE_ANNOTATION, parent.hex_trace_id) if in_trace
+            set_attribute(TelemetryConst::TRACE_NAME_ANNOTATION, name)
+            make_current
+            logger.debug { "[OTLP] Telemetry '#{name}' trace ID: #{@span.context.hex_trace_id}" }
+          when TraceLevel::NESTED
+            @span = tracer.start_span(name, links: links.empty? ? nil : links, start_timestamp: start_timestamp)
+            set_attribute(TelemetryConst::TRACE_NAME_ANNOTATION, name)
+            make_current
+          end
+        end
+
+        def success=(success)
+          return if @span.nil?
+
+          @span.status = success ? OpenTelemetry::Trace::Status.ok : OpenTelemetry::Trace::Status.error
+        end
+
+        def set_attribute(key, value)
+          @span&.set_attribute(key, value)
+        end
+
+        def record_exception(exception)
+          return if @span.nil? || exception.nil?
+
+          # The exception event below holds the same details, but span attributes can be filtered and
+          # searched on in trace backends, which events often cannot.
+          @span.set_attribute(TelemetryConst::EXCEPTION_TYPE_ANNOTATION, exception.class.name)
+          @span.set_attribute(TelemetryConst::EXCEPTION_MESSAGE_ANNOTATION, exception.message.to_s)
+          @span.record_exception(exception)
+        end
+
+        # @param end_timestamp [Time, nil] when the span ended; now when nil
+        def close(end_timestamp: nil)
+          return if @span.nil?
+
+          @span.finish(end_timestamp: end_timestamp)
+          OpenTelemetry::Context.detach(@token)
+        end
+
+        # Records a copy of this context's span at the given trace level: same start and end times,
+        # attributes and status, linked to the original and carrying its trace ID. Used to submit a
+        # span that was recorded inside another trace as a trace of its own as well.
+        #
+        # Does nothing when the span cannot be read back, as with the no-op spans the OpenTelemetry API
+        # hands out before an SDK is installed.
+        def record_copy(trace_level)
+          return if @span.nil? || !@span.respond_to?(:to_span_data)
+
+          original = @span.to_span_data
+          copy = OpenTelemetryContext.new(
+            @tracer, "#{TelemetryConst::COPY_TRACE_NAME_PREFIX}#{name}", trace_level,
+            start_timestamp: nanoseconds_to_time(original.start_timestamp), links: [OpenTelemetry::Trace::Link.new(@span.context)]
+          )
+          original.attributes&.each do |key, value|
+            copy.set_attribute(key, value) unless key == TelemetryConst::TRACE_NAME_ANNOTATION
+          end
+          copy.span&.status = original.status
+          copy.set_attribute(TelemetryConst::SOURCE_TRACE_ANNOTATION, original.hex_trace_id)
+          copy.close(end_timestamp: nanoseconds_to_time(original.end_timestamp))
+        end
+
+        protected
+
+        attr_reader :span
+
+        private
+
+        # Recorded spans report their timestamps as nanoseconds since the epoch, but new spans are given
+        # theirs as times.
+        def nanoseconds_to_time(nanoseconds)
+          nanoseconds && Time.at(0, nanoseconds, :nanosecond)
+        end
+
+        def make_current
+          @token = OpenTelemetry::Context.attach(OpenTelemetry::Trace.context_with_span(@span))
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/utils/telemetry/open_telemetry_counter.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+module AwsAdvancedRubyDriverWrapper
+  module Utils
+    module Telemetry
+      # A counter that only goes up.
+      class OpenTelemetryCounter
+        attr_reader :name
+
+        def initialize(meter, name)
+          @name = name
+          @counter = meter.create_counter(name)
+        end
+
+        def add(value)
+          @counter.add(value)
+        end
+
+        def inc
+          add(1)
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/utils/telemetry/open_telemetry_factory.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+require_relative '../../version'
+require_relative 'telemetry_const'
+require_relative 'open_telemetry_context'
+require_relative 'open_telemetry_counter'
+require_relative 'open_telemetry_gauge'
+
+module AwsAdvancedRubyDriverWrapper
+  module Utils
+    module Telemetry
+      # Records telemetry through the OpenTelemetry API. The application owns the SDK: it installs
+      # the tracer and meter providers and the exporters, and until it does, the API discards what is
+      # recorded here.
+      #
+      # The OpenTelemetry gems are optional dependencies of the wrapper, so they are only loaded
+      # when a backend that needs them is selected.
+      module OpenTelemetryFactory
+        NAME_MAX_LENGTH = 255
+
+        @gauges = {}
+        @gauges_lock = Mutex.new
+
+        class << self
+          def require_traces_api!
+            require 'opentelemetry-api'
+          rescue LoadError
+            raise LoadError,
+                  "telemetry_traces_backend 'otlp' requires 'opentelemetry-api'. " \
+                  "Add it to your Gemfile: gem 'opentelemetry-api' (or gem 'opentelemetry-sdk')"
+          end
+
+          def require_metrics_api!
+            require 'opentelemetry-metrics-api'
+            begin
+              # Since opentelemetry-metrics-api 0.9.0, OpenTelemetry.meter_provider is only defined
+              # once this is required. Earlier versions define it as soon as the API is loaded.
+              require 'opentelemetry/metrics/global'
+            rescue LoadError
+              nil
+            end
+          rescue LoadError
+            raise LoadError,
+                  "telemetry_metrics_backend 'otlp' requires 'opentelemetry-metrics-api'. " \
+                  "Add it to your Gemfile: gem 'opentelemetry-metrics-api' (or gem 'opentelemetry-metrics-sdk')"
+          end
+
+          def open_telemetry_context(name, trace_level)
+            OpenTelemetryContext.new(tracer, name, trace_level)
+          end
+
+          def post_copy(context, trace_level)
+            return if trace_level == TraceLevel::NO_TRACE || !context.is_a?(OpenTelemetryContext)
+            # A top-level copy must not find the trace in progress, or it would be linked to that trace
+            # as well as to the span it copies.
+            return context.record_copy(trace_level) if trace_level == TraceLevel::NESTED
+
+            OpenTelemetry::Context.with_current(OpenTelemetry::Context.empty) { context.record_copy(trace_level) }
+          end
+
+          # Unlike gauges, counters need no registry: in current versions of the metrics SDK (0.21 on),
+          # creating one again under the same name returns the instrument the meter already has, so every
+          # counter object adds to the same total.
+          def create_counter(name)
+            OpenTelemetryCounter.new(meter, trim(name))
+          end
+
+          # There is one gauge per name for the whole process, since every connection records through
+          # the same meter. Creating a gauge that already exists replaces its callback, so the gauge
+          # reports the value of the callback set last.
+          def create_gauge(name, callback)
+            name = trim(name)
+            @gauges_lock.synchronize do
+              gauge = (@gauges[name] ||= OpenTelemetryGauge.new(meter, name))
+              gauge.callback = callback
+              gauge
+            end
+          end
+
+          # Stops every gauge from reporting until it is created again: a gauge without a callback is
+          # skipped when metrics are collected. The gauges themselves stay registered, since
+          # registering one again under the same name would not take a new callback. For testing only.
+          #
+          # @api private
+          def clear_gauge_callbacks!
+            @gauges_lock.synchronize { @gauges.each_value { |gauge| gauge.callback = nil } }
+          end
+
+          private
+
+          # Both are safe to keep: until the application installs its SDK, the API hands out proxies
+          # that start delegating to the SDK once it is installed.
+          def tracer
+            @tracer ||= OpenTelemetry.tracer_provider.tracer(INSTRUMENTATION_NAME, VERSION)
+          end
+
+          def meter
+            @meter ||= OpenTelemetry.meter_provider.meter(INSTRUMENTATION_NAME, version: VERSION)
+          end
+
+          def trim(name)
+            name.length > NAME_MAX_LENGTH ? name[0, NAME_MAX_LENGTH] : name
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/utils/telemetry/open_telemetry_gauge.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+module AwsAdvancedRubyDriverWrapper
+  module Utils
+    module Telemetry
+      # A gauge whose value is read from its callback each time metrics are collected.
+      #
+      # The instrument is registered once, and reads whichever callback was set last. The callback
+      # can therefore be replaced, which a second registration of the same instrument would not do.
+      class OpenTelemetryGauge
+        attr_reader :name
+        attr_writer :callback
+
+        def initialize(meter, name)
+          @name = name
+          @callback = nil
+          @gauge = meter.create_observable_gauge(name, callback: -> { @callback&.call })
+        end
+      end
+    end
+  end
+end