newrelic_rpm 3.12.0.288 → 9.10.2

data/lib/tasks/helpers/version_bump.rb

@@ -0,0 +1,62 @@
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
+
+module VersionBump
+  MAJOR = 0
+  MINOR = 1
+  TINY = 2
+  VERSION = {major: MAJOR, minor: MINOR, tiny: TINY}
+
+  # Updates version.rb with new version number
+  def self.update_version
+    bump_type = determine_bump_type
+    file = read_file('lib/new_relic/version.rb')
+    new_version = {}
+
+    VERSION.each do |key, current|
+      file.gsub!(/(#{key.to_s.upcase} = )(\d+)/) do
+        match = Regexp.last_match
+
+        new_version[key] = if bump_type == current # bump type, increase by 1
+          match[2].to_i + 1
+        elsif bump_type < current # right of bump type, goes to 0
+          0
+        else # left of bump type, stays the same
+          match[2].to_i
+        end
+
+        match[1] + new_version[key].to_s
+      end
+    end
+
+    write_file('lib/new_relic/version.rb', file)
+    new_version.values.join('.')
+  end
+
+  def self.read_file(path)
+    File.read(File.expand_path(path))
+  end
+
+  def self.write_file(path, file)
+    File.write(File.expand_path(path), file)
+  end
+
+  # Determined version based on if changelog has a feature or not for version
+  def self.determine_bump_type
+    file = read_file('CHANGELOG.md')
+    lines = file.split('## ')[1].split('- **')
+    return MAJOR if lines.first.include?('Major version')
+    return MINOR if lines.any? { |line| line.include?('Feature:') }
+
+    TINY
+  end
+
+  # Replace dev with version number in changelog
+  def self.update_changelog(version)
+    file = read_file('CHANGELOG.md')
+    file.gsub!('## dev', "## v#{version}")
+    file.gsub!('Version <dev>', "Version #{version}")
+    write_file('CHANGELOG.md', file)
+  end
+end

data/lib/tasks/install.rake

@@ -1,11 +1,15 @@
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
+
 namespace :newrelic do
-  desc "Install a default config/newrelic.yml file"
+  desc 'Install a default config/newrelic.yml file'
   task :install do
-    load File.expand_path(File.join(File.dirname(__FILE__), "..", "..", "install.rb"))
+    load File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'install.rb'))
   end
 
-  desc "Gratefulness is always appreciated"
+  desc 'Gratefulness is always appreciated'
   task :thanks do
-    puts "The Ruby agent team is grateful to Jim Weirich for his kindness and his code. He will be missed."
+    puts 'The Ruby agent team is grateful to Jim Weirich for his kindness and his code. He will be missed.'
   end
 end

data/lib/tasks/instrumentation_generator/README.md

@@ -0,0 +1,63 @@
+# Instrumentation Generator
+
+## Usage
+
+`thor list` can be passed to get a list of all available thor commands
+
+### instrumentation:scaffold
+
+This task requires one parameter by default: the name of the library or class you are instrumenting. This task generates the basic file structure needed to add new instrumentation to the Ruby agent.
+
+Run it using:
+
+`thor instrumentation:scaffold gem_name`
+
+It accepts two optional parameters:
+
+- `--method`: the name of a method to instrument. Only one method can be accepted at this time. Defaults to `method_to_instrument`
+- `--args`: the arguments for the instrumented method. A comma-separated list can be given if there are multiple arguments. Defaults to `*args`.
+
+With the optional parameters, the task can be run like so:
+
+`thor instrumentation:scaffold gem_name --method=method_to_instrument --args=arg1,arg2,arg3`
+
+### WIP: instrumentation:add_new_method
+
+Are you trying add instrumentation for a method within library we already instrument? This task is for you! Instead of building the entire scaffold, this task inserts only the changes needed within the `instrumentation.rb` and test files to instrument the new method. It requires one argument, the name of the existing instrumentation to add the method to. If the instrumented library does not already exist, it will create a new scaffold for that library.
+
+Run it using:
+
+`thor instrumentation:scaffold gem_name`
+
+It accepts two optional parameters:
+
+- `--method`: the name of a method to instrument. Only one method can be accepted at this time. Defaults to `method_to_instrument`
+- `--args`: the arguments for the instrumented method. A comma-separated list can be given if there are multiple arguments. Defaults to `*args`.
+
+With the optional parameters, the task can be run like so:
+
+`thor instrumentation:add_new_method gem_name --method=method_to_instrument --args=arg1,arg2,arg3`
+
+## Idea
+
+Create a CLI, similar to Rails’ generators and scaffold scripts, to create the required files and basic classes for instrumenting new libraries. The hope is that the parts of adding new instrumentation that is repetitive can be eliminated and/or reduced so that it takes less time to add new instrumentation and we can spend development time considering the best attributes to collect and interactions to measure. I also hope this project will reduce the overall toil related to adding new instrumentation.
+
+The files we create with little variation besides library and method names are:
+
+- Lib
+  - Dependency detection
+  - Chain
+  - Prepend
+  - Instrumentation
+- Tests
+  - configuration/newrelic.yml
+  - Envfile
+  - Test file
+
+Furthermore, we also create very similar snippets inside the default source configuration file that could be generated by this project as well.
+
+## Outcome
+
+A prototype outside the agent was first created. This prototype generated the required files to add instrumentation. The prototype accepted three arguments: name (name of the library), method (method to instrument), args (arguments for the method). This prototype has evolved into the current directory.
+
+This project leverages the Ruby gem Thor, a toolkit for building powerful command-line interfaces used in Bundler, Vagrant, Rails and others powers this CLI.

data/lib/tasks/instrumentation_generator/TODO.md

@@ -0,0 +1,33 @@
+# TODO
+
+# - [X] Create instrumentation file
+
+# - [X] Create chain file
+
+# - [X] Create prepend file
+
+# - [X] Create dependency detection file
+
+# - [X] Add config to default source
+
+# - [X] Create multiverse suite
+
+# - [X] Create Envfile
+
+# - [X] Create test file with examples
+
+# - [X] Create option for method names to instrument
+
+# - [X] Add entry to newrelic.yml
+
+# - [ ] Append a new method to instrument to an existing instrumentation class (with tests?)
+
+# - [ ] Documentation: examples of what to add in each gap (Good examples of tests, instrumentation, etc. as comments to guide users)
+
+# - [ ] Handle multi-word gem names (camel case for classes, handle hyphens, concurrent-ruby as example)
+
+# - [ ] Allow multiple method arguments to be passed to the command line
+
+# - [ ] Add tests for the instrumentation_generator code
+
+# - [ ] See if instrumentation PRs can get automatically generated when an already instrumented library adds methods to its codebase

data/lib/tasks/instrumentation_generator/instrumentation.thor

@@ -0,0 +1,129 @@
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
+
+require_relative '../../new_relic/language_support'
+require 'thor'
+
+class Instrumentation < Thor
+  include Thor::Actions
+
+  INSTRUMENTATION_ROOT = 'lib/new_relic/agent/instrumentation/'
+  MULTIVERSE_SUITE_ROOT = 'test/multiverse/suites/'
+  DEFAULT_SOURCE_LOCATION = 'lib/new_relic/agent/configuration/default_source.rb'
+  NEWRELIC_YML_LOCATION = 'newrelic.yml'
+
+  desc('scaffold NAME', 'Scaffold the required files for adding new instrumentation')
+  long_desc <<~LONGDESC
+    `instrumentation scaffold` requires one parameter by default: the name of the
+    library or class you are instrumenting. This task generates the basic
+    file structure needed to add new instrumentation to the Ruby agent.
+  LONGDESC
+
+  source_root(File.dirname(__FILE__))
+
+  option :method,
+    default: 'method_to_instrument',
+    desc: 'The method you would like to prepend or chain instrumentation onto'
+  option :args,
+    default: '*args',
+    desc: 'The arguments associated with the original method'
+
+  def scaffold(name)
+    @name = name
+    @snake_name = snake_name(@name)
+    @method = options[:method] if options[:method]
+    @args = options[:args] if options[:args]
+    @class_name = ::NewRelic::LanguageSupport.camelize(name)
+    base_path = "#{INSTRUMENTATION_ROOT}#{@snake_name}"
+
+    empty_directory(base_path)
+    create_instrumentation_files(base_path)
+    append_to_default_source(@name, @snake_name)
+    # append_to_newrelic_yml(@name, @snake_name) # This is now done on release, we don't need it anymore, but leaving it to be sure.
+    create_tests(name)
+  end
+
+  desc 'add_new_method NAME', 'Inserts a new method into an existing piece of instrumentation'
+
+  option :method, required: true, desc: 'The name of the method to instrument'
+  option :args, default: '*args', desc: 'The arguments associated with the instrumented method'
+
+  def add_new_method(name, method_name)
+    # Verify that existing instrumentation exists
+    # if it doesn't, should we just call the #scaffold method instead since we have all the stuff
+    # otherwise, inject the new method into the instrumentation matching the first arg
+    # add to only chain, instrumentation, prepend
+    # move the method content to a partial
+  end
+
+  private
+
+  def create_instrumentation_files(base_path)
+    %w[chain instrumentation prepend].each do |file|
+      template("templates/#{file}.tt", "#{base_path}/#{file}.rb")
+    end
+
+    template('templates/dependency_detection.tt', "#{base_path}.rb")
+  end
+
+  def create_tests(name)
+    @name = name
+    @instrumentation_method_global_erb_snippet = '<%= $instrumentation_method %>'
+    @snake_name = snake_name(@name)
+    base_path = "#{MULTIVERSE_SUITE_ROOT}#{@snake_name}"
+    empty_directory(base_path)
+    template('templates/Envfile.tt', "#{base_path}/Envfile")
+    template('templates/test.tt', "#{base_path}/#{@snake_name}_instrumentation_test.rb")
+
+    empty_directory("#{base_path}/config")
+    template('templates/newrelic.yml.tt', "#{base_path}/config/newrelic.yml")
+  end
+
+  def append_to_default_source(name, snake_name)
+    insert_into_file(
+      DEFAULT_SOURCE_LOCATION,
+      config_block(name, snake_name),
+      after: ":description => 'Controls auto-instrumentation of bunny at start-up. May be one of: `auto`, `prepend`, `chain`, `disabled`.'
+        },\n"
+    )
+  end
+
+  def append_to_newrelic_yml(name, snake_name)
+    insert_into_file(
+      NEWRELIC_YML_LOCATION,
+      yaml_block(name, snake_name),
+      after: "# instrumentation.bunny: auto\n"
+    )
+  end
+
+  def config_block(name, snake_name)
+    # Don't change to <<~
+    # We want to preserve the whitespace so the config is correctly indented
+    <<-CONFIG
+        :'instrumentation.#{snake_name}' => {
+          :default => 'auto',
+          :public => true,
+          :type => String,
+          :dynamic_name => true,
+          :allowed_from_server => false,
+          :description => 'Controls auto-instrumentation of the #{name} library at start-up. May be one of `auto`, `prepend`, `chain`, `disabled`.'
+        },
+    CONFIG
+  end
+
+  def yaml_block(name, snake_name)
+    <<~HEREDOC
+
+      # Controls auto-instrumentation of #{name} at start-up.
+      # May be one of [auto|prepend|chain|disabled]
+      # instrumentation.#{snake_name}: auto
+    HEREDOC
+  end
+
+  def snake_name(name)
+    name.downcase.tr('-', '_')
+  end
+end
+
+Instrumentation.start(ARGV)

data/lib/tasks/instrumentation_generator/templates/Envfile.tt

@@ -0,0 +1,9 @@
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
+
+instrumentation_methods :chain, :prepend
+
+gemfile <<~RB
+  gem '<%= @name.downcase %>'
+RB

data/lib/tasks/instrumentation_generator/templates/chain.tt

@@ -0,0 +1,21 @@
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
+
+module NewRelic::Agent::Instrumentation
+  module <%= @class_name %>::Chain
+    def self.instrument!
+      ::<%= @class_name %>.class_eval do
+        include NewRelic::Agent::Instrumentation::<%= @class_name %>
+
+        alias_method(:<%= @method.downcase %>_without_new_relic, :<%= @method.downcase %>)
+
+        def <%= @method.downcase %><%= "(#{@args})" unless @args.empty? %>
+          <%= @method.downcase %>_with_new_relic<%= "(#{@args})" unless @args.empty? %> do
+            <%= @method.downcase %>_without_new_relic<%= "(#{@args})" unless @args.empty? %>
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tasks/instrumentation_generator/templates/chain_method.tt

@@ -0,0 +1,7 @@
+alias_method(:<%= @method.downcase %>_without_new_relic, :<%= @method.downcase %>)
+
+def <%= @method.downcase %><%= "(#{@args})" unless @args.empty? %>
+  <%= @method.downcase %>_with_new_relic<%= "(#{@args})" unless @args.empty? %> do
+    <%= @method.downcase %>_without_new_relic<%= "(#{@args})" unless @args.empty? %>
+  end
+end

data/lib/tasks/instrumentation_generator/templates/dependency_detection.tt

@@ -0,0 +1,29 @@
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
+
+require_relative '<%= @snake_name.downcase %>/instrumentation'
+require_relative '<%= @snake_name.downcase %>/chain'
+require_relative '<%= @snake_name.downcase %>/prepend'
+
+DependencyDetection.defer do
+  named :<%= @name.match?(/\-|\_/) ? "'#{@snake_name}'" : @name.downcase %>
+
+  depends_on do
+    # The class that needs to be defined to prepend/chain onto. This can be used
+    # to determine whether the library is installed.
+    defined?(::<%= @class_name %>)
+    # Add any additional requirements to verify whether this instrumentation
+    # should be installed
+  end
+
+  executes do
+    ::NewRelic::Agent.logger.info('Installing <%= @name.downcase %> instrumentation')
+
+    if use_prepend?
+      prepend_instrument ::<%= @class_name %>, NewRelic::Agent::Instrumentation::<%= @class_name %>::Prepend
+    else
+      chain_instrument NewRelic::Agent::Instrumentation::<%= @class_name %>::Chain
+    end
+  end
+end

data/lib/tasks/instrumentation_generator/templates/instrumentation.tt

@@ -0,0 +1,13 @@
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
+
+module NewRelic::Agent::Instrumentation
+  module <%= @class_name %>
+
+    def <%= @method.downcase %>_with_new_relic<%= "(#{@args})" unless @args.empty? %>
+      # add instrumentation content here
+      yield
+    end
+  end
+end

data/lib/tasks/instrumentation_generator/templates/instrumentation_method.tt

@@ -0,0 +1,3 @@
+def <%= @method.downcase %>_with_new_relic<%= "(#{@args})" unless @args.empty? %>
+  # add instrumentation content here
+end

data/lib/tasks/instrumentation_generator/templates/newrelic.yml.tt

@@ -0,0 +1,19 @@
+---
+development:
+  error_collector:
+    enabled: true
+  apdex_t: 0.5
+  monitor_mode: true
+  license_key: bootstrap_newrelic_admin_license_key_000
+  instrumentation:
+    <%= @snake_name %>: <%= @instrumentation_method_global_erb_snippet %>
+  app_name: test
+  log_level: debug
+  host: 127.0.0.1
+  api_host: 127.0.0.1
+  transaction_trace:
+    record_sql: obfuscated
+    enabled: true
+    stack_trace_threshold: 0.5
+    transaction_threshold: 1.0
+  capture_params: false

data/lib/tasks/instrumentation_generator/templates/prepend.tt

@@ -0,0 +1,13 @@
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
+
+module NewRelic::Agent::Instrumentation
+  module <%= @class_name %>::Prepend
+    include NewRelic::Agent::Instrumentation::<%= @class_name %>
+
+    def <%= @method.downcase %><%= "(#{@args})" unless @args.empty? %>
+      <%= @method.downcase %>_with_new_relic<%= "(#{@args})" unless @args.empty? %> { super }
+    end
+  end
+end

data/lib/tasks/instrumentation_generator/templates/prepend_method.tt

@@ -0,0 +1,3 @@
+def <%= @method.downcase %><%= "(#{@args})" unless @args.empty? %>
+  <%= @method.downcase %>_with_new_relic<%= "(#{@args})" unless @args.empty? %> { super }
+end

data/lib/tasks/instrumentation_generator/templates/test.tt

@@ -0,0 +1,15 @@
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
+
+class <%= @class_name %>InstrumentationTest < Minitest::Test
+  def setup
+    @stats_engine = NewRelic::Agent.instance.stats_engine
+  end
+
+  def teardown
+    NewRelic::Agent.instance.stats_engine.clear_stats
+  end
+
+  # Add tests here
+end

data/lib/tasks/newrelic.rb

@@ -0,0 +1,10 @@
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
+
+#
+# If you are looking to instrument rake tasks in a Rails environment, but the
+# task doesn't depend on :environment, this task may be included to ensure that
+# the agent will load.
+
+NewRelic::Agent.manual_start(:sync_startup => false)

data/lib/tasks/newrelicyml.rake

@@ -0,0 +1,13 @@
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
+
+require_relative 'helpers/newrelicyml'
+
+namespace :newrelic do
+  desc 'Update newrelic.yml with latest config options from default_source.rb'
+  task :update_newrelicyml do
+    NewRelicYML.write_file
+    puts 'newrelic.yml updated'
+  end
+end

data/lib/tasks/tests.rake

@@ -1,36 +1,107 @@
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
+
+require_relative 'helpers/matches'
+include Matches
+
 begin
   require 'rake/testtask'
-rescue LoadError => e
+rescue LoadError
 end
 
 if defined? Rake::TestTask
-  namespace :test do |t|
-    def look_for_seed(tasks)
-      matches = tasks.map { |t| /(seed=.*?)[,\]]/.match(t) }.compact
-      if matches.any?
-        matches.first[1]
-      else
-        nil
+  def name_for_number(content, number)
+    (number - 1).downto(0).each do |i|
+      return Regexp.last_match(1) if content[i] =~ /^\s*def (test_.+)\s*$/
+    end
+  end
+
+  def info_from_test_var
+    return {} unless ENV['TEST'].to_s =~ /^(.+)((?::\d+)+)/
+
+    file = Regexp.last_match(1)
+    numbers = Regexp.last_match(2).split(':').reject(&:empty?).uniq.map(&:to_i)
+    abs = File.expand_path(File.join('../../..', file), __FILE__)
+    raise "File >>#{abs}<< does not exist!" unless File.exist?(abs)
+
+    content = File.read(abs).split("\n")
+    {file: file, numbers: numbers, content: content}
+  end
+
+  def test_names_from_test_file(info)
+    info[:numbers].each_with_object([]) do |number, names|
+      name = name_for_number(info[:content], number)
+      unless name
+        warn "Unable to determine a test name given line >>#{number}<< for file >>#{info[:file]}<<"
+        next
       end
+      names << name
     end
+  end
+
+  # Allow ENV['TEST'] to be set to a test file path with one or more
+  # `:<line number>` patterns on the end of it.
+  #
+  # For example:
+  #   TEST=test/new_relic/agent/autostart_test.rb:57 bundle exec rake test
+  #
+  # The `autostart_test.rb` file will be read, and starting from line 57 and
+  # working upwards in the file (downwards by line number), a test definition
+  # will be searched for that matches `def test_<rest of the test name>`.
+  #
+  # Multiple line numbers can be specified like so:
+  #   TEST=test/new_relic/agent/autostart_test.rb:57:26 bundle exec rake test
+  #
+  # For this multiple line number based example, both lines 57 and 26 will
+  # serve as separate starting points for the search for a test name.
+  #
+  # All test names that are discovered will be "ORed" into a regex pattern with
+  # pipes ('|') that is passed to Minitest via
+  #   `TESTOPTS="--name='test_name1|test_name2'"`
+  #
+  # Once a line with one or more `:<line number>` values on the end of it has
+  # been found, replace the value of ENV['TEST'] with the path leading up to
+  # the first colon before invoking Minitest.
+  #
+  # Why refer to a test by line number instead of just supplying the name
+  # directly? The primary use case is text editor integration. A text editor
+  # can be taught to "run the single unit test containing the line the cursor is
+  # on" by building a string containing the path to the file, a colon, (':'),
+  # and the line number.
+  def process_line_numbers
+    info = info_from_test_var
+    return unless info.key?(:file)
+
+    test_names = test_names_from_test_file(info)
+    raise "Could not determine any test names for file >>#{abs}<< given numbers >>#{numbers}" if test_names.empty?
+
+    ENV['TESTOPTS'] = "#{ENV['TESTOPTS']} --name='#{test_names.map { |n| Regexp.escape(n) }.join('|')}'"
+    ENV['TEST'] = info[:file]
+  end
 
+  namespace :test do
     tasks = Rake.application.top_level_tasks
-    ENV["TESTOPTS"] ||= ""
-    if tasks.any? { |t| t.include?("verbose")}
-      ENV["TESTOPTS"] += " -v"
+    ENV['TESTOPTS'] ||= ''
+    if tasks.any? { |t| t.include?('verbose') }
+      ENV['TESTOPTS'] += ' -v'
     end
     if seed = look_for_seed(tasks)
-      ENV["TESTOPTS"] += " --" + seed
+      ENV['TESTOPTS'] += ' --' + seed
     end
 
-    agent_home = File.expand_path(File.join(File.dirname(__FILE__),'..','..'))
+    process_line_numbers
+
+    agent_home = File.expand_path(File.join(File.dirname(__FILE__), '..', '..'))
 
     Rake::TestTask.new(:newrelic) do |t|
+      file_pattern = ENV['file']
+      file_pattern = file_pattern.split(',').map { |f| "#{agent_home}/#{f}".gsub('//', '/') } if file_pattern
+      file_pattern ||= "#{agent_home}/test/new_relic/**/*_test.rb"
+
       t.libs << "#{agent_home}/test"
       t.libs << "#{agent_home}/lib"
-      t.pattern = "#{agent_home}/test/new_relic/**/*_test.rb"
-      t.verbose = true
+      t.pattern = Array(file_pattern)
     end
-
   end
 end