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

data/lib/appsignal/cli/helpers.rb

@@ -36,51 +36,6 @@ module Appsignal
         "\e[#{color_code}m#{text}\e[#{reset_color_code}m"
       end
 
-      def print_empty_line
-        puts "\n"
-      end
-
-      def rails_present?
-        require "rails"
-        true
-      rescue LoadError
-        false
-      end
-
-      # The Rails gem being loadable says nothing about the directory the
-      # command runs in, so check for the app itself as well.
-      def rails_app_present?
-        rails_present? &&
-          File.exist?(Appsignal::Utils::RailsHelper.environment_config_path)
-      end
-
-      def load_rails_app(environment)
-        # Pass the environment given as a command line option to the app, so
-        # that the AppSignal config file uses it when the app loads it.
-        ENV["_APPSIGNAL_CONFIG_FILE_ENV"] = environment
-        # Require the railtie manually. It was not loaded when AppSignal
-        # loaded, because the `Rails` constant was not present at that point.
-        require "appsignal/integrations/railtie"
-        # Start the Rails app, including its railties and initializers.
-        require Appsignal::Utils::RailsHelper.environment_config_path
-      ensure
-        ENV.delete("_APPSIGNAL_CONFIG_FILE_ENV")
-      end
-
-      # Yields the error when the app fails to load, so that a command can
-      # report it in its own way.
-      def require_rails_app_if_present(environment)
-        return unless rails_app_present?
-
-        load_rails_app(environment)
-      rescue LoadError, StandardError => error
-        print_empty_line
-        puts "ERROR: Error encountered while loading the Rails app"
-        puts "#{error.class}: #{error.message}"
-        puts error.backtrace
-        yield error if block_given?
-      end
-
       def periods
         3.times do
           print "."

data/lib/appsignal/config.rb

@@ -91,6 +91,7 @@ module Appsignal
     DEFAULT_CONFIG = {
       :activejob_report_errors => "all",
       :ca_file_path => File.expand_path(File.join("../../../resources/cacert.pem"), __FILE__),
+      :collector_endpoint => nil,
       :dns_servers => [],
       :enable_allocation_tracking => true,
       :enable_at_exit_hook => "on_error",
@@ -107,8 +108,12 @@ module Appsignal
       :enable_rake_performance_instrumentation => false,
       :endpoint => "https://push.appsignal.com",
       :files_world_accessible => true,
+      :filter_attributes => [],
+      :filter_function_parameters => [],
       :filter_metadata => [],
       :filter_parameters => [],
+      :filter_request_payload => [],
+      :filter_request_query_parameters => [],
       :filter_session_data => [],
       :ignore_actions => [],
       :ignore_errors => [],
@@ -139,9 +144,14 @@ module Appsignal
         REQUEST_METHOD REQUEST_PATH SERVER_NAME SERVER_PORT
         SERVER_PROTOCOL
       ],
+      :response_headers => [],
       :send_environment_metadata => true,
+      :send_function_parameters => nil,
       :send_params => true,
+      :send_request_payload => nil,
+      :send_request_query_parameters => nil,
       :send_session_data => true,
+      :service_name => nil,
       :sidekiq_report_errors => "all",
       :default_tags => {}
     }.freeze
@@ -167,6 +177,7 @@ module Appsignal
       :name => "APPSIGNAL_APP_NAME",
       :bind_address => "APPSIGNAL_BIND_ADDRESS",
       :ca_file_path => "APPSIGNAL_CA_FILE_PATH",
+      :collector_endpoint => "APPSIGNAL_COLLECTOR_ENDPOINT",
       :enable_at_exit_hook => "APPSIGNAL_ENABLE_AT_EXIT_HOOK",
       :hostname => "APPSIGNAL_HOSTNAME",
       :host_role => "APPSIGNAL_HOST_ROLE",
@@ -177,6 +188,7 @@ module Appsignal
       :logging_endpoint => "APPSIGNAL_LOGGING_ENDPOINT",
       :endpoint => "APPSIGNAL_PUSH_API_ENDPOINT",
       :push_api_key => "APPSIGNAL_PUSH_API_KEY",
+      :service_name => "APPSIGNAL_SERVICE_NAME",
       :sidekiq_report_errors => "APPSIGNAL_SIDEKIQ_REPORT_ERRORS",
       :statsd_port => "APPSIGNAL_STATSD_PORT",
       :nginx_port => "APPSIGNAL_NGINX_PORT",
@@ -221,21 +233,29 @@ module Appsignal
       :ownership_set_namespace => "APPSIGNAL_OWNERSHIP_SET_NAMESPACE",
       :running_in_container => "APPSIGNAL_RUNNING_IN_CONTAINER",
       :send_environment_metadata => "APPSIGNAL_SEND_ENVIRONMENT_METADATA",
+      :send_function_parameters => "APPSIGNAL_SEND_FUNCTION_PARAMETERS",
       :send_params => "APPSIGNAL_SEND_PARAMS",
+      :send_request_payload => "APPSIGNAL_SEND_REQUEST_PAYLOAD",
+      :send_request_query_parameters => "APPSIGNAL_SEND_REQUEST_QUERY_PARAMETERS",
       :send_session_data => "APPSIGNAL_SEND_SESSION_DATA"
     }.freeze
 
     # @!visibility private
     ARRAY_OPTIONS = {
       :dns_servers => "APPSIGNAL_DNS_SERVERS",
+      :filter_attributes => "APPSIGNAL_FILTER_ATTRIBUTES",
+      :filter_function_parameters => "APPSIGNAL_FILTER_FUNCTION_PARAMETERS",
       :filter_metadata => "APPSIGNAL_FILTER_METADATA",
       :filter_parameters => "APPSIGNAL_FILTER_PARAMETERS",
+      :filter_request_payload => "APPSIGNAL_FILTER_REQUEST_PAYLOAD",
+      :filter_request_query_parameters => "APPSIGNAL_FILTER_REQUEST_QUERY_PARAMETERS",
       :filter_session_data => "APPSIGNAL_FILTER_SESSION_DATA",
       :ignore_actions => "APPSIGNAL_IGNORE_ACTIONS",
       :ignore_errors => "APPSIGNAL_IGNORE_ERRORS",
       :ignore_logs => "APPSIGNAL_IGNORE_LOGS",
       :ignore_namespaces => "APPSIGNAL_IGNORE_NAMESPACES",
-      :request_headers => "APPSIGNAL_REQUEST_HEADERS"
+      :request_headers => "APPSIGNAL_REQUEST_HEADERS",
+      :response_headers => "APPSIGNAL_RESPONSE_HEADERS"
     }.freeze
 
     # @!visibility private
@@ -248,6 +268,39 @@ module Appsignal
       :default_tags => "APPSIGNAL_DEFAULT_TAGS"
     }.freeze
 
+    # Collector mode requires Ruby 3.1+. The OpenTelemetry Ruby SDK relies on
+    # `Process._fork` (introduced in Ruby 3.1) for its fork hooks, without
+    # which background reader threads don't restart in child processes and
+    # buffered telemetry is lost after a fork.
+    # @!visibility private
+    MIN_RUBY_VERSION_FOR_COLLECTOR_MODE = "3.1"
+
+    # Configuration options that only have an effect when the integration is
+    # in collector mode. When the agent is in use, setting any of these emits
+    # a warning at startup.
+    # @!visibility private
+    COLLECTOR_ONLY_OPTIONS = [
+      :filter_attributes,
+      :filter_function_parameters,
+      :filter_request_payload,
+      :filter_request_query_parameters,
+      :response_headers,
+      :send_function_parameters,
+      :send_request_payload,
+      :send_request_query_parameters,
+      :service_name
+    ].freeze
+
+    # Existing AppSignal options that only affect the agent's handling of
+    # trace data. In collector mode these don't filter anything; users need
+    # their collector-mode equivalents (see COLLECTOR_ONLY_OPTIONS).
+    # @!visibility private
+    AGENT_ONLY_TRACE_OPTIONS = [
+      :filter_metadata,
+      :filter_parameters,
+      :send_params
+    ].freeze
+
     # @!visibility private
     attr_reader :root_path, :env, :config_hash
 
@@ -452,6 +505,57 @@ module Appsignal
       valid? && active_for_env?
     end
 
+    # Check if collector mode is configured.
+    #
+    # Returns true when a non-empty `collector_endpoint` is set and the
+    # running Ruby version is at least {MIN_RUBY_VERSION_FOR_COLLECTOR_MODE}.
+    # On older Rubies, `collector_endpoint` is ignored (with a warning) and
+    # the AppSignal agent is used instead.
+    #
+    # This is the *intent* check — it answers "did the user ask for
+    # collector mode, and could we honor it?". It does not say whether the
+    # OpenTelemetry SDK actually booted. See {#collector_mode?} for that.
+    #
+    # Memoised: the result is cached on first call so hot paths avoid
+    # re-running the string-strip predicate, and so the unsupported-Ruby
+    # warning is emitted at most once per `Config` instance.
+    #
+    # @return [Boolean] True if collector mode is configured.
+    def collector_mode_configured?
+      return @collector_mode_configured if defined?(@collector_mode_configured)
+
+      endpoint = config_hash[:collector_endpoint]
+      configured = !endpoint.nil? && !endpoint.to_s.strip.empty?
+
+      if configured && Gem::Version.new(RUBY_VERSION) <
+          Gem::Version.new(MIN_RUBY_VERSION_FOR_COLLECTOR_MODE)
+        Appsignal::Utils::StdoutAndLoggerMessage.warning(
+          "Collector mode requires Ruby #{MIN_RUBY_VERSION_FOR_COLLECTOR_MODE} or higher " \
+            "(running Ruby #{RUBY_VERSION}). The `collector_endpoint` option will be " \
+            "ignored and the AppSignal agent will be used instead."
+        )
+        @collector_mode_configured = false
+      else
+        @collector_mode_configured = configured
+      end
+    end
+
+    # Check if AppSignal is actively running in collector mode.
+    #
+    # True only if collector mode is {#collector_mode_configured? configured}
+    # *and* `Appsignal::OpenTelemetry.configure` has successfully booted the
+    # SDK in this process. Use this for backend dispatch on hot paths
+    # (metric and log emits): if the OTel boot failed, callers fall back to
+    # the agent backend rather than silently dropping data into no-op
+    # providers.
+    #
+    # @return [Boolean] True if collector mode is configured and started.
+    def collector_mode?
+      collector_mode_configured? &&
+        defined?(Appsignal::OpenTelemetry) &&
+        Appsignal::OpenTelemetry.started?
+    end
+
     # @!visibility private
     def write_to_environment
       ENV["_APPSIGNAL_ACTIVE"]                       = active?.to_s
@@ -528,6 +632,30 @@ module Appsignal
       else
         @valid = true
       end
+
+      warn_for_mode_mismatch
+    end
+
+    # Emit warnings when a configuration option is set that has no effect in
+    # the current mode (collector vs. agent).
+    #
+    # Uses {#collector_mode_configured?} (intent) rather than
+    # {#collector_mode?} so the warnings fire based on what the user asked
+    # for, independent of whether the OpenTelemetry SDK successfully booted.
+    # @!visibility private
+    def warn_for_mode_mismatch
+      if collector_mode_configured?
+        warn_user_modified(AGENT_ONLY_TRACE_OPTIONS) do |option|
+          "The collector is in use. The '#{option}' configuration option is " \
+            "only used by the agent for trace data and will be ignored."
+        end
+      else
+        warn_user_modified(COLLECTOR_ONLY_OPTIONS) do |option|
+          "The agent is in use. The '#{option}' configuration option is " \
+            "only used by the collector and will be ignored. Set " \
+            "'collector_endpoint' to use the collector."
+        end
+      end
     end
 
     # Deep freeze the config object so it cannot be modified during the runtime
@@ -551,6 +679,17 @@ module Appsignal
 
     private
 
+    # Yield a warning for each option in `options` whose effective value
+    # differs from the default. Setting an option to its default value is
+    # a no-op, so we don't warn about it.
+    def warn_user_modified(options)
+      options.each do |option|
+        next if config_hash[option] == DEFAULT_CONFIG[option]
+
+        logger.warn(yield(option))
+      end
+    end
+
     def logger
       Appsignal.internal_logger
     end

data/lib/appsignal/demo.rb

@@ -70,7 +70,7 @@ module Appsignal
       end
 
       def add_params_to(transaction)
-        transaction.add_params(
+        transaction.add_request_payload(
           "controller" => "demo",
           "action" => "hello"
         )

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

@@ -7,13 +7,27 @@ module Appsignal
       class RenderFormatter < Appsignal::EventFormatter
         BLANK = ""
 
+        def opentelemetry_attributes(_payload)
+          Appsignal::OpenTelemetry::Rendering.attributes
+        end
+
         def format(payload)
-          return nil unless payload[:identifier]
+          # The title is the template's path made relative to the application's
+          # root, so a template rendered outside an application gets no title.
+          return unless payload[:identifier] && root_path
 
           [payload[:identifier].sub(root_path, BLANK), nil]
         end
 
+        # The application's root, which a template'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 template render in the application without a title.
         def root_path
+          return unless defined?(Rails)
+
           @root_path ||= "#{Rails.root}/"
         end
       end
@@ -21,24 +35,22 @@ module Appsignal
   end
 end
 
-if defined?(Rails)
-  Appsignal::EventFormatter.register(
-    "render_partial.action_view",
-    Appsignal::EventFormatter::ActionView::RenderFormatter
-  )
-  Appsignal::EventFormatter.register(
-    "render_template.action_view",
-    Appsignal::EventFormatter::ActionView::RenderFormatter
-  )
-  # Action View reports the template's path for these two as well, so they are
-  # titled the same way. A collection reports the partial it rendered for each
-  # item, and a layout reports itself.
-  Appsignal::EventFormatter.register(
-    "render_collection.action_view",
-    Appsignal::EventFormatter::ActionView::RenderFormatter
-  )
-  Appsignal::EventFormatter.register(
-    "render_layout.action_view",
-    Appsignal::EventFormatter::ActionView::RenderFormatter
-  )
-end
+Appsignal::EventFormatter.register(
+  "render_partial.action_view",
+  Appsignal::EventFormatter::ActionView::RenderFormatter
+)
+Appsignal::EventFormatter.register(
+  "render_template.action_view",
+  Appsignal::EventFormatter::ActionView::RenderFormatter
+)
+# Action View reports the template's path for these two as well, so they are
+# titled the same way. A collection reports the partial it rendered for each
+# item, and a layout reports itself.
+Appsignal::EventFormatter.register(
+  "render_collection.action_view",
+  Appsignal::EventFormatter::ActionView::RenderFormatter
+)
+Appsignal::EventFormatter.register(
+  "render_layout.action_view",
+  Appsignal::EventFormatter::ActionView::RenderFormatter
+)

data/lib/appsignal/event_formatter/active_job/perform_formatter.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Appsignal
+  class EventFormatter
+    # @!visibility private
+    module ActiveJob
+      # Active Job reports the job it is running as a `perform.active_job`
+      # notification. The job's own transaction already carries its title, so
+      # this formatter only describes the event as the work of performing a
+      # job.
+      class PerformFormatter < Appsignal::EventFormatter
+        PERFORM_ATTRIBUTES =
+          Appsignal::OpenTelemetry::Messaging.perform_attributes("active_job").freeze
+
+        def opentelemetry_attributes(payload)
+          PERFORM_ATTRIBUTES.merge(
+            { "messaging.destination.name" => queue_name(payload) }.compact
+          )
+        end
+
+        # The queue the job being performed is on, which the notification
+        # carries as the job itself.
+        def queue_name(payload)
+          job = payload[:job]
+          job.queue_name if job.respond_to?(:queue_name)
+        end
+      end
+    end
+  end
+end
+
+Appsignal::EventFormatter.register(
+  "perform.active_job",
+  Appsignal::EventFormatter::ActiveJob::PerformFormatter
+)

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