newrelic-telemetry_sdk 0.1.0

data/lib/newrelic/telemetry_sdk/clients/trace_client.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+# frozen_string_literal: true
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-telemetry-sdk-ruby/blob/main/LICENSE for complete details.
+
+require_relative 'client'
+
+module NewRelic
+  module TelemetrySdk
+    # The {TraceClient} sends {Span} data to the Trace API host endpoint.
+    #
+    # @example
+    #   trace_client = NewRelic::TelemetrySdk::TraceClient.new
+    #   
+    #   span = NewRelic::TelemetrySdk::Span.new(
+    #     id: random_id(16),
+    #     trace_id: random_id(32),
+    #     start_time: Time.now,
+    #     name: "Net::HTTP#get"
+    #   )
+    #   trace_client.report span
+    #
+    class TraceClient < Client
+      def initialize host: trace_api_host
+        super host: host,
+              path: '/trace/v1',
+              headers: {
+                :'Content-Type' => 'application/json',
+                :'Api-Key' => api_insert_key,
+                :'Data-Format' => 'newrelic',
+                :'Data-Format-Version' => '1'
+              },
+              payload_type: :spans
+      end
+
+      private 
+      
+      def trace_api_host
+        TelemetrySdk.config.trace_api_host
+      end
+    end
+  end
+end

data/lib/newrelic/telemetry_sdk/config.rb

@@ -0,0 +1,97 @@
+# encoding: utf-8
+# frozen_string_literal: true
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-telemetry-sdk-ruby/blob/main/LICENSE for complete details.
+
+module NewRelic
+  module TelemetrySdk
+    
+    # This class allows setting configuration options for the Telemetry SDK
+    # via NewRelic::TelemetrySdk.configure.
+    #
+    # @example Setting the API Key
+    #   NewRelic::TelemetrySdk.configure do |config|
+    #     config.api_insert_key = ENV["API_KEY"]
+    #   end
+    #
+    # @api public
+    class Config
+
+      # Default host for the Trace Client
+      DEFAULT_TRACE_API_HOST = "https://trace-api.newrelic.com"
+
+      # Default harvest interval in seconds
+      DEFAULT_HARVEST_INTERVAL = 5
+
+      # Default backoff strategy factorial
+      DEFAULT_BACKOFF_FACTOR = 5
+
+      # Default maximum backoff wait time in seconds
+      DEFAULT_BACKOFF_MAX = 80
+
+      # Default number of retries to send same data
+      DEFAULT_MAX_RETRIES = 8
+
+      # @!attribute api_insert_key [optional, String]
+      # A New Relic Insert API key. Necessary for sending data to
+      # New Relic via the Telemetry SDK. Defaults to +API_INSERT_KEY+
+      # environment variable.
+      # @see https://docs.newrelic.com/docs/apis/get-started/intro-apis/types-new-relic-api-keys#event-insert-key Types of New Relic API keys: Insert API key
+      attr_accessor :api_insert_key
+
+      # @!attribute logger [optional, Logger]
+      # A Logger object customized with your preferred log output
+      # destination (if any) and log level.
+      attr_accessor :logger
+
+      # @!attribute audit_logging_enabled [optional, Boolean]
+      # If audit logging is enabled, the contents of every payload
+      # sent to New Relic will be recorded in logs.
+      # This is a very verbose log level for debugging purposes.
+      attr_accessor :audit_logging_enabled
+
+      # @!attribute harvest_interval [optional, Integer]
+      # The frequency of automatic harvest (in seconds) if sending data
+      # with a harvester.
+      # Defaults to {DEFAULT_HARVEST_INTERVAL} seconds.
+      attr_accessor :harvest_interval
+
+      # @!attribute backoff_factor [optional, Integer]
+      # The amount of time (in seconds) to wait after sending data
+      # to New Relic fails before attempting to send again.
+      # Defaults to {DEFAULT_HARVEST_INTERVAL} seconds.
+      attr_accessor :backoff_factor
+
+      # @!attribute backoff_max [optional, Integer]
+      # If data cannot be sent to New Relic intermittently, the SDK will
+      # retry the request at increasing intervals, but will stop increasing
+      # the retry intervals when they have reached +backoff_max+ seconds.
+      # Defaults to {DEFAULT_BACKOFF_MAX} seconds.
+      # @see https://github.com/newrelic/newrelic-telemetry-sdk-specs/blob/master/communication.md#graceful-degradation Graceful Degradation
+      attr_accessor :backoff_max
+
+      # @!attribute max_retries [optional, Integer]
+      # The maximum number of times to retry sending data to New Relic.
+      # Defaults to {DEFAULT_MAX_RETRIES}.
+      attr_accessor :max_retries
+
+      # @!attribute trace_api_host [optional, String]
+      # An alternative New Relic host URL where spans can be sent.
+      # Defaults to {DEFAULT_TRACE_API_HOST}
+      attr_accessor :trace_api_host
+
+      # @api private
+      def initialize
+        @api_insert_key = ENV[API_INSERT_KEY]
+        @logger = Logger.logger
+        @audit_logging_enabled = false
+
+        @harvest_interval = DEFAULT_HARVEST_INTERVAL
+        @backoff_factor = DEFAULT_BACKOFF_FACTOR
+        @backoff_max = DEFAULT_BACKOFF_MAX
+        @max_retries = DEFAULT_MAX_RETRIES
+        @trace_api_host = DEFAULT_TRACE_API_HOST
+      end
+    end
+  end
+end

data/lib/newrelic/telemetry_sdk/configurator.rb

@@ -0,0 +1,95 @@
+# encoding: utf-8
+# frozen_string_literal: true
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-telemetry-sdk-ruby/blob/main/LICENSE for complete details.
+
+module NewRelic
+  module TelemetrySdk
+    # The {Configurator} provides the mechanism through which the SDK is configured.
+    # 
+    # @example
+    #   NewRelic::TelemetrySdk.configure do |config|
+    #     config.api_insert_key = ENV["API_KEY"]
+    #   end
+    #
+    # See {Config} for details on what properties can be configured.
+    #
+    # @api public
+    class Configurator
+      def self.config
+        @config ||= Config.new
+      end
+
+      # Removes any configurations that were previously customized, effectively
+      # resetting the {Config} state to defaults
+      #
+      # @api private
+      def self.reset
+        @config = nil
+      end
+
+      # Allows direct access to the config state.  The primary purpose of this method is
+      # to access config properties throughout the SDK.
+      #
+      # @note Unlike configuring with # {#self.configure}, setting config properties here 
+      #       may, or may not become immediately active.  Use with care.
+      #
+      # @api public
+      def config
+        Configurator.config
+      end
+
+      # Set Telemetry SDK configuration with a block.
+      # See {Config} for options.
+      #
+      # @example Setting the API Key
+      #   NewRelic::TelemetrySdk.configure do |config|
+      #     config.api_insert_key = ENV["API_KEY"]
+      #   end
+      #
+      # @api public
+      def configure
+        Logger.logger = config.logger
+      end
+
+      private
+
+      # Delegates any setter methods to the Config object if it responds to such.
+      # All other missing methods are propagated up the chain.
+      def method_missing method, *args, &block
+        if method.to_s =~ /\=$/ && config.respond_to?(method)
+          config.send method, *args, &block
+        else
+          super
+        end
+      end
+    end
+
+    # Set Telemetry SDK configuration with a block.
+    # See {Config} for options.
+    #
+    #
+    # @example Setting the API Key
+    #   NewRelic::TelemetrySdk.configure do |config|
+    #     config.api_insert_key = ENV["API_KEY"]
+    #   end
+    #
+    # @api public
+    def self.configure
+      configurator = Configurator.new
+      yield configurator if block_given?
+      configurator.configure
+    end
+
+    # Allows direct access to the config state.  The primary purpose of this method is
+    # to access config properties throughout the SDK.
+    #
+    # @note Unlike configuring with # {#self.configure}, setting config properties here 
+    #       may, or may not become immediately active.  Use with care.
+    #
+    # @api public
+    def self.config
+      Configurator.config
+    end
+  end
+end

data/lib/newrelic/telemetry_sdk/exception.rb

@@ -0,0 +1,14 @@
+# encoding: utf-8
+# frozen_string_literal: true
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-telemetry-sdk-ruby/blob/main/LICENSE for complete details.
+
+module NewRelic
+  module TelemetrySdk
+    # A {RetriableServerResponseException} is used to signal that the SDK
+    # should attempt to resend the data that received a response error
+    # from the server on the previous attempt.
+    # @private
+    class RetriableServerResponseException < StandardError; end
+  end
+end

data/lib/newrelic/telemetry_sdk/harvester.rb

@@ -0,0 +1,117 @@
+# encoding: utf-8
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-telemetry-sdk-ruby/blob/main/LICENSE for complete details.
+
+module NewRelic
+  module TelemetrySdk
+    # This class handles sending data to New Relic automatically at configured
+    # intervals.
+    #
+    # @example
+    #   harvester = NewRelic::TelemetrySdk::Harvester.new 
+    #   trace_client = NewRelic::TelemetrySdk::TraceClient.new
+    #   buffer = NewRelic::TelemetrySdk::Buffer.new
+    #   harvester.register 'external_spans', buffer, trace_client
+    #   harvester.start
+    #
+    # @api public
+    class Harvester
+      include NewRelic::TelemetrySdk::Logger
+
+      def initialize
+        @pipelines = {}
+        @shutdown = false
+        @running = false
+        @lock = Mutex.new
+      end
+
+      # Register a pipeline (i.e. a buffer from which data can be harvested
+      # via a +flush+ method and a client that can be used to send that data).
+      # @param name [String]
+      #     A unique name for the type of data associated with this pipeline.
+      #     Examples: 'spans', 'external_spans'
+      # @param buffer [Buffer]
+      #     An instance of NewRelic::TelemetrySdk::Buffer in which data can be
+      #     stored for harvest.
+      # @param client [Client]
+      #     An instance of a NewRelic::TelemetrySdk::Client subclass which will
+      #     send harvested data to the correct New Relic backend (e.g. TraceClient
+      #     for spans).
+      #
+      # @api public
+      def register name, buffer, client
+        logger.info "Registering pipeline #{name}"
+        @lock.synchronize do
+          @pipelines[name] = {
+            buffer: buffer,
+            client: client
+          }
+        end
+      rescue => e
+        log_error "Encountered error while registering buffer #{name}.", e
+      end
+
+      def [] name
+        @pipelines[name]
+      end
+
+      def interval
+        TelemetrySdk.config.harvest_interval
+      end
+
+      def running?
+        @running
+      end
+
+      # Start scheduled harvests via this harvester.
+      #
+      # @api public
+      def start
+        logger.info "Harvesting every #{interval} seconds"
+        @running = true
+        @harvest_thread = Thread.new do
+          begin
+            while !@shutdown do
+              sleep interval
+              harvest
+            end
+            harvest
+            @running = false
+          rescue => e
+            log_error "Encountered error in harvester", e
+          end
+        end
+      end
+
+      # Stop scheduled harvests via this harvester. Any remaining
+      # buffered data will be sent before the harvest thread is stopped.
+      #
+      # @api public
+      def stop
+        logger.info "Stopping harvester"
+        @shutdown = true
+        @harvest_thread.join if @running
+      rescue => e
+        log_error "Encountered error stopping harvester", e
+      end
+
+    private
+
+      def harvest
+        @lock.synchronize do
+          @pipelines.values.each do |pipeline|
+            send_data_via pipeline
+          end
+        end
+      end
+
+      def send_data_via pipeline
+        batch = pipeline[:buffer].flush
+        if !batch.nil? && batch[0].respond_to?(:any?) && batch[0].any?
+          pipeline[:client].report_batch batch
+        end
+      end
+
+    end
+  end
+end

data/lib/newrelic/telemetry_sdk/logger.rb

@@ -0,0 +1,90 @@
+# encoding: utf-8
+# frozen_string_literal: true
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-telemetry-sdk-ruby/blob/main/LICENSE for complete details.
+
+module NewRelic
+  module TelemetrySdk
+    # The Logger Singleton object manages the logger for the SDK and is fully configurable by the user.  
+    # Any Ruby class that responds to the common methods of the Ruby standard {::Logger} class can
+    # be configured for the SDk.
+    # 
+    # The logger may be configured like this:
+    # @example with configure block
+    #   require 'logger'
+    #
+    #   logger = ::Logger.new(STDOUT)
+    #   logger.level = Logger::WARN
+    #
+    #   NewRelic::TelemetrySdk.configure do |config|
+    #     config.logger = logger
+    #   end
+    #
+    # @example without configure block
+    #   require 'logger'
+    #   
+    #   NewRelic::TelemetrySdk.logger = ::Logger.new("/dev/null")
+    #
+    # @api public
+    module Logger
+      LOG_LEVELS = %w{debug info warn error fatal}
+      private_constant :LOG_LEVELS
+      
+      LOG_LEVELS.each do |level|
+        define_method "log_#{level}_once" do |key, *msgs|
+          log_once level, key, *msgs
+        end
+      end
+
+      def self.logger= logger
+        @logger = logger
+      end
+    
+      def self.logger
+        @logger ||= ::Logger.new(STDOUT)
+      end
+    
+      def log_once(level, key, *msgs)
+        logger_mutex.synchronize do
+          return if already_logged.include?(key)
+          already_logged[key] = true
+        end
+
+        logger.send(level, *msgs)
+      end
+
+      def clear_already_logged
+        logger_mutex.synchronize do
+          @already_logged = {}
+        end
+      end
+
+      def log_error(message, exception = nil)
+        logger.error message
+        logger.error exception if exception
+      end
+
+      def logger
+        Logger.logger
+      end
+      
+      def logger= logger
+        Logger.logger = logger
+      end
+
+      private
+
+      def logger_mutex
+        @logger_mutex ||= Mutex.new
+      end
+
+      def already_logged
+        @already_logged ||= {}
+      end
+    end
+
+    def self.logger
+      Logger.logger
+    end
+  end
+end