appsignal 4.10.1-java → 5.0.0.rc.1-java

data/lib/appsignal/event_formatter/active_record/sql_formatter.rb

@@ -5,6 +5,25 @@ module Appsignal
     # @!visibility private
     module ActiveRecord
       class SqlFormatter < Appsignal::EventFormatter
+        # A query is an outgoing call to a datastore.
+        def opentelemetry_kind
+          :client
+        end
+
+        # The payload carries the connection the query ran on (Rails 6.0+),
+        # whose `adapter_name` is each adapter's own name for itself, such as
+        # `"PostgreSQL"` or `"Mysql2"`. A name the mapping does not recognise
+        # is left to the SQL sentinel, same as an adapter this gem has never
+        # heard of.
+        def opentelemetry_attributes(payload)
+          name = Appsignal::OpenTelemetry::SqlDbSystem.name_for_active_record(
+            payload[:connection]&.adapter_name
+          )
+          return unless name
+
+          { "db.system.name" => name }
+        end
+
         def format(payload)
           [payload[:name], payload[:sql], SQL_BODY_FORMAT]
         end

data/lib/appsignal/event_formatter/elastic_search/search_formatter.rb

@@ -5,6 +5,21 @@ module Appsignal
     # @!visibility private
     module ElasticSearch
       class SearchFormatter < Appsignal::EventFormatter
+        # A search is an outgoing call to an Elasticsearch cluster.
+        def opentelemetry_kind
+          :client
+        end
+
+        def opentelemetry_attributes(payload)
+          {
+            "db.system.name" => "elasticsearch",
+            # This notification is only emitted for a search, so that is the
+            # operation every one of these spans describes.
+            "db.operation.name" => "search",
+            "db.collection.name" => search_index(payload)
+          }.compact
+        end
+
         def format(payload)
           [
             "#{payload[:name]}: #{payload[:klass]}",
@@ -12,6 +27,18 @@ module Appsignal
           ]
         end
 
+        # The index a search ran against, which the notification carries in the
+        # search it describes. A search that names more than one index, or none
+        # at all, is left without this attribute rather than described with a
+        # value that is not an index name.
+        def search_index(payload)
+          search = payload[:search]
+          return unless search.respond_to?(:[])
+
+          index = search[:index]
+          index if index.is_a?(String)
+        end
+
         def sanitized_search(search)
           return unless search.is_a?(Hash)
 

data/lib/appsignal/event_formatter/recorded_elsewhere.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Appsignal
+  class EventFormatter
+    # Registered for an event that a dedicated AppSignal integration already
+    # records with richer semantics. The generic instrumentation paths ask the
+    # registry whether to record an event, so registering this for an event
+    # name is how that integration claims it.
+    #
+    # @!visibility private
+    class RecordedElsewhere < Appsignal::EventFormatter
+      def record?
+        false
+      end
+    end
+  end
+end

data/lib/appsignal/event_formatter/rom/sql_formatter.rb

@@ -5,6 +5,18 @@ module Appsignal
     # @!visibility private
     module Rom
       class SqlFormatter < Appsignal::EventFormatter
+        # These events arrive over dry-monitor, which is a notification bus
+        # rather than a library that queries a database. ROM is what emits
+        # them, so that is what the scope names.
+        def opentelemetry_scope
+          ["appsignal-ruby/rom", Appsignal::VERSION]
+        end
+
+        # A query is an outgoing call to a datastore.
+        def opentelemetry_kind
+          :client
+        end
+
         # dry-monitor reports an event under an id rather than a name, so the
         # first value here names the event. Naming it after ROM keeps every ROM
         # query in one group.
@@ -17,6 +29,18 @@ module Appsignal
         def format(payload)
           ["query.rom", payload[:query], SQL_BODY_FORMAT]
         end
+
+        # The payload's `name` is Sequel's `database_type` symbol for the
+        # database ROM is talking to, so this uses Sequel's own lookup
+        # rather than a coincidentally similar one. A symbol the mapping does
+        # not recognise is left to the SQL sentinel, same as an engine this
+        # gem has never heard of.
+        def opentelemetry_attributes(payload)
+          name = Appsignal::OpenTelemetry::SqlDbSystem.name_for_sequel(payload[:name])
+          return unless name
+
+          { "db.system.name" => name }
+        end
       end
     end
   end

data/lib/appsignal/event_formatter/sequel/sql_formatter.rb

@@ -10,6 +10,11 @@ module Appsignal
       # formatter the sequel-rails events are recorded without the SQL query
       # that's being executed.
       class SqlFormatter < Appsignal::EventFormatter
+        # A query is an outgoing call to a datastore.
+        def opentelemetry_kind
+          :client
+        end
+
         def format(payload)
           [payload[:name].to_s, payload[:sql], SQL_BODY_FORMAT]
         end

data/lib/appsignal/event_formatter/view_component/render_formatter.rb

@@ -7,11 +7,28 @@ module Appsignal
       class RenderFormatter < Appsignal::EventFormatter
         BLANK = ""
 
+        def opentelemetry_attributes(_payload)
+          Appsignal::OpenTelemetry::Rendering.attributes
+        end
+
         def format(payload)
+          # The body is the component's path made relative to the application's
+          # root, so a component rendered outside an application gets no title
+          # and no body.
+          return unless root_path
+
           [payload[:name], payload[:identifier].sub(root_path, BLANK)]
         end
 
+        # The application's root, which a component's path is made relative to.
+        #
+        # Whether there is an application is decided here, when the event is
+        # formatted, rather than when this file is loaded. AppSignal can be
+        # required before Rails is, and deciding it at load time would leave
+        # every component render in the application without a title.
         def root_path
+          return unless defined?(Rails)
+
           @root_path ||= "#{Rails.root}/"
         end
       end
@@ -19,13 +36,7 @@ module Appsignal
   end
 end
 
-if defined?(Rails)
-  Appsignal::EventFormatter.register(
-    "render.view_component",
-    Appsignal::EventFormatter::ViewComponent::RenderFormatter
-  )
-  Appsignal::EventFormatter.register(
-    "!render.view_component",
-    Appsignal::EventFormatter::ViewComponent::RenderFormatter
-  )
-end
+Appsignal::EventFormatter.register(
+  "render.view_component",
+  Appsignal::EventFormatter::ViewComponent::RenderFormatter
+)

data/lib/appsignal/event_formatter.rb

@@ -102,8 +102,77 @@ module Appsignal
         formatter&.format(payload)
       end
 
+      # The OpenTelemetry span kind for an event, which its formatter can
+      # declare. An event with no formatter, or whose formatter declares
+      # nothing, has no kind of its own and falls back to the default.
+      #
+      # A formatter written against the documented interface only implements
+      # `format`, so ask whether this one answers to the method at all rather
+      # than assuming every formatter does.
+      #
+      # @!visibility private
+      def opentelemetry_kind(name)
+        formatter = formatter_for(name)
+        return unless formatter.respond_to?(:opentelemetry_kind)
+
+        formatter.opentelemetry_kind
+      end
+
+      # The OpenTelemetry attributes describing an event, which its formatter
+      # can build from the event's payload. An event with no formatter, or
+      # whose formatter describes nothing, gets no attributes of its own.
+      #
+      # @!visibility private
+      def opentelemetry_attributes(name, payload)
+        formatter = formatter_for(name)
+        return unless formatter.respond_to?(:opentelemetry_attributes)
+
+        formatter.opentelemetry_attributes(payload)
+      end
+
+      # The OpenTelemetry instrumentation scope for an event, which its
+      # formatter can declare. It names the library the instrumentation is for,
+      # which is not always the library the event arrived through.
+      #
+      # An event with no formatter, or whose formatter declares nothing, is
+      # left to the scope the recording path derives for it.
+      #
+      # @!visibility private
+      def opentelemetry_scope(name)
+        formatter = formatter_for(name)
+        return unless formatter.respond_to?(:opentelemetry_scope)
+
+        formatter.opentelemetry_scope
+      end
+
+      # Whether the generic instrumentation paths should record an event, which
+      # its formatter can answer. An event a dedicated integration already
+      # records says no, so that it is not recorded a second time. An event
+      # with no formatter, or whose formatter says nothing, is recorded.
+      #
+      # @!visibility private
+      def record?(name)
+        formatter = formatter_for(name)
+        return true unless formatter.respond_to?(:record?)
+
+        formatter.record?
+      end
+
       private
 
+      # The formatter registered for an event name.
+      #
+      # A formatter is registered under whatever key was given to `register`,
+      # which is a String for every formatter in this gem. An event can be
+      # instrumented under a Symbol name, so fall back to the String form of it.
+      #
+      # `format` does not do this, on purpose. It has always looked a name up
+      # exactly as given, so making it match a Symbol name would start giving a
+      # title to events that have never had one.
+      def formatter_for(name)
+        formatters[name] || formatters[name.to_s]
+      end
+
       def initialize_formatter(name, formatter)
         format_method = formatter.instance_method(:format)
         if !format_method || format_method.arity != 1
@@ -123,6 +192,15 @@ module Appsignal
       end
     end
 
+    # The title and the body to show for an event, as an array. A formatter
+    # that is registered to describe an event in some other way, rather than to
+    # name it, does not have to implement this.
+    #
+    # @!visibility private
+    def format(_payload)
+      nil
+    end
+
     # @return [Integer]
     # @api public
     DEFAULT = 0

data/lib/appsignal/extension.rb

@@ -46,6 +46,10 @@ module Appsignal
         def data_array_new
           Appsignal::Extension::MockData.new
         end
+
+        def allocation_count
+          0
+        end
       end
     end
 

data/lib/appsignal/helpers/instrumentation.rb

@@ -102,6 +102,18 @@ module Appsignal
       #   within the block with {#set_action}.
       #   This will not update the active transaction's action if
       #   {.monitor} is called when another transaction is already active.
+      # @param opentelemetry_kind [Symbol] In collector mode, the OpenTelemetry
+      #   span kind: one of `:server`, `:consumer`, `:producer` or `:internal`.
+      #   Defaults to `:server`.
+      # @param opentelemetry_relationship [Symbol] In collector mode, how an
+      #   incoming `opentelemetry_context` relates to this transaction's span:
+      #   one of `:parent`, `:link`, `:both` or `:none`. Defaults to `:parent`.
+      # @param opentelemetry_context In collector mode, an incoming OpenTelemetry
+      #   trace context to relate this transaction's span to.
+      # @param opentelemetry_scope [Array(String, String)] In collector mode, the
+      #   OpenTelemetry instrumentation scope to record this transaction's spans
+      #   under, given as a `[name, version]` pair. Defaults to the AppSignal
+      #   scope.
       # @yield [] The block to monitor.
       # @yieldreturn [Object] The return value of the block
       # @raise [Exception] Any exception that occurs within the given block is
@@ -112,7 +124,14 @@ module Appsignal
       #
       # @see https://docs.appsignal.com/ruby/instrumentation/background-jobs.html
       #   Monitor guide
-      def monitor(action:, namespace: nil)
+      def monitor( # rubocop:disable Metrics/ParameterLists
+        action:,
+        namespace: nil,
+        opentelemetry_context: nil,
+        opentelemetry_scope: nil,
+        opentelemetry_kind: nil,
+        opentelemetry_relationship: nil
+      )
         return yield unless Appsignal.active?
 
         has_parent_transaction = Appsignal::Transaction.current?
@@ -133,7 +152,13 @@ module Appsignal
           if has_parent_transaction
             Appsignal::Transaction.current
           else
-            Appsignal::Transaction.create(namespace || Appsignal::Transaction::HTTP_REQUEST)
+            Appsignal::Transaction.create(
+              namespace || Appsignal::Transaction::HTTP_REQUEST,
+              :opentelemetry_context => opentelemetry_context,
+              :opentelemetry_scope => opentelemetry_scope,
+              :opentelemetry_kind => opentelemetry_kind,
+              :opentelemetry_relationship => opentelemetry_relationship
+            )
           end
 
         begin
@@ -168,6 +193,18 @@ module Appsignal
       #   within the block with {#set_action}.
       #   This will not update the active transaction's action if
       #   {.monitor} is called when another transaction is already active.
+      # @param opentelemetry_kind [Symbol] In collector mode, the OpenTelemetry
+      #   span kind: one of `:server`, `:consumer`, `:producer` or `:internal`.
+      #   Defaults to `:server`.
+      # @param opentelemetry_relationship [Symbol] In collector mode, how an
+      #   incoming `opentelemetry_context` relates to this transaction's span:
+      #   one of `:parent`, `:link`, `:both` or `:none`. Defaults to `:parent`.
+      # @param opentelemetry_context In collector mode, an incoming OpenTelemetry
+      #   trace context to relate this transaction's span to.
+      # @param opentelemetry_scope [Array(String, String)] In collector mode, the
+      #   OpenTelemetry instrumentation scope to record this transaction's spans
+      #   under, given as a `[name, version]` pair. Defaults to the AppSignal
+      #   scope.
       # @yield [] The block to monitor.
       # @yieldreturn [Object] The return value of the block
       # @raise [Exception] Any exception that occurs within the given block is
@@ -175,13 +212,29 @@ module Appsignal
       # @return [Object, nil] The value of the given block is returned.
       #
       # @see monitor
-      def monitor_and_stop(action:, namespace: nil, &block)
+      def monitor_and_stop( # rubocop:disable Metrics/ParameterLists
+        action:,
+        namespace: nil,
+        opentelemetry_context: nil,
+        opentelemetry_scope: nil,
+        opentelemetry_kind: nil,
+        opentelemetry_relationship: nil,
+        &block
+      )
         Appsignal::Utils::StdoutAndLoggerMessage.warning \
           "The `Appsignal.monitor_and_stop` helper is deprecated. " \
             "Use the `Appsignal.monitor` along with our `enable_at_exit_hook` " \
             "option instead."
 
-        monitor(:namespace => namespace, :action => action, &block)
+        monitor(
+          :namespace => namespace,
+          :action => action,
+          :opentelemetry_context => opentelemetry_context,
+          :opentelemetry_scope => opentelemetry_scope,
+          :opentelemetry_kind => opentelemetry_kind,
+          :opentelemetry_relationship => opentelemetry_relationship,
+          &block
+        )
       ensure
         Appsignal.stop("monitor_and_stop")
       end
@@ -218,6 +271,18 @@ module Appsignal
       #
       # @since 0.6.0
       # @param error [Exception] The error to send to AppSignal.
+      # @param opentelemetry_kind [Symbol] In collector mode, the OpenTelemetry
+      #   span kind: one of `:server`, `:consumer`, `:producer` or `:internal`.
+      #   Defaults to `:server`.
+      # @param opentelemetry_relationship [Symbol] In collector mode, how an
+      #   incoming `opentelemetry_context` relates to this transaction's span:
+      #   one of `:parent`, `:link`, `:both` or `:none`. Defaults to `:parent`.
+      # @param opentelemetry_context In collector mode, an incoming OpenTelemetry
+      #   trace context to relate this transaction's span to.
+      # @param opentelemetry_scope [Array(String, String)] In collector mode, the
+      #   OpenTelemetry instrumentation scope to record this transaction's spans
+      #   under, given as a `[name, version]` pair. Defaults to the AppSignal
+      #   scope.
       # @yield [transaction] yields block to allow modification of the
       #   transaction before it's send.
       # @yieldparam transaction [Transaction] yields the AppSignal transaction
@@ -226,7 +291,14 @@ module Appsignal
       #
       # @see https://docs.appsignal.com/ruby/instrumentation/exception-handling.html
       #   Exception handling guide
-      def send_error(error, &block)
+      def send_error(
+        error,
+        opentelemetry_context: nil,
+        opentelemetry_scope: nil,
+        opentelemetry_kind: nil,
+        opentelemetry_relationship: nil,
+        &block
+      )
         return unless Appsignal.active?
 
         unless error.is_a?(Exception)
@@ -237,8 +309,14 @@ module Appsignal
         end
 
         transaction =
-          Appsignal::Transaction.new(Appsignal::Transaction::HTTP_REQUEST)
-        transaction.set_error(error, &block)
+          Appsignal::Transaction.new(
+            Appsignal::Transaction::HTTP_REQUEST,
+            :opentelemetry_context => opentelemetry_context,
+            :opentelemetry_scope => opentelemetry_scope,
+            :opentelemetry_kind => opentelemetry_kind,
+            :opentelemetry_relationship => opentelemetry_relationship
+          )
+        transaction.set_error(error, :source => "Appsignal.send_error", &block)
 
         transaction.complete
       end
@@ -348,6 +426,20 @@ module Appsignal
       # @since 4.0.0
       # @param exception [Exception] The error to add to the current
       #   transaction.
+      # @param opentelemetry_kind [Symbol] In collector mode, the OpenTelemetry
+      #   span kind: one of `:server`, `:consumer`, `:producer` or `:internal`.
+      #   Defaults to `:server`. Only used when a new transaction is created.
+      # @param opentelemetry_relationship [Symbol] In collector mode, how an
+      #   incoming `opentelemetry_context` relates to this transaction's span:
+      #   one of `:parent`, `:link`, `:both` or `:none`. Defaults to `:parent`.
+      #   Only used when a new transaction is created.
+      # @param opentelemetry_context In collector mode, an incoming OpenTelemetry
+      #   trace context to relate this transaction's span to. Only used when a
+      #   new transaction is created.
+      # @param opentelemetry_scope [Array(String, String)] In collector mode, the
+      #   OpenTelemetry instrumentation scope to record this transaction's spans
+      #   under, given as a `[name, version]` pair. Defaults to the AppSignal
+      #   scope.
       # @yield [transaction] yields block to allow modification of the
       #   transaction.
       # @yieldparam transaction [Transaction] yields the AppSignal transaction
@@ -356,7 +448,14 @@ module Appsignal
       #
       # @see https://docs.appsignal.com/ruby/instrumentation/exception-handling.html
       #   Exception handling guide
-      def report_error(exception, &block)
+      def report_error(
+        exception,
+        opentelemetry_context: nil,
+        opentelemetry_scope: nil,
+        opentelemetry_kind: nil,
+        opentelemetry_relationship: nil,
+        &block
+      )
         unless exception.is_a?(Exception)
           Appsignal.internal_logger.error "Appsignal.report_error: " \
             "Cannot add error. " \
@@ -370,10 +469,16 @@ module Appsignal
           if has_parent_transaction
             Appsignal::Transaction.current
           else
-            Appsignal::Transaction.new(Appsignal::Transaction::HTTP_REQUEST)
+            Appsignal::Transaction.new(
+              Appsignal::Transaction::HTTP_REQUEST,
+              :opentelemetry_context => opentelemetry_context,
+              :opentelemetry_scope => opentelemetry_scope,
+              :opentelemetry_kind => opentelemetry_kind,
+              :opentelemetry_relationship => opentelemetry_relationship
+            )
           end
 
-        transaction.add_error(exception, &block)
+        transaction.add_error(exception, :source => "Appsignal.report_error", &block)
 
         transaction.complete unless has_parent_transaction
       end
@@ -602,16 +707,95 @@ module Appsignal
       end
       alias set_params add_params
 
+      # Add the request payload to the current transaction.
+      #
+      # The request payload is the parameters of an incoming request, such as
+      # the query string and the request body. In collector mode it maps to its
+      # own attribute, separate from the function parameters.
+      #
+      # Behaves like {#add_params}: merges when called multiple times, and a
+      # block takes precedence over the argument.
+      #
+      # @param params [Hash<String, Object>, Array<Object>] The request payload to add to the
+      #   transaction.
+      # @yield This block is called when the transaction is sampled. The block's
+      #   return value will become the new request payload.
+      # @yieldreturn [Hash<String, Object>, Array<Object>]
+      # @return [void]
+      #
+      # @see #add_function_parameters
+      def add_request_payload(params = nil, &block)
+        return unless Appsignal.active?
+        return unless Appsignal::Transaction.current?
+
+        transaction = Appsignal::Transaction.current
+        transaction.add_request_payload(params, &block)
+      end
+
+      # Add the function parameters to the current transaction.
+      #
+      # The function parameters are the arguments a background job or function
+      # was called with. In collector mode they map to their own attribute,
+      # separate from the request payload.
+      #
+      # Behaves like {#add_params}: merges when called multiple times, and a
+      # block takes precedence over the argument.
+      #
+      # @param params [Hash<String, Object>, Array<Object>] The function parameters to add to
+      #   the transaction.
+      # @yield This block is called when the transaction is sampled. The block's
+      #   return value will become the new function parameters.
+      # @yieldreturn [Hash<String, Object>, Array<Object>]
+      # @return [void]
+      #
+      # @see #add_request_payload
+      def add_function_parameters(params = nil, &block)
+        return unless Appsignal.active?
+        return unless Appsignal::Transaction.current?
+
+        transaction = Appsignal::Transaction.current
+        transaction.add_function_parameters(params, &block)
+      end
+
+      # Add the query parameters to the current transaction.
+      #
+      # The query parameters are the parameters parsed from an incoming
+      # request's query string. In collector mode they map to their own
+      # attribute, separate from the request payload and the function
+      # parameters.
+      #
+      # Behaves like {#add_params}: merges when called multiple times, and a
+      # block takes precedence over the argument.
+      #
+      # @param params [Hash<String, Object>, Array<Object>] The query parameters to add to the
+      #   transaction.
+      # @yield This block is called when the transaction is sampled. The block's
+      #   return value will become the new query parameters.
+      # @yieldreturn [Hash<String, Object>, Array<Object>]
+      # @return [void]
+      #
+      # @see #add_request_payload
+      def add_query_parameters(params = nil, &block)
+        return unless Appsignal.active?
+        return unless Appsignal::Transaction.current?
+
+        transaction = Appsignal::Transaction.current
+        transaction.add_query_parameters(params, &block)
+      end
+
       # Mark the parameters sample data to be set as an empty value.
       #
-      # Use this helper to unset request parameters / background job arguments
-      # and not report any for this transaction.
+      # Use this helper to report no parameters for this transaction, whatever
+      # their source.
       #
-      # If parameters would normally be added by AppSignal instrumentations of
-      # libraries, these parameters will not be added to the Transaction.
+      # This suppresses every params channel. In collector mode, where the
+      # request payload and the function parameters (a background job's
+      # arguments) are tracked as separate attributes, it suppresses both, not
+      # only the request payload. Parameters that an AppSignal integration would
+      # otherwise add are not added.
       #
-      # Calling {#add_params} after this helper will add new parameters to the
-      # transaction.
+      # Calling {#add_params}, {#add_request_payload} or
+      # {#add_function_parameters} after this helper adds parameters again.
       #
       # @since 4.2.0
       # @return [void]
@@ -715,7 +899,7 @@ module Appsignal
       # Breadcrumbs can be used to trace what path a user has taken
       # before encountering an error.
       #
-      # Only the last 20 added breadcrumbs will be saved.
+      # At most 20 of the added breadcrumbs will be saved.
       #
       # @example
       #   Appsignal.add_breadcrumb(
@@ -786,6 +970,12 @@ module Appsignal
       #   instrumented. Accepted values are {EventFormatter::DEFAULT} and
       #   {EventFormatter::SQL_BODY_FORMAT}, but we recommend you use
       #   {.instrument_sql} instead of {EventFormatter::SQL_BODY_FORMAT}.
+      # @param opentelemetry_kind [Symbol] In collector mode, the OpenTelemetry
+      #   span kind for the event's span, such as `:client` for an outgoing HTTP
+      #   request. Defaults to the OpenTelemetry default of `:internal`.
+      # @param opentelemetry_scope [Array(String, String)] In collector mode, the
+      #   OpenTelemetry instrumentation scope to record the event's span under,
+      #   given as a `[name, version]` pair. Defaults to the AppSignal scope.
       # @yield [] yields the given block of code instrumented in an AppSignal
       #   event.
       # @return [Object] Returns the block's return value.
@@ -795,15 +985,25 @@ module Appsignal
       #   AppSignal custom instrumentation guide
       # @see https://docs.appsignal.com/api/event-names.html
       #   AppSignal event naming guide
-      def instrument(
+      def instrument( # rubocop:disable Metrics/ParameterLists
         name,
         title = nil,
         body = nil,
         body_format = Appsignal::EventFormatter::DEFAULT,
+        opentelemetry_kind: nil,
+        opentelemetry_scope: nil,
         &block
       )
         Appsignal::Transaction.current
-          .instrument(name, title, body, body_format, &block)
+          .instrument(
+            name,
+            title,
+            body,
+            body_format,
+            :opentelemetry_kind => opentelemetry_kind,
+            :opentelemetry_scope => opentelemetry_scope,
+            &block
+          )
       end
 
       # Instrumentation helper for SQL queries.
@@ -827,6 +1027,13 @@ module Appsignal
       #   naming guide listed under "See also".
       # @param title [String, nil] Human readable name of the event.
       # @param body [String, nil] SQL query that's being executed.
+      # @param opentelemetry_kind [Symbol] In collector mode, the OpenTelemetry
+      #   span kind for the event's span. Defaults to `:client`, because a query
+      #   is an outgoing call to a datastore. Pass `:internal` for a query that
+      #   is not an outgoing call.
+      # @param opentelemetry_scope [Array(String, String)] In collector mode, the
+      #   OpenTelemetry instrumentation scope to record the event's span under,
+      #   given as a `[name, version]` pair. Defaults to the AppSignal scope.
       # @yield [] yields the given block of code instrumented in an AppSignal
       #   event.
       # @return [Object] Returns the block's return value.
@@ -836,12 +1043,21 @@ module Appsignal
       #   AppSignal custom instrumentation guide
       # @see https://docs.appsignal.com/api/event-names.html
       #   AppSignal event naming guide
-      def instrument_sql(name, title = nil, body = nil, &block)
+      def instrument_sql(
+        name,
+        title = nil,
+        body = nil,
+        opentelemetry_kind: :client,
+        opentelemetry_scope: nil,
+        &block
+      )
         instrument(
           name,
           title,
           body,
           Appsignal::EventFormatter::SQL_BODY_FORMAT,
+          :opentelemetry_kind => opentelemetry_kind,
+          :opentelemetry_scope => opentelemetry_scope,
           &block
         )
       end