opentelemetry-instrumentation-aws_sdk 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05256cef329eccec85d4d6732b402aa9c1be08fa39da455cee3ed43d4b0ed9c7
-  data.tar.gz: d4f05d032386bdbabfb064e051757a02fc27b75947594bb89211b311abb54446
+  metadata.gz: 5a1737d6415b37a7dd50b35665accac0bd593102b70727293ac6ebce5dd1a18e
+  data.tar.gz: 6d384f2db9b25de83ed241078860ffef7adbf97af82eef6040e37d090f33a251
 SHA512:
-  metadata.gz: 7dada29094deea482504658785d9b13ce16d2e8d4198d0c08b64c378618cda70d30744ece8a0b59a12df3a39f18a23ca9f93c1b3186ea51e53e4a6c03e887127
-  data.tar.gz: 379d073b4f1d46dce866fdd15a85677cc7f436b82c608a40731f4a716222fda9b3774fecf0264679046f79b1cf71179398a7c555c7815f8f35e5ce461784eb73
+  metadata.gz: af47533a44748af6fdd8bb6df9954d1bad9feb1fd4b14940aaa7ea10a1fe91f490552d533a820f3ad2408174f68ba5d9abfcaba35f55af7f50e7341a841a190f
+  data.tar.gz: eef0233dcf8f745fd90805c96a1d85d377d128be21ff629e812195af4f141499a824c629a0cda120add8ad89e2220fdd9e78159cdb11833056e35096f80b2638

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Release History: opentelemetry-instrumentation-aws_sdk
 
+### v0.8.0 / 2025-01-16
+
+* BREAKING CHANGE: Set minimum supported version to Ruby 3.1
+
+* ADDED: Set minimum supported version to Ruby 3.1
+
+### v0.7.0 / 2024-10-08
+
+* ADDED: Integration with V3 telemetry provider
+
 ### v0.6.0 / 2024-09-19
 
 * ADDED: All AWS services emit traces

data/README.md

@@ -32,6 +32,30 @@ OpenTelemetry::SDK.configure do |c|
   c.use_all
 end
 ```
+### Configuration options
+This instrumentation offers the following configuration options: 
+* `:inject_messaging_context` (default: `false`): When set to `true`, adds context key/value 
+ to Message Attributes for SQS/SNS messages.
+* `suppress_internal_instrumentation` (default: `false`): When set to `true`, any spans with 
+ span kind of `internal` are suppressed from traces.
+
+## Integration with SDK V3's Telemetry support
+AWS SDK for Ruby V3 added support for Observability which includes a new configuration, 
+`telemetry_provider` and an OpenTelemetry-based telemetry provider. Only applies to
+AWS service gems released after 2024-09-03. 
+
+Using later versions of these gems will give more details on the internal spans. 
+See below for example usage:
+```ruby
+# configures the OpenTelemetry SDK with instrumentation defaults
+OpenTelemetry::SDK.configure do |c|
+  c.use 'OpenTelemetry::Instrumentation::AwsSdk'
+end
+
+# create open-telemetry provider and pass to client config
+otel_provider = Aws::Telemetry::OTelProvider.new
+client = Aws::S3::Client.new(telemetry_provider: otel_provider)
+```
 
 ## Example
 

data/lib/opentelemetry/instrumentation/aws_sdk/handler.rb

@@ -7,26 +7,23 @@
 module OpenTelemetry
   module Instrumentation
     module AwsSdk
-      # Generates Spans for all interactions with AwsSdk
+      # This handler supports specifically supports V2 and V3
+      # prior to Observability support released on 2024-09-03.
       class Handler < Seahorse::Client::Handler
         def call(context)
           return super unless context
 
-          service_id = service_name(context)
-          operation = context.operation&.name
-          client_method = "#{service_id}.#{operation}"
+          service_id = HandlerHelper.service_id(context, legacy: true)
+          client_method = HandlerHelper.client_method(service_id, context)
 
           tracer.in_span(
-            span_name(context, client_method, service_id),
-            attributes: attributes(context, client_method, service_id, operation),
-            kind: span_kind(client_method, service_id)
+            HandlerHelper.span_name(context, client_method, service_id, legacy: true),
+            attributes: HandlerHelper.span_attributes(context, client_method, service_id, legacy: true),
+            kind: HandlerHelper.span_kind(client_method, service_id)
           ) do |span|
-            if instrumentation_config[:inject_messaging_context] &&
-               %w[SQS SNS].include?(service_id)
-              MessagingHelper.inject_context(context, client_method)
-            end
+            MessagingHelper.inject_context_if_supported(context, client_method, service_id)
 
-            if instrumentation_config[:suppress_internal_instrumentation]
+            if HandlerHelper.instrumentation_config[:suppress_internal_instrumentation]
               OpenTelemetry::Common::Utilities.untraced { super }
             else
               super
@@ -49,47 +46,6 @@ module OpenTelemetry
         def tracer
           AwsSdk::Instrumentation.instance.tracer
         end
-
-        def instrumentation_config
-          AwsSdk::Instrumentation.instance.config
-        end
-
-        def service_name(context)
-          # Support aws-sdk v2.0.x, which 'metadata' has a setter method only
-          return context.client.class.to_s.split('::')[1] if ::Seahorse::Model::Api.instance_method(:metadata).parameters.length.positive?
-
-          context.client.class.api.metadata['serviceId'] || context.client.class.to_s.split('::')[1]
-        end
-
-        def span_kind(client_method, service_id)
-          case service_id
-          when 'SQS', 'SNS'
-            MessagingHelper.span_kind(client_method)
-          else
-            OpenTelemetry::Trace::SpanKind::CLIENT
-          end
-        end
-
-        def span_name(context, client_method, service_id)
-          case service_id
-          when 'SQS', 'SNS'
-            MessagingHelper.legacy_span_name(context, client_method)
-          else
-            client_method
-          end
-        end
-
-        def attributes(context, client_method, service_id, operation)
-          {
-            'aws.region' => context.config.region,
-            OpenTelemetry::SemanticConventions::Trace::RPC_SYSTEM => 'aws-api',
-            OpenTelemetry::SemanticConventions::Trace::RPC_METHOD => operation,
-            OpenTelemetry::SemanticConventions::Trace::RPC_SERVICE => service_id
-          }.tap do |attrs|
-            attrs[SemanticConventions::Trace::DB_SYSTEM] = 'dynamodb' if service_id == 'DynamoDB'
-            MessagingHelper.apply_span_attributes(context, attrs, client_method, service_id) if %w[SQS SNS].include?(service_id)
-          end
-        end
       end
 
       # A Seahorse::Client::Plugin that enables instrumentation for all AWS services

data/lib/opentelemetry/instrumentation/aws_sdk/handler_helper.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Instrumentation
+    module AwsSdk
+      # Utility module that contains shared methods between AwsSdk and Telemetry handlers
+      module HandlerHelper
+        class << self
+          def instrumentation_config
+            AwsSdk::Instrumentation.instance.config
+          end
+
+          def client_method(service_id, context)
+            "#{service_id}.#{context.operation.name}".delete(' ')
+          end
+
+          def span_attributes(context, client_method, service_id, legacy: false)
+            {
+              'aws.region' => context.config.region,
+              OpenTelemetry::SemanticConventions::Trace::CODE_FUNCTION => context.operation_name.to_s,
+              OpenTelemetry::SemanticConventions::Trace::CODE_NAMESPACE => 'Aws::Plugins::Telemetry',
+              OpenTelemetry::SemanticConventions::Trace::RPC_METHOD => context.operation.name,
+              OpenTelemetry::SemanticConventions::Trace::RPC_SERVICE => service_id,
+              OpenTelemetry::SemanticConventions::Trace::RPC_SYSTEM => 'aws-api'
+            }.tap do |attrs|
+              attrs[OpenTelemetry::SemanticConventions::Trace::CODE_NAMESPACE] = 'Aws::Plugins::AwsSdk' if legacy
+              attrs[SemanticConventions::Trace::DB_SYSTEM] = 'dynamodb' if service_id == 'DynamoDB'
+
+              MessagingHelper.apply_span_attributes(context, attrs, client_method, service_id) if MessagingHelper::SUPPORTED_SERVICES.include?(service_id)
+            end
+          end
+
+          def span_kind(client_method, service_id)
+            case service_id
+            when *MessagingHelper::SUPPORTED_SERVICES
+              MessagingHelper.span_kind(client_method)
+            else
+              OpenTelemetry::Trace::SpanKind::CLIENT
+            end
+          end
+
+          def span_name(context, client_method, service_id, legacy: false)
+            case service_id
+            when *MessagingHelper::SUPPORTED_SERVICES
+              if legacy
+                MessagingHelper.legacy_span_name(context, client_method)
+              else
+                MessagingHelper.span_name(context, client_method)
+              end
+            else
+              client_method
+            end
+          end
+
+          def service_id(context, legacy: false)
+            if legacy
+              legacy_service_id(context)
+            else
+              context.config.api.metadata['serviceId'] ||
+                context.config.api.metadata['serviceAbbreviation'] ||
+                context.config.api.metadata['serviceFullName']
+            end
+          end
+
+          private
+
+          def legacy_service_id(context)
+            # Support aws-sdk v2.0.x, which 'metadata' has a setter method only
+            return context.client.class.to_s.split('::')[1] if ::Seahorse::Model::Api.instance_method(:metadata).parameters.length.positive?
+
+            context.client.class.api.metadata['serviceId'] || context.client.class.to_s.split('::')[1]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/instrumentation/aws_sdk/instrumentation.rb

@@ -7,12 +7,38 @@
 module OpenTelemetry
   module Instrumentation
     module AwsSdk
-      # Instrumentation class that detects and installs the AwsSdk instrumentation
+      # The `OpenTelemetry::Instrumentation::AwsSdk::Instrumentation` class contains
+      # logic to detect and install the AwsSdk instrumentation.
+      #
+      # ## Configuration keys and options
+      #
+      # ### `:inject_messaging_context`
+      #
+      # Allows adding of context key/value to Message Attributes for SQS/SNS messages.
+      #
+      # - `false` **(default)** - Context key/value will not be added.
+      # - `true` - Context key/value will be added.
+      #
+      # ### `:suppress_internal_instrumentation`
+      #
+      # Disables tracing of spans of `internal` span kind.
+      #
+      # - `false` **(default)** - Internal spans are traced.
+      # - `true` - Internal spans are not traced.
+      #
+      # @example An explicit default configuration
+      #   OpenTelemetry::SDK.configure do |c|
+      #     c.use 'OpenTelemetry::Instrumentation::AwsSdk', {
+      #       inject_messaging_context: false,
+      #       suppress_internal_instrumentation: false
+      #     }
+      #   end
       class Instrumentation < OpenTelemetry::Instrumentation::Base
         MINIMUM_VERSION = Gem::Version.new('2.0.0')
 
         install do |_config|
           require_dependencies
+          patch_telemetry_plugin if telemetry_plugin?
           add_plugins(Seahorse::Client::Base, *loaded_service_clients)
         end
 
@@ -41,12 +67,34 @@ module OpenTelemetry
 
         def require_dependencies
           require_relative 'handler'
+          require_relative 'handler_helper'
           require_relative 'message_attributes'
           require_relative 'messaging_helper'
+          require_relative 'patches/telemetry'
         end
 
         def add_plugins(*targets)
-          targets.each { |klass| klass.add_plugin(AwsSdk::Plugin) }
+          targets.each do |klass|
+            next if supports_telemetry_plugin?(klass)
+
+            klass.add_plugin(AwsSdk::Plugin)
+          end
+        end
+
+        def supports_telemetry_plugin?(klass)
+          telemetry_plugin? &&
+            klass.plugins.include?(Aws::Plugins::Telemetry)
+        end
+
+        def telemetry_plugin?
+          ::Aws::Plugins.const_defined?(:Telemetry)
+        end
+
+        # Patches AWS SDK V3's telemetry plugin for integration
+        # This patch supports configuration set by this gem and
+        # additional span attributes that was not provided by the plugin
+        def patch_telemetry_plugin
+          ::Aws::Plugins::Telemetry::Handler.prepend(Patches::Handler)
         end
 
         def loaded_service_clients

data/lib/opentelemetry/instrumentation/aws_sdk/messaging_helper.rb

@@ -9,6 +9,7 @@ module OpenTelemetry
     module AwsSdk
       # An utility class to help SQS/SNS-related span attributes/context injection
       class MessagingHelper
+        SUPPORTED_SERVICES = %w[SQS SNS].freeze
         class << self
           SQS_SEND_MESSAGE = 'SQS.SendMessage'
           SQS_SEND_MESSAGE_BATCH = 'SQS.SendMessageBatch'
@@ -16,6 +17,10 @@ module OpenTelemetry
           SNS_PUBLISH = 'SNS.Publish'
           SEND_MESSAGE_CLIENT_METHODS = [SQS_SEND_MESSAGE, SQS_SEND_MESSAGE_BATCH, SNS_PUBLISH].freeze
 
+          def supported_services
+            SUPPORTED_SERVICES
+          end
+
           def queue_name(context)
             topic_arn = context.params[:topic_arn]
             target_arn = context.params[:target_arn]
@@ -34,6 +39,17 @@ module OpenTelemetry
             'unknown'
           end
 
+          def span_name(context, client_method)
+            case client_method
+            when SQS_SEND_MESSAGE, SQS_SEND_MESSAGE_BATCH, SNS_PUBLISH
+              "#{client_method}.#{queue_name(context)}.Publish"
+            when SQS_RECEIVE_MESSAGE
+              "#{client_method}.#{queue_name(context)}.Receive"
+            else
+              client_method
+            end
+          end
+
           def legacy_span_name(context, client_method)
             case client_method
             when SQS_SEND_MESSAGE, SQS_SEND_MESSAGE_BATCH, SNS_PUBLISH
@@ -65,6 +81,13 @@ module OpenTelemetry
             end
           end
 
+          def inject_context_if_supported(context, client_method, service_id)
+            if HandlerHelper.instrumentation_config[:inject_messaging_context] &&
+               SUPPORTED_SERVICES.include?(service_id)
+              inject_context(context, client_method)
+            end
+          end
+
           def inject_context(context, client_method)
             return unless SEND_MESSAGE_CLIENT_METHODS.include?(client_method)
 

data/lib/opentelemetry/instrumentation/aws_sdk/patches/telemetry.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Instrumentation
+    module AwsSdk
+      module Patches
+        # Patch for Telemetry Plugin Handler in V3 SDK
+        module Handler
+          def call(context)
+            span_wrapper(context) { @handler.call(context) }
+          end
+
+          private
+
+          def span_wrapper(context, &block)
+            service_id = HandlerHelper.service_id(context)
+            client_method = HandlerHelper.client_method(service_id, context)
+            context.tracer.in_span(
+              HandlerHelper.span_name(context, client_method, service_id),
+              attributes: HandlerHelper.span_attributes(context, client_method, service_id),
+              kind: HandlerHelper.span_kind(client_method, service_id)
+            ) do |span|
+              MessagingHelper.inject_context_if_supported(context, client_method, service_id)
+
+              if HandlerHelper.instrumentation_config[:suppress_internal_instrumentation]
+                OpenTelemetry::Common::Utilities.untraced { super }
+              else
+                yield span
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/instrumentation/aws_sdk/version.rb

@@ -7,7 +7,7 @@
 module OpenTelemetry
   module Instrumentation
     module AwsSdk
-      VERSION = '0.6.0'
+      VERSION = '0.8.0'
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opentelemetry-instrumentation-aws_sdk
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - OpenTelemetry Authors
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-20 00:00:00.000000000 Z
+date: 2025-01-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opentelemetry-api
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.22.1
+        version: 0.23.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.22.1
+        version: 0.23.0
 - !ruby/object:Gem::Dependency
   name: appraisal
   requirement: !ruby/object:Gem::Requirement
@@ -156,28 +156,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.66.0
+        version: 1.69.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.66.0
+        version: 1.69.1
 - !ruby/object:Gem::Dependency
   name: rubocop-performance
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.20'
+        version: 1.23.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.20'
+        version: 1.23.0
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -198,14 +198,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.19'
+        version: 3.24.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.19'
+        version: 3.24.0
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -235,19 +235,21 @@ files:
 - lib/opentelemetry/instrumentation.rb
 - lib/opentelemetry/instrumentation/aws_sdk.rb
 - lib/opentelemetry/instrumentation/aws_sdk/handler.rb
+- lib/opentelemetry/instrumentation/aws_sdk/handler_helper.rb
 - lib/opentelemetry/instrumentation/aws_sdk/instrumentation.rb
 - lib/opentelemetry/instrumentation/aws_sdk/message_attributes.rb
 - lib/opentelemetry/instrumentation/aws_sdk/messaging_helper.rb
+- lib/opentelemetry/instrumentation/aws_sdk/patches/telemetry.rb
 - lib/opentelemetry/instrumentation/aws_sdk/version.rb
 homepage: https://github.com/open-telemetry/opentelemetry-ruby-contrib
 licenses:
 - Apache-2.0
 metadata:
-  changelog_uri: https://rubydoc.info/gems/opentelemetry-instrumentation-aws_sdk/0.6.0/file/CHANGELOG.md
+  changelog_uri: https://rubydoc.info/gems/opentelemetry-instrumentation-aws_sdk/0.8.0/file/CHANGELOG.md
   source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation/aws_sdk
   bug_tracker_uri: https://github.com/open-telemetry/opentelemetry-ruby-contrib/issues
-  documentation_uri: https://rubydoc.info/gems/opentelemetry-instrumentation-aws_sdk/0.6.0
-post_install_message: 
+  documentation_uri: https://rubydoc.info/gems/opentelemetry-instrumentation-aws_sdk/0.8.0
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -255,15 +257,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.33
-signing_key: 
+rubygems_version: 3.3.27
+signing_key:
 specification_version: 4
 summary: AWS SDK instrumentation for the OpenTelemetry framework
 test_files: []