semantic_logger 4.1.1 → 4.2.0

data/lib/semantic_logger/log.rb

@@ -47,7 +47,10 @@ module SemanticLogger
   # context [Hash]
   #   Named contexts that were captured when the log entry was created.
   class Log
-    attr_accessor :level, :thread_name, :name, :message, :payload, :time, :duration, :tags, :level_index, :exception, :metric, :backtrace, :metric_amount, :named_tags, :context
+    attr_accessor :level, :level_index, :name, :message, :time, :duration,
+                  :payload, :exception, :thread_name, :backtrace,
+                  :tags, :named_tags, :context,
+                  :metric, :metric_amount, :dimensions
 
     def initialize(name, level, index = nil)
       @level       = level
@@ -65,7 +68,17 @@ module SemanticLogger
     #
     # Example:
     #   logger.info(name: 'value')
-    def assign(message: nil, payload: nil, min_duration: 0.0, exception: nil, metric: nil, metric_amount: 1, duration: nil, backtrace: nil, log_exception: :full, on_exception_level: nil)
+    def assign(message: nil,
+               payload: nil,
+               min_duration: 0.0,
+               exception: nil,
+               metric: nil,
+               metric_amount: nil,
+               duration: nil,
+               backtrace: nil,
+               log_exception: :full,
+               on_exception_level: nil,
+               dimensions: nil)
       # Elastic logging: Log when :duration exceeds :min_duration
       # Except if there is an exception when it will always be logged
       if duration
@@ -95,14 +108,15 @@ module SemanticLogger
       end
 
       if backtrace
-        self.backtrace = self.class.cleanse_backtrace(backtrace)
+        self.backtrace = Utils.cleanse_backtrace(backtrace)
       elsif level_index >= SemanticLogger.backtrace_level_index
-        self.backtrace = self.class.cleanse_backtrace
+        self.backtrace = Utils.cleanse_backtrace
       end
 
       if metric
         self.metric        = metric
         self.metric_amount = metric_amount
+        self.dimensions    = dimensions
       end
 
       self.payload = payload if payload && (payload.size > 0)
@@ -125,6 +139,8 @@ module SemanticLogger
       elsif exception.nil? && payload && payload.respond_to?(:backtrace) && payload.respond_to?(:message)
         exception = payload
         payload   = nil
+      elsif payload.is_a?(String)
+        message = message.nil? ? payload : "#{message} -- #{payload}"
       end
 
       # Add result of block as message or payload if not nil
@@ -277,16 +293,9 @@ module SemanticLogger
       (self.context ||= {})[key] = value
     end
 
-    private
-
-    SELF_PATTERN = File.join('lib', 'semantic_logger')
-
-    # Extract the backtrace leaving out Semantic Logger
-    def self.cleanse_backtrace(stack = caller)
-      while (first = stack.first) && first.include?(SELF_PATTERN)
-        stack.shift
-      end
-      stack
+    # A metric only event has a metric but no message, exception, or payload.
+    def metric_only?
+      metric && message.nil? && exception.nil? && payload.nil?
     end
 
   end

data/lib/semantic_logger/loggable.rb

@@ -5,29 +5,34 @@
 #   By including this mix-in into any class it will define a class level logger
 #   and also make it accessible via instance methods
 #
-# Example
+# Example:
+#   require 'semantic_logger'
+#   SemanticLogger.default_level = :debug
+#   SemanticLogger.add_appender(io: STDOUT, formatter: :color)
 #
-#  require 'semantic_logger'
-#  SemanticLogger.default_level = :debug
-#  SemanticLogger.add_appender(io: STDOUT, formatter: :color)
+#   class ExternalSupplier
+#     # Create class and instance logger methods
+#     include SemanticLogger::Loggable
 #
-#  class ExternalSupplier
-#    # Create class and instance logger methods
-#    include SemanticLogger::Loggable
+#     def call_supplier(amount, name)
+#       logger.debug "Calculating with amount", { amount: amount, name: name }
 #
-#    def call_supplier(amount, name)
-#      logger.debug "Calculating with amount", { amount: amount, name: name }
+#       # Measure and log on completion how long the call took to the external supplier
+#       logger.measure_info "Calling external interface" do
+#         # Code to call the external supplier ...
+#       end
+#     end
+#   end
 #
-#      # Measure and log on completion how long the call took to the external supplier
-#      logger.measure_info "Calling external interface" do
-#        # Code to call the external supplier ...
-#      end
-#    end
-#  end
+# Notes:
+# * To forcibly replace Rails or any other existing logging methods
+#   use `prepend` instead of `include`. For example:
+#     ExternalSupplier.prepend SemanticLogger::Loggable
 module SemanticLogger
   module Loggable
 
     def self.included(base)
+      base.extend ClassMethods
       base.class_eval do
         # Returns [SemanticLogger::Logger] class level logger
         def self.logger
@@ -51,5 +56,73 @@ module SemanticLogger
       end
     end
 
+    module ClassMethods
+      # Measure and log the performance of an instance method.
+      #
+      # Parameters:
+      #   method_name: [Symbol]
+      #     The name of the method that should be measured.
+      #
+      #   options: [Hash]
+      #     Any valid options that can be passed to measure.
+      #
+      # Approximate overhead when logging a method call with a metric:
+      #   0.044 ms  per method call.
+      #   0.009 ms  per method call. If `min_duration` is not met
+      #   0.0005 ms per method call. If `level` is not met
+      def logger_measure_method(method_name,
+                                min_duration: 0.0,
+                                metric: "#{name}/#{method_name}",
+                                log_exception: :partial,
+                                on_exception_level: nil,
+                                message: "##{method_name}",
+                                level: :info)
+
+        # unless visibility = Utils.method_visibility(self, method_name)
+        #   logger.warn("Unable to measure method: #{name}##{method_name} since it does not exist")
+        #   return false
+        # end
+
+        index = SemanticLogger.level_to_index(level)
+
+        logger_measure_module.module_eval(<<-EOT, __FILE__, __LINE__ + 1)
+          def #{method_name}(*args, &block)
+            if logger.send(:level_index) <= #{index}
+              logger.send(
+                :measure_method,
+                index:              #{index}, 
+                level:              #{level.inspect}, 
+                message:            #{message.inspect}, 
+                min_duration:       #{min_duration},
+                metric:             #{metric.inspect},
+                log_exception:      #{log_exception.inspect},
+                on_exception_level: #{on_exception_level.inspect}
+              ) do
+                super(*args, &block)
+              end
+            else
+              super(*args, &block)
+            end
+          end
+        EOT
+        #{"#{visibility} :#{method_name}" unless visibility == :public}
+        true
+      end
+
+      private
+
+      # Dynamic Module to intercept method calls for measuring purposes.
+      def logger_measure_module
+        if const_defined?(:SemanticLoggerMeasure, _search_ancestors = false)
+          const_get(:SemanticLoggerMeasure)
+        else
+          mod = const_set(:SemanticLoggerMeasure, Module.new)
+          prepend mod
+          mod
+        end
+      end
+
+    end
+
   end
 end

data/lib/semantic_logger/logger.rb

@@ -38,25 +38,5 @@ module SemanticLogger
       Processor << log
     end
 
-    # DEPRECATED
-    def self.queue_size
-      Processor.queue_size
-    end
-
-    # DEPRECATED
-    def self.flush
-      Processor.flush
-    end
-
-    # DEPRECATED
-    def self.close
-      Processor.close
-    end
-
-    # DEPRECATED
-    def self.logger=(logger)
-      Processor.logger = logger
-    end
-
   end
 end

data/lib/semantic_logger/metric/new_relic.rb

@@ -0,0 +1,75 @@
+begin
+  require 'newrelic_rpm'
+rescue LoadError
+  raise 'Gem newrelic_rpm is required for logging to New Relic. Please add the gem "newrelic_rpm" to your Gemfile.'
+end
+
+# Send Metrics to NewRelic
+#
+# The :error and :fatal log entries will show up under
+# "Applications" > "Application Name" > "Events" > "Errors" in New Relic.
+#
+# Example:
+#   SemanticLogger.add_appender(metric: :new_relic)
+class SemanticLogger::Metric::NewRelic < SemanticLogger::Subscriber
+  attr_accessor :prefix
+
+  # Create Appender
+  #
+  # Parameters
+  #   :prefix [String]
+  #     Prefix to add to every metric before forwarding to NewRelic.
+  #     Default: 'Custom'
+  #
+  #   level: [:trace | :debug | :info | :warn | :error | :fatal]
+  #     Override the log level for this appender.
+  #     Default: :error
+  #
+  #   formatter: [Object|Proc]
+  #     An instance of a class that implements #call, or a Proc to be used to format
+  #     the output from this appender
+  #     Default: Use the built-in formatter (See: #call)
+  #
+  #   filter: [Regexp|Proc]
+  #     RegExp: Only include log messages where the class name matches the supplied.
+  #     regular expression. All other messages will be ignored.
+  #     Proc: Only include log messages where the supplied Proc returns true
+  #           The Proc must return true or false.
+  def initialize(prefix: 'Custom',
+                 level: nil,
+                 formatter: nil,
+                 filter: nil,
+                 application: nil,
+                 host: nil,
+                 &block)
+
+    @prefix = prefix
+    super(level: level, formatter: formatter, filter: filter, application: application, host: host, &block)
+  end
+
+  # Returns metric name to use.
+  def call(log, _logger)
+    metric = log.metric
+    # Add prefix for NewRelic
+    metric = "#{prefix}/#{metric}" unless metric.start_with?(prefix)
+    metric
+  end
+
+  def log(log)
+    name = formatter.call(log, self)
+    if duration = log.duration
+      # Convert duration to seconds
+      ::NewRelic::Agent.record_metric(name, duration / 1000.0)
+    else
+      ::NewRelic::Agent.increment_metric(name, log.metric_amount || 1)
+    end
+    true
+  end
+
+  # Only forward log entries that contain metrics.
+  def should_log?(log)
+    # Does not support metrics with dimensions.
+    log.metric && !log.dimensions && meets_log_level?(log) && !filtered?(log)
+  end
+
+end

data/lib/semantic_logger/metric/signalfx.rb

@@ -0,0 +1,123 @@
+# Forward application metrics to SignalFx.
+#
+# Example:
+#   SemanticLogger.add_appender(
+#     metric: :signalfx,
+#     token:  'SIGNALFX_ORG_ACCESS_TOKEN'
+#   )
+class SemanticLogger::Metric::Signalfx < SemanticLogger::Appender::Http
+  attr_reader :full_url
+
+  END_POINT = 'v2/datapoint'
+
+  # Create SignalFx metrics appender.
+  #
+  # Parameters:
+  #   token: [String]
+  #     Access Token to use for sending metrics.
+  #     Obtain the Signalfx token via the Signalfx Web UI under `Organization` -> `Access Tokens`.
+  #
+  #   dimensions: [Array<String>]
+  #     Dimensions to forward to signalfx when they are present in the named tags of any log message.
+  #     By default `application` and `host` are always included as dimensions in all forwarded metrics.
+  #     Example: [:user_id, :state]
+  #
+  #   filter: [Regexp|Proc]
+  #     RegExp: Only include log messages where the class name matches the supplied
+  #             regular expression. All other messages will be ignored.
+  #     Proc: Only include log messages where the supplied Proc returns true.
+  #           The Proc must return true or false.
+  #
+  #   host: [String]
+  #     Name of this host to send as a dimension.
+  #     Default: SemanticLogger.host
+  #
+  #   application: [String]
+  #     Name of this application to send as a dimension.
+  #     Default: SemanticLogger.application
+  #
+  #   url: [String]
+  #     Override the SignalFx service url.
+  #     For historical data use: https://backfill.signalfx.com/v1/backfill
+  #     Default: https://ingest.signalfx.com
+  #
+  # Notes:
+  #
+  # When sending a metric to Signalfx, it is necessary to send both a `gauge` and a `counter` when a
+  # duration is included in the metric, otherwise it is not possible to chart counts of the metric.
+  # Unfortunately this doubles the number of metrics, but it is the way Signalfx works.
+  # Using a `count` of a `gauge` in a chart will significantly under-count the number of occurrences.
+  #
+  # If dimensions are added to the metric, then the metric will be sent as-is and
+  # the above logic will _not_ be applied.
+  #
+  # Example, Gauge metric, supplying the duration in `metric_amount`:
+  #   logger.info(metric: 'Filters.average', metric_amount: 1.2, dimensions: {user: 'jbloggs'})
+  #
+  # Example, Counter metric:
+  #   logger.info(metric: 'Filters.count', dimensions: {user: 'jbloggs'})
+  #
+  # Example, Counter metric with a count other than 1:
+  #   logger.info(metric: 'Filters.count', metric_amount: 23, dimensions: {user: 'jbloggs'})
+  #
+  # When a duration is supplied and no dimensions are supplied:
+  #   logger.info(metric: 'Common/User/authorize', duration: 1.4)
+  #
+  # Then it is translated into the following 2 log entries under the covers:
+  #   logger.info(metric: 'Application.average', metric_amount: 1.4, dimensions: {class: 'Common::User', action: 'authorize'})
+  #   logger.info(metric: 'Application.counter', metric_amount: 1, dimensions: {class: 'Common::User', action: 'authorize'})
+  #
+  # Similarly with a measure block which automatically supplies the duration:
+  #   logger.measure_info(metric: 'Common/User/authorize') do
+  #     sleep 1
+  #   end
+  def initialize(token:,
+                 dimensions: nil,
+                 url: 'https://ingest.signalfx.com',
+                 open_timeout: 2.0,
+                 read_timeout: 1.0,
+                 continue_timeout: 1.0,
+                 filter: nil,
+                 application: nil,
+                 host: nil,
+                 formatter: nil,
+                 &block)
+
+    formatter ||= SemanticLogger::Formatters::Signalfx.new(token: token, dimensions: dimensions)
+
+    super(
+      url:              url,
+      read_timeout:     read_timeout,
+      open_timeout:     open_timeout,
+      continue_timeout: continue_timeout,
+      filter:           filter,
+      application:      application,
+      host:             host,
+      formatter:        formatter,
+      &block
+    )
+
+    @header['X-SF-TOKEN'] = token
+    @full_url             = "#{url}/#{END_POINT}"
+  end
+
+  def log(log)
+    message = formatter.call(log, self)
+    logger.trace(message)
+    post(message, full_url)
+  end
+
+  # Logs in batches
+  def batch(logs)
+    message = formatter.batch(logs, self)
+    logger.trace(message)
+    post(message, full_url)
+  end
+
+  # Only forward log entries that contain metrics.
+  def should_log?(log)
+    log.metric && meets_log_level?(log) && !filtered?(log)
+  end
+
+end
+

data/lib/semantic_logger/{metrics → metric}/statsd.rb

@@ -6,8 +6,10 @@ rescue LoadError
 end
 
 module SemanticLogger
-  module Metrics
+  module Metric
     class Statsd < Subscriber
+      attr_accessor :url
+
       # Create Statsd metrics subscriber
       #
       # Parameters:
@@ -20,12 +22,16 @@ module SemanticLogger
       #     Default: udp://localhost:8125
       #
       # Example:
-      #   subscriber = SemanticLogger::Metrics::Statsd.new(url: 'udp://localhost:8125')
-      #   SemanticLogger.on_metric(subscriber)
-      def initialize(options = {})
-        options = options.dup
-        @url    = options.delete(:url) || 'udp://localhost:8125'
-        uri     = URI.parse(@url)
+      #   SemanticLogger.add_appender(
+      #     metric: :statsd,
+      #     url:    'localhost:8125'
+      #   )
+      def initialize(url: 'udp://localhost:8125')
+        @url = url
+      end
+
+      def reopen
+        uri = URI.parse(@url)
         raise('Statsd only supports udp. Example: "udp://localhost:8125"') if uri.scheme != 'udp'
 
         @statsd           = ::Statsd.new(uri.host, uri.port)
@@ -33,7 +39,7 @@ module SemanticLogger
         @statsd.namespace = path.sub('/', '') if path != ''
       end
 
-      def call(log)
+      def log(log)
         metric = log.metric
         if duration = log.duration
           @statsd.timing(metric, duration)
@@ -47,6 +53,12 @@ module SemanticLogger
         end
       end
 
+      # Only forward log entries that contain metrics.
+      def should_log?(log)
+        # Does not support metrics with dimensions.
+        log.metric && !log.dimensions && meets_log_level?(log) && !filtered?(log)
+      end
+
     end
   end
 end