newrelic_rpm 6.3.0.355 → 9.2.0

data/lib/new_relic/agent/distributed_tracing/trace_context.rb

@@ -0,0 +1,245 @@
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
+
+require_relative 'trace_context_payload'
+
+module NewRelic
+  module Agent
+    module DistributedTracing
+      class TraceContext
+        VERSION = 0x0
+
+        COMMA = ','
+        EQUALS = '='
+        INVALID_TRACE_ID = ('0' * 32)
+        INVALID_PARENT_ID = ('0' * 16)
+        INVALID_VERSION = 'ff'
+
+        TRACE_ID_KEY = 'trace_id'
+        TRACE_FLAGS_KEY = 'trace_flags'
+        PARENT_ID_KEY = 'parent_id'
+        VERSION_KEY = 'version'
+        UNDEFINED_FIELDS_KEY = 'undefined_fields'
+
+        TP_VERSION = "(?<#{VERSION_KEY}>[a-f\\d]{2})"
+        TP_TRACE_ID = "(?<#{TRACE_ID_KEY}>[a-f\\d]{32})"
+        TP_PARENT_ID = "(?<#{PARENT_ID_KEY}>[a-f\\d]{16})"
+        TP_TRACE_FLAGS = "(?<#{TRACE_FLAGS_KEY}>\\d{2})"
+        TP_UNDEFINED_FIELDS = "(?<#{UNDEFINED_FIELDS_KEY}>-[a-zA-Z\\d-]*)"
+        TRACE_PARENT_REGEX = /\A#{TP_VERSION}-#{TP_TRACE_ID}-#{TP_PARENT_ID}-#{TP_TRACE_FLAGS}#{TP_UNDEFINED_FIELDS}?\z/
+
+        TRACE_PARENT_FORMAT_STRING = '%02x-%s-%s-%02x'
+
+        MAX_TRACE_STATE_SIZE = 512 # bytes
+        MAX_TRACE_STATE_ENTRY_SIZE = 128 # bytes
+
+        SUPPORTABILITY_TRACE_PARENT_PARSE_EXCEPTION = 'Supportability/TraceContext/TraceParent/Parse/Exception'
+        SUPPORTABILITY_TRACE_STATE_PARSE_EXCEPTION = 'Supportability/TraceContext/TraceState/Parse/Exception'
+        SUPPORTABILITY_TRACE_STATE_INVALID_NR_ENTRY = 'Supportability/TraceContext/TraceState/InvalidNrEntry'
+
+        class << self
+          def insert(format: NewRelic::FORMAT_NON_RACK,
+            carrier: nil,
+            parent_id: nil,
+            trace_id: nil,
+            trace_flags: nil,
+            trace_state: nil)
+
+            trace_parent_header = trace_parent_header_for_format(format)
+            carrier[trace_parent_header] = format_trace_parent( \
+              trace_id: trace_id,
+              parent_id: parent_id,
+              trace_flags: trace_flags
+            )
+
+            trace_state_header = trace_state_header_for_format(format)
+            carrier[trace_state_header] = trace_state if trace_state && !trace_state.empty?
+          end
+
+          def parse(format: NewRelic::FORMAT_NON_RACK,
+            carrier: nil,
+            trace_state_entry_key: nil)
+            trace_parent = extract_traceparent(format, carrier)
+            unless trace_parent_valid?(trace_parent)
+              NewRelic::Agent.increment_metric(SUPPORTABILITY_TRACE_PARENT_PARSE_EXCEPTION)
+              return nil
+            end
+
+            begin
+              if header_data = extract_tracestate(format, carrier, trace_state_entry_key)
+                header_data.trace_parent = trace_parent
+                header_data
+              end
+            rescue Exception
+              NewRelic::Agent.increment_metric(SUPPORTABILITY_TRACE_STATE_PARSE_EXCEPTION)
+              return nil
+            end
+          end
+
+          def create_trace_state_entry(entry_key, payload)
+            +"#{entry_key}=#{payload}"
+          end
+
+          private
+
+          def format_trace_parent(trace_id: nil,
+            parent_id: nil,
+            trace_flags: nil)
+            sprintf(TRACE_PARENT_FORMAT_STRING,
+              VERSION,
+              trace_id,
+              parent_id,
+              trace_flags)
+          end
+
+          def extract_traceparent(format, carrier)
+            header_name = trace_parent_header_for_format(format)
+            return unless header = carrier[header_name]
+
+            if matchdata = header.match(TRACE_PARENT_REGEX)
+              TRACE_PARENT_REGEX.named_captures.inject({}) do |hash, (name, (index))|
+                hash[name] = matchdata[index]
+                hash
+              end
+            end
+          end
+
+          def trace_parent_valid?(trace_parent)
+            return false if trace_parent.nil?
+            return false if trace_parent[TRACE_ID_KEY] == INVALID_TRACE_ID
+            return false if trace_parent[PARENT_ID_KEY] == INVALID_PARENT_ID
+            return false if trace_parent[VERSION_KEY] == INVALID_VERSION
+            return false if trace_parent[VERSION_KEY].to_i(16) == VERSION && !trace_parent[UNDEFINED_FIELDS_KEY].nil?
+
+            true
+          end
+
+          def trace_parent_header_for_format(format)
+            if format == NewRelic::FORMAT_RACK
+              NewRelic::HTTP_TRACEPARENT_KEY
+            else
+              NewRelic::TRACEPARENT_KEY
+            end
+          end
+
+          def trace_state_header_for_format(format)
+            if format == NewRelic::FORMAT_RACK
+              NewRelic::HTTP_TRACESTATE_KEY
+            else
+              NewRelic::TRACESTATE_KEY
+            end
+          end
+
+          def extract_tracestate(format, carrier, trace_state_entry_key)
+            header_name = trace_state_header_for_format(format)
+            header = carrier[header_name]
+            return HeaderData.create if header.nil? || header.empty?
+
+            payload = nil
+            trace_state_size = 0
+            trace_state_vendors = +''
+            trace_state = header.split(COMMA).map(&:strip)
+            trace_state.reject! do |entry|
+              if entry == NewRelic::EMPTY_STR
+                false
+              else
+                vendor_id = entry.slice(0, entry.index(EQUALS))
+                if vendor_id == trace_state_entry_key
+                  payload = entry.slice!(trace_state_entry_key.size + 1, entry.size)
+                  true
+                else
+                  trace_state_size += entry.size
+                  trace_state_vendors << vendor_id << COMMA
+                  false
+                end
+              end
+            end
+
+            trace_state_vendors.chomp!(COMMA)
+
+            HeaderData.create(trace_state_payload: payload ? decode_payload(payload) : nil,
+              trace_state_entries: trace_state,
+              trace_state_size: trace_state_size,
+              trace_state_vendors: trace_state_vendors)
+          end
+
+          def decode_payload(payload)
+            TraceContextPayload.from_s(payload)
+          rescue
+            if payload
+              NewRelic::Agent.increment_metric(SUPPORTABILITY_TRACE_STATE_INVALID_NR_ENTRY)
+            end
+            return nil
+          end
+        end
+
+        class HeaderData
+          class << self
+            def create(trace_parent: nil,
+              trace_state_payload: nil,
+              trace_state_entries: nil,
+              trace_state_size: 0,
+              trace_state_vendors: nil)
+              new(trace_parent, \
+                trace_state_payload, \
+                trace_state_entries, \
+                trace_state_size, \
+                trace_state_vendors)
+            end
+          end
+
+          def initialize(trace_parent, trace_state_payload, trace_state_entries, trace_state_size, trace_state_vendors)
+            @trace_parent = trace_parent
+            @trace_state = nil
+            @trace_state_entries = trace_state_entries
+            @trace_state_payload = trace_state_payload
+            @trace_state_size = trace_state_size
+            @trace_state_vendors = trace_state_vendors
+          end
+
+          attr_accessor :trace_parent, :trace_state_payload, :trace_state_vendors
+
+          def trace_state(trace_state_entry)
+            @trace_state ||= join_trace_state(trace_state_entry.size)
+            @trace_state_entries = nil
+
+            trace_state_entry = "#{trace_state_entry}#{@trace_state}"
+          end
+
+          def trace_id
+            @trace_parent[TRACE_ID_KEY]
+          end
+
+          def parent_id
+            @trace_parent[PARENT_ID_KEY]
+          end
+
+          private
+
+          def join_trace_state(trace_state_entry_size)
+            return @trace_state || NewRelic::EMPTY_STR if @trace_state_entries.nil? || @trace_state_entries.empty?
+
+            max_size = MAX_TRACE_STATE_SIZE - trace_state_entry_size
+            return @trace_state_entries.join(COMMA).prepend(COMMA) if @trace_state_size < max_size
+
+            joined_trace_state = +''
+
+            used_size = 0
+
+            @trace_state_entries.each do |entry|
+              entry_size = entry.size + 1
+              break if used_size + entry_size > max_size
+              next if entry_size > MAX_TRACE_STATE_ENTRY_SIZE
+
+              joined_trace_state << COMMA << entry
+              used_size += entry_size
+            end
+
+            joined_trace_state
+          end
+        end
+      end
+    end
+  end
+end

data/lib/new_relic/agent/distributed_tracing/trace_context_payload.rb

@@ -0,0 +1,127 @@
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
+
+require 'new_relic/coerce'
+
+module NewRelic
+  module Agent
+    class TraceContextPayload
+      VERSION = 0
+      PARENT_TYPE = 0
+      DELIMITER = '-'.freeze
+      SUPPORTABILITY_PARSE_EXCEPTION = 'Supportability/TraceContext/Parse/Exception'.freeze
+
+      TRUE_CHAR = '1'.freeze
+      FALSE_CHAR = '0'.freeze
+
+      PARENT_TYPES = %w[App Browser Mobile].map(&:freeze).freeze
+
+      class << self
+        def create(version: VERSION,
+          parent_type: PARENT_TYPE,
+          parent_account_id: nil,
+          parent_app_id: nil,
+          id: nil,
+          transaction_id: nil,
+          sampled: nil,
+          priority: nil,
+          timestamp: now_ms)
+
+          new(version, parent_type, parent_account_id, parent_app_id, id,
+            transaction_id, sampled, priority, timestamp)
+        end
+
+        include NewRelic::Coerce
+
+        def from_s(payload_string)
+          attrs = payload_string.split(DELIMITER)
+
+          payload = create( \
+            version: int!(attrs[0]),
+            parent_type: int!(attrs[1]),
+            parent_account_id: attrs[2],
+            parent_app_id: attrs[3],
+            id: value_or_nil(attrs[4]),
+            transaction_id: value_or_nil(attrs[5]),
+            sampled: value_or_nil(attrs[6]) ? boolean_int!(attrs[6]) == 1 : nil,
+            priority: float!(attrs[7]),
+            timestamp: int!(attrs[8])
+          )
+          handle_invalid_payload(message: 'payload missing attributes') unless payload.valid?
+          payload
+        rescue => e
+          handle_invalid_payload(error: e)
+          raise
+        end
+
+        private
+
+        def now_ms
+          Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+        end
+
+        def handle_invalid_payload(error: nil, message: nil)
+          NewRelic::Agent.increment_metric(SUPPORTABILITY_PARSE_EXCEPTION)
+          if error
+            NewRelic::Agent.logger.warn('Error parsing trace context payload', error)
+          elsif message
+            NewRelic::Agent.logger.warn("Error parsing trace context payload: #{message}")
+          end
+        end
+      end
+
+      attr_accessor :version,
+        :parent_type_id,
+        :parent_account_id,
+        :parent_app_id,
+        :id,
+        :transaction_id,
+        :sampled,
+        :priority,
+        :timestamp
+
+      alias_method :sampled?, :sampled
+
+      def initialize(version, parent_type_id, parent_account_id, parent_app_id,
+        id, transaction_id, sampled, priority, timestamp)
+        @version = version
+        @parent_type_id = parent_type_id
+        @parent_account_id = parent_account_id
+        @parent_app_id = parent_app_id
+        @id = id
+        @transaction_id = transaction_id
+        @sampled = sampled
+        @priority = priority
+        @timestamp = timestamp
+      end
+
+      def parent_type
+        @parent_type_string ||= PARENT_TYPES[@parent_type_id]
+      end
+
+      def valid?
+        version \
+          && parent_type_id \
+          && !parent_account_id.empty? \
+          && !parent_app_id.empty? \
+          && timestamp
+      rescue
+        false
+      end
+
+      def to_s
+        result = version.to_s # required
+        result << DELIMITER << parent_type_id.to_s # required
+        result << DELIMITER << parent_account_id # required
+        result << DELIMITER << parent_app_id # required
+        result << DELIMITER << (id || NewRelic::EMPTY_STR)
+        result << DELIMITER << (transaction_id || NewRelic::EMPTY_STR)
+        result << DELIMITER << (sampled ? TRUE_CHAR : FALSE_CHAR)
+        result << DELIMITER << sprintf('%.6f', priority)
+        result << DELIMITER << timestamp.to_s # required
+        result
+      end
+    end
+  end
+end

data/lib/new_relic/agent/distributed_tracing.rb

@@ -1,8 +1,14 @@
-# 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 'new_relic/agent/distributed_trace_payload'
+require_relative 'distributed_tracing/cross_app_payload'
+require_relative 'distributed_tracing/cross_app_tracing'
+
+require_relative 'distributed_tracing/distributed_trace_transport_type'
+require_relative 'distributed_tracing/distributed_trace_payload'
+
+require_relative 'distributed_tracing/trace_context'
 
 module NewRelic
   module Agent
@@ -14,54 +20,129 @@ module NewRelic
     #
     # @api public
     module DistributedTracing
+      extend NewRelic::SupportabilityHelper
       extend self
 
-      # Create a payload object containing the current transaction's
-      # tracing properties (e.g., duration, priority).  You can use
-      # this object to generate headers to inject into a network
-      # request, so that the downstream service can participate in a
-      # distributed trace.
+      # Adds the Distributed Trace headers so that the downstream service can participate in a
+      # distributed trace. This method should be called every time an outbound call is made
+      # since the header payload contains a timestamp.
+      #
+      # Distributed Tracing must be enabled to use this method.
+      #
+      # +insert_distributed_trace_headers+ always inserts W3C trace context headers and inserts
+      # New Relic distributed tracing header by default. New Relic headers may be suppressed by
+      # setting +exclude_new_relic_header+ to +true+ in your configuration file.
       #
-      # @return [DistributedTracePayload] Payload for the current
-      #                                   transaction, or +nil+ if we
-      #                                   could not create the payload
+      # @param headers           [Hash]     Is a Hash to which the distributed trace headers
+      #                                     will be inserted.
+      #
+      # @return           {Transaction}     The transaction the headers were inserted from,
+      #                                     or +nil+ if headers were not inserted.
       #
       # @api public
-      def create_distributed_trace_payload
-        if transaction = Transaction.tl_current
-          transaction.create_distributed_trace_payload
+      #
+      def insert_distributed_trace_headers(headers = {})
+        record_api_supportability_metric(:insert_distributed_trace_headers)
+
+        unless Agent.config[:'distributed_tracing.enabled']
+          NewRelic::Agent.logger.warn('Not configured to insert distributed trace headers')
+          return nil
         end
+
+        return unless valid_api_argument_class?(headers, 'headers', Hash)
+
+        return unless transaction = Transaction.tl_current
+
+        transaction.distributed_tracer.insert_headers(headers)
+        transaction
       rescue => e
-        NewRelic::Agent.logger.error 'error during create_distributed_trace_payload', e
+        NewRelic::Agent.logger.error('error during insert_distributed_trace_headers', e)
         nil
       end
 
-      # Decode a JSON string containing distributed trace properties
-      # (e.g., calling application, priority) and apply them to the
-      # current transaction.  You can use it to receive distributed
-      # tracing information protocols the agent does not already
-      # support.
+      # Accepts distributed tracing headers from any source that has been packaged
+      # as a Ruby Hash, thereby allowing the user to manually inject distributed
+      # tracing headers.  It is optimized to process +HTTP_TRACEPARENT+, +HTTP_TRACESTATE+,
+      # and +HTTP_NEWRELIC+ as the given Hash keys.  which is the most common scenario
+      # from Rack middleware in most Ruby applications.  However, the Hash keys are
+      # case-insensitive and the "HTTP_" prefixes may also be omitted.
+      #
+      # Calling this method is not necessary in a typical HTTP trace as
+      # distributed tracing is already handled by the agent.
+      #
+      # When used, invoke this method as early as possible in a transaction's life-cycle
+      # as calling after the headers are already created will have no effect.
+      #
+      # This method accepts both W3C trace context and New Relic distributed tracing headers.
+      # When both are present, only the W3C headers are utilized.  When W3C trace context
+      # headers are present, New Relic headers are ignored regardless if W3C trace context
+      # headers are valid and parsable.
+      #
+      # @param headers         [Hash]     Incoming distributed trace headers as a Ruby
+      #                                   Hash object.  Hash keys are expected to be one of
+      #                                   +TRACEPARENT+, +TRACESTATE+, +NEWRELIC+ and are
+      #                                   case-insensitive, with or without "HTTP_" prefixes.
       #
-      # This method will fail if you call it after calling
-      # {#create_distributed_trace_payload}.
+      #                                   either as a JSON string or as a
+      #                                   header-friendly string returned from
+      #                                   {DistributedTracePayload#http_safe}
       #
-      # @param payload [String] Incoming distributed trace payload,
-      #                         either as a JSON string or as a
-      #                         header-friendly string returned from
-      #                         {DistributedTracePayload#http_safe}
+      # @param transport_Type  [String]   May be one of:  +HTTP+, +HTTPS+, +Kafka+, +JMS+,
+      #                                   +IronMQ+, +AMQP+, +Queue+, +Other+.  Values are
+      #                                   case sensitive.  All other values result in +Unknown+
       #
-      # @return nil
+      # @return {Transaction} if successful, +nil+ otherwise
       #
       # @api public
-      def accept_distributed_trace_payload payload
-        if transaction = Transaction.tl_current
-          transaction.accept_distributed_trace_payload(payload)
+      #
+      def accept_distributed_trace_headers(headers, transport_type = NewRelic::HTTP)
+        record_api_supportability_metric(:accept_distributed_trace_headers)
+
+        unless Agent.config[:'distributed_tracing.enabled']
+          NewRelic::Agent.logger.warn('Not configured to accept distributed trace headers')
+          return nil
         end
-        nil
+
+        return unless valid_api_argument_class?(headers, 'headers', Hash)
+        return unless valid_api_argument_class?(transport_type, 'transport_type', String)
+
+        return unless transaction = Transaction.tl_current
+
+        # assume we have Rack conforming keys when transport_type is HTTP(S)
+        # otherwise, fish for key/value pairs regardless of prefix and case-sensitivity.
+        hdr = if transport_type.start_with?(NewRelic::HTTP)
+          headers
+        else
+          # start with the most common case first
+          hdr = {
+            NewRelic::HTTP_TRACEPARENT_KEY => headers[NewRelic::TRACEPARENT_KEY],
+            NewRelic::HTTP_TRACESTATE_KEY => headers[NewRelic::TRACESTATE_KEY],
+            NewRelic::HTTP_NEWRELIC_KEY => headers[NewRelic::NEWRELIC_KEY]
+          }
+
+          # when not found, search for any casing for trace context headers, ignoring potential prefixes
+          hdr[NewRelic::HTTP_TRACEPARENT_KEY] ||= variant_key_value(headers, NewRelic::TRACEPARENT_KEY)
+          hdr[NewRelic::HTTP_TRACESTATE_KEY] ||= variant_key_value(headers, NewRelic::TRACESTATE_KEY)
+          hdr[NewRelic::HTTP_NEWRELIC_KEY] ||= variant_key_value(headers, NewRelic::CANDIDATE_NEWRELIC_KEYS)
+          hdr
+        end
+
+        transaction.distributed_tracer.accept_incoming_request(hdr, transport_type)
+        transaction
       rescue => e
-        NewRelic::Agent.logger.error 'error during accept_distributed_trace_payload', e
+        NewRelic::Agent.logger.error('error during accept_distributed_trace_headers', e)
         nil
       end
+
+      private
+
+      def has_variant_key?(key, variants)
+        key.to_s.downcase.end_with?(*Array(variants))
+      end
+
+      def variant_key_value(headers, variants)
+        (headers.detect { |k, v| has_variant_key?(k, variants) } || NewRelic::EMPTY_ARRAY)[1]
+      end
     end
   end
 end

data/lib/new_relic/agent/encoding_normalizer.rb

@@ -1,6 +1,6 @@
-# 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
 
 # This module was extracted from NewRelic::JSONWrapper
 
@@ -19,12 +19,14 @@ module NewRelic
           normalize_string(object.to_s)
         when Array
           return object if object.empty?
+
           object.map { |x| normalize_object(x) }
         when Hash
           return object if object.empty?
+
           hash = {}
           object.each_pair do |k, v|
-            k = normalize_string(k)      if k.is_a?(String)
+            k = normalize_string(k) if k.is_a?(String)
             k = normalize_string(k.to_s) if k.is_a?(Symbol)
             hash[k] = normalize_object(v)
           end