newrelic_rpm 7.0.0 → 8.8.0

data/DOCKER.md

@@ -0,0 +1,167 @@
+# Using Docker with the New Relic Ruby Agent
+
+These instructions will guide you through the process of setting up Docker for
+use with developing the New Relic Ruby Agent. The use of Docker containers can
+provide for a consistent experience free from machine specific issues.
+
+## Quick Start
+
+```shell
+# unit tests (Ruby only)
+$ docker build -t newrelic_rpm .
+$ docker run --rm newrelic_rpm
+
+# or
+
+# functional tests (MySQL, PostgreSQL, Redis, etc.)
+$ docker-compose up
+$ docker-compose exec app bundle exec rake test:all
+```
+
+
+## Install Docker
+
+You will need to have [Docker Desktop](https://www.docker.com/) installed and
+running on your machine.
+
+If you are using on macOS and using [Homebrew](https://brew.sh/), Docker can be
+installed as a cask via:
+
+```shell
+$ brew install --cask docker
+```
+
+and then launched via the `/Applications/Docker.app` launcher that is installed.
+
+For alternatives to using macOS with Homebrew, see Docker's
+[Get Started Guide](https://www.docker.com/get-started).
+
+
+## Clone the project
+
+Use git to clone the [newrelic/newrelic-ruby-agent](https://github.com/newrelic/newrelic-ruby-agent)
+project.
+
+The [Dockerfile](Dockerfile) and [docker-compose.yml](docker-compose.yml)
+files are located in the root of the project, where this `DOCKER.md`
+document resides.
+
+
+## Using just the Dockerfile (unit tests and standalone dev only)
+
+The project `Dockerfile` can be used by itself to run the project unit tests.
+Docker Compose and the project `docker-compose.yml` file will be needed to
+run functional tests which involve communicating with data systems such as
+PostgreSQL and Redis.
+
+To run the unit tests using `Dockerfile` by itself, first change
+directories to the root of the project, then build an image, and
+finally run a container from the image:
+
+```shell
+$ cd /path/to/project/git/clone
+$ docker build -t newrelic_rpm .
+$ docker run --rm newrelic_rpm
+```
+
+The `Dockerfile` specifies a default Ruby version to test with. To override this
+version, pass the `ruby_version` build arg like so when building the image:
+
+```shell
+docker build --build-arg ruby_version=2.7 .
+```
+
+**Legend:**
+* `build -t <TAG>` applies a tag to the image during building.
+* `.` indicates "here" and tells Docker that the `Dockerfile` file can be found
+  in the current directory
+* `run --rm` tells Docker to remove the container after the tests complete.
+* `--build-arg ruby_version=<RUBY VERSION>` specifies that a given Ruby version should be used (use MAJOR.MINOR or optionally MAJOR.MINOR.PATCH)
+
+
+## Using Docker Compose (for functional tests and developing with services)
+
+Docker Compose launches multiple containers simultaneously to support the
+running of the functional tests that require a variety of data handling
+server applications such as PostgreSQL, Redis, memcached, etc. Each one of
+these server applications uses its own container and then there's a Ruby
+container (referred to as the "app" container) that runs the Minitest tests
+while connecting to the other containers.
+
+In one shell session, change to the root of the project and then bring up all
+containers with Docker Compose:
+
+```shell
+$ docker-compose up
+```
+
+By default, `docker-compose` will use the default Ruby version specified in the
+`Dockerfile` file. To override this version with a custom desired version, set
+the `RUBY_VERSION` environment variable before calling `docker-compose`,
+like so:
+
+```shell
+RUBY_VERSION=3.0 docker-compose up
+```
+
+In a separate shell session (probably in a separate terminal split, tab, or
+window), execute the 'test:all' rake task to test all standard, environment,
+and multiverse tests:
+
+```shell
+$ docker-compose exec app bundle exec rake test:all
+```
+
+In lieu of running the tests, an interactive Bash shell can be
+launched against the running Ruby app container for development and/or
+debugging. While the `docker-compose up` shell session is still running,
+bring up an additional local shell session and run the following:
+
+```shell
+$ docker-compose exec app bash
+```
+
+You will be dropped at a Bash prompt as the "relic" user, with "ruby" and
+"bundle" in your PATH.
+
+
+## Output
+
+When using Docker Compose, one shell session will produce STDOUT output that
+pertains to all of the services (MySQL, MongoDB, etc.) and the other shell
+session will produce STDOUT output related to the Ruby based functional tests.
+Both streams of output may provide information about any errors or warnings
+that take place.
+
+
+## Cleanup
+
+If the project `Dockerfile` is being used without Docker Compose, then use
+`docker ps` to show information about containers and `docker images`
+for information about images. The `docker stop`, `docker kill`, `docker rm`
+and `docker rmi` commands can be used with the appropriate container and image
+ids. Run `docker --help` or read through the hosted [CLI documentation](https://docs.docker.com/engine/reference/commandline/docker/).
+
+When Docker Compose is used, invoking `ctrl-c` in the shell session that is
+running the `docker-compose up` command should suffice to prompt Docker Compose
+to shut down all running containers. Otherwise, `docker-compose down` can be
+ran after the `docker-compose up` process has been stopped. All relevant
+containers and images can then be optionally discarded using the `docker` CLI
+commands described in the previous paragraph.
+
+Use `docker ps -a` to show a list of all containers. Pass a container id to
+`docker rm` (ex: `docker rm 5c15ee2f1c4f`) to remove it.
+
+Use `docker images` to show a list of all images. Typically, you'll want to
+keep these images if you plan on running Docker with them again in the future.
+If you are done with them, you can pass an image id to `docker rmi` to remove
+an image (ex: `docker rmi 4253856b2570`).
+
+## Questions, Feature Requests, Contributions, etc.
+
+The maintainers of New Relic's Ruby agent project are hopeful that the use of
+containers and these instructions can provide consistency and a lowered barrier
+of entry when it comes to providing contributions to the agent project itself.
+
+For questions, feature requests, proposals to support Podman, PRs to improve
+behavior or documentation, etc., please see [CONTRIBUTING.md](CONTRIBUTING.md).

data/Dockerfile

@@ -0,0 +1,10 @@
+ARG ruby_version=3.1
+
+FROM ruby:$ruby_version
+
+WORKDIR /usr/src/app
+
+COPY . .
+RUN bundle install
+
+CMD ["bundle", "exec", "rake"]

data/Guardfile

@@ -1,24 +1,24 @@
 require './test/multiverse/lib/multiverse/bundler_patch'
 
-test_folders = Dir.glob("test/new_relic/*").select{|f| File.directory?(f)}
-test_folders += Dir.glob("test/new_relic/**/*").select{|f| File.directory?(f)}
+test_folders = Dir.glob("test/new_relic/*").select { |f| File.directory?(f) }
+test_folders += Dir.glob("test/new_relic/**/*").select { |f| File.directory?(f) }
 
-rake_lib_path = Bundler.with_unbundled_env{ `bundle exec gem which rake`.chomp.gsub("lib/rake.rb", "lib") }
-ruby_options = %{-w -I"#{rake_lib_path}" "#{rake_lib_path}/rake/rake_test_loader.rb"}
+rake_lib_path = Bundler.with_unbundled_env { `bundle exec gem which rake`.chomp.gsub("lib/rake.rb", "lib") }
+ruby_options = %(-w -I"#{rake_lib_path}" "#{rake_lib_path}/rake/rake_test_loader.rb")
 
 guard_options = {
   spring: "bundle exec ruby #{ruby_options} ",
-  test_folders: ['test/new_relic'] + test_folders, 
+  test_folders: ['test/new_relic'] + test_folders,
   all_after_pass: false,
   all_on_start: false
 }
 
 guard :minitest, guard_options do
-  watch(%r{^lib/(.+)\.rb$})     { |m| "test/#{m[1]}_test.rb" }
+  watch(%r{^lib/(.+)\.rb$}) { |m| "test/#{m[1]}_test.rb" }
   watch(%r{^test/.+_test\.rb$})
-  watch(%r{^test/rum/.*})       { "test/new_relic/rack/browser_monitoring_test.rb" }
+  watch(%r{^test/rum/.*}) { "test/new_relic/rack/browser_monitoring_test.rb" }
   watch(%r{^test/fixtures/cross_agent_tests/distributed_tracing/(.+).json}) { |m| "test/new_relic/agent/distributed_tracing/#{m[1]}_cross_agent_test.rb" }
-  watch('test/test_helper.rb')  { "test/new_relic" }
+  watch('test/test_helper.rb') { "test/new_relic" }
   watch('test/agent_helper.rb') { "test/new_relic" }
   watch('lib/new_relic/agent/configuration/default_source.rb') { "test/new_relic/agent/configuration/orphan_configuration_test.rb" }
   watch(%r{^lib/new_relic/agent/transaction/(.+).rb}) { |m| "test/new_relic/agent/distributed_tracing/#{m[1]}_cross_agent_test.rb" }

data/LICENSE

@@ -175,10 +175,6 @@
 
    END OF TERMS AND CONDITIONS
 
-   Versions 6.12.0 and above for this project are licensed under 
-   Apache 2.0.  For prior versions of this project, please see the 
-   LICENSE file in the root directory of that version for more information.
-
    APPENDIX: How to apply the Apache License to your work.
 
       To apply the Apache License to your work, attach the following
@@ -204,5 +200,3 @@
    See the License for the specific language governing permissions and
    limitations under the License.
 
-
-

data/README.md

@@ -1,4 +1,4 @@
-[![Community Plus header](https://github.com/newrelic/opensource-website/raw/master/src/images/categories/Community_Plus.png)](https://opensource.newrelic.com/oss-category/#community-plus)
+[![Blue banner - Community Plus: This code is currently maintained by New Relic engineering teams and delivered here in GitHub. See the README for troubleshooting and defect reporting instructions.](https://github.com/newrelic/opensource-website/raw/master/src/images/categories/Community_Plus.png)](https://opensource.newrelic.com/oss-category/#community-plus)
 
 # New Relic Ruby Agent
 
@@ -8,9 +8,11 @@ You can also extend the agent's performance monitoring to
 [collect and analyze business data](https://docs.newrelic.com/docs/agents/ruby-agent/getting-started/introduction-new-relic-ruby#business-data)
 to help you improve the customer experience and make data-driven business decisions.
 
-The New Relic Ruby Agent is dual-purposed as a either a Gem or a Rails plugin,
+The New Relic Ruby agent is dual-purposed as either a Gem or a Rails plugin,
 hosted on [github](https://github.com/newrelic/newrelic-ruby-agent).
 
+[![Gem Version](https://badge.fury.io/rb/newrelic_rpm.svg)](https://badge.fury.io/rb/newrelic_rpm)
+
 ## Supported Environments
 
 An up-to-date list of Ruby versions and frameworks for the latest agent
@@ -21,11 +23,13 @@ Environments" section below.
 
 ## Installing and Using
 
+The latest released gem for the Ruby agent can be found at [Rubygems.org](https://rubygems.org/gems/newrelic_rpm)
+
 ### Quick Start
 
 #### With Bundler
 
-For using with Bundler, add the Ruby Agent to your project's Gemfile.
+For using with Bundler, add the Ruby agent to your project's Gemfile.
 
 ```ruby
 gem 'newrelic_rpm'
@@ -67,16 +71,18 @@ For complete documentation on installing the New Relic Ruby agent, see the follo
 * [GAE Flexible Environment](https://docs.newrelic.com/docs/agents/ruby-agent/installation/install-new-relic-ruby-agent-gae-flexible-environment)
 * [Pure Rack Apps](http://docs.newrelic.com/docs/ruby/rack-middlewares)
 * [Ruby agent and Heroku](https://docs.newrelic.com/docs/agents/ruby-agent/installation/ruby-agent-heroku)
-* [Background Jobs](https://docs.newrelic.com/docs/agents/ruby-agent/background-jobs)
+* [Background Jobs](https://docs.newrelic.com/docs/agents/ruby-agent/background-jobs/monitor-ruby-background-processes)
 * [Uninstall the Ruby agent](https://docs.newrelic.com/docs/agents/ruby-agent/installation/uninstall-ruby-agent)
 
 ### Recording Deploys
 
-The Ruby Agent supports recording deployments in New Relic via a command line
-tool or Capistrano recipes. For more information on these features see
+The Ruby agent supports* recording deployments in New Relic via a command line
+tool or Capistrano recipes. For more information on these features, see
 [our deployment documentation](http://docs.newrelic.com/docs/ruby/recording-deployments-with-the-ruby-agent)
 for more information.
 
+*There is a [known issue](https://github.com/newrelic/newrelic-ruby-agent/issues/715) that prevents newly generated New Relic API keys from recording deploys.
+
 ## Support
 
 Should you need assistance with New Relic products, you are in good hands with several support diagnostic tools and support channels.
@@ -99,17 +105,14 @@ If the issue has been confirmed as a bug or is a Feature request, please file a
 
 At New Relic we take your privacy and the security of your information seriously, and are committed to protecting your information. We must emphasize the importance of not sharing personal data in public forums, and ask all users to scrub logs and diagnostic information for sensitive information, whether personal, proprietary, or otherwise.
 
-We define “Personal Data” as any information relating to an identified or identifiable individual, including, for example, your name, phone number, post code or zip code, Device ID, IP address and email address.
+We define “Personal Data” as any information relating to an identified or identifiable individual, including, for example, your name, phone number, post code or zip code, Device ID, IP address, and email address.
 
 Please review [New Relic’s General Data Privacy Notice](https://newrelic.com/termsandconditions/privacy) for more information.
 
-## Roadmap
-See our [roadmap](https://github.com/newrelic/newrelic-ruby-agent/blob/main/ROADMAP.md), to learn more about our product vision, understand our plans, and provide us valuable feedback.
-
 ## Contributing
 
-We encourage contributions to improve the New Relic Ruby agent! Keep in mind when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project.
-If you have any questions, or to execute our corporate CLA, required if your contribution is on behalf of a company,  please drop us an email at opensource@newrelic.com.
+We encourage contributions to improve the New Relic Ruby agent! Keep in mind when you submit your pull request, you'll need to sign the Contributor License Agreement (CLA) via the click-through using CLA-Assistant. You only have to sign the CLA one time per project.
+If you have any questions, or to execute our corporate CLA (required if your contribution is on behalf of a company), please drop us an email at opensource@newrelic.com.
 
 **A note about vulnerabilities**
 
@@ -124,13 +127,12 @@ the [New Relic Ruby agent](https://opensource.newrelic.com/projects/newrelic/new
 
 ## License
 
-The New Relic Ruby agent is licensed under the [Apache 2.0](http://apache.org/licenses/LICENSE-2.0.txt) License.
-The New Relic Ruby agent also uses source code from third-party libraries. Full details on which libraries are used and the terms under which they are licensed can be found in the [THIRD_PARTY_NOTICES.md](https://github.com/newrelic/newrelic-ruby-agent/blob/main/THIRD_PARTY_NOTICES.md).
+As of version 6.12 (released July 16, 2020), the New Relic Ruby agent is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for a copy of the license. For older agent versions, check the LICENSE file included with the source code.
 
-## Thank You
+The New Relic Ruby agent may use source code from third-party libraries. When used, these libraries will be outlined in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
 
-Thank you, and may your application scale to infinity plus one.
+## Thank You
 
-Lew Cirne, Founder and CEO
+Thank you,
 
-New Relic, Inc.
+New Relic Ruby agent team

data/Rakefile

@@ -10,16 +10,7 @@ task :test => ['test:newrelic']
 
 namespace :test do
   desc "Run all tests"
-  task :all => %w{newrelic multiverse}
-
-  begin
-    require 'test_bisect'
-    TestBisect::BisectTask.new do |t|
-      t.test_task_name = 'test:newrelic'
-    end
-  rescue LoadError
-  end
-
+  task :all => %w[newrelic multiverse all_compatible_envs]
   agent_home = File.expand_path(File.dirname(__FILE__))
 
   desc "Run agent performance tests"
@@ -27,14 +18,21 @@ namespace :test do
     require File.expand_path(File.join(File.dirname(__FILE__), 'test', 'performance', 'lib', 'performance'))
     options = {}
     options[:suite] = args[:suite] if args[:suite]
-    options[:name]  = args[:name]  if args[:name]
+    options[:name] = args[:name] if args[:name]
     Performance::Runner.new(options).run_and_report
   end
 
-  desc "Run agent within existing mini environments"
-  task :env, [:env1, :env2, :env3, :env4, :env5, :env6] => [] do |t, args|
+  desc "Run agent within existing mini environment(s): env[name1,name2,name3,etc.]"
+  task :env do |t, args|
     require File.expand_path(File.join(File.dirname(__FILE__), 'test', 'environments', 'lib', 'environments', 'runner'))
-    Environments::Runner.new(args.map{|_,v| v}).run_and_report
+    Environments::Runner.new(args.to_a).run_and_report
+  end
+
+  desc "Run all mini environment tests known to work with the current Ruby version"
+  task :all_compatible_envs do |t, args|
+    require File.expand_path(File.join(File.dirname(__FILE__), 'test', 'helpers', 'ruby_rails_mappings'))
+    rails_versions = rails_versions_for_ruby_version(RUBY_VERSION)
+    Rake::Task['test:env'].invoke(*rails_versions)
   end
 
   Rake::TestTask.new(:intentional_fail) do |t|
@@ -51,15 +49,14 @@ namespace :test do
 
   # Note unit testing task is defined in lib/tasks/tests.rake to facilitate
   # running them in a rails application environment.
-
 end
 
 desc 'Record build number and stage'
-task :record_build, [ :build_number, :stage ] do |t, args|
+task :record_build, [:build_number, :stage] do |t, args|
   build_string = args.build_number
   build_string << ".#{args.stage}" unless args.stage.nil? || args.stage.empty?
 
-  gitsha = File.exists?(".git") ? `git rev-parse HEAD` : "Unknown"
+  gitsha = File.exist?(".git") ? `git rev-parse HEAD` : "Unknown"
   gitsha.chomp!
 
   File.open("lib/new_relic/build.rb", "w") do |f|
@@ -110,24 +107,38 @@ task :update_ca_bundle do |t|
 end
 
 namespace :cross_agent_tests do
-  cross_agent_tests_upstream_path = File.expand_path(File.join(File.dirname(__FILE__), '..', 'cross_agent_tests'))
-  cross_agent_tests_local_path    = File.expand_path(File.join(File.dirname(__FILE__), 'test', 'fixtures', 'cross_agent_tests'))
+  CROSS_AGENT_TESTS_UPSTREAM_PATH = File.expand_path(File.join('..', 'cross_agent_tests')).freeze
+  CROSS_AGENT_TESTS_LOCAL_PATH = File.expand_path(File.join('test', 'fixtures', 'cross_agent_tests')).freeze
+
+  def prompt_to_continue(command, destination = 'local')
+    puts "The following rsync command will be executed to update the #{destination} copy of the specs:"
+    puts
+    puts command
+    puts
+    puts "CAUTION: Any unsaved changes that exist within the #{destination} content will be OVERWRITTEN!"
+    if destination.eql?('local')
+      puts 'CAUTION 2: Before continuing, make sure your local repo is on the correct, synced branch!'
+    end
+    puts
+    print "Do you wish to continue? ('y' to continue, return to cancel) [n] "
+    continue = STDIN.gets.chomp
+    if continue.downcase.eql?('y')
+      system(command)
+    else
+      puts 'Cancelled'
+    end
+  end
 
-  # Note: before you pull, make sure your local repo is on the correct, synced branch!
   desc 'Pull latest changes from cross_agent_tests repo'
   task :pull do
-    puts "Updating embedded cross_agent_tests from #{cross_agent_tests_upstream_path}..."
-    cmd = "rsync -avu --exclude .git #{cross_agent_tests_upstream_path}/ #{cross_agent_tests_local_path}/"
-    puts cmd
-    system(cmd)
+    command = "  rsync -av --exclude .git #{CROSS_AGENT_TESTS_UPSTREAM_PATH}/ #{CROSS_AGENT_TESTS_LOCAL_PATH}/"
+    prompt_to_continue(command)
   end
 
   desc 'Copy changes from embedded cross_agent_tests to official repo working copy'
   task :push do
-    puts "Copying changes from embedded cross_agent_tests to #{cross_agent_tests_upstream_path}..."
-    cmd = "rsync -avu #{cross_agent_tests_local_path}/ #{cross_agent_tests_upstream_path}/"
-    puts cmd
-    system(cmd)
+    command = "rsync -av #{CROSS_AGENT_TESTS_LOCAL_PATH}/ #{CROSS_AGENT_TESTS_UPSTREAM_PATH}/"
+    prompt_to_continue(command, 'remote (agent spec repo)')
   end
 end
 
@@ -137,4 +148,3 @@ task :console do
   ARGV.clear
   Pry.start
 end
-