appoptics_apm_mnfst 4.5.2

data/lib/appoptics_apm/loading.rb

@@ -0,0 +1,65 @@
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+
+require 'digest/sha1'
+
+module AppOpticsAPM
+  module Util
+    ##
+    # This module was used solely for the deprecated RUM ID calculation
+    # but may be useful in the future.
+    #
+    module Base64URL
+      module_function
+
+      def encode(bin)
+        c = [bin].pack('m0').gsub(/\=+\Z/, '').tr('+/', '-_').rstrip
+        m = c.size % 4
+        c += '=' * (4 - m) if m != 0
+        c
+      end
+
+      def decode(bin)
+        m = bin.size % 4
+        bin += '=' * (4 - m) if m != 0
+        bin.tr('-_', '+/').unpack('m0').first
+      end
+    end
+  end
+
+  ##
+  # This module houses all of the loading functionality for the appoptics_apm em.
+
+  # Note that this does not necessarily _have_ to include initialization routines
+  # (although it can).
+  #
+  # Actual initialization is often separated out as it can be dependent on on the state
+  # of the stack boot process.  e.g. code requiring that initializers, frameworks or
+  # instrumented libraries are already loaded...
+  #
+  module Loading
+    ##
+    # Load the appoptics_apm tracing API
+    #
+    def self.require_api
+      pattern = File.join(File.dirname(__FILE__), 'api', '*.rb')
+      Dir.glob(pattern) do |f|
+        require f
+      end
+
+      begin
+        require 'appoptics_apm/api'
+      rescue LoadError => e
+        AppOpticsAPM.logger.fatal "[appoptics_apm/error] Couldn't load api: #{e.message}"
+      end
+    end
+  end
+end
+
+AppOpticsAPM::Loading.require_api
+
+# Auto-start the Reporter unless we are running Unicorn on Heroku
+# In that case, we start the reporters after fork
+unless AppOpticsAPM.heroku? && AppOpticsAPM.forking_webserver?
+  AppOpticsAPM::Reporter.start if AppOpticsAPM.loaded
+end

data/lib/appoptics_apm/logger.rb

@@ -0,0 +1,42 @@
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+
+require 'logger'
+
+module AppOpticsAPM
+  class << self
+    attr_accessor :logger
+  end
+
+  class Logger
+    # Fatal message
+    def fatal(string, exception = nil)
+      AppOpticsAPM.logger.fatal(string) if AppOpticsAPM.logger
+    end
+
+    # Error message
+    def error(msg, exception = nil)
+      AppOpticsAPM.logger.error(string) if AppOpticsAPM.logger
+    end
+
+    # Warn message
+    def warn(msg, exception = nil)
+      AppOpticsAPM.logger.warn(string) if AppOpticsAPM.logger
+    end
+
+    # Info message
+    def info(msg, exception = nil)
+      AppOpticsAPM.logger.info(string) if AppOpticsAPM.logger
+    end
+
+    # Debug message
+    def debug(msg, exception = nil)
+      AppOpticsAPM.logger.debug(string) if AppOpticsAPM.logger
+    end
+
+  end
+end
+
+AppOpticsAPM.logger = Logger.new(STDERR)
+# set log level to INFO to be consistent with the c-lib, DEBUG would be default
+AppOpticsAPM.logger.level = Logger::INFO

data/lib/appoptics_apm/method_profiling.rb

@@ -0,0 +1,33 @@
+
+module AppOpticsAPM
+  module MethodProfiling
+    def profile_wrapper(method, report_kvs, opts, *args, &block)
+      report_kvs[:Backtrace] = AppOpticsAPM::API.backtrace(2) if opts[:backtrace]
+      report_kvs[:Arguments] = args if opts[:arguments]
+
+      # if this is a rails controller we want to set the transaction for the outbound metrics
+      if defined?(request) && defined?(request.env)
+        report_kvs['Controller'] = self.class.name
+        report_kvs['Action'] = self.action_name
+        request.env['appoptics_apm.controller'] = report_kvs['Controller']
+        request.env['appoptics_apm.action'] = report_kvs['Action']
+      end
+
+      AppOpticsAPM::API.log(nil, :profile_entry, report_kvs)
+
+      begin
+        rv = self.send(method, *args, &block)
+        report_kvs[:ReturnValue] = rv if opts[:result]
+        rv
+      rescue => e
+        AppOpticsAPM::API.log_exception(nil, e)
+        raise
+      ensure
+        report_kvs.delete(:Backtrace)
+        report_kvs.delete(:Controller)
+        report_kvs.delete(:Action)
+        AppOpticsAPM::API.log(nil, :profile_exit, report_kvs)
+      end
+    end
+  end
+end

data/lib/appoptics_apm/noop/README.md

@@ -0,0 +1,9 @@
+Here we can define modules and classes for noop mode.
+
+Instead of polluting code with AppOpticsAPM.loaded conditionals
+
+we load these classes when in noop mode and they expose noop behavior.
+
+so far only one class is needed:
+
+- AppOpticsAPM::Context  and its toString() method from oboe

data/lib/appoptics_apm/noop/context.rb

@@ -0,0 +1,26 @@
+####
+# noop version of AppOpticsAPM::Context
+#
+#
+
+module AppOpticsAPM
+  module Context
+
+    ##
+    # noop version of :toString
+    # toString would return the current context (xtrace) as string
+    #
+    # the noop version returns an empty string
+    #
+    def self.toString
+      ''
+    end
+
+    ##
+    # noop version of :clear
+    #
+    def self.clear
+
+    end
+  end
+end

data/lib/appoptics_apm/noop/metadata.rb

@@ -0,0 +1,22 @@
+####
+# noop version of AppOpticsAPM::Metadata
+#
+#
+
+module AppOpticsAPM
+  class Metadata
+
+    ##
+    # noop version of :makeRandom
+    #
+    # needs to return an object that responds to :isValid
+    #
+    def self.makeRandom
+      Metadata.new
+    end
+
+    def isValid
+      false
+    end
+  end
+end

data/lib/appoptics_apm/ruby.rb

@@ -0,0 +1,35 @@
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+
+module AppOpticsAPM
+  ##
+  # 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 AppOpticsAPM.loaded
+          AppOpticsAPM::Inst.load_instrumentation
+        end
+      end
+    end
+  end
+end
+
+if AppOpticsAPM.loaded && !AppOpticsAPM.framework?
+  AppOpticsAPM::Ruby.load
+end

data/lib/appoptics_apm/sdk/custom_metrics.rb

@@ -0,0 +1,92 @@
+#--
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+#++
+
+module AppOpticsAPM
+  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
+      #       AppOpticsAPM::SDK.increment_metric(name, 1, false, tags)
+      #     end
+      #   end
+      #
+      # === Returns:
+      # * true on success, false on failure
+      #
+      def increment_metric(name, count = 1, with_hostname = false, tags_kvs = {})
+        with_hostname = with_hostname ? 1 : 0
+        tags, tags_count = make_tags(tags_kvs)
+        AppOpticsAPM::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
+      #       AppOpticsAPM::SDK.summary_metric(name, duration, 1, false, tags)
+      #     end
+      #   end
+      #
+      # === Returns:
+      # * true on success, false on failure
+      #
+      def summary_metric(name, value, count = 1, with_hostname = false, tags_kvs = {})
+        with_hostname = with_hostname ? 1 : 0
+        tags, tags_count = make_tags(tags_kvs)
+        AppOpticsAPM::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)
+          AppOpticsAPM.logger.warn("[appoptics_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 = AppOpticsAPM::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/appoptics_apm/sdk/tracing.rb

@@ -0,0 +1,315 @@
+#--
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+#++
+
+module AppOpticsAPM
+  module SDK
+
+    ##
+    # Traces are best created with an <tt>AppOpticsAPM::SDK.start_trace</tt> block and
+    # <tt>AppOpticsAPM::SDK.trace</tt> blocks around calls to be traced.
+    # These two methods guarantee proper nesting of traces, handling of the tracing context, as well as avoiding
+    # broken traces in case of exceptions.
+    #
+    # Some optional keys that can be used in the +opts+ hash:
+    # * +:Controller+
+    # * +:Action+
+    # * +:HTTP-Host+
+    # * +:URL+
+    # * +:Method+
+    #
+    # as well as custom keys. The information will show up in the raw data view of a span.
+    #
+    # Invalid keys: +:Label+, +:Layer+, +:Edge+, +:Timestamp+, +:Timestamp_u+, +:TransactionName+ (allowed in start_trace)
+    #
+    # The methods are exposed as singleton methods for AppOpticsAPM::SDK.
+    #
+    # === Usage:
+    # * +AppOpticsAPM::SDK.appoptics_ready?+
+    # * +AppOpticsAPM::SDK.get_transaction_name+
+    # * +AppOpticsAPM::SDK.set_transaction_name+
+    # * +AppOpticsAPM::SDK.start_trace+
+    # * +AppOpticsAPM::SDK.start_trace_with_target+
+    # * +AppOpticsAPM::SDK.trace+
+    # * +AppOpticsAPM::SDK.tracing?+
+    #
+    # === Example:
+    #   class MonthlyCouponEmailJob
+    #     def perform(*args)
+    #
+    #       # KVs to report to the dashboard
+    #       report_kvs = {}
+    #       report_kvs[:Spec] = :job
+    #       report_kvs[:Controller] = :MonthlyEmailJob
+    #       report_kvs[:Action] = :CouponEmailer
+    #
+    #       # Start tracing this job with start_trace
+    #       AppOpticsAPM::SDK.start_trace('starling', nil, report_kvs) do
+    #         monthly = MonthlyEmail.new(:CouponEmailer)
+    #
+    #         # Trace a sub-component of this trace
+    #         AppOpticsAPM::SDK.trace(self.class.name) do
+    #
+    #           # The work to be done
+    #           users = User.all
+    #           users.each do |u|
+    #             monthly.send(u.email)
+    #           end
+    #
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    module Tracing
+
+      # Trace a given block of code.
+      #
+      # Also detects any exceptions thrown by the block and report errors.
+      #
+      # === Arguments:
+      # * +:span+       - The span the block of code belongs to.
+      # * +:opts+       - (optional) A hash containing key/value pairs that will be reported along with the first event of this span.
+      # * +:protect_op+ - (optional) The operation being traced.  Used to avoid double tracing operations that call each other.
+      #
+      # === Example:
+      #
+      #   def computation_with_appoptics(n)
+      #     AppOpticsAPM::SDK.trace('computation', { :number => n }, :computation) do
+      #       return n if n == 0
+      #       n + computation_with_appoptics(n-1)
+      #     end
+      #   end
+      #
+      #   result = computation_with_appoptics(100)
+      #
+      # === Returns:
+      # * The result of the block.
+      #
+      def trace(span, opts = {}, protect_op = nil)
+        return yield if !AppOpticsAPM.loaded || !AppOpticsAPM.tracing? || AppOpticsAPM.tracing_layer_op?(protect_op)
+
+        opts.delete(:TransactionName)
+        opts.delete('TransactionName')
+
+        AppOpticsAPM::API.log_entry(span, opts, protect_op)
+        opts[:Backtrace] && opts.delete(:Backtrace) # to avoid sending backtrace twice (faster to check presence here)
+        begin
+          yield
+        rescue Exception => e
+          AppOpticsAPM::API.log_exception(span, e)
+          raise
+        ensure
+          AppOpticsAPM::API.log_exit(span, opts, protect_op)
+        end
+      end
+
+
+      # Collect metrics and start tracing a given block of code.
+      #
+      # This will start a trace depending on configuration and probability, detect any exceptions
+      # thrown by the block, and report errors.
+      #
+      # When start_trace returns control to the calling context, the trace will be
+      # completed and the tracing context will be cleared.
+      #
+      # === Arguments:
+      #
+      # * +span+   - Name for the span to be used as label in the trace view.
+      # * +xtrace+ - (optional) incoming X-Trace identifier to be continued.
+      # * +opts+   - (optional) hash containing key/value pairs that will be reported with this span.
+      #   The value of :TransactionName will set the transaction_name.
+      #
+      # === Example:
+      #
+      #   def handle_request(request, response)
+      #     # ... code that processes request and response ...
+      #   end
+      #
+      #   def handle_request_with_appoptics(request, response)
+      #     AppOpticsAPM::SDK.start_trace('custom_trace', nil, :TransactionName => 'handle_request') do
+      #       handle_request(request, response)
+      #     end
+      #   end
+      #
+      # === Returns:
+      # * The result of the block.
+      #
+      def start_trace(span, xtrace = nil, opts = {})
+        start_trace_with_target(span, xtrace, {}, opts) { yield }
+      end
+
+      # Collect metrics, trace a given block of code, and assign trace info to target.
+      #
+      # This will start a trace depending on configuration and probability, detect any exceptions
+      # thrown by the block, report errors, and assign an X-Trace to the target.
+      #
+      # The motivating use case for this is HTTP streaming in rails3. We need
+      # access to the exit event's trace id so we can set the header before any
+      # work is done, and before any headers are sent back to the client.
+      #
+      # === Arguments:
+      # * +span+   - The span the block of code belongs to.
+      # * +xtrace+ - (optional) incoming X-Trace identifier to be continued.
+      # * +target+ - (optional) has to respond to #[]=, The target object in which to place the trace information.
+      # * +opts+   - (optional) hash containing key/value pairs that will be reported with this span.
+      #
+      # === Example:
+      #
+      #   def handle_request(request, response)
+      #     # ... code that processes request and response ...
+      #   end
+      #
+      #   def handle_request_with_appoptics(request, response)
+      #     AppOpticsAPM::SDK.start_trace_with_target('rails', request['X-Trace'], response) do
+      #       handle_request(request, response)
+      #     end
+      #   end
+      #
+      # === Returns:
+      # * The result of the block.
+      #
+      def start_trace_with_target(span, xtrace, target, opts = {})
+        return yield unless AppOpticsAPM.loaded
+
+        if AppOpticsAPM::Context.isValid # not an entry span!
+          result = trace(span, opts) { yield }
+          target['X-Trace'] = AppOpticsAPM::Context.toString
+          return result
+        end
+
+        # :TransactionName and 'TransactionName' need to be removed from opts
+        AppOpticsAPM.transaction_name = opts.delete('TransactionName') || opts.delete(:TransactionName)
+
+        AppOpticsAPM::API.log_start(span, xtrace, opts)
+        opts[:Backtrace] && opts.delete(:Backtrace) # to avoid sending backtrace twice (faster to check presence here)
+
+        # AppOpticsAPM::Event.startTrace creates an Event without an Edge
+        exit_evt = AppOpticsAPM::Event.startTrace(AppOpticsAPM::Context.get)
+        result = begin
+          AppOpticsAPM::API.send_metrics(span, opts) do
+            target['X-Trace'] = AppOpticsAPM::EventUtil.metadataString(exit_evt)
+            yield
+          end
+        rescue Exception => e
+          AppOpticsAPM::API.log_exception(span, e)
+          exit_evt.addEdge(AppOpticsAPM::Context.get)
+          xtrace = AppOpticsAPM::API.log_end(span, opts, exit_evt)
+          e.instance_variable_set(:@xtrace, xtrace)
+          raise
+        end
+
+        exit_evt.addEdge(AppOpticsAPM::Context.get)
+        AppOpticsAPM::API.log_end(span, opts, exit_evt)
+
+        result
+      end
+
+      # Provide a custom transaction name
+      #
+      # The AppOpticsAPM gem tries to create meaningful transaction names from controller+action
+      # or something similar depending on the framework used. However, you may want to override the
+      # transaction name to better describe your instrumented operation.
+      #
+      # Take note that on the dashboard the transaction name is converted to lowercase, and might be
+      # truncated with invalid characters replaced. Method calls with an empty string or a non-string
+      # argument won't change the current transaction name.
+      #
+      # The configuration +AppOpticsAPM.Config+['transaction_name']+['prepend_domain']+ can be set to
+      # true to have the domain name prepended to the transaction name when an event or a metric are
+      # logged. This is a global setting.
+      #
+      # === Argument:
+      #
+      # * +name+ - A non-empty string with the custom transaction name
+      #
+      # === Example:
+      #
+      #   class DogfoodsController < ApplicationController
+      #
+      #     def create
+      #       @dogfood = Dogfood.new(params.permit(:brand, :name))
+      #       @dogfood.save
+      #
+      #       AppOpticsAPM::SDK.set_transaction_name("dogfoodscontroller.create_for_#{params[:brand]}")
+      #
+      #       redirect_to @dogfood
+      #     end
+      #
+      #   end
+      #
+      # === Returns:
+      # * (String or nil) the current transaction name
+      #
+      def set_transaction_name(name)
+        if name.is_a?(String) && name.strip != ''
+          AppOpticsAPM.transaction_name = name
+        else
+          AppOpticsAPM.logger.debug "[appoptics_apm/api] Could not set transaction name, provided name is empty or not a String."
+        end
+        AppOpticsAPM.transaction_name
+      end
+
+
+      # Get the currently set custom transaction name.
+      #
+      # This is provided for testing
+      #
+      # === Returns:
+      # * (String or nil) the current transaction name (without domain prepended)
+      #
+      def get_transaction_name
+        AppOpticsAPM.transaction_name
+      end
+
+      # Determine if this transaction is being traced.
+      #
+      # Tracing puts some extra load on a system, therefor not all transaction are traced.
+      # The +tracing?+ method helps to determine this so that extra work can be avoided when not tracing.
+      #
+      # === Example:
+      #
+      #   kvs = expensive_info_gathering_method  if AppOpticsAPM::SDK.tracing?
+      #   AppOpticsAPM::SDK.trace('some_span', kvs) do
+      #     # this may not create a trace every time it runs
+      #     db_request
+      #   end
+      #
+      def tracing?
+        AppOpticsAPM.tracing?
+      end
+
+      # Wait for AppOptics to be ready to send traces.
+      #
+      # This may be useful in short lived background processes when it is important to capture
+      # information during the whole time the process is running. Usually AppOptics doesn't block an
+      # application while it is starting up.
+      #
+      # === Argument:
+      #
+      # * +wait_milliseconds+ (int, default 3000) the maximum time to wait in milliseconds
+      #
+      # === Example:
+      #
+      #   unless AppopticsAPM::SDK.appoptics_ready?(10_000)
+      #     Logger.info "AppOptics not ready after 10 seconds, no metrics will be sent"
+      #   end
+      #
+      def appoptics_ready?(wait_milliseconds = 3000)
+        return false unless AppOpticsAPM.loaded
+        # These codes are returned by isReady:
+        # OBOE_SERVER_RESPONSE_UNKNOWN 0
+        # OBOE_SERVER_RESPONSE_OK 1
+        # OBOE_SERVER_RESPONSE_TRY_LATER 2
+        # OBOE_SERVER_RESPONSE_LIMIT_EXCEEDED 3
+        # OBOE_SERVER_RESPONSE_INVALID_API_KEY 4
+        # OBOE_SERVER_RESPONSE_CONNECT_ERROR 5
+        AppopticsAPM::Context.isReady(wait_milliseconds) == 1
+      end
+    end
+
+    extend Tracing
+
+  end
+end