appsignal 4.10.4-java → 5.0.0-java

data/lib/appsignal/integrations/shoryuken.rb

@@ -2,20 +2,122 @@
 
 module Appsignal
   module Integrations
+    # @!visibility private
+    #
+    # Reads and writes W3C trace context the way OpenTelemetry's aws-sdk
+    # instrumentation does: as SQS message attributes, using the global
+    # propagator. Staying wire-equivalent means that if both AppSignal and
+    # OpenTelemetry's aws-sdk instrumentation are active, one simply shadows the
+    # other rather than corrupting the carrier. Collector mode only.
+    module ShoryukenTraceContext
+      module_function
+
+      # SQS allows at most 10 message attributes per message. Mirror
+      # OpenTelemetry and skip propagation rather than risk the enqueue failing
+      # when the user already fills the slots.
+      MAX_MESSAGE_ATTRIBUTES = 10
+
+      # Writes each trace header as an SQS message attribute, matching the shape
+      # OpenTelemetry's aws-sdk instrumentation injects on send.
+      module MessageAttributeSetter
+        def self.set(carrier, key, value)
+          return if carrier.length >= MAX_MESSAGE_ATTRIBUTES
+
+          carrier[key] = { :string_value => value, :data_type => "String" }
+        end
+      end
+
+      # Reads a trace header back out of a message attribute. Works both for the
+      # plain hash we inject and for the `Aws::SQS::Types::MessageAttributeValue`
+      # struct delivered on receive, since both respond to `[:string_value]` /
+      # `[:data_type]`.
+      module MessageAttributeGetter
+        def self.get(carrier, key)
+          attribute = carrier[key]
+          attribute[:string_value] if attribute && attribute[:data_type] == "String"
+        end
+      end
+
+      # Read the incoming context off a message's SQS message attributes so the
+      # transaction links back to the enqueuer. Returns an
+      # `OpenTelemetry::Context`, or `nil` outside collector mode.
+      def extract(message_attributes)
+        Appsignal::OpenTelemetry.if_started do
+          ::OpenTelemetry.propagation.extract(
+            message_attributes || {},
+            :getter => MessageAttributeGetter
+          )
+        end
+      end
+
+      # Write the current trace context into the outgoing send `options`.
+      # Injects into a scratch carrier first and merges it into the message
+      # attributes only when something was written, so an enqueue with no active
+      # span (no transaction, or outside collector mode) leaves the options
+      # untouched -- a transparent pass-through.
+      def inject(options)
+        Appsignal::OpenTelemetry.if_started do
+          carrier = {}
+          ::OpenTelemetry.propagation.inject(carrier, :setter => MessageAttributeSetter)
+          next if carrier.empty?
+
+          options[:message_attributes] = (options[:message_attributes] || {}).merge(carrier)
+        end
+      end
+    end
+
     # @!visibility private
     class ShoryukenMiddleware
       def call(worker_instance, queue, sqs_msg, body, &block)
-        transaction = Appsignal::Transaction.create(Appsignal::Transaction::BACKGROUND_JOB)
+        batch = sqs_msg.is_a?(Array)
+        # How many messages this call covers, which is only reported for a batch.
+        batch_size = sqs_msg.size if batch
 
-        Appsignal.instrument("perform_job.shoryuken", &block)
+        # Read the incoming trace context off the message so the transaction
+        # links back to the enqueuer. A batch carries messages from multiple
+        # traces with no single parent, so only single messages link back.
+        # No-op outside collector mode.
+        context = extract_context(sqs_msg, body) unless batch
+
+        transaction = Appsignal::Transaction.create(
+          Appsignal::Transaction::BACKGROUND_JOB,
+          :opentelemetry_context => context,
+          :opentelemetry_scope => ["appsignal-ruby/shoryuken", Appsignal::VERSION],
+          :opentelemetry_kind => :consumer,
+          # A message batch is a batch on the receiving side, and carries no
+          # context to relate to at all, so the body it reads here is the single
+          # message's job data or nothing.
+          :opentelemetry_relationship =>
+            Appsignal::OpenTelemetry.active_job_relationship(batch ? nil : body)
+        )
+        # Describes this span as a job being performed. The messaging system is
+        # what the trace timeline reads to recognize background job work.
+        # Shoryuken runs on Amazon SQS, so it takes the `aws_sqs` value the
+        # OpenTelemetry semantic conventions define for it.
+        transaction.add_opentelemetry_attributes(
+          Appsignal::OpenTelemetry::Messaging.perform_attributes(
+            "aws_sqs", :destination => queue, :batch_size => batch_size
+          )
+        )
+
+        Appsignal.instrument(
+          "perform_job.shoryuken",
+          :opentelemetry_scope => ["appsignal-ruby/shoryuken", Appsignal::VERSION]
+        ) do
+          Appsignal::Transaction.current.add_opentelemetry_attributes(
+            Appsignal::OpenTelemetry::Messaging.perform_attributes(
+              "aws_sqs", :destination => queue, :batch_size => batch_size
+            )
+          )
+          block.call
+        end
       rescue Exception => error
         transaction.set_error(error)
         raise
       ensure
-        batch = sqs_msg.is_a?(Array)
         attributes = fetch_attributes(batch, sqs_msg)
         transaction.set_action_if_nil("#{worker_instance.class.name}#perform")
-        transaction.add_params_if_nil { fetch_args(batch, sqs_msg, body) }
+        transaction.add_function_parameters_if_nil { fetch_args(batch, sqs_msg, body) }
         transaction.add_tags(attributes)
         transaction.add_tags("queue" => queue)
         transaction.add_tags("batch" => true) if batch
@@ -29,6 +131,21 @@ module Appsignal
 
       private
 
+      # The trace context to continue: the Active Job layer when this is an
+      # Active Job job, the message's own attributes otherwise. See `Appsignal::OpenTelemetry.extract_active_job_context`
+      # for why that layer wins.
+      # SQS allows ten message attributes per message, shared with whatever the
+      # user puts there.
+      #
+      # The Active Job adapter registers a worker that parses the message body as
+      # JSON, so an Active Job job's body arrives here as its serialized job
+      # data. Nothing checks that it is one: a body with no readable trace
+      # context in it reads as "nothing here" on its own.
+      def extract_context(sqs_msg, body)
+        Appsignal::OpenTelemetry.extract_active_job_context(body) ||
+          ShoryukenTraceContext.extract(sqs_msg.message_attributes)
+      end
+
       def fetch_attributes(batch, sqs_msg)
         if batch
           # We can't instrument batched message separately, the `yield` will
@@ -73,7 +190,9 @@ module Appsignal
     end
 
     # Shoryuken client middleware that records an `enqueue.shoryuken` event so
-    # the enqueue shows up under the active transaction.
+    # the enqueue shows up under the active transaction (both modes), and in
+    # collector mode writes the current trace context onto the outgoing message
+    # so the job that later performs links back to it.
     #
     # Like all AppSignal events, this only records when there's an active
     # transaction (e.g. enqueuing from within a web request or another job). An
@@ -81,13 +200,36 @@ module Appsignal
     #
     # @!visibility private
     class ShoryukenClientMiddleware
-      def call(options, &block)
+      def call(options)
+        # When enqueue instrumentation is disabled, drop the trace context along
+        # with the event. Without an enqueue event there is no producer span, so
+        # the context we would write is that of whatever span is current, such as
+        # the surrounding web request. The job that performs later would then
+        # link back to a span that is not a producer.
+        return yield if Appsignal.config && !Appsignal.config[:enable_job_enqueue_instrumentation]
+
         # Under Active Job the enqueue is already recorded as an
-        # `enqueue.active_job` event, so skip recording it again here.
-        return yield if Appsignal::Transaction.current? &&
-          Appsignal::Transaction.current.job_enqueue_events_suppressed?
+        # `enqueue.active_job` event, so skip recording it again here. The trace
+        # context is still injected so the performed job links back.
+        if Appsignal::Transaction.current? &&
+            Appsignal::Transaction.current.job_enqueue_events_suppressed?
+          ShoryukenTraceContext.inject(options)
+          return yield
+        end
 
-        Appsignal.instrument("enqueue.shoryuken", enqueue_title(options), &block)
+        Appsignal.instrument(
+          "enqueue.shoryuken",
+          enqueue_title(options),
+          :opentelemetry_kind => :producer,
+          :opentelemetry_scope => ["appsignal-ruby/shoryuken", Appsignal::VERSION]
+        ) do
+          Appsignal::Transaction.current.add_opentelemetry_attributes(
+            Appsignal::OpenTelemetry::Messaging
+              .enqueue_attributes("aws_sqs", :destination => queue_name(options))
+          )
+          ShoryukenTraceContext.inject(options)
+          yield
+        end
       end
 
       private
@@ -99,8 +241,13 @@ module Appsignal
         worker_class = options.dig(:message_attributes, "shoryuken_class", :string_value)
         return "enqueue #{worker_class} job" if worker_class
 
-        queue = options[:queue_url].to_s.split("/").last
-        "enqueue on #{queue}"
+        "enqueue on #{queue_name(options)}"
+      end
+
+      # The queue a message is being sent to, which SQS identifies by a URL whose
+      # last segment is the queue's name.
+      def queue_name(options)
+        options[:queue_url].to_s.split("/").last
       end
     end
   end

data/lib/appsignal/integrations/sidekiq.rb

@@ -38,10 +38,18 @@ module Appsignal
           # Sidekiq error outside of the middleware scope.
           # Can be a job JSON parse error or some other error happening in
           # Sidekiq.
-          transaction = Appsignal::Transaction.create(Appsignal::Transaction::BACKGROUND_JOB)
+          transaction = Appsignal::Transaction.create(
+            Appsignal::Transaction::BACKGROUND_JOB,
+            :opentelemetry_scope => ["appsignal-ruby/sidekiq", Appsignal::VERSION],
+            :opentelemetry_kind => :consumer,
+            :opentelemetry_relationship => :both
+          )
+          transaction.add_opentelemetry_attributes(
+            Appsignal::OpenTelemetry::Messaging.perform_attributes("sidekiq")
+          )
           transaction.set_action_if_nil("SidekiqInternal")
           transaction.set_metadata("sidekiq_error", sidekiq_context[:context])
-          transaction.add_params_if_nil(:jobstr => sidekiq_context[:jobstr])
+          transaction.add_function_parameters_if_nil(:jobstr => sidekiq_context[:jobstr])
           transaction.set_error(exception)
         end
 
@@ -98,24 +106,52 @@ module Appsignal
       end
     end
 
-    # Sidekiq client middleware that runs on enqueue. Records an
-    # `enqueue.sidekiq` event so the enqueue shows up under the active
-    # transaction.
+    # Client middleware that runs on enqueue. Records an `enqueue.sidekiq`
+    # event so the enqueue shows up under the active transaction (both modes),
+    # and in collector mode writes the trace context onto the job hash so the
+    # job that later performs links back to it.
     #
     # Like all AppSignal events, this only records when there's an active
-    # transaction (e.g. enqueuing from within a web request or another job). An
-    # enqueue with no transaction is a transparent pass-through.
+    # transaction (e.g. enqueuing from within a web request or another job).
+    # An enqueue with no transaction is a transparent pass-through.
     #
     # @!visibility private
     class SidekiqClientMiddleware
-      def call(_worker_class, job, _queue, _redis_pool, &block)
+      def call(_worker_class, job, _queue, _redis_pool)
+        # When enqueue instrumentation is disabled, drop the trace context along
+        # with the event. Without an enqueue event there is no producer span, so
+        # the context we would write is that of whatever span is current, such as
+        # the surrounding web request. The job that performs later would then
+        # link back to a span that is not a producer.
+        return yield if Appsignal.config && !Appsignal.config[:enable_job_enqueue_instrumentation]
+
         # Under Active Job the enqueue is already recorded as an
-        # `enqueue.active_job` event, so skip recording it again here.
-        return yield if Appsignal::Transaction.current? &&
-          Appsignal::Transaction.current.job_enqueue_events_suppressed?
+        # `enqueue.active_job` event, so skip recording it again here. The trace
+        # context is still injected so the performed job links back.
+        if Appsignal::Transaction.current? &&
+            Appsignal::Transaction.current.job_enqueue_events_suppressed?
+          Appsignal::OpenTelemetry.inject_context(job)
+          return yield
+        end
 
         title = "enqueue #{SidekiqActionName.parse_action_name(job)} job"
-        Appsignal.instrument("enqueue.sidekiq", title, &block)
+        Appsignal.instrument(
+          "enqueue.sidekiq",
+          title,
+          :opentelemetry_kind => :producer,
+          :opentelemetry_scope => ["appsignal-ruby/sidekiq", Appsignal::VERSION]
+        ) do
+          # Describes this span as a job being enqueued. The messaging system
+          # is what the trace timeline reads to recognize background job work,
+          # and `sidekiq` is the value OpenTelemetry's own Sidekiq
+          # instrumentation uses.
+          Appsignal::Transaction.current.add_opentelemetry_attributes(
+            Appsignal::OpenTelemetry::Messaging
+              .enqueue_attributes("sidekiq", :destination => job["queue"])
+          )
+          Appsignal::OpenTelemetry.inject_context(job)
+          yield
+        end
       end
     end
 
@@ -126,7 +162,7 @@ module Appsignal
       EXCLUDED_JOB_KEYS = %w[
         args backtrace class created_at enqueued_at error_backtrace error_class
         error_message failed_at jid retried_at retry wrapped cattr tags retry_for
-        unique_for
+        unique_for traceparent tracestate __otel_headers
       ].freeze
 
       def self.sidekiq8?
@@ -138,7 +174,21 @@ module Appsignal
       def call(_worker, item, _queue, &block)
         job_status = nil
         action_name = formatted_action_name(item)
-        transaction = Appsignal::Transaction.create(Appsignal::Transaction::BACKGROUND_JOB)
+        # Read trace context off the job so the transaction links back to the
+        # enqueuer. No-op outside collector mode.
+        job_data = active_job_data(item)
+        transaction = Appsignal::Transaction.create(
+          Appsignal::Transaction::BACKGROUND_JOB,
+          :opentelemetry_context => extract_context(item, job_data),
+          :opentelemetry_scope => ["appsignal-ruby/sidekiq", Appsignal::VERSION],
+          :opentelemetry_kind => :consumer,
+          :opentelemetry_relationship =>
+            Appsignal::OpenTelemetry.active_job_relationship(job_data)
+        )
+        transaction.add_opentelemetry_attributes(
+          Appsignal::OpenTelemetry::Messaging
+            .perform_attributes("sidekiq", :destination => item["queue"])
+        )
         transaction.set_action_if_nil(action_name)
 
         formatted_metadata(item).each do |key, value|
@@ -146,13 +196,22 @@ module Appsignal
         end
 
         begin
-          Appsignal.instrument "perform_job.sidekiq", &block
+          Appsignal.instrument(
+            "perform_job.sidekiq",
+            :opentelemetry_scope => ["appsignal-ruby/sidekiq", Appsignal::VERSION]
+          ) do
+            Appsignal::Transaction.current.add_opentelemetry_attributes(
+              Appsignal::OpenTelemetry::Messaging
+                .perform_attributes("sidekiq", :destination => item["queue"])
+            )
+            block.call
+          end
         rescue Exception => exception
           job_status = :failed
           raise exception
         ensure
           if transaction
-            transaction.add_params_if_nil { parse_arguments(item) }
+            transaction.add_function_parameters_if_nil { parse_arguments(item) }
             enqueued_at = item["enqueued_at"]
             queue_start =
               if self.class.sidekiq8?
@@ -189,6 +248,25 @@ module Appsignal
 
       private
 
+      # The trace context to continue: the Active Job layer when this is an
+      # Active Job job, the Sidekiq job itself otherwise. See `Appsignal::OpenTelemetry.extract_active_job_context`
+      # for why that layer wins.
+      def extract_context(item, job_data)
+        Appsignal::OpenTelemetry.extract_active_job_context(job_data) ||
+          Appsignal::OpenTelemetry.extract_job_context(item)
+      end
+
+      # The serialized Active Job job data inside a Sidekiq job, or nil when this
+      # is not an Active Job job. Both Active Job adapters for Sidekiq, the one in
+      # Rails and the one in the Sidekiq gem, enqueue a wrapper class with the
+      # job data as its only argument and name the real job class in `wrapped`.
+      def active_job_data(item)
+        return unless item["wrapped"]
+
+        job_data = item["args"]&.first
+        job_data if job_data.is_a?(Hash)
+      end
+
       def increment_counter(key, value, tags = {})
         Appsignal.increment_counter "sidekiq_#{key}", value, tags
       end

data/lib/appsignal/integrations/webmachine.rb

@@ -10,20 +10,71 @@ module Appsignal
           if has_parent_transaction
             Appsignal::Transaction.current
           else
-            Appsignal::Transaction.create(Appsignal::Transaction::HTTP_REQUEST)
+            # Read the incoming trace context off the request headers so the
+            # transaction continues the upstream trace. No-op outside collector
+            # mode. Webmachine isn't Rack: `request.headers` is a case-insensitive
+            # `Webmachine::Headers`, so the default getter reads it directly.
+            Appsignal::Transaction.create(
+              Appsignal::Transaction::HTTP_REQUEST,
+              :opentelemetry_context => Appsignal::OpenTelemetry.if_started do
+                ::OpenTelemetry.propagation.extract(request.headers)
+              end,
+              :opentelemetry_scope => ["appsignal-ruby/webmachine", Appsignal::VERSION]
+            )
           end
 
+        unless has_parent_transaction
+          # Describes the transaction's span as an incoming HTTP request.
+          # Together with the SERVER span kind the transaction already carries,
+          # this is what the trace timeline reads to recognize a web request.
+          # Set here, where the transaction is created, so they land on the
+          # transaction's own span rather than on the event started below.
+          #
+          # Webmachine isn't Rack: the path, scheme, query string, host and port
+          # come off the request's `URI` rather than from Rack's readers. The
+          # request's own `query` is the parsed form, so the URI is where the
+          # string itself is. Webmachine has no environment to read the protocol
+          # version from, so that one is left undescribed.
+          transaction.add_opentelemetry_attributes(
+            Appsignal::OpenTelemetry::HttpServerRequest.attributes_for(
+              :method => request.method,
+              :path => request.uri&.path,
+              :scheme => request.uri&.scheme,
+              :query => request.uri&.query,
+              :host => request.uri&.host,
+              :port => request.uri&.port
+            )
+          )
+        end
+
         begin
-          transaction.add_params_if_nil { request.query }
-          transaction.add_headers_if_nil { request.headers if request.respond_to?(:headers) }
+          transaction.add_query_parameters_if_nil { request.query }
+          # `Webmachine::Headers` names a header the way OpenTelemetry does, in
+          # lowercase and with dashes, so these are headers and nothing else.
+          transaction.add_request_headers_if_nil do
+            request.headers if request.respond_to?(:headers)
+          end
 
-          Appsignal.instrument("process_action.webmachine") do
+          Appsignal.instrument(
+            "process_action.webmachine",
+            :opentelemetry_scope => ["appsignal-ruby/webmachine", Appsignal::VERSION]
+          ) do
             super
           end
         ensure
           transaction.set_action_if_nil("#{resource.class.name}##{request.method}")
 
-          Appsignal::Transaction.complete_current! unless has_parent_transaction
+          unless has_parent_transaction
+            # Describes the response on the transaction's span, which the
+            # semantic conventions ask for whenever a response was sent. The
+            # event above has closed by now, so this lands on the transaction's
+            # own span.
+            transaction.add_opentelemetry_attributes(
+              Appsignal::OpenTelemetry::HttpResponse.attributes_for(response.code)
+            )
+
+            Appsignal::Transaction.complete_current!
+          end
         end
       end
 

data/lib/appsignal/loaders/padrino.rb

@@ -20,7 +20,8 @@ module Appsignal
         Padrino.before_load do
           Padrino.use Appsignal::Rack::EventMiddleware
           Padrino.use Appsignal::Rack::SinatraBaseInstrumentation,
-            :instrument_event_name => "process_action.padrino"
+            :instrument_event_name => "process_action.padrino",
+            :opentelemetry_scope => ["appsignal-ruby/padrino", Appsignal::VERSION]
         end
       end
 

data/lib/appsignal/logger/extension_backend.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Appsignal
+  class Logger < ::Logger
+    # @!visibility private
+    #
+    # Routes Appsignal::Logger emits through the AppSignal C-extension,
+    # which forwards them to the agent. This is the default backend used
+    # when collector mode is not active.
+    module ExtensionBackend
+      class << self
+        def emit(group, severity, format, message, attributes)
+          Appsignal::Extension.log(
+            group,
+            SEVERITY_MAP.fetch(severity, 0),
+            format,
+            message,
+            Appsignal::Utils::Data.generate(attributes)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/appsignal/logger/opentelemetry_backend.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "appsignal/opentelemetry/attributes"
+
+module Appsignal
+  class Logger < ::Logger
+    # @!visibility private
+    #
+    # Routes Appsignal::Logger emits through the OpenTelemetry logs SDK
+    # using the logger provider configured at `Appsignal.start` time when
+    # collector mode is active.
+    #
+    # Each emit attaches two well-known attributes that the AppSignal
+    # collector consumes:
+    #
+    # - `appsignal.group` — overrides the collector's default
+    #   `service.name`-based grouping with the logger's `group` argument.
+    # - `appsignal.format` — the lowercase parse-format name
+    #   (`plaintext`/`logfmt`/`json`/`autodetect`) the processor uses to
+    #   extract structured attributes from the message body.
+    module OpenTelemetryBackend
+      # Maps Ruby `::Logger` severities to OTel SeverityNumber + the
+      # human-readable severity text.
+      OTEL_SEVERITY_MAP = {
+        ::Logger::DEBUG => [5, "DEBUG"],
+        ::Logger::INFO => [9, "INFO"],
+        ::Logger::WARN => [13, "WARN"],
+        ::Logger::ERROR => [17, "ERROR"],
+        ::Logger::FATAL => [21, "FATAL"]
+      }.freeze
+
+      # Maps the integer parse-format flag on `Appsignal::Logger` to the
+      # lowercase string the AppSignal collector and processor share.
+      FORMAT_NAMES = {
+        Appsignal::Logger::PLAINTEXT => "plaintext",
+        Appsignal::Logger::LOGFMT => "logfmt",
+        Appsignal::Logger::JSON => "json",
+        Appsignal::Logger::AUTODETECT => "autodetect"
+      }.freeze
+
+      class << self
+        def emit(group, severity, format, message, attributes)
+          number, text = OTEL_SEVERITY_MAP.fetch(severity, [0, nil])
+          otel_attributes = Appsignal::OpenTelemetry::Attributes.format(attributes)
+          otel_attributes["appsignal.group"] = group.to_s
+          otel_attributes["appsignal.format"] = FORMAT_NAMES.fetch(format, "autodetect")
+          logger.on_emit(
+            :severity_number => number,
+            :severity_text => text,
+            :body => message,
+            :attributes => otel_attributes
+          )
+        end
+
+        private
+
+        # Resolve the OTel logger on each emit. The logger provider caches it
+        # by name, so this is a registry lookup rather than a rebuild, and it
+        # always reflects the currently configured provider.
+        def logger
+          ::OpenTelemetry.logger_provider.logger(:name => "appsignal-logger")
+        end
+      end
+    end
+  end
+end

data/lib/appsignal/logger.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "logger"
-require "set"
 
 module Appsignal
   # Logger that flushes logs to the AppSignal logging service.
@@ -55,6 +54,8 @@ module Appsignal
     # @!visibility private
     AUTODETECT = 3
     # @!visibility private
+    FORMATS = [PLAINTEXT, LOGFMT, JSON, AUTODETECT].freeze
+    # @!visibility private
     SEVERITY_MAP = {
       DEBUG => 2,
       INFO => 3,
@@ -83,7 +84,7 @@ module Appsignal
       @group = group
       @level = level
       @silenced = false
-      @format = format
+      @format = validated_format(format)
       @mutex = Mutex.new
       @default_attributes = attributes
       @appsignal_attributes = attributes
@@ -145,13 +146,7 @@ module Appsignal
 
       message = formatter.call(severity, Time.now, group, message) if formatter
 
-      Appsignal::Extension.log(
-        group,
-        SEVERITY_MAP.fetch(severity, 0),
-        @format,
-        message.to_s,
-        Appsignal::Utils::Data.generate(appsignal_attributes)
-      )
+      Appsignal::Backends.logger.emit(group, severity, @format, message.to_s, appsignal_attributes)
 
       false
     end
@@ -299,5 +294,14 @@ module Appsignal
     ensure
       @appsignal_attributes = default_attributes
     end
+
+    def validated_format(format)
+      return format if FORMATS.include?(format)
+
+      Appsignal.internal_logger.warn(
+        "Unknown Appsignal::Logger format #{format.inspect}; falling back to AUTODETECT"
+      )
+      AUTODETECT
+    end
   end
 end

data/lib/appsignal/metrics/extension_backend.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module Metrics
+    # @!visibility private
+    #
+    # Routes custom metric helper calls through the AppSignal C-extension,
+    # which forwards them to the agent. This is the default backend used
+    # when collector mode is not active.
+    module ExtensionBackend
+      class << self
+        def set_gauge(name, value, tags)
+          Appsignal::Extension.set_gauge(
+            name.to_s,
+            value.to_f,
+            Appsignal::Utils::Data.generate(tags)
+          )
+        rescue RangeError
+          Appsignal.internal_logger
+            .warn("The gauge value '#{value}' for metric '#{name}' is too big")
+        end
+
+        def increment_counter(name, value, tags)
+          Appsignal::Extension.increment_counter(
+            name.to_s,
+            value.to_f,
+            Appsignal::Utils::Data.generate(tags)
+          )
+        rescue RangeError
+          Appsignal.internal_logger
+            .warn("The counter value '#{value}' for metric '#{name}' is too big")
+        end
+
+        def add_distribution_value(name, value, tags)
+          Appsignal::Extension.add_distribution_value(
+            name.to_s,
+            value.to_f,
+            Appsignal::Utils::Data.generate(tags)
+          )
+        rescue RangeError
+          Appsignal.internal_logger
+            .warn("The distribution value '#{value}' for metric '#{name}' is too big")
+        end
+      end
+    end
+  end
+end