newrelic_rpm 3.1.0 → 3.1.1.beta1

data/lib/new_relic/agent/shim_agent.rb

@@ -9,7 +9,6 @@ module NewRelic
       end
       def initialize
         super
-        @histogram.extend NewRelic::Histogram::Shim
         @stats_engine.extend NewRelic::Agent::StatsEngine::Shim
         @stats_engine.extend NewRelic::Agent::StatsEngine::Transactions::Shim
         @transaction_sampler.extend NewRelic::Agent::TransactionSampler::Shim

data/lib/new_relic/agent/stats_engine.rb

@@ -4,6 +4,7 @@ require 'new_relic/agent/stats_engine/transactions'
 
 module NewRelic
   module Agent
+    # This class handles all the statistics gathering for the agent
     class StatsEngine
       include MetricStats
       include Samplers

data/lib/new_relic/agent/stats_engine/metric_stats.rb

@@ -1,7 +1,10 @@
 module NewRelic
   module Agent
     class StatsEngine
+      # Handles methods related to actual Metric collection
       module MetricStats
+        # A simple mutex-synchronized hash to make sure our statistics
+        # are internally consistent even in truly-threaded rubies like JRuby
         class SynchronizedHash < Hash
           def initialize(*args)
             @mutex = Mutex.new
@@ -38,17 +41,20 @@ module NewRelic
             }
           end
         end
-
+        
+        # Returns all of the metric names of all the stats in the engine
         def metrics
           stats_hash.keys.map(&:to_s)
         end
-
+        
+        # a simple accessor for looking up a stat with no scope -
+        # returns a new stats object if no stats object for that
+        # metric exists yet
         def get_stats_no_scope(metric_name)
           stats_hash[NewRelic::MetricSpec.new(metric_name, '')] ||= NewRelic::MethodTraceStats.new
         end
 
         # This version allows a caller to pass a stat class to use
-        #
         def get_custom_stats(metric_name, stat_class)
           stats_hash[NewRelic::MetricSpec.new(metric_name)] ||= stat_class.new
         end
@@ -69,13 +75,21 @@ module NewRelic
           end
           stats
         end
-
+        
+        # Returns a stat if one exists, otherwise returns nil. If you
+        # want auto-initialization, use one of get_stats or get_stats_no_scope
         def lookup_stats(metric_name, scope_name = '')
           stats_hash[NewRelic::MetricSpec.new(metric_name, scope_name)]
         end
-
+        
+        # This module was extracted from the harvest method and should
+        # be refactored
         module Harvest
-
+          
+          # merge data from previous harvests into this stats engine -
+          # takes into account the case where there are new stats for
+          # that metric, and the case where there is no current data
+          # for that metric
           def merge_data(metric_data_hash)
             metric_data_hash.each do |metric_spec, metric_data|
               new_data = lookup_stats(metric_spec.name, metric_spec.scope)
@@ -172,7 +186,9 @@ module NewRelic
         def reset_stats
           stats_hash.values.each { |s| s.reset }
         end
-
+        
+        # returns a memoized SynchronizedHash that holds the actual
+        # instances of Stats keyed off their MetricName
         def stats_hash
           @stats_hash ||= SynchronizedHash.new
         end

data/lib/new_relic/agent/stats_engine/samplers.rb

@@ -6,14 +6,20 @@ module Agent
       def add_harvest_sampler(*args); end
       def start_sampler_thread(*args); end
     end
-
+    
+    # Contains statistics engine extensions to support the concept of samplers
     module Samplers
 
       # By default a sampler polls on harvest time, once a minute.  However you can
       # override #use_harvest_sampler? to return false and it will sample
       # every POLL_PERIOD seconds on a background thread.
       POLL_PERIOD = 20
-
+      
+      # starts the sampler thread which runs periodically, rather than
+      # at harvest time. This is deprecated, and should not actually
+      # be used - mo threads mo problems
+      #
+      # returns unless there are actually periodic samplers to run
       def start_sampler_thread
 
         return if @sampler_thread && @sampler_thread.alive?

data/lib/new_relic/agent/stats_engine/transactions.rb

@@ -1,10 +1,9 @@
+# -*- coding: utf-8 -*-
 module NewRelic
 module Agent
   class StatsEngine
-
-    # Defines methods that stub out the stats engine methods
-    # when the agent is disabled
-
+    # A simple stack element that tracks the current name and length
+    # of the executing stack
     class ScopeStackElement
       attr_reader :name, :deduct_call_time_from_parent
       attr_accessor :children_time
@@ -14,8 +13,13 @@ module Agent
         @children_time = 0
       end
     end
-
+    
+    # Handles pushing and popping elements onto an internal stack that
+    # tracks where time should be allocated in Transaction Traces
     module Transactions
+      
+      # Defines methods that stub out the stats engine methods
+      # when the agent is disabled
       module Shim # :nodoc:
         def start_transaction(*args); end
         def end_transaction; end
@@ -25,16 +29,21 @@ module Agent
         def scope_name; end
         def pop_scope(*args); end
       end
-
+      
+      # add a new transaction sampler, unless we're currently in a
+      # transaction (then we fail)
       def transaction_sampler= sampler
         fail "Can't add a scope listener midflight in a transaction" if scope_stack.any?
         @transaction_sampler = sampler
       end
-
+      
+      # removes a transaction sampler
       def remove_transaction_sampler(l)
         @transaction_sampler = nil
       end
-
+      
+      # Pushes a scope onto the transaction stack - this generates a
+      # TransactionSample::Segment at the end of transaction execution
       def push_scope(metric, time = Time.now.to_f, deduct_call_time_from_parent = true)
 
         stack = scope_stack
@@ -52,7 +61,9 @@ module Agent
         stack.push scope
         scope
       end
-
+      
+      # Pops a scope off the transaction stack - this updates the
+      # transaction sampler that we've finished execution of a traced method
       def pop_scope(expected_scope, duration, time=Time.now.to_f)
         capture_gc_time if collecting_gc?
         stack = scope_stack
@@ -69,7 +80,8 @@ module Agent
         @transaction_sampler.notice_pop_scope(scope.name, time) if @transaction_sampler
         scope
       end
-
+      
+      # Returns the latest ScopeStackElement
       def peek_scope
         scope_stack.last
       end
@@ -86,7 +98,8 @@ module Agent
         Thread::current[:newrelic_scope_name] = transaction
         Thread::current[:newrelic_most_recent_transaction] = transaction
       end
-
+      
+      # Returns the current scope name from the thread local
       def scope_name
         Thread::current[:newrelic_scope_name]
       end
@@ -173,7 +186,8 @@ module Agent
           pop_scope(gc_scope, elapsed, time)
         end
       end
-
+      
+      # Returns the current scope stack, memoized to a thread local variable
       def scope_stack
         Thread::current[:newrelic_scope_stack] ||= []
       end

data/lib/new_relic/agent/transaction_sampler.rb

@@ -3,7 +3,9 @@ require 'new_relic/control'
 require 'new_relic/agent/transaction_sample_builder'
 module NewRelic
   module Agent
-
+    
+    # This class contains the logic of sampling a transaction -
+    # creation and modification of transaction samples
     class TransactionSampler
 
       # Module defining methods stubbed out when the agent is disabled

data/lib/new_relic/agent/worker_loop.rb

@@ -12,14 +12,17 @@ module NewRelic
         @next_invocation_time = Time.now
         @period = 60.0
       end
-
+      
+      # returns a class-level memoized mutex to make sure we don't run overlapping
       def lock
         @@lock ||= Mutex.new
       end
-
+      
+      # a helper to access the NewRelic::Control.instance.log
       def log
         NewRelic::Control.instance.log
       end
+      
       # Run infinitely, calling the registered tasks at their specified
       # call periods.  The caller is responsible for creating the thread
       # that runs this worker loop.  This will run the task immediately.
@@ -38,15 +41,20 @@ module NewRelic
           run_task if keep_running
         end
       end
-
+      
+      # a simple accessor for @should_run
       def keep_running
         @should_run
       end
-
+      
+      # Sets @should_run to false. Returns false
       def stop
         @should_run = false
       end
-
+      
+      # Executes the block given to the worker loop, and handles many
+      # possible errors. Also updates the execution time so that the
+      # next run occurs on schedule, even if we execute at some odd time
       def run_task
         begin
           lock.synchronize do

data/lib/new_relic/collection_helper.rb

@@ -1,3 +1,5 @@
+require 'new_relic/control'
+
 module NewRelic
   module CollectionHelper
   DEFAULT_TRUNCATION_SIZE=256
@@ -29,12 +31,13 @@ module NewRelic
   # Return nil if there is no backtrace
 
   def strip_nr_from_backtrace(backtrace)
-    if backtrace
+    if backtrace && !NewRelic::Control.instance.disable_backtrace_cleanup?
       # this is for 1.9.1, where strings no longer have Enumerable
       backtrace = backtrace.split("\n") if String === backtrace
-      backtrace = backtrace.reject {|line| line =~ /new_?relic/ }
+      backtrace = backtrace.map &:to_s
+      backtrace = backtrace.reject {|line| line.include?(NewRelic::Control.newrelic_root) }
       # rename methods back to their original state
-      backtrace = backtrace.collect {|line| line.to_s.gsub(/_without_(newrelic|trace)/, "")}
+      backtrace = backtrace.collect {|line| line.gsub(/_without_(newrelic|trace)/, "")}
     end
     backtrace
   end

data/lib/new_relic/control.rb

@@ -8,6 +8,7 @@ require 'erb'
 require 'socket'
 require 'net/https'
 require 'logger'
+require 'new_relic/control/frameworks'
 require 'new_relic/control/profiling'
 require 'new_relic/control/logging_methods'
 require 'new_relic/control/configuration'
@@ -30,9 +31,6 @@ module NewRelic
   # The Control also implements some of the public API for the agent.
   #
   class Control
-    # used for framework-specific subclasses
-    module Frameworks; end
-
     # done in a subfile for load order purposes
     # extend ClassMethods
     # include InstanceMethods

data/lib/new_relic/control/class_methods.rb

@@ -1,16 +1,19 @@
 module NewRelic
   class Control
+    # class-level methods for lazy creation of NewRelic::Control and
+    # NewRelic::LocalEnvironment instances.
     module ClassMethods
       # Access the Control singleton, lazy initialized
       def instance
         @instance ||= new_instance
       end
-
+      
+      # Access the LocalEnvironment singleton, lazy initialized
       def local_env
         @local_env ||= NewRelic::LocalEnvironment.new
       end
 
-      # Create the concrete class for environment specific behavior:
+      # Create the concrete class for environment specific behavior
       def new_instance
         if local_env.framework == :test
           load_test_framework
@@ -25,7 +28,9 @@ module NewRelic
         require "config/test_control"
         NewRelic::Control::Frameworks::Test.new(local_env, config)
       end
-
+      
+      # Loads the specified framework class from the
+      # NewRelic::Control::Frameworks module
       def load_framework_class(framework)
         begin
           require "new_relic/control/frameworks/#{framework}"

data/lib/new_relic/control/configuration.rb

@@ -1,5 +1,7 @@
 module NewRelic
   class Control
+    # used to contain methods to look up settings from the
+    # configuration located in newrelic.yml
     module Configuration
       def settings
         unless @settings
@@ -65,11 +67,13 @@ module NewRelic
       end
 
       def license_key
-        fetch('license_key')
+        fetch('license_key', ENV['NEWRELIC_LICENSE_KEY'])
       end
+      
       def capture_params
         fetch('capture_params')
       end
+      
       # True if we are sending data to the server, monitoring production
       def monitor_mode?
         fetch('monitor_mode', fetch('enabled'))
@@ -79,12 +83,14 @@ module NewRelic
       def developer_mode?
         fetch('developer_mode', fetch('developer'))
       end
-
+      
+      # whether we should install the
+      # NewRelic::Rack::BrowserMonitoring middleware automatically on
+      # Rails applications
       def browser_monitoring_auto_instrument?
         fetch('browser_monitoring', {}).fetch('auto_instrument', true)
       end
 
-      # True if the app runs in multi-threaded mode
       def multi_threaded?
         fetch('multi_threaded')
       end
@@ -97,6 +103,8 @@ module NewRelic
       def use_textmate?
         fetch('textmate')
       end
+      
+      # defaults to 2MiB
       def post_size_limit
         fetch('post_size_limit', 2 * 1024 * 1024)
       end
@@ -135,12 +143,19 @@ module NewRelic
       def validate_token
         self['validate_token'] || ENV['NR_VALIDATE_TOKEN']
       end
-
+      
       def use_ssl?
         @use_ssl = fetch('ssl', false) unless @use_ssl
         @use_ssl
       end
-
+      
+      def log_file_path
+        fetch('log_file_path', 'log/')
+      end
+      
+      # only verify certificates if you're very sure you want this
+      # level of security, it includes possibly app-crashing dns
+      # lookups every connection to the server
       def verify_certificate?
         unless @verify_certificate
           unless use_ssl?
@@ -151,6 +166,10 @@ module NewRelic
         end
         @verify_certificate
       end
+
+      def disable_backtrace_cleanup?
+        fetch('disable_backtrace_cleanup')
+      end
     end
     include Configuration
   end

data/lib/new_relic/control/frameworks.rb

@@ -0,0 +1,10 @@
+module NewRelic
+  class Control
+    # Contains subclasses of NewRelic::Control that are used when
+    # starting the agent within an application. Framework-specific
+    # logic should be included here, as documented within the Control
+    # abstract parent class
+    module Frameworks
+    end
+  end
+end

data/lib/new_relic/control/frameworks/external.rb

@@ -1,11 +1,11 @@
-# This is the control used when starting up in the context of
-# The New Relic Infrastructure Agent.  We want to call this
-# out specifically because in this context we are not monitoring
-# the running process, but actually external things.
 require 'new_relic/control/frameworks/ruby'
 module NewRelic
   class Control
     module Frameworks
+      # This is the control used when starting up in the context of
+      # The New Relic Infrastructure Agent.  We want to call this
+      # out specifically because in this context we are not monitoring
+      # the running process, but actually external things.
       class External < NewRelic::Control::Frameworks::Ruby
         def init_config(options={})
           super

data/lib/new_relic/control/frameworks/merb.rb

@@ -1,6 +1,7 @@
 module NewRelic
   class Control
     module Frameworks
+      # Includes limited support for Merb
       class Merb < NewRelic::Control
 
         def env