solarwinds_apm 5.0.0

data/lib/solarwinds_apm/oboe_init_options.rb

@@ -0,0 +1,191 @@
+# Copyright (c) 2019 SolarWinds, LLC.
+# All rights reserved.
+
+require 'singleton'
+
+module SolarWindsAPM
+
+  class OboeInitOptions
+    include Singleton
+
+    attr_reader :reporter, :host, :service_name, :ec2_md_timeout, :grpc_proxy # exposing these mainly for testing
+
+    def initialize
+      # optional hostname alias
+      @hostname_alias = ENV['SW_APM_HOSTNAME_ALIAS'] || SolarWindsAPM::Config[:hostname_alias] || ''
+      # level at which log messages will be written to log file (0-6)
+      @debug_level = (ENV['SW_APM_DEBUG_LEVEL'] || SolarWindsAPM::Config[:debug_level] || 3).to_i
+      # file name including path for log file
+      # TODO eventually find better way to combine ruby and oboe logs
+      @log_file_path = ENV['SW_APM_LOGFILE'] || ''
+      # maximum number of transaction names to track
+      @max_transactions = (ENV['SW_APM_MAX_TRANSACTIONS'] || -1).to_i
+      # maximum wait time for flushing data before terminating in milli seconds
+      @max_flush_wait_time = (ENV['SW_APM_FLUSH_MAX_WAIT_TIME'] || -1).to_i
+      # events flush timeout in seconds (threshold for batching messages before sending off)
+      @events_flush_interval = (ENV['SW_APM_EVENTS_FLUSH_INTERVAL'] || -1).to_i
+      # events flush batch size in KB (threshold for batching messages before sending off)
+      @event_flush_batch_size = (ENV['SW_APM_EVENTS_FLUSH_BATCH_SIZE'] || -1).to_i
+
+      # the reporter to be used (ssl, upd, file, null)
+      # collector endpoint (reporter=ssl), udp address (reporter=udp), or file path (reporter=file)
+      @reporter, @host = reporter_and_host
+
+      # the service key
+      @service_key = read_and_validate_service_key
+      # path to the SSL certificate (only for ssl)
+      @trusted_path = ENV['SW_APM_TRUSTEDPATH'] || ''
+      # size of the message buffer
+      @buffer_size = (ENV['SW_APM_BUFSIZE'] || -1).to_i
+      # flag indicating if trace metrics reporting should be enabled (default) or disabled
+      @trace_metrics = (ENV['SW_APM_TRACE_METRICS'] || -1).to_i
+      # the histogram precision (only for ssl)
+      @histogram_precision = (ENV['SW_APM_HISTOGRAM_PRECISION'] || -1).to_i
+      # custom token bucket capacity
+      @token_bucket_capacity = (ENV['SW_APM_TOKEN_BUCKET_CAPACITY'] || -1).to_i
+      # custom token bucket rate
+      @token_bucket_rate = (ENV['SW_APM_TOKEN_BUCKET_RATE'] || -1).to_i
+      # use single files in file reporter for each event
+      @file_single = (ENV['SW_APM_REPORTER_FILE_SINGLE'].to_s.downcase == 'true') ? 1 : 0
+      # timeout for ec2 metadata
+      @ec2_md_timeout = read_and_validate_ec2_md_timeout
+      @grpc_proxy = read_and_validate_proxy
+      # hardcoded arg for lambda (lambda not supported yet)
+      # hardcoded arg for grpc hack
+      # hardcoded arg for trace id format to use w3c format
+    end
+
+    def re_init # for testing with changed ENV vars
+      initialize
+    end
+
+    def array_for_oboe
+      [
+        @hostname_alias,         # 0
+        @debug_level,            # 1
+        @log_file_path,          # 2
+        @max_transactions,       # 3
+        @max_flush_wait_time,    # 4
+        @events_flush_interval,  # 5
+        @event_flush_batch_size, # 6
+
+        @reporter,               # 7
+        @host,                   # 8
+        @service_key,            # 9
+        @trusted_path,           #10
+        @buffer_size,            #11
+        @trace_metrics,          #12
+        @histogram_precision,    #13
+        @token_bucket_capacity,  #14
+        @token_bucket_rate,      #15
+        @file_single,            #16
+        @ec2_md_timeout,         #17
+        @grpc_proxy,             #18
+        0,                       #19 arg for lambda (no lambda for ruby yet)
+        1,                       #20 arg for grpc hack, hardcoded to include hack
+        1                        #21 arg for trace id format to use w3c format
+      ]
+    end
+
+    def service_key_ok?
+      return !@service_key.empty? || @reporter != 'ssl'
+    end
+
+    private
+
+    def reporter_and_host
+
+      reporter = ENV['SW_APM_REPORTER'] || 'ssl'
+      # override with 'file', e.g. when running tests
+      # changed my mind => set the right reporter in the env when running tests !!!
+      # reporter = 'file' if ENV.key?('SW_APM_GEM_TEST')
+
+      host = ''
+      case reporter
+      when 'ssl', 'file'
+        host = ENV['SW_APM_COLLECTOR'] || ''
+      when 'udp'
+        host = ENV['SW_APM_COLLECTOR'] ||
+                "#{SolarWindsAPM::Config[:reporter_host]}:#{SolarWindsAPM::Config[:reporter_port]}"
+        # TODO decide what to do
+        # ____ SolarWindsAPM::Config[:reporter_host] and
+        # ____ SolarWindsAPM::Config[:reporter_port] were moved here from
+        # ____ oboe_metal.rb and are not documented anywhere
+        # ____ udp is for internal use only
+      when 'null'
+        host = ''
+      end
+
+      [reporter, host]
+    end
+
+    def read_and_validate_service_key
+      return '' unless @reporter == 'ssl'
+
+      service_key = ENV['SW_APM_SERVICE_KEY'] || SolarWindsAPM::Config[:service_key]
+      unless service_key
+        SolarWindsAPM.logger.error "[solarwinds_apm/oboe_options] SW_APM_SERVICE_KEY not configured."
+        return ''
+      end
+
+      match = service_key.match( /([^:]+)(:{0,1})(.*)/ )
+      token = match[1]
+      service_name = match[3]
+
+      return '' unless validate_token(token)
+      return '' unless validate_transform_service_name(service_name)
+
+      return "#{token}:#{service_name}"
+    end
+
+    def validate_token(token)
+      if (token !~ /^[0-9a-zA-Z_-]{71}$/) && ENV['SW_APM_COLLECTOR'] !~ /java-collector:1222/
+        masked = "#{token[0..3]}...#{token[-4..-1]}"
+        SolarWindsAPM.logger.error "[solarwinds_apm/oboe_options] SW_APM_SERVICE_KEY problem. API Token in wrong format. Masked token: #{masked}"
+        return false
+      end
+
+      true
+    end
+
+    def validate_transform_service_name(service_name)
+      service_name = 'test_ssl_collector' if ENV['SW_APM_COLLECTOR'] =~ /java-collector:1222/
+      if service_name.empty?
+        SolarWindsAPM.logger.error "[solarwinds_apm/oboe_options] SW_APM_SERVICE_KEY problem. Service Name is missing"
+        return false
+      end
+
+      name = service_name.dup
+      name.downcase!
+      name.gsub!(/[^a-z0-9.:_-]/, '')
+      name = name[0..254]
+
+      if name != service_name
+        SolarWindsAPM.logger.warn "[solarwinds_apm/oboe_options] SW_APM_SERVICE_KEY problem. Service Name transformed from #{service_name} to #{name}"
+        service_name = name
+      end
+      @service_name = service_name # instance variable used in testing
+      true
+    end
+
+    def read_and_validate_ec2_md_timeout
+      timeout = ENV['SW_APM_EC2_METADATA_TIMEOUT'] || SolarWindsAPM::Config[:ec2_metadata_timeout]
+      return 1000 unless timeout.is_a?(Integer) || timeout =~ /^\d+$/
+      timeout = timeout.to_i
+      return timeout.between?(0, 3000) ? timeout : 1000
+    end
+
+    def read_and_validate_proxy
+      proxy = ENV['SW_APM_PROXY'] || SolarWindsAPM::Config[:http_proxy] || ''
+      return proxy if proxy == ''
+
+      unless proxy =~ /http:\/\/.*:\d+$/
+        SolarWindsAPM.logger.error "[solarwinds_apm/oboe_options] SW_APM_PROXY/http_proxy doesn't start with 'http://', #{proxy}"
+        return '' # try without proxy, it may work, shouldn't crash but may not report
+      end
+
+      proxy
+    end
+  end
+end
+

data/lib/solarwinds_apm/ruby.rb

@@ -0,0 +1,35 @@
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+
+module SolarWindsAPM
+  ##
+  # This module provides a method to manually initialize the
+  # Ruby instrumentation.  Normally this is done by detecting
+  # frameworks at load time and inserting initialization hooks.
+  module Ruby
+    class << self
+      def initialize
+        load
+      end
+
+      ##
+      # The core method to load Ruby instrumentation.  Call this
+      # from raw Ruby scripts or in Ruby applications where a
+      # supported framework isn't being used.  Supported frameworks
+      # will instead be detected at load time and initialization is
+      # automatic.
+      def load
+        # In case some apps call this manually, make sure
+        # that the gem is fully loaded and not in no-op
+        # mode (e.g. on unsupported platforms etc.)
+        if SolarWindsAPM.loaded
+          SolarWindsAPM::Inst.load_instrumentation
+        end
+      end
+    end
+  end
+end
+
+if SolarWindsAPM.loaded && !SolarWindsAPM.framework?
+  SolarWindsAPM::Ruby.load
+end

data/lib/solarwinds_apm/sdk/current_trace_info.rb

@@ -0,0 +1,123 @@
+#--
+# Copyright (c) SolarWinds, LLC.
+# All rights reserved.
+#++
+
+module SolarWindsAPM
+  module SDK
+
+    module CurrentTraceInfo
+      # Creates an instance of {TraceInfo} with instance methods {TraceInfo#trace_id},
+      # {TraceInfo#span_id}, {TraceInfo#trace_flags}, {TraceInfo#for_log},
+      # and {TraceInfo#hash_for_log}.
+      #
+      # === Example:
+      #
+      #   trace = SolarWindsAPM::SDK.current_trace_info
+      #   trace.for_log        # 'trace_id=7435a9fe510ae4533414d425dadf4e18 span_id=49e60702469db05f trace_flags=01' or '' depends on Config
+      #   trace.hash_for_log   # { trace_id: '7435a9fe510ae4533414d425dadf4e18',
+      #                            span_id: '49e60702469db05f',
+      #                            trace_flags: ''}  or {} depends on Config
+      #
+      # Configure trace info injection with lograge:
+      #
+      #    Lograge.custom_options = lambda do |event|
+      #       SolarWindsAPM::SDK.current_trace_info.hash_for_log
+      #    end
+      #
+
+      def current_trace_info
+        TraceInfo.new
+      end
+
+      # @attr trace_id
+      # @attr span_id
+      # @attr trace_flags
+      class TraceInfo
+        attr_reader :tracestring, :trace_id, :span_id, :trace_flags, :do_log
+
+        SQL_REGEX=/\/\*\s*traceparent=.*\*\/\s*/.freeze
+
+        def initialize
+          tracestring = SolarWindsAPM::Context.toString
+          parts = SolarWindsAPM::TraceString.split(tracestring)
+
+          @tracestring = parts[:tracestring]
+          @trace_id = parts[:trace_id]
+          @span_id = parts[:span_id]
+          @trace_flags = parts[:flags]
+
+          @do_log = log? # true if the tracecontext should be added to logs
+          @do_sql = sql? # true if the tracecontext should be added to sql
+        end
+
+        # for_log returns a string in the format
+        # 'trace_id=<trace_id> span_id=<span_id> trace_flags=<trace_flags>' or ''.
+        #
+        # An empty string is returned depending on the setting for
+        # <tt>SolarWindsAPM::Config[:log_traceId]</tt>, which can be :never,
+        # :sampled, :traced, or :always.
+        #
+        def for_log
+          @for_log ||= @do_log ? "trace_id=#{@trace_id} span_id=#{@span_id} trace_flags=#{@trace_flags}" : ''
+        end
+
+        def hash_for_log
+          @hash_for_log ||= @do_log ? { trace_id: @trace_id,
+                                       span_id: @span_id,
+                                       trace_flags: @trace_flags } : {}
+        end
+
+        def for_sql
+          @for_sql ||= @do_sql ? "/*traceparent='#{@tracestring}'*/" : ''
+        end
+
+        ##
+        # add_traceparent_to_sql
+        #
+        # returns the sql with "/*traceparent='#{@tracestring}'*/" prepended
+        # and adds the QueryTag kv to kvs
+        #
+        def add_traceparent_to_sql(sql, kvs)
+          sql = sql.gsub(SQL_REGEX, '') # remove if it was added before
+
+          unless for_sql.empty?
+            kvs[:QueryTag] = for_sql
+            return "#{for_sql}#{sql}"
+          end
+
+          sql
+        end
+
+        private
+
+        # if true the trace info should be added to the log message
+        def log?
+          case SolarWindsAPM::Config[:log_traceId]
+          when :never, nil
+            false
+          when :always
+            # there is no way @tracestring is not ok
+            # it may be all 0s, but that is ok
+            # SolarWindsAPM::TraceString.ok?(@tracestring)
+            true
+          when :traced
+            SolarWindsAPM::TraceString.valid?(@tracestring)
+          when :sampled
+            SolarWindsAPM::TraceString.sampled?(@tracestring)
+          end
+        end
+
+        # if true the trace info should be added to the sql query
+        def sql?
+           SolarWindsAPM::Config[:tag_sql] &&
+             SolarWindsAPM::TraceString.sampled?(@tracestring)
+        end
+
+      end
+
+    end
+
+    extend CurrentTraceInfo
+  end
+end

data/lib/solarwinds_apm/sdk/custom_metrics.rb

@@ -0,0 +1,94 @@
+#--
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+#++
+
+module SolarWindsAPM
+  module SDK
+
+    module CustomMetrics
+
+      # Send counts
+      #
+      # Use this method to report the number of times an action occurs. The metric counts reported are summed and flushed every 60 seconds.
+      #
+      # === Arguments:
+      #
+      # * +name+          (String) Name to be used for the metric. Must be 255 or fewer characters and consist only of A-Za-z0-9.:-*
+      # * +count+         (Integer, optional, default = 1): Count of actions being reported
+      # * +with_hostname+ (Boolean, optional, default = false): Indicates if the host name should be included as a tag for the metric
+      # * +tags_kvs+      (Hash, optional): List of key/value pairs to describe the metric. The key must be <= 64 characters, the value must be <= 255 characters, allowed characters: A-Za-z0-9.:-_
+      #
+      # === Example:
+      #
+      #   class WorkTracker
+      #     def counting(name, tags = {})
+      #       yield # yield to where work is done
+      #       SolarWindsAPM::SDK.increment_metric(name, 1, false, tags)
+      #     end
+      #   end
+      #
+      # === Returns:
+      # * 0 on success, error code on failure
+      #
+      def increment_metric(name, count = 1, with_hostname = false, tags_kvs = {})
+        return true unless SolarWindsAPM.loaded
+        with_hostname = with_hostname ? 1 : 0
+        tags, tags_count = make_tags(tags_kvs)
+        SolarWindsAPM::CustomMetrics.increment(name.to_s, count, with_hostname, nil, tags, tags_count) == 1
+      end
+
+      # Send values with counts
+      #
+      # Use this method to report a value for each or multiple counts. The metric values reported are aggregated and flushed every 60 seconds. The dashboard displays the average value per count.
+      #
+      # === Arguments:
+      #
+      # * +name+          (String) Name to be used for the metric. Must be 255 or fewer characters and consist only of A-Za-z0-9.:-*
+      # * +value+         (Numeric) Value to be added to the current sum
+      # * +count+         (Integer, optional, default = 1): Count of actions being reported
+      # * +with_hostname+ (Boolean, optional, default = false): Indicates if the host name should be included as a tag for the metric
+      # * +tags_kvs+      (Hash, optional): List of key/value pairs to describe the metric. The key must be <= 64 characters, the value must be <= 255 characters, allowed characters: A-Za-z0-9.:-_
+      #
+      # === Example:
+      #
+      #   class WorkTracker
+      #     def timing(name, tags = {})
+      #       start = Time.now
+      #       yield # yield to where work is done
+      #       duration = Time.now - start
+      #       SolarWindsAPM::SDK.summary_metric(name, duration, 1, false, tags)
+      #     end
+      #   end
+      #
+      # === Returns:
+      # * 0 on success, error code on failure
+      #
+      def summary_metric(name, value, count = 1, with_hostname = false, tags_kvs = {})
+        return true unless SolarWindsAPM.loaded
+        with_hostname = with_hostname ? 1 : 0
+        tags, tags_count = make_tags(tags_kvs)
+        SolarWindsAPM::CustomMetrics.summary(name.to_s, value, count, with_hostname, nil, tags, tags_count) == 1
+      end
+
+      private
+
+      def make_tags(tags_kvs)
+        unless tags_kvs.is_a?(Hash)
+          SolarWindsAPM.logger.warn("[solarwinds_apm/metrics] CustomMetrics received tags_kvs that are not a Hash (found #{tags_kvs.class}), setting tags_kvs = {}")
+          tags_kvs = {}
+        end
+        count = tags_kvs.size
+        tags = SolarWindsAPM::MetricTags.new(count)
+
+        tags_kvs.each_with_index do |(k, v), i|
+          tags.add(i, k.to_s, v.to_s)
+        end
+
+        [tags, count]
+      end
+    end
+
+    extend CustomMetrics
+  end
+end

data/lib/solarwinds_apm/sdk/logging.rb

@@ -0,0 +1,37 @@
+# Copyright (c) 2019 SolarWinds, LLC.
+# All rights reserved.
+#
+
+module SolarWindsAPM
+  module SDK
+    module Logging
+
+      # Log an information event in the current span
+      #
+      # a possible use-case is to collect extra information during the execution of a request
+      #
+      # === Arguments:
+      # * +kvs+   - (optional) hash containing key/value pairs that will be reported with this span.
+      #
+      def log_info(kvs)
+        SolarWindsAPM::API.log_info(SolarWindsAPM.layer, kvs)
+      end
+
+      # Log an exception/error event in the current span
+      #
+      # this may be helpful to track problems when an exception is rescued
+      #
+      # === Arguments:
+      # * +exception+ - an exception, must respond to :message and :backtrace
+      # * +kvs+      - (optional) hash containing key/value pairs that will be reported with this span.
+      #
+      def log_exception(exception, kvs = {})
+        SolarWindsAPM::API.log_exception(SolarWindsAPM.layer, exception, kvs)
+      end
+
+    end
+
+    extend Logging
+
+  end
+end

data/lib/solarwinds_apm/sdk/trace_context_headers.rb

@@ -0,0 +1,69 @@
+#sh Copyright (c) SolarWinds, LLC.
+# All rights reserved.
+
+module SolarWindsAPM
+  module SDK
+    ##
+    #
+    # Module to be included in classes with outbound calls
+    #
+    module TraceContextHeaders
+
+      ##
+      # Add w3c tracecontext to headers arg
+      #
+      # === Argument:
+      # * +:headers+   outbound headers, a Hash or other object that can have key/value assigned
+      #
+      # Internally it uses SolarWindsAPM.trace_context, which is a thread local
+      # variable containing verified and processed incoming w3c headers.
+      # It gets populated by requests processed by Rack or through the
+      # :headers arg in SolarWindsAPM::SDK.start_trace
+      #
+      # === Example:
+      # class OutboundCaller
+      #   include SolarWindsAPM::SDK::TraceContextHeaders
+      #
+      #   # create new headers
+      #   def faraday_send
+      #     conn = Faraday.new(:url => 'http://example.com')
+      #     headers = add_tracecontext_headers
+      #     conn.get('/', nil, headers)
+      #   end
+      #
+      #   # add to given headers
+      #   def excon_send(headers)
+      #     conn = Excon.new('http://example.com')
+      #     add_tracecontext_headers(headers)
+      #     conn.get(headers: headers)
+      #   end
+      # end
+      #
+      # === Returns:
+      # * The headers with w3c tracecontext added, also modifies the headers arg if given
+      #
+      def add_tracecontext_headers(headers = {})
+        begin
+          if SolarWindsAPM::Context.isValid
+            headers['traceparent'] = SolarWindsAPM::Context.toString
+            parent_id_flags = SolarWindsAPM::TraceString.span_id_flags(headers['traceparent'])
+            tracestate = SolarWindsAPM.trace_context&.tracestate
+            headers['tracestate'] = SolarWindsAPM::TraceState.add_sw_member(tracestate, parent_id_flags)
+          else
+            # make sure we propagate an incoming trace_context even if we don't trace
+            if SolarWindsAPM.trace_context
+              headers['traceparent'] = SolarWindsAPM.trace_context.traceparent
+              headers['tracestate'] = SolarWindsAPM.trace_context.tracestate
+            end
+          end
+        rescue => e
+          # we don't know what the class of headers is and the obj may not
+          # be able to accept a key/value assignment
+          # unfortunately I could not find a method to check for that
+          # therefore we're catching the error and don't change the headers
+        end
+        headers
+      end
+    end
+  end
+end