newrelic_rpm 3.12.0.288 → 9.10.2

data/lib/new_relic/agent.rb

@@ -1,9 +1,8 @@
-# encoding: utf-8
 # This file is distributed under New Relic's license terms.
-# See https://github.com/newrelic/rpm/blob/master/LICENSE for complete details.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
 
 require 'forwardable'
-require 'new_relic/control'
 
 # @api public
 module NewRelic
@@ -27,19 +26,17 @@ module NewRelic
 
     require 'new_relic/version'
     require 'new_relic/local_environment'
-    require 'new_relic/metrics'
     require 'new_relic/metric_spec'
     require 'new_relic/metric_data'
-    require 'new_relic/collection_helper'
     require 'new_relic/noticed_error'
-    require 'new_relic/timer_lib'
+    require 'new_relic/agent/noticeable_error'
+    require 'new_relic/supportability_helper'
+    require 'new_relic/thread_local_storage'
 
-    require 'new_relic/agent'
+    require 'new_relic/agent/encoding_normalizer'
     require 'new_relic/agent/stats'
     require 'new_relic/agent/chained_call'
-    require 'new_relic/agent/cross_app_monitor'
     require 'new_relic/agent/agent'
-    require 'new_relic/agent/shim_agent'
     require 'new_relic/agent/method_tracer'
     require 'new_relic/agent/worker_loop'
     require 'new_relic/agent/event_loop'
@@ -48,20 +45,29 @@ module NewRelic
     require 'new_relic/agent/sql_sampler'
     require 'new_relic/agent/commands/thread_profiler_session'
     require 'new_relic/agent/error_collector'
-    require 'new_relic/agent/busy_calculator'
+    require 'new_relic/agent/error_filter'
     require 'new_relic/agent/sampler'
     require 'new_relic/agent/database'
+    require 'new_relic/agent/database_adapter'
+    require 'new_relic/agent/datastores'
     require 'new_relic/agent/pipe_channel_manager'
     require 'new_relic/agent/configuration'
     require 'new_relic/agent/rules_engine'
     require 'new_relic/agent/http_clients/uri_util'
     require 'new_relic/agent/system_info'
+    require 'new_relic/agent/external'
+    require 'new_relic/agent/deprecator'
+    require 'new_relic/agent/logging'
+    require 'new_relic/agent/distributed_tracing'
+    require 'new_relic/agent/attribute_pre_filtering'
+    require 'new_relic/agent/attribute_processing'
+    require 'new_relic/agent/linking_metadata'
+    require 'new_relic/agent/local_log_decorator'
+    require 'new_relic/agent/llm'
+    require 'new_relic/agent/aws'
 
     require 'new_relic/agent/instrumentation/controller_instrumentation'
 
-    # this is a shim that's here only for backwards compatibility
-    require 'new_relic/agent/instrumentation/metric_frame'
-
     require 'new_relic/agent/samplers/cpu_sampler'
     require 'new_relic/agent/samplers/memory_sampler'
     require 'new_relic/agent/samplers/object_sampler'
@@ -71,6 +77,8 @@ module NewRelic
     require 'thread'
     require 'resolv'
 
+    extend NewRelic::SupportabilityHelper
+
     # An exception that is thrown by the server if the agent license is invalid.
     class LicenseException < StandardError; end
 
@@ -78,7 +86,11 @@ module NewRelic
     class ForceDisconnectException < StandardError; end
 
     # An exception that forces an agent to restart.
-    class ForceRestartException < StandardError; end
+    class ForceRestartException < StandardError
+      def message
+        "#{super}, restarting."
+      end
+    end
 
     # Used to blow out of a periodic task without logging a an error, such as for routine
     # failures.
@@ -94,26 +106,36 @@ module NewRelic
     # An error while serializing data for the collector
     class SerializationError < StandardError; end
 
-    class BackgroundLoadingError < StandardError; end
-
     # placeholder name used when we cannot determine a transaction's name
     UNKNOWN_METRIC = '(unknown)'.freeze
+    LLM_FEEDBACK_MESSAGE = 'LlmFeedbackMessage'
+
+    attr_reader :error_group_callback
+    attr_reader :llm_token_count_callback
 
     @agent = nil
+    @error_group_callback = nil
+    @llm_token_count_callback = nil
+    @logger = nil
+    @tracer_lock = Mutex.new
+    @tracer_queue = []
+    @metrics_already_recorded = Set.new
 
     # The singleton Agent instance.  Used internally.
-    def agent #:nodoc:
+    def agent # :nodoc:
       return @agent if @agent
+
       NewRelic::Agent.logger.warn("Agent unavailable as it hasn't been started.")
       NewRelic::Agent.logger.warn(caller.join("\n"))
       nil
     end
 
-    def agent=(new_instance)#:nodoc:
+    def agent=(new_instance) # :nodoc:
       @agent = new_instance
+      add_deferred_method_tracers_now
     end
 
-    alias instance agent #:nodoc:
+    alias instance agent # :nodoc:
 
     # Primary interface to logging is fronted by this accessor
     # Access via ::NewRelic::Agent.logger
@@ -125,17 +147,40 @@ module NewRelic
       @logger = log
     end
 
-    # This needs to come after the definition of the logger method above, since
-    # instantiating the config writes to the Logger.
+    # A third-party class may call add_method_tracer before the agent
+    # is initialized; these methods enable us to defer these calls
+    # until we have started up and can process them.
+    #
+    def add_or_defer_method_tracer(receiver, method_name, metric_name, options)
+      @tracer_lock.synchronize do
+        options[:code_information] = NewRelic::Agent::MethodTracerHelpers.code_information(receiver, method_name)
+
+        if @agent
+          receiver.send(:_nr_add_method_tracer_now, method_name, metric_name, options)
+        else
+          @tracer_queue << [receiver, method_name, metric_name, options]
+        end
+      end
+    end
 
-    @config = NewRelic::Agent::Configuration::Manager.new
+    def add_deferred_method_tracers_now
+      @tracer_lock.synchronize do
+        @tracer_queue.each do |receiver, method_name, metric_name, options|
+          receiver.send(:_nr_add_method_tracer_now, method_name, metric_name, options)
+        end
 
-    attr_reader :config
+        @tracer_queue = []
+      end
+    end
+
+    def config
+      @config ||= Configuration::Manager.new
+    end
 
     # For testing
     # Important that we don't change the instance or we orphan callbacks
     def reset_config
-      @config.reset_to_defaults
+      config.reset_to_defaults
     end
 
     # @!group Recording custom metrics
@@ -156,21 +201,38 @@ module NewRelic
     # This method is safe to use from any thread.
     #
     # @api public
-    def record_metric(metric_name, value) #THREAD_LOCAL_ACCESS
+    def record_metric(metric_name, value) # THREAD_LOCAL_ACCESS
+      record_api_supportability_metric(:record_metric)
+
+      return unless agent
+
       if value.is_a?(Hash)
         stats = NewRelic::Agent::Stats.new
-
-        stats.call_count = value[:count] if value[:count]
-        stats.total_call_time = value[:total] if value[:total]
-        stats.total_exclusive_time = value[:total] if value[:total]
-        stats.min_call_time = value[:min] if value[:min]
-        stats.max_call_time = value[:max] if value[:max]
-        stats.sum_of_squares = value[:sum_of_squares] if value[:sum_of_squares]
-        value = stats
+        value = stats.hash_merge(value)
       end
+
       agent.stats_engine.tl_record_unscoped_metrics(metric_name, value)
     end
 
+    def record_metric_once(metric_name, value = 0.0)
+      return unless @metrics_already_recorded.add?(metric_name)
+
+      record_metric(metric_name, value)
+    end
+
+    def record_instrumentation_invocation(library)
+      record_metric_once("Supportability/#{library}/Invoked")
+    end
+
+    # see ActiveSupport::Inflector.demodulize
+    def base_name(klass_name)
+      return klass_name unless ridx = klass_name.rindex('::')
+
+      klass_name[(ridx + 2), klass_name.length]
+    end
+
+    SUPPORTABILITY_INCREMENT_METRIC = 'Supportability/API/increment_metric'.freeze
+
     # Increment a simple counter metric.
     #
     # +metric_name+ should follow a slash separated path convention. Application
@@ -179,9 +241,16 @@ module NewRelic
     # This method is safe to use from any thread.
     #
     # @api public
-    def increment_metric(metric_name, amount=1) #THREAD_LOCAL_ACCESS
-      agent.stats_engine.tl_record_unscoped_metrics(metric_name) do |stats|
-        stats.increment_count(amount)
+    #
+    def increment_metric(metric_name, amount = 1) # THREAD_LOCAL_ACCESS
+      return unless agent
+
+      if amount == 1
+        metrics = [metric_name, SUPPORTABILITY_INCREMENT_METRIC]
+        agent.stats_engine.tl_record_unscoped_metrics(metrics) { |stats| stats.increment_count }
+      else
+        agent.stats_engine.tl_record_unscoped_metrics(metric_name) { |stats| stats.increment_count(amount) }
+        agent.stats_engine.tl_record_unscoped_metrics(SUPPORTABILITY_INCREMENT_METRIC) { |stats| stats.increment_count }
       end
     end
 
@@ -189,8 +258,8 @@ module NewRelic
 
     # @!group Recording custom errors
 
-    # Set a filter to be applied to errors that the Ruby Agent will
-    # track.  The block should evalute to the exception to track
+    # Set a filter to be applied to errors that the Ruby agent will
+    # track.  The block should evaluate to the exception to track
     # (which could be different from the original exception) or nil to
     # ignore this exception.
     #
@@ -201,6 +270,8 @@ module NewRelic
     # @api public
     #
     def ignore_error_filter(&block)
+      record_api_supportability_metric(:ignore_error_filter)
+
       if block
         NewRelic::Agent::ErrorCollector.ignore_error_filter = block
       else
@@ -208,22 +279,80 @@ module NewRelic
       end
     end
 
-    # Notice the error with the given available options:
+    # Send an error to New Relic.
+    #
+    # @param [Exception] exception Error you wish to send
+    # @param [Hash]      options Modify how New Relic processes the error
+    # @option options [Hash]    :custom_params Custom parameters to attach to the trace
+    # @option options [Boolean] :expected Only record the error trace
+    #                           (do not affect error rate or Apdex status)
+    # @option options [String]  :uri Request path, minus request params or query string
+    #                           (usually not needed)
+    # @option options [String]  :metric Metric name associated with the transaction
+    #                           (usually not needed)
+    #
+    # Any option keys other than the ones listed here are treated as
+    # <code>:custom_params</code>.
     #
-    # * <tt>:uri</tt> => Request path, minus request params or query string
-    # * <tt>:metric</tt> => The metric name associated with the transaction
-    # * <tt>:custom_params</tt> => Custom parameters
+    # *Note:* Previous versions of the agent allowed passing
+    # <code>:request_params</code>, but those are now ignored.  If you
+    # need to record the request parameters, call this method inside a
+    # transaction or pass the information in
+    # <code>:custom_params</code>.
     #
-    # Previous versions of the agent allowed passing :request_params but
-    # those are now ignored. Associate the request with the enclosing
-    # transaction, or record additional information as custom attributes.
-    # Anything left over is treated as custom params.
+    # Most of the time, you do not need to specify the
+    # <code>:uri</code> or <code>:metric</code> options; only pass
+    # them if you are calling <code>notice_error</code> outside a
+    # transaction.
     #
     # @api public
     #
-    def notice_error(exception, options={})
+    def notice_error(exception, options = {})
+      record_api_supportability_metric(:notice_error)
+
       Transaction.notice_error(exception, options)
-      nil # don't return a noticed error datastructure. it can only hurt.
+      nil # don't return a noticed error data structure. it can only hurt.
+    end
+
+    # Set a callback proc for determining an error's error group name
+    #
+    # @param callback_proc [Proc] the callback proc
+    #
+    # Typically this method should be called only once to set a callback for
+    # use with all noticed errors. If it is called multiple times, each new
+    # callback given will replace the old one.
+    #
+    # The proc will be called with a single hash as its input argument and is
+    # expected to return a string representing the desired error group.
+    #
+    # see https://docs.newrelic.com/docs/errors-inbox/errors-inbox/#groups
+    #
+    # The hash passed to the customer defined callback proc has the following
+    # keys:
+    #
+    # :error => The Ruby error class instance, likely inheriting from
+    #           StandardError. Call `#class`, `#message`, and `#backtrace` on
+    #           the error object to retrieve the error's class, message, and
+    #           backtrace.
+    # :customAttributes => Any customer defined custom attributes that have been
+    #                      associated with the current transaction.
+    # :'request.uri' => The current request URI if available
+    # :'http.statusCode' => The HTTP status code (200, 404, etc.) if available
+    # :'http.method' => The HTTP method (GET, PUT, etc.) if available
+    # :'error.expected' => Whether (true) or not (false) the error was expected
+    # :options => The options hash passed to `NewRelic::Agent.notice_error`
+    #
+    # @api public
+    #
+    def set_error_group_callback(callback_proc)
+      unless callback_proc.is_a?(Proc)
+        NewRelic::Agent.logger.error("#{self}.#{__method__}: expected an argument of type Proc, " \
+                                     "got #{callback_proc.class}")
+        return
+      end
+
+      record_api_supportability_metric(:set_error_group_callback)
+      @error_group_callback = callback_proc
     end
 
     # @!endgroup
@@ -255,23 +384,112 @@ module NewRelic
     # @api public
     #
     def record_custom_event(event_type, event_attrs)
+      record_api_supportability_metric(:record_custom_event)
+
       if agent && NewRelic::Agent.config[:'custom_insights_events.enabled']
         agent.custom_event_aggregator.record(event_type, event_attrs)
       end
+
       nil
     end
 
+    # Records user feedback events for LLM applications. This API must pass
+    # the current trace id as a parameter, which can be obtained using:
+    #
+    #   NewRelic::Agent::Tracer.current_trace_id
+    #
+    # @param [String] ID of the trace where the chat completion(s) related
+    #   to the feedback occurred.
+    #
+    # @param [String or Integer] Rating provided by an end user
+    #   (ex: “Good", "Bad”, 1, 2, 5, 8, 10).
+    #
+    # @param [optional, String] Category of the feedback as provided by the
+    #   end user (ex: “informative”, “inaccurate”).
+    #
+    # @param start_time [optional, String] Freeform text feedback from an
+    #   end user.
+    #
+    # @param [optional, Hash] Set of key-value pairs to store any other
+    #   desired data to submit with the feedback event.
+    #
+    # @api public
+    #
+    def record_llm_feedback_event(trace_id:,
+      rating:,
+      category: nil,
+      message: nil,
+      metadata: NewRelic::EMPTY_HASH)
+
+      record_api_supportability_metric(:record_llm_feedback_event)
+      unless NewRelic::Agent.config[:'distributed_tracing.enabled']
+        return NewRelic::Agent.logger.error('Distributed tracing must be enabled to record LLM feedback')
+      end
+
+      feedback_message_event = {
+        'trace_id': trace_id,
+        'rating': rating,
+        'category': category,
+        'message': message,
+        'id': NewRelic::Agent::GuidGenerator.generate_guid,
+        'ingest_source': NewRelic::Agent::Llm::LlmEvent::INGEST_SOURCE
+      }
+      feedback_message_event.merge!(metadata) unless metadata.empty?
+
+      NewRelic::Agent.record_custom_event(LLM_FEEDBACK_MESSAGE, feedback_message_event)
+    rescue ArgumentError
+      raise
+    rescue => exception
+      NewRelic::Agent.logger.error('record_llm_feedback_event', exception)
+    end
+
+    # @!endgroup
+
+    # @!group LLM callbacks
+
+    # Set a callback proc for calculating `token_count` attributes for
+    # LlmEmbedding and LlmChatCompletionMessage events
+    #
+    # @param callback_proc [Proc] the callback proc
+    #
+    # This method should be called only once to set a callback for
+    # use with all LLM token calculations. If it is called multiple times, each
+    # new callback will replace the old one.
+    #
+    # The proc will be called with a single hash as its input argument and
+    # must return an Integer representing the number of tokens used for that
+    # particular prompt, completion message, or embedding. Values less than or
+    # equal to 0 will not be attached to an event.
+    #
+    # The hash has the following keys:
+    #
+    # :model => [String] The name of the LLM model
+    # :content => [String] The message content or prompt
+    #
+    # @api public
+    #
+    def set_llm_token_count_callback(callback_proc)
+      unless callback_proc.is_a?(Proc)
+        NewRelic::Agent.logger.error("#{self}.#{__method__}: expected an argument of type Proc, " \
+                                     "got #{callback_proc.class}")
+        return
+      end
+
+      record_api_supportability_metric(:set_llm_token_count_callback)
+      @llm_token_count_callback = callback_proc
+    end
+
     # @!endgroup
 
     # @!group Manual agent configuration and startup/shutdown
 
-    # Call this to manually start the Agent in situations where the Agent does
+    # Call this to manually start the agent in situations where the agent does
     # not auto-start.
     #
-    # When the app environment loads, so does the Agent. However, the
-    # Agent will only connect to the service if a web front-end is found. If
+    # When the app environment loads, so does the agent. However, the
+    # agent will only connect to the service if a web front-end is found. If
     # you want to selectively monitor ruby processes that don't use
-    # web plugins, then call this method in your code and the Agent
+    # web plugins, then call this method in your code and the agent
     # will fire up and start reporting to the service.
     #
     # Options are passed in as overrides for values in the
@@ -282,12 +500,11 @@ module NewRelic
     #
     # @api public
     #
-    def manual_start(options={})
-      raise "Options must be a hash" unless Hash === options
-      if options[:start_channel_listener]
-        NewRelic::Agent::PipeChannelManager.listener.start
-      end
-      NewRelic::Control.instance.init_plugin({ :agent_enabled => true, :sync_startup => true }.merge(options))
+    def manual_start(options = {})
+      raise 'Options must be a hash' unless Hash === options
+
+      NewRelic::Control.instance.init_plugin({:agent_enabled => true, :sync_startup => true}.merge(options))
+      record_api_supportability_metric(:manual_start)
     end
 
     # Register this method as a callback for processes that fork
@@ -302,7 +519,7 @@ module NewRelic
     # jobs or other work.  If you are doing this with a web dispatcher
     # that forks worker processes then you will need to force the
     # agent to reconnect, which it won't do by default.  Passenger and
-    # Rainbows and Unicorn are already handled, nothing special needed for them.
+    # Unicorn are already handled, nothing special needed for them.
     #
     # Options:
     # * <tt>:force_reconnect => true</tt> to force the spawned process to
@@ -315,8 +532,10 @@ module NewRelic
     #
     # @api public
     #
-    def after_fork(options={})
-      agent.after_fork(options)
+    def after_fork(options = {})
+      record_api_supportability_metric(:after_fork)
+      # the following line needs else branch coverage
+      agent.after_fork(options) if agent # rubocop:disable Style/SafeNavigation
     end
 
     # Shutdown the agent.  Call this before exiting.  Sends any queued data
@@ -326,8 +545,9 @@ module NewRelic
     #
     # @api public
     #
-    def shutdown(options={})
-      agent.shutdown if agent
+    def shutdown(options = {})
+      record_api_supportability_metric(:shutdown)
+      agent&.shutdown
     end
 
     # Clear out any data the agent has buffered but has not yet transmitted
@@ -335,7 +555,9 @@ module NewRelic
     #
     # @api public
     def drop_buffered_data
-      agent.drop_buffered_data
+      # the following line needs else branch coverage
+      agent.drop_buffered_data if agent # rubocop:disable Style/SafeNavigation
+      record_api_supportability_metric(:drop_buffered_data)
     end
 
     # Add instrumentation files to the agent.  The argument should be
@@ -348,15 +570,16 @@ module NewRelic
     # @api public
     #
     def add_instrumentation(file_pattern)
-      NewRelic::Control.instance.add_instrumentation file_pattern
+      record_api_supportability_metric(:add_instrumentation)
+      NewRelic::Control.instance.add_instrumentation(file_pattern)
     end
 
     # Require agent testing helper methods
     #
     # @api public
     def require_test_helper
-      path = File.join(__FILE__, '..', '..', '..', 'test', 'agent_helper')
-      require File.expand_path(path)
+      record_api_supportability_metric(:require_test_helper)
+      require File.expand_path('../../../test/agent_helper', __FILE__)
     end
 
     # This method sets the block sent to this method as a sql
@@ -376,6 +599,7 @@ module NewRelic
     # @api public
     #
     def set_sql_obfuscator(type = :replace, &block)
+      record_api_supportability_metric(:set_sql_obfuscator)
       NewRelic::Agent::Database.set_sql_obfuscator(type, &block)
     end
 
@@ -390,8 +614,8 @@ module NewRelic
     # @api public
     #
     def ignore_transaction
-      txn = NewRelic::Agent::Transaction.tl_current
-      txn.ignore! if txn
+      record_api_supportability_metric(:ignore_transaction)
+      NewRelic::Agent::Transaction.tl_current&.ignore!
     end
 
     # This method disables the recording of Apdex metrics in the current
@@ -400,8 +624,8 @@ module NewRelic
     # @api public
     #
     def ignore_apdex
-      txn = NewRelic::Agent::Transaction.tl_current
-      txn.ignore_apdex! if txn
+      record_api_supportability_metric(:ignore_apdex)
+      NewRelic::Agent::Transaction.tl_current&.ignore_apdex!
     end
 
     # This method disables browser monitoring javascript injection in the
@@ -410,35 +634,27 @@ module NewRelic
     # @api public
     #
     def ignore_enduser
-      txn = NewRelic::Agent::Transaction.tl_current
-      txn.ignore_enduser! if txn
+      record_api_supportability_metric(:ignore_enduser)
+      NewRelic::Agent::Transaction.tl_current&.ignore_enduser!
     end
 
     # Yield to the block without collecting any metrics or traces in
     # any of the subsequent calls.  If executed recursively, will keep
     # track of the first entry point and turn on tracing again after
-    # leaving that block.  This uses the thread local TransactionState.
+    # leaving that block.  This uses the thread local Tracer::State.
     #
     # @api public
     #
     def disable_all_tracing
-      agent.push_trace_execution_flag(false)
-      yield
-    ensure
-      agent.pop_trace_execution_flag
-    end
+      record_api_supportability_metric(:disable_all_tracing)
+
+      return yield unless agent
 
-    # This method disables the recording of transaction traces in the given
-    # block.  See also #disable_all_tracing
-    #
-    # @api public
-    #
-    def disable_transaction_tracing
-      state = agent.set_record_tt(false)
       begin
+        agent.push_trace_execution_flag(false)
         yield
       ensure
-        agent.set_record_tt(state)
+        agent.pop_trace_execution_flag
       end
     end
 
@@ -454,6 +670,10 @@ module NewRelic
     # @api public
     #
     def disable_sql_recording
+      record_api_supportability_metric(:disable_sql_recording)
+
+      return yield unless agent
+
       state = agent.set_record_sql(false)
       begin
         yield
@@ -466,19 +686,7 @@ module NewRelic
 
     # Check to see if we are capturing metrics currently on this thread.
     def tl_is_execution_traced?
-      NewRelic::Agent::TransactionState.tl_get.is_execution_traced?
-    end
-
-    # helper method to check the thread local to determine whether the
-    # transaction in progress is traced or not
-    def tl_is_transaction_traced?
-      NewRelic::Agent::TransactionState.tl_get.is_transaction_traced?
-    end
-
-    # helper method to check the thread local to determine whether sql
-    # is being recorded or not
-    def tl_is_sql_recorded?
-      NewRelic::Agent::TransactionState.tl_get.is_sql_recorded?
+      NewRelic::Agent::Tracer.state.is_execution_traced?
     end
 
     # @!group Adding custom attributes to traces
@@ -491,15 +699,122 @@ module NewRelic
     # these custom attributes will also be present in the script injected into
     # the response body, making them available on Insights PageView events.
     #
+    #
+    # @param [Hash] params      A Hash of attributes to be attached to the transaction event.
+    #                           Keys should be strings or symbols, and values
+    #                           may be strings, symbols, numeric values or
+    #                           booleans.
+    #
     # @api public
     #
-    def add_custom_attributes(params) #THREAD_LOCAL_ACCESS
-      if params.is_a? Hash
-        txn = Transaction.tl_current
-        txn.add_custom_attributes(params) if txn
-      else
+    def add_custom_attributes(params) # THREAD_LOCAL_ACCESS
+      record_api_supportability_metric(:add_custom_attributes)
+
+      unless params.is_a?(Hash)
         ::NewRelic::Agent.logger.warn("Bad argument passed to #add_custom_attributes. Expected Hash but got #{params.class}")
+        return
+      end
+
+      if NewRelic::Agent.agent&.serverless?
+        ::NewRelic::Agent.logger.warn('Custom attributes are not supported in serverless mode')
+        return
+      end
+
+      Transaction.tl_current&.add_custom_attributes(params)
+      segment = ::NewRelic::Agent::Tracer.current_segment
+      add_new_segment_attributes(params, segment) if segment
+    end
+
+    def add_new_segment_attributes(params, segment)
+      # Make sure not to override existing segment-level custom attributes
+      segment_custom_keys = segment.attributes.custom_attributes.keys.map(&:to_sym)
+      segment.add_custom_attributes(params.reject do |k, _v|
+        segment_custom_keys.include?(k.to_sym) if k.respond_to?(:to_sym) # param keys can be integers
+      end)
+    end
+
+    # Add custom attributes to the span event for the current span. Attributes will be visible on spans in the
+    # New Relic Distributed Tracing UI and on span events in New Relic Insights.
+    #
+    # Custom attributes will not be transmitted when +high_security+ setting is enabled or
+    # +custom_attributes+ setting is disabled.
+    #
+    # @param [Hash] params      A Hash of attributes to be attached to the span event.
+    #                           Keys should be strings or symbols, and values
+    #                           may be strings, symbols, numeric values or
+    #                           booleans.
+    #
+    # @see https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/get-started/glossary#span
+    # @api public
+    def add_custom_span_attributes(params)
+      record_api_supportability_metric(:add_custom_span_attributes)
+
+      if params.is_a?(Hash)
+        if segment = NewRelic::Agent::Tracer.current_segment
+          segment.add_custom_attributes(params)
+        end
+      else
+        ::NewRelic::Agent.logger.warn("Bad argument passed to #add_custom_span_attributes. Expected Hash but got #{params.class}")
+      end
+    end
+
+    # Add global custom attributes to log events for the current agent instance. As these attributes are global to the
+    # agent instance, they will be attached to all log events generated by the agent, and this methods usage isn't
+    # suitable for setting dynamic values.
+    #
+    # @param [Hash] params    A Hash of attributes to attach to log
+    #                         events. The agent accepts up to 240 custom
+    #                         log event attributes.
+    #
+    #                         Keys will be coerced into Strings and must
+    #                         be less than 256 characters. Keys longer
+    #                         than 255 characters will be truncated.
+    #
+    #                         Values may be Strings, Symbols, numeric
+    #                         values or Booleans and must be less than
+    #                         4095 characters. If the value is a String
+    #                         or a Symbol, values longer than 4094
+    #                         characters will be truncated. If the value
+    #                         exceeds 4094 characters and is of a
+    #                         different class, the attribute pair will
+    #                         be dropped.
+    #
+    #                         This API can be called multiple times.
+    #                         If the same key is passed more than once,
+    #                         the value associated with the last call
+    #                         will be preserved.
+    #
+    #                         Attribute pairs with empty or nil contents
+    #                         will be dropped.
+    # @api public
+    def add_custom_log_attributes(params)
+      record_api_supportability_metric(:add_custom_log_attributes)
+
+      if params.is_a?(Hash)
+        NewRelic::Agent.agent.log_event_aggregator.add_custom_attributes(params)
+      else
+        NewRelic::Agent.logger.warn("Bad argument passed to #add_custom_log_attributes. Expected Hash but got #{params.class}.")
+      end
+    end
+
+    # Set the user id for the current transaction. When present, this value will be included in the agent attributes for transaction and error events as 'enduser.id'.
+    #
+    # @param [String] user_id    The user id to add to the current transaction attributes
+    #
+    # @api public
+    def set_user_id(user_id)
+      record_api_supportability_metric(:set_user_id)
+
+      if user_id.nil? || user_id.empty?
+        ::NewRelic::Agent.logger.warn('NewRelic::Agent.set_user_id called with a nil or empty user id.')
+        return
       end
+
+      default_destinations = NewRelic::Agent::AttributeFilter::DST_TRANSACTION_TRACER |
+        NewRelic::Agent::AttributeFilter::DST_TRANSACTION_EVENTS |
+        NewRelic::Agent::AttributeFilter::DST_ERROR_COLLECTOR
+
+      NewRelic::Agent::Transaction.add_agent_attribute(:'enduser.id', user_id, default_destinations)
     end
 
     # @!endgroup
@@ -510,7 +825,9 @@ module NewRelic
     # apply a reasonable default based on framework routing, but in
     # cases where this is insufficient, this can be used to manually
     # control the name of the transaction.
-    # The category of transaction can be specified via the +:category+ option:
+    #
+    # The category of transaction can be specified via the +:category+ option.
+    # The following are the only valid categories:
     #
     # * <tt>:category => :controller</tt> indicates that this is a
     #   controller action and will appear with all the other actions.
@@ -529,7 +846,8 @@ module NewRelic
     #
     # @api public
     #
-    def set_transaction_name(name, options={})
+    def set_transaction_name(name, options = {})
+      record_api_supportability_metric(:set_transaction_name)
       Transaction.set_overriding_transaction_name(name, options[:category])
     end
 
@@ -538,7 +856,9 @@ module NewRelic
     #
     # @api public
     #
-    def get_transaction_name #THREAD_LOCAL_ACCESS
+    def get_transaction_name # THREAD_LOCAL_ACCESS
+      record_api_supportability_metric(:get_transaction_name)
+
       txn = Transaction.tl_current
       if txn
         namer = Instrumentation::ControllerInstrumentation::TransactionNamer
@@ -550,16 +870,16 @@ module NewRelic
 
     # Yield to a block that is run with a database metric name context.  This means
     # the Database instrumentation will use this for the metric name if it does not
-    # otherwise know about a model.  This is re-entrant.
+    # otherwise know about a model.  This is reentrant.
     #
     # @param [String,Class,#to_s] model the DB model class
     #
     # @param [String] method the name of the finder method or other method to
     # identify the operation with.
     #
-    def with_database_metric_name(model, method = nil, &block) #THREAD_LOCAL_ACCESS
-      if txn = Transaction.tl_current
-        txn.with_database_metric_name(model, method, &block)
+    def with_database_metric_name(model, method = nil, product = nil, &block)
+      if txn = Tracer.current_transaction
+        txn.with_database_metric_name(model, method, product, &block)
       else
         yield
       end
@@ -568,17 +888,53 @@ module NewRelic
     # Subscribe to events of +event_type+, calling the given +handler+
     # when one is sent.
     def subscribe(event_type, &handler)
-      agent.events.subscribe( event_type, &handler )
+      agent.events.subscribe(event_type, &handler)
     end
 
     # Fire an event of the specified +event_type+, passing it an the given +args+
     # to any registered handlers.
     def notify(event_type, *args)
-      agent.events.notify( event_type, *args )
+      agent.events.notify(event_type, *args)
     rescue
-      NewRelic::Agent.logger.debug "Ignoring exception during %p event notification" % [event_type]
+      NewRelic::Agent.logger.debug('Ignoring exception during %p event notification' % [event_type])
+    end
+
+    # @!group Trace and Entity metadata
+
+    TRACE_ID_KEY = 'trace.id'.freeze
+    SPAN_ID_KEY = 'span.id'.freeze
+    ENTITY_NAME_KEY = 'entity.name'.freeze
+    ENTITY_TYPE_KEY = 'entity.type'.freeze
+    ENTITY_GUID_KEY = 'entity.guid'.freeze
+    HOSTNAME_KEY = 'hostname'.freeze
+
+    ENTITY_TYPE = 'SERVICE'.freeze
+
+    # Returns a new hash containing trace and entity metadata that can be used
+    # to relate data to a trace or to an entity in APM.
+    #
+    # This hash includes:
+    # * trace.id    - The current trace id, if there is a current trace id. This
+    #   value may be omitted.
+    # * span.id     - The current span id, if there is a current span.  This
+    #   value may be omitted.
+    # * entity.name - The name of the current application. This is read from
+    #   the +app_name+ key in your config.  If there are multiple application
+    #   names, the first one is used.
+    # * entity.type - The entity type is hardcoded to the string +'SERVICE'+.
+    # * entity.guid - The guid of the current entity.
+    # * hostname    - The fully qualified hostname.
+    #
+    # @api public
+    def linking_metadata
+      metadata = Hash.new
+      LinkingMetadata.append_service_linking_metadata(metadata)
+      LinkingMetadata.append_trace_linking_metadata(metadata)
+      metadata
     end
 
+    # @!endgroup
+
     # @!group Manual browser monitoring configuration
 
     # This method returns a string suitable for inclusion in a page - known as
@@ -593,106 +949,16 @@ module NewRelic
     # In previous agents there was a corresponding footer required, but all the
     # work is now done by this single method.
     #
-    # @api public
-    #
-    def browser_timing_header
-      agent.javascript_instrumentor.browser_timing_header
-    end
-
-    # @!endgroup
-
-    # @!group Deprecated methods
-
-    # In previous agent releases, this method was required for manual RUM
-    # instrumentation. That work is now all done by the browser_timing_header
-    # method, but this is left for compatibility.
-    #
-    # @api public
-    # @deprecated
-    #
-    def browser_timing_footer
-      ""
-    end
-
-    ADD_CUSTOM_ATTRIBUTES  = "NewRelic::Agent.add_custom_attributes".freeze
-    ADD_CUSTOM_PARAMETERS  = "NewRelic::Agent.add_custom_parameters".freeze
-    ADD_REQUEST_PARAMETERS = "NewRelic::Agent.add_request_parameters".freeze
-    SET_USER_ATTRIBUTES    = "NewRelic::Agent.set_user_attributes".freeze
-
-    # Deprecated. Use add_custom_attributes instead.
-    #
-    # @deprecated
-    # @api public
-    #
-    def add_custom_parameters(*args)
-      NewRelic::Agent::Deprecator.deprecate(ADD_CUSTOM_PARAMETERS, ADD_CUSTOM_ATTRIBUTES)
-      add_custom_attributes(*args)
-    end
-
-    # Deprecated. Use add_custom_attributes instead.
-    #
-    # @deprecated
-    # @api public
-    #
-    def add_request_parameters(*args)
-      NewRelic::Agent::Deprecator.deprecate(ADD_REQUEST_PARAMETERS, ADD_CUSTOM_ATTRIBUTES)
-      add_custom_attributes(*args)
-    end
-
-    # Deprecated. Use add_custom_attributes instead.
-    #
-    # @deprecated
-    # @api public
-    #
-    def set_user_attributes(*args)
-      NewRelic::Agent::Deprecator.deprecate(SET_USER_ATTRIBUTES, ADD_CUSTOM_ATTRIBUTES)
-      add_custom_attributes(*args)
-    end
-
-    # Get or create a statistics gatherer that will aggregate numerical data
-    # under a metric name.
-    #
-    # +metric_name+ should follow a slash separated path convention. Application
-    # specific metrics should begin with "Custom/".
-    #
-    # Return a NewRelic::Agent::Stats that accepts data
-    # via calls to add_data_point(value).
-    #
-    # This method is deprecated in favor of record_metric and increment_metric,
-    # and is not thread-safe.
+    # @param [String] nonce The nonce to use in the javascript tag for browser instrumentation
     #
     # @api public
-    # @deprecated
-    #
-    def get_stats(metric_name, use_scope=false)
-      agent.stats_engine.get_stats(metric_name, use_scope)
-    end
-
-    alias get_stats_no_scope get_stats
-
-    # Deprecated in favor of drop_buffered_data
     #
-    # @api public
-    # @deprecated
-    def reset_stats; drop_buffered_data; end
+    def browser_timing_header(nonce = nil)
+      record_api_supportability_metric(:browser_timing_header)
 
-    # Cancel the collection of the current transaction in progress, if
-    # any.  Only affects the transaction started on this thread once
-    # it has started and before it has completed.
-    #
-    # This method has been deprecated in favor of ignore_transaction,
-    # which does what people expect this method to do.
-    #
-    # @api public
-    # @deprecated
-    #
-    def abort_transaction!
-      Transaction.abort_transaction!
-    end
+      return EMPTY_STR unless agent
 
-    # Remove after 5/9/15
-    def record_transaction(*args)
-      NewRelic::Agent.logger.warn('This method has been deprecated, please see https://docs.newrelic.com/docs/ruby/ruby-agent-api for current API documentation.')
+      agent.javascript_instrumentor.browser_timing_header(nonce)
     end
 
     # @!endgroup