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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6d6acf8b543263a2008bfc4ea0f20a57194d01aa2acdc5886292e8ead23e112
-  data.tar.gz: b1f7a59ef1b33459306bfb60a0681e581e1c1dd9be78a315d08d419c310e3296
+  metadata.gz: 77d0e22fb5459d6180f21e04d33c74b67fccf48bd536f9d421f2360803336edd
+  data.tar.gz: 4080ad48951daa435a0798951a5f36d98e62fe3b9cc62a0a94b04043e0b02b23
 SHA512:
-  metadata.gz: 7181d57c290de3067026ec31912c5da273b2dc7597453eda533f61b82f2654cbd467e81bb572ab93cd0fbdd38abdb582ba17a67de3a71185c1474724eba5254d
-  data.tar.gz: f4c27203476610873135cf6db61ae788c4f5bbab59b56f7cddd0a2bb2f657dfd19a3224ffddd240cde62b58dad51cfdfdaa078b1083ec81f33e75178e3cc445e
+  metadata.gz: 3dcc132106477e0181cff58f8bbed8ed1db7d6c3cebb81dac5b2cc9fc1a8e8b96cfcaf768bf1bfc4fff9c2529ddf6aa920ac30b9fc8367c7687f477f948ab048
+  data.tar.gz: e053bcbe1bb2ec6ad4e09efb80cbd86593ab9342acfe16bda373f596bc96e507920a611cff9802fd46a8219851feaf909a59b2e35b5d9e7bce60c4f2eb1716e2

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 # AppSignal for Ruby gem Changelog
 
+## 5.0.0.rc.1
+
+_Published on 2026-08-21._
+
+### Added
+
+- Add a `collector_endpoint` configuration option (`APPSIGNAL_COLLECTOR_ENDPOINT` environment variable) that puts the integration in _collector mode_. In collector mode AppSignal reports traces, metrics and logs to an AppSignal Collector, over OTLP/HTTP.
+
+  Collector mode requires Ruby 3.1 or newer, and the OpenTelemetry gems, which are not installed by default. Add the `appsignal-opentelemetry` gem alongside `appsignal` to install them. When they are missing or too old, AppSignal logs a warning and keeps reporting through its agent.
+
+  (major [84d83b65](https://github.com/appsignal/appsignal-ruby/commit/84d83b657d65a93859ba73f295216a3b0ee9cab1), [90768626](https://github.com/appsignal/appsignal-ruby/commit/9076862677444c7772e6f8fbe1e3d5a646a4849d))
+- Add configuration options that map to OpenTelemetry resource attributes in collector mode: `service_name`, `filter_attributes`, `filter_function_parameters`, `filter_request_query_parameters`, `filter_request_payload`, `response_headers`, `send_function_parameters`, `send_request_query_parameters` and `send_request_payload`.
+
+  In collector mode, existing options are passed to the collector as resource attributes as well: `name`, environment, `hostname`, `revision`, `ignore_actions`, `ignore_errors`, `ignore_namespaces`, `request_headers`, `filter_session_data` and `send_session_data`.
+
+  Setting any of these without `collector_endpoint`, or setting `filter_parameters`, `filter_metadata` or `send_params` with it, logs a warning at startup.
+
+  (minor [84d83b65](https://github.com/appsignal/appsignal-ruby/commit/84d83b657d65a93859ba73f295216a3b0ee9cab1), [90768626](https://github.com/appsignal/appsignal-ruby/commit/9076862677444c7772e6f8fbe1e3d5a646a4849d))
+
+## 4.10.1
+
+_Published on 2026-08-20._
+
+### Fixed
+
+- Use the CA certificate configured in `APPSIGNAL_CA_FILE_PATH` to download the
+  AppSignal agent when installing this gem.
+
+  The gem downloads the agent from our servers over HTTPS during installation. It
+  always used the CA certificate bundled with the gem to verify that connection,
+  whatever the value of the `ca_file_path` configuration option. This meant the
+  installation failed behind a proxy that intercepts TLS connections, such as
+  Zscaler, even when `APPSIGNAL_CA_FILE_PATH` pointed to a CA bundle that trusts
+  the proxy.
+
+  The bundled CA certificate is still used when `APPSIGNAL_CA_FILE_PATH` is not
+  set.
+
+  Thanks [@Cosmo](https://github.com/Cosmo) for your contribution!
+
+  (patch [5a126864](https://github.com/appsignal/appsignal-ruby/commit/5a126864314b0c4f244dab653c9548f48f7fd413), [0c49fc51](https://github.com/appsignal/appsignal-ruby/commit/0c49fc51a385d8e70a324792dc7dace3109b8424))
+
 ## 4.10.0
 
 _Published on 2026-08-10._

data/Rakefile

@@ -72,7 +72,50 @@ GITHUB_ACTION_WORKFLOW_FILE = ".github/workflows/ci.yml"
 PRIMARY_JOB_GEMSET = "no_dependencies"
 DEFAULT_RUNS_ON = "ubuntu-latest"
 
+COLLECTOR_GEMFILE_PARTIAL = "collector.rb"
+
 namespace :build_matrix do
+  namespace :gemfiles do
+    # Generates a `<base>-collector.gemfile` next to each base gemfile. The
+    # variant layers the optional OpenTelemetry gems (`gemfiles/collector.rb`)
+    # on top of the base, so collector-mode test runs resolve them while the
+    # base gemfiles (and the gemspec) stay OpenTelemetry-free. Regenerate
+    # whenever a base gemfile is added or removed.
+    task :generate do
+      base_gemfiles =
+        Dir["gemfiles/*.gemfile"]
+          .map { |path| File.basename(path) }
+          .reject { |name| name.end_with?("-collector.gemfile") }
+          .sort
+
+      base_gemfiles.each do |base|
+        name = base.sub(/\.gemfile\z/, "")
+        contents =
+          "# DO NOT EDIT\n" \
+            "# This is a generated file by the " \
+            "`rake build_matrix:gemfiles:generate` task.\n" \
+            "# It layers the optional OpenTelemetry gems (gemfiles/" \
+            "#{COLLECTOR_GEMFILE_PARTIAL}) on top of #{base}.\n" \
+            "\n" \
+            "eval_gemfile File.expand_path(#{base.inspect}, __dir__)\n" \
+            "eval_gemfile File.expand_path(" \
+            "#{COLLECTOR_GEMFILE_PARTIAL.inspect}, __dir__)\n"
+        File.write("gemfiles/#{name}-collector.gemfile", contents)
+      end
+
+      puts "Generated #{base_gemfiles.count} `-collector` gemfiles."
+    end
+
+    task :validate => :generate do
+      output = `git status --porcelain gemfiles`
+      if output.include?("-collector.gemfile")
+        puts "The `-collector` gemfiles are out of date. The changes were not committed."
+        puts "Please run `rake build_matrix:gemfiles:generate` and commit the changes."
+        exit 1
+      end
+    end
+  end
+
   namespace :github do
     task :generate do
       yaml = YAML.load_file("build_matrix.yml")
@@ -113,6 +156,21 @@ namespace :build_matrix do
             job["steps"] << test_step
             builds[build_matrix_key(ruby["ruby"], :ruby_gem => ruby_gem["gem"])] = job
           end
+
+          # On collector-capable Rubies, additionally run the gem's
+          # `-collector` gemfile (base gems + optional OpenTelemetry gems) so
+          # collector-mode specs are exercised. These always depend on the
+          # primary job for the Ruby version and run on Ubuntu only.
+          next unless collector_ruby?(matrix, ruby_version)
+
+          collector_gem = "#{ruby_gem["gem"]}-collector"
+          collector_job = build_job(ruby_version, :ruby_gem => collector_gem)
+          collector_job["env"] = matrix["env"]
+            .merge("BUNDLE_GEMFILE" => "gemfiles/#{collector_gem}.gemfile")
+          collector_job["needs"] = build_matrix_key(ruby["ruby"])
+          collector_job["steps"] << test_step
+          builds[build_matrix_key(ruby["ruby"], :ruby_gem => collector_gem)] =
+            collector_job
         end
 
         # Add build for macOS
@@ -191,6 +249,14 @@ namespace :build_matrix do
             out << "#{bundler_version} #{gemfile_env} ./script/bundler_wrapper install --quiet || { echo 'Bundling failed'; exit 1; }"
             out << "echo 'Running #{gemfile} in #{ruby_version}'"
             out << "#{bundler_version} #{gemfile_env} ./script/bundler_wrapper exec rspec || { echo 'Running specs failed'; exit 1; }"
+
+            next unless collector_ruby?(matrix, ruby_version)
+
+            collector_env = "env BUNDLE_GEMFILE=gemfiles/#{gemfile}-collector.gemfile"
+            out << "echo 'Bundling #{gemfile}-collector in #{ruby_version}'"
+            out << "#{bundler_version} #{collector_env} ./script/bundler_wrapper install --quiet || { echo 'Bundling failed'; exit 1; }"
+            out << "echo 'Running #{gemfile}-collector in #{ruby_version}'"
+            out << "#{bundler_version} #{collector_env} ./script/bundler_wrapper exec rspec || { echo 'Running specs failed'; exit 1; }"
           end
           # rubocop:enable Layout/LineLength
           out << ""
@@ -207,6 +273,10 @@ namespace :build_matrix do
     end
   end
 
+  def collector_ruby?(matrix, ruby_version)
+    Array(matrix.dig("collector", "ruby")).include?(ruby_version)
+  end
+
   def gemset_for_ruby(ruby, matrix)
     gems = matrix["gems"]
     if ruby["gems"]
@@ -288,6 +358,23 @@ namespace :build do
   desc "Build all gem versions"
   task :all => ["ruby:gem", "jruby:gem"]
 
+  desc "Build every package in this repository"
+  task :packages => :all do
+    # Build the companion gem by delegating to its own Rakefile rather than
+    # duplicating its build logic here. mono builds each package directly, so
+    # this task is only a convenience for developers building from the root.
+    #
+    # Clear the Bundler environment first so the sub-build resolves against the
+    # package's own Gemfile instead of inheriting this repository's
+    # BUNDLE_GEMFILE. Install its dependencies first, then build it.
+    Bundler.with_unbundled_env do
+      Dir.chdir("packages/opentelemetry") do
+        sh "bundle install"
+        sh "bundle exec rake build:all"
+      end
+    end
+  end
+
   desc "Clean up all gem build artifacts"
   task :clean do
     FileUtils.rm_rf File.expand_path("pkg", __dir__)

data/appsignal.gemspec

@@ -7,6 +7,7 @@ IGNORED_PATHS = [
   ".changesets/",
   ".github/",
   "gemfiles/",
+  "packages/",
   "script/",
   "spec/",
 
@@ -60,6 +61,13 @@ Gem::Specification.new do |gem|
   # Needs 2.0+ because we rely on Rack::Events
   gem.add_dependency "rack", ">= 2.0.0"
 
+  # The OpenTelemetry SDK and OTLP exporters are *optional* and intentionally
+  # not declared here: they're only needed in collector mode (Ruby 3.1+), so
+  # bundling them would break Ruby 2.7 and burden non-collector users. Apps
+  # that enable collector mode add them to their own Gemfile; the minimum
+  # versions live in `lib/appsignal/opentelemetry/dependencies.rb` and are
+  # enforced at boot by `Appsignal::OpenTelemetry.configure`.
+
   gem.add_development_dependency "pry"
   gem.add_development_dependency "rake", ">= 12"
   gem.add_development_dependency "rspec", "~> 3.8"

data/build_matrix.yml

@@ -2,7 +2,7 @@ github:
   name: Ruby gem CI
   "on":
     push:
-      branches: ["main", "develop"]
+      branches: ["main", "develop", "*-stable"]
     pull_request:
       types: [opened, reopened, synchronize]
     schedule:
@@ -107,6 +107,18 @@ matrix:
     JRUBY_OPTS: ""
     COV: "1"
 
+  # Ruby versions that additionally run each gem's `-collector` gemfile (the
+  # optional OpenTelemetry gems layered on top). Collector mode requires Ruby
+  # 3.1+ (the OTel metrics SDK's fork hooks rely on `Process._fork`) and does
+  # not support JRuby's forking model, so only these versions are listed.
+  collector:
+    ruby:
+      - "4.0.0"
+      - "3.4.1"
+      - "3.3.4"
+      - "3.2.5"
+      - "3.1.6"
+
   gemsets: # By default all gems are tested
     none:
       - "no_dependencies"
@@ -281,6 +293,7 @@ matrix:
           - "3.4.1"
           - "3.3.4"
           - "3.2.5"
+    - gem: "mongo"
     - gem: "resque-2"
     - gem: "resque-3"
       only:

data/ext/appsignal_extension.c

@@ -834,10 +834,23 @@ static VALUE add_distribution_value(VALUE self, VALUE key, VALUE value, VALUE ta
   return Qnil;
 }
 
+// Per-thread running total of object allocations, incremented on every Ruby
+// NEWOBJ event. Thread-local because MRI maps each Ruby thread to its own OS
+// thread, so this attributes allocations to the thread doing the work, which is
+// the thread the transaction runs on. Collector mode reads it through
+// Appsignal::Extension.allocation_count and diffs two snapshots to get the
+// allocations made during a transaction or an event.
+static __thread unsigned long long appsignal_thread_allocation_count = 0;
+
 static void track_allocation(rb_event_flag_t flag, VALUE arg1, VALUE arg2, ID arg3, VALUE arg4) {
+  appsignal_thread_allocation_count++;
   appsignal_track_allocation();
 }
 
+static VALUE allocation_count(VALUE self) {
+  return ULL2NUM(appsignal_thread_allocation_count);
+}
+
 static VALUE install_allocation_event_hook(VALUE self) {
   // This event hook is only available on Ruby 2.1 and 2.2
   #if defined(RUBY_INTERNAL_EVENT_NEWOBJ)
@@ -956,6 +969,7 @@ void Init_appsignal_extension(void) {
 
   // Other helper methods
   rb_define_singleton_method(Extension, "install_allocation_event_hook", install_allocation_event_hook, 0);
+  rb_define_singleton_method(Extension, "allocation_count", allocation_count, 0);
   rb_define_singleton_method(Extension, "running_in_container?", running_in_container, 0);
   rb_define_singleton_method(Extension, "set_environment_metadata", set_environment_metadata, 2);
 

data/ext/base.rb

@@ -22,6 +22,13 @@ def ext_path(path)
   File.join(EXT_PATH, path)
 end
 
+def ca_file_path
+  configured_path = ENV.fetch("APPSIGNAL_CA_FILE_PATH", nil)
+  return configured_path if configured_path && !configured_path.strip.empty?
+
+  CA_CERT_PATH
+end
+
 def report
   @report ||=
     begin
@@ -132,7 +139,7 @@ def download_archive(type)
       proxy, _error = http_proxy
       args = [
         download_url,
-        { :ssl_ca_cert => CA_CERT_PATH,
+        { :ssl_ca_cert => ca_file_path,
           :proxy => proxy }
       ]
       if URI.respond_to?(:open) # rubocop:disable Style/GuardClause

data/lib/appsignal/backends.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "appsignal/metrics/extension_backend"
+require "appsignal/metrics/opentelemetry_backend"
+require "appsignal/logger/extension_backend"
+require "appsignal/logger/opentelemetry_backend"
+require "appsignal/transaction/base_backend"
+require "appsignal/transaction/extension_backend"
+require "appsignal/transaction/opentelemetry_backend"
+
+module Appsignal
+  # @!visibility private
+  #
+  # Looks up the active backend for each AppSignal subsystem. In normal
+  # operation, subsystems route through the C-extension (and its agent).
+  # When collector mode is configured and the OpenTelemetry SDK has booted
+  # successfully, supported subsystems route through OTel instead.
+  #
+  # Centralizes the mode-check so per-subsystem call sites don't repeat the
+  # "if collector? then OTel else Extension" branch. Future subsystems plug
+  # in by adding one more lookup method here.
+  module Backends
+    class << self
+      def metrics
+        if collector?
+          Appsignal::Metrics::OpenTelemetryBackend
+        else
+          Appsignal::Metrics::ExtensionBackend
+        end
+      end
+
+      def logger
+        if collector?
+          Appsignal::Logger::OpenTelemetryBackend
+        else
+          Appsignal::Logger::ExtensionBackend
+        end
+      end
+
+      def transaction
+        if collector?
+          Appsignal::Transaction::OpenTelemetryBackend
+        else
+          Appsignal::Transaction::ExtensionBackend
+        end
+      end
+
+      private
+
+      def collector?
+        Appsignal.config&.collector_mode? || false
+      end
+    end
+  end
+end

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
+)