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

data/lib/appsignal/rack.rb

@@ -7,9 +7,46 @@ module Appsignal
     APPSIGNAL_EVENT_HANDLER_ID = "appsignal.event_handler_id"
     APPSIGNAL_EVENT_HANDLER_HAS_ERROR = "appsignal.event_handler.error"
     APPSIGNAL_RESPONSE_INSTRUMENTED = "appsignal.response_instrumentation_active"
+    APPSIGNAL_RESPONSE_STATUS = "appsignal.response_status"
     RACK_AFTER_REPLY = "rack.after_reply"
 
     class Utils
+      # Fetch the HTTP request method from the request.
+      #
+      # The request class is configurable, so reading the method can raise.
+      # Log and return nil in that case, leaving it to the caller to skip
+      # whatever it needed the method for.
+      #
+      # @param request [Rack::Request] Request object.
+      # @return [String, NilClass]
+      def self.request_method_from(request)
+        request.request_method
+      rescue => error
+        Appsignal.internal_logger.error(
+          "Exception while fetching the HTTP request method: #{error.class}: #{error}"
+        )
+        nil
+      end
+
+      # Fetch a value that describes the request, named after the method that
+      # reads it.
+      #
+      # The request class is configurable, so reading from the request can
+      # raise. Log and return nil in that case, leaving it to the caller to skip
+      # whatever it needed the value for.
+      #
+      # @param request [Rack::Request] Request object.
+      # @param name [Symbol] Name of the method that reads the value.
+      # @return [Object, NilClass]
+      def self.request_value_from(request, name)
+        request.public_send(name)
+      rescue => error
+        Appsignal.internal_logger.error(
+          "Exception while fetching the HTTP request #{name}: #{error.class}: #{error}"
+        )
+        nil
+      end
+
       # Fetch the queue start time from the request environment.
       #
       # @since 3.11.0
@@ -53,14 +90,14 @@ module Appsignal
         # TODO: Remove in next major/minor version
         transaction.set_metadata("path", request_path)
 
-        request_method = request_method_for(request)
+        request_method = Appsignal::Rack::Utils.request_method_from(request)
         if request_method
           transaction.set_metadata("request_method", request_method)
           # TODO: Remove in next major/minor version
           transaction.set_metadata("method", request_method)
         end
 
-        transaction.add_params { params_for(request) }
+        transaction.add_request_payload { params_for(request) }
         transaction.add_session_data { session_data_for(request) }
         transaction.add_headers do
           request.env if request.respond_to?(:env)
@@ -84,15 +121,6 @@ module Appsignal
         nil
       end
 
-      def request_method_for(request)
-        request.request_method
-      rescue => error
-        Appsignal.internal_logger.error(
-          "Exception while fetching the HTTP request method: #{error.class}: #{error}"
-        )
-        nil
-      end
-
       def session_data_for(request)
         return unless request.respond_to?(:session)
 

data/lib/appsignal/sample_data.rb

@@ -61,6 +61,10 @@ module Appsignal
       @empty
     end
 
+    # The sample-data category this holds (e.g. `:params`, `:request_payload`).
+    # Used to name the data in log messages.
+    attr_reader :key
+
     protected
 
     attr_reader :blocks

data/lib/appsignal/transaction/base_backend.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Appsignal
+  class Transaction
+    # @!visibility private
+    #
+    # The interface every transaction backend implements. `Appsignal::Backends
+    # .transaction` picks a concrete backend per mode -- ExtensionBackend in
+    # agent mode, OpenTelemetryBackend in collector mode. This base documents the
+    # contract; a backend that leaves a method unimplemented raises here.
+    class BaseBackend
+      # Instrumented events.
+      def start_event(opentelemetry_kind: nil, opentelemetry_scope: nil)
+        raise NotImplementedError
+      end
+
+      def finish_event(_name, _title, _body, _body_format)
+        raise NotImplementedError
+      end
+
+      def record_event( # rubocop:disable Metrics/ParameterLists
+        _name, _title, _body, _body_format, _duration,
+        opentelemetry_kind: nil, opentelemetry_scope: nil
+      )
+        raise NotImplementedError
+      end
+
+      # Transaction metadata.
+      def set_action(_action)
+        raise NotImplementedError
+      end
+
+      def set_namespace(_namespace)
+        raise NotImplementedError
+      end
+
+      def set_metadata(_key, _value)
+        raise NotImplementedError
+      end
+
+      def set_queue_start(_start)
+        raise NotImplementedError
+      end
+
+      # OpenTelemetry span attributes, set on whichever span the backend is
+      # currently recording. Only meaningful in collector mode; agent mode has
+      # no span to hang them on.
+      def set_attributes(_attributes)
+        raise NotImplementedError
+      end
+
+      # Maps each logical params channel (`:params`, `:request_payload`,
+      # `:function_parameters`) to the storage bucket it lands in. Channels that
+      # share a bucket merge into one `SampleData` object on the transaction;
+      # distinct buckets stay separate. The bucket name is also the sample-data
+      # key `set_sample_data` receives for that bucket, so it must be a key this
+      # backend's `set_sample_data` knows how to store.
+      def params_mapping
+        raise NotImplementedError
+      end
+
+      # Sample data (params, session, tags, ...), breadcrumbs and errors.
+      def set_sample_data(_key, _data)
+        raise NotImplementedError
+      end
+
+      def add_breadcrumb(_breadcrumb)
+        raise NotImplementedError
+      end
+
+      def set_error(_class_name, _message, _backtrace, _causes, _root_cause_missing)
+        raise NotImplementedError
+      end
+
+      # Whether the backend can hold more than one error on a single
+      # transaction. When it can't (agent mode), the Transaction reports the
+      # extra errors as duplicate transactions instead.
+      def supports_multiple_errors?
+        raise NotImplementedError
+      end
+
+      # Lifecycle.
+      def finish
+        raise NotImplementedError
+      end
+
+      def complete
+        raise NotImplementedError
+      end
+
+      def discard
+        raise NotImplementedError
+      end
+
+      # Only used when `supports_multiple_errors?` is false (agent mode).
+      # Backends that support multiple errors never duplicate and leave this
+      # unimplemented.
+      def duplicate(_new_transaction_id)
+        raise NotImplementedError
+      end
+
+      def to_json # rubocop:disable Lint/ToJSON
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/appsignal/transaction/extension_backend.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module Appsignal
+  class Transaction
+    # @!visibility private
+    #
+    # The transaction backend used in agent mode. Wraps a per-transaction
+    # handle on the C extension (`Appsignal::Extension::Transaction`) and
+    # forwards every call to it.
+    #
+    # In agent mode `Appsignal::Backends.transaction` returns this class;
+    # `Appsignal::Transaction#initialize` instantiates one and stores it in
+    # `@backend`.
+    class ExtensionBackend < BaseBackend
+      # rubocop:disable Layout/LineLength
+      BACKTRACE_REGEX =
+        %r{(?<gem>[\w-]+ \(.+\) )?(?<path>:?/?\w+?.+?):(?<line>:?\d+)(?::in `(?<method>.+)')?$}.freeze
+      # rubocop:enable Layout/LineLength
+
+      # @!visibility private
+      attr_writer :breadcrumbs
+
+      # The `opentelemetry_*` keyword arguments (context, scope, kind and
+      # relationship) shape the OpenTelemetry span in collector mode. Agent mode
+      # has no notion of them, so they are accepted and ignored. They are listed
+      # explicitly, rather than swallowed with `**`, so an unexpected keyword
+      # still raises, matching the OpenTelemetry backend.
+      # rubocop:disable Metrics/ParameterLists, Lint/UnusedMethodArgument
+      def initialize(
+        transaction_id,
+        namespace,
+        handle: nil,
+        opentelemetry_context: nil,
+        opentelemetry_scope: nil,
+        opentelemetry_kind: nil,
+        opentelemetry_relationship: nil
+      )
+        super()
+        @handle = handle ||
+          Appsignal::Extension.start_transaction(transaction_id, namespace, 0) ||
+          Appsignal::Extension::MockTransaction.new
+        @breadcrumbs = []
+      end
+      # rubocop:enable Metrics/ParameterLists, Lint/UnusedMethodArgument
+
+      # Agent mode has no span kind or instrumentation scope;
+      # `opentelemetry_kind` and `opentelemetry_scope` are ignored here.
+      def start_event(opentelemetry_kind: nil, opentelemetry_scope: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @handle.start_event(0)
+      end
+
+      def finish_event(name, title, body, body_format)
+        @handle.finish_event(name, title, body, body_format, 0)
+      end
+
+      # Agent mode has no span kind or instrumentation scope;
+      # `opentelemetry_kind` and `opentelemetry_scope` are ignored here.
+      def record_event(name, title, body, body_format, duration, opentelemetry_kind: nil, opentelemetry_scope: nil, opentelemetry_attributes: nil) # rubocop:disable Lint/UnusedMethodArgument, Metrics/ParameterLists, Layout/LineLength
+        @handle.record_event(name, title, body, body_format, duration, 0)
+      end
+
+      def set_action(action)
+        @handle.set_action(action)
+      end
+
+      def set_namespace(namespace)
+        @handle.set_namespace(namespace)
+      end
+
+      def set_queue_start(start)
+        @handle.set_queue_start(start)
+      end
+
+      def set_metadata(key, value)
+        @handle.set_metadata(key, value)
+      end
+
+      # Agent mode has no OpenTelemetry spans, so there is nothing to set the
+      # attributes on. A transaction event has no attribute equivalent in the
+      # agent protocol either, so they are dropped rather than stored somewhere
+      # else.
+      def set_attributes(_attributes)
+      end
+
+      # The agent has a single params slot, so every params channel maps to one
+      # `:params` bucket. The transaction merges the channels into it, and only
+      # the `:params` key ever reaches `set_sample_data`.
+      PARAMS_MAPPING = {
+        :params => :params,
+        :request_payload => :params,
+        :function_parameters => :params,
+        :query_parameters => :params
+      }.freeze
+
+      def params_mapping
+        PARAMS_MAPPING
+      end
+
+      # `data` is a raw Ruby Hash/Array; the C extension wants a `Data` object,
+      # so serialize it here (mirrors how `set_error` serializes its backtrace).
+      def set_sample_data(key, data)
+        @handle.set_sample_data(key, Appsignal::Utils::Data.generate(data))
+      end
+
+      # Buffer breadcrumbs, keeping the last `BREADCRUMB_LIMIT`, and flush them as
+      # sample data on completion.
+      def add_breadcrumb(breadcrumb)
+        @breadcrumbs.push(breadcrumb)
+        @breadcrumbs = @breadcrumbs.last(Appsignal::Transaction::BREADCRUMB_LIMIT)
+      end
+
+      # Serializes the backtrace to a C-extension `Data` object and records the
+      # error, then flushes the causes as `error_causes` sample data in the
+      # agent's first-line shape.
+      def set_error(class_name, message, backtrace, causes, root_cause_missing)
+        backtrace_data =
+          if backtrace
+            Appsignal::Utils::Data.generate(backtrace)
+          else
+            Appsignal::Extension.data_array_new
+          end
+        @handle.set_error(class_name, message, backtrace_data)
+
+        set_sample_data("error_causes", error_causes_sample_data(causes, root_cause_missing))
+      end
+
+      def finish
+        @handle.finish(0)
+      end
+
+      def complete
+        unless @breadcrumbs.empty?
+          @handle.set_sample_data("breadcrumbs", Appsignal::Utils::Data.generate(@breadcrumbs))
+        end
+        @handle.complete
+      end
+
+      # Discarding in agent mode drops the transaction: the extension handle is
+      # simply abandoned and never told to complete, so nothing is sent. There
+      # is no `ignore_subtrace` concept on the agent path. This mirrors the
+      # pre-backend behavior, where `Transaction#complete` returned before
+      # touching the handle on a discarded transaction.
+      def discard
+      end
+
+      # The extension transaction holds a single error, so the Transaction
+      # reports additional errors as duplicate transactions instead.
+      def supports_multiple_errors?
+        false
+      end
+
+      def duplicate(new_transaction_id)
+        self.class.new(
+          new_transaction_id, nil, :handle => @handle.duplicate(new_transaction_id)
+        ).tap { |backend| backend.breadcrumbs = @breadcrumbs.dup }
+      end
+
+      def to_json # rubocop:disable Lint/ToJSON
+        @handle.to_json
+      end
+
+      private
+
+      # Projects the neutral causes to the agent's first-line shape. A truncated
+      # chain marks its last entry as not the root cause.
+      def error_causes_sample_data(causes, root_cause_missing)
+        sample_data = causes.map do |cause|
+          {
+            :name => cause[:name],
+            :message => cause[:message],
+            :first_line => first_formatted_backtrace_line(cause[:backtrace])
+          }
+        end
+        sample_data.last[:is_root_cause] = false if root_cause_missing && sample_data.any?
+        sample_data
+      end
+
+      # Parses the first backtrace line into the fields the UI links on (gem,
+      # path, line, method), with the path made relative to the app root.
+      def first_formatted_backtrace_line(backtrace)
+        first_line = backtrace&.first
+        return unless first_line
+
+        captures = BACKTRACE_REGEX.match(first_line)
+        return unless captures
+
+        captures.named_captures
+          .merge("original" => first_line)
+          .tap do |c|
+            config = Appsignal.config
+            c["gem"] = c["gem"]&.strip
+            root_path = config.root_path
+            if c["path"].start_with?(root_path)
+              c["path"].delete_prefix!(root_path)
+              c["path"].delete_prefix!("/")
+            end
+            c["revision"] = config[:revision]
+            c["line"] = c["line"].to_i
+          end
+      end
+    end
+  end
+end