newrelic_rpm 6.15.0 → 9.7.1

data/lib/tasks/helpers/config.html.erb

@@ -0,0 +1,114 @@
+---
+title: Ruby agent configuration
+tags:
+  - Agents
+  - Ruby agent
+  - Configuration
+metaDescription: 'APM for Ruby: how to configure the Ruby agent, including editing the config file and setting environment variables.'
+redirects:
+  - /docs/agents/ruby-agent/configuration/ruby-agent-configuration
+  - /docs/ruby/ruby-agent-configuration
+  - /docs/agents/ruby-agent/installation-and-configuration/ruby-agent-configuration
+  - /docs/agents/ruby-agent/installation-configuration/ruby-agent-configuration
+---
+
+<CONTRIBUTOR_NOTE>
+  This file is automatically generated from values defined in `lib/new_relic/agent/configuration/default_source.rb`.
+  Make all changes directly to `default_source.rb.`
+  Submit PRs or raise issues at: https://github.com/newrelic/newrelic-ruby-agent
+</CONTRIBUTOR_NOTE>
+
+You can configure the New Relic Ruby agent with settings in a configuration file, environment variables, or programmatically with server-side configuration. This document summarizes the configuration options available for the Ruby agent.
+
+If the default value for a configuration option is `(Dynamic)`, this means the Ruby agent calculates the default at runtime. The value for the config setting defaults to the value of another setting as appropriate.
+
+## Configuration methods and precedence [#Options]
+
+The primary (default) method to configure the Ruby agent is via the configuration file (`newrelic.yml`) in the `config` subdirectory. To set configuration values using environment variables:
+
+1. Add the prefix `NEW_RELIC_` to the setting's name.
+2. Replace any periods `.` with underscores `_`.
+
+You can also configure a few values in the UI via [server-side configuration](/docs/agents/manage-apm-agents/configuration/server-side-agent-configuration).
+
+The Ruby agent follows this order of precedence for configuration:
+
+1. Environment variables
+2. Server-side configuration
+3. Configuration file (`newrelic.yml`)
+4. Default configuration settings
+
+In other words, environment variables override all other configuration settings and info, server-side configuration overrides the configuration file and default config settings, and so on.
+
+## View and edit config file options [#Edit]
+
+The Ruby agent's `newrelic.yml` is a standard YAML configuration file. It typically includes a `Defaults` section at the top, plus sections below for each application environment (`Development`, `Test`, `Staging`, and `Production`).
+
+The Ruby agent determines which section of the `newrelic.yml` config file to read from by looking at certain environment variables to derive the application's environment. This can be useful when you want to use `info` for the `log_level` config setting in your production environment, and you want more verbose `log_level` config settings (such as `debug`) in your development environment.
+
+Here is an example `newrelic.yml` config file:
+
+```yaml
+common: &default_settings
+  license_key: 'YOUR_LICENSE_KEY'
+  app_name: 'My Application Name'
+production:
+  <<: *default_settings
+  log_level: info
+development:
+  <<: *default_settings
+  log_level: debug
+```
+
+The Ruby agent looks for the following environment variables, in this order, to find the application environment:
+
+1. `NEW_RELIC_ENV`
+2. `RUBY_ENV`
+3. `RAILS_ENV`
+4. `APP_ENV`
+5. `RACK_ENV`
+
+If the Ruby agent doesn't detect values for any of those environment variables, it will default the application environment to `development` and read from the `development` section of the `newrelic.yml` config file.
+
+When running the Ruby agent in a Rails app, the agent first looks for the `NEW_RELIC_ENV` environment variable to determine the application environment and which section of the `newrelic.yml` to use. If `NEW_RELIC_ENV` is not present, the agent uses the Rails environment (`RAILS_ENV`).
+
+When you edit the config file, be sure to:
+
+* Indent only with two spaces.
+* Indent only where relevant, in stanzas such as **`error_collector`**.
+
+If you do not indent correctly, the agent may throw an `Unable to parse configuration file` error on startup.
+
+To view the most current list of available Ruby agent configuration options, use the `rake newrelic:config:docs` command. This document describes the most common options.
+
+## Update the config file [#Updates]
+
+This documentation applies to the Ruby agent's latest release. For details on earlier versions, refer to the comments in `newrelic.yml` itself.
+
+To update `newrelic.yml` file after a new release, use the template in the base directory of the agent gem. When you update to new gem versions, examine or diff `config/newrelic.yml` and `newrelic.yml` in the [installation directory](/docs/agents/manage-apm-agents/troubleshooting/find-agent-root-directory#ruby-agent) to take advantage of new configuration options.
+
+<Callout variant="important">
+  Updating the gem does not automatically update `config/newrelic.yml`.
+</Callout>
+
+<% sections.each do |(section_key, section_name, section_description, configs)| %>
+## <%=section_name%>
+
+<%= "#{section_description}" unless section_description.nil? %>
+
+<CollapserGroup>
+  <% configs.each do |config|%>
+  <Collapser id="<%= config[:key].gsub('.', '-') %>" title="<%=config[:key]%>">
+    <table>
+      <tbody>
+        <tr><th>Type</th><td><%=config[:type]%></td></tr>
+        <tr><th>Default</th><td>`<%=config[:default]%>`</td></tr>
+        <tr><th>Environ variable</th><td>`<%=config[:env_var]%>`</td></tr>
+      </tbody>
+    </table>
+
+  <%=config[:description]%>
+  </Collapser>
+  <% end %>
+</CollapserGroup>
+<% end %>

data/lib/tasks/helpers/format.rb

@@ -0,0 +1,127 @@
+# 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 Format
+  DEFAULT_CONFIG_PATH = 'ruby-agent-configuration.mdx'
+
+  def output(format)
+    result = build_erb(format).result(binding).split("\n").map(&:rstrip).join("\n").gsub('.  ', '. ')
+    File.write(DEFAULT_CONFIG_PATH, result)
+  end
+
+  private
+
+  def sections
+    @sections ||= flatten_config_hash(build_config_hash)
+  end
+
+  def add_data_to_sections(sections)
+    sections.each do |section|
+      section_key = section[0]
+      section.insert(1, format_name(section_key))
+      section.insert(2, SECTION_DESCRIPTIONS[section_key])
+    end
+  end
+
+  def build_config_hash
+    sections = Hash.new { |hash, key| hash[key] = [] }
+    NewRelic::Agent::Configuration::DEFAULTS.each do |key, value|
+      next unless value[:public]
+
+      key = key.to_s
+      section_key = section_key(key, key.split('.'))
+      sections[section_key] << format_sections(key, value)
+    end
+    sections
+  end
+
+  def build_erb(format)
+    require 'erb'
+    path = File.join(File.dirname(__FILE__), "config.#{format}.erb")
+    template = File.read(File.expand_path(path))
+    ERB.new(template)
+  end
+
+  def flatten_config_hash(config_hash)
+    sections = []
+    config = [GENERAL, 'transaction_tracer', 'error_collector',
+      'browser_monitoring', 'transaction_events',
+      'application_logging']
+
+    config.each { |config| sections << pluck(config, config_hash) }
+
+    sections.concat(config_hash.to_a.sort_by { |a| a.first })
+    add_data_to_sections(sections)
+
+    sections
+  end
+
+  def format_default_value(spec)
+    return spec[:documentation_default] if !spec[:documentation_default].nil?
+
+    if spec[:default].is_a?(Proc)
+      '(Dynamic)'
+    else
+      "#{spec[:default].inspect}"
+    end
+  end
+
+  def format_description(value)
+    description = ''
+    description += '**DEPRECATED** ' if value[:deprecated]
+    description += value[:description]
+    description
+  end
+
+  def format_env_var(key)
+    return 'None' if NON_ENV_CONFIGS.include?(key)
+
+    "NEW_RELIC_#{key.tr('.', '_').upcase}"
+  end
+
+  def format_name(key)
+    name = NAME_OVERRIDES[key]
+    return name if name
+
+    title = key.split('_')
+      .each { |fragment| fragment[0] = fragment[0].upcase }
+      .join(' ')
+    "#{title} [##{key.tr('_', '-')}]"
+  end
+
+  def format_sections(key, value)
+    {
+      :key => key,
+      :type => format_type(value[:type]),
+      :description => format_description(value),
+      :default => format_default_value(value),
+      :env_var => format_env_var(key)
+    }
+  end
+
+  def format_type(type)
+    if type == NewRelic::Agent::Configuration::Boolean
+      'Boolean'
+    else
+      type
+    end
+  end
+
+  def pluck(key, config_hash)
+    value = config_hash.delete(key)
+    [key, value]
+  end
+
+  def section_key(key, components)
+    if /^disable_/.match?(key) # "disable_httpclient"
+      DISABLING
+    elsif components.length >= 2 && !(components[1] == 'attributes') # "analytics_events.enabled"
+      components.first
+    elsif components[1] == 'attributes' # "transaction_tracer.attributes.enabled"
+      ATTRIBUTES
+    else
+      GENERAL
+    end
+  end
+end

data/lib/tasks/helpers/matches.rb

@@ -0,0 +1,12 @@
+# 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 Matches
+  def look_for_seed(tasks)
+    matches = tasks.map { |t| /(seed=.*?)[,\]]/.match(t) }.compact
+    if matches.any?
+      matches.first[1]
+    end
+  end
+end

data/lib/tasks/helpers/newrelicyml.rb

@@ -0,0 +1,144 @@
+# 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/agent/configuration/default_source'
+
+module NewRelicYML
+  CRITICAL = [:'agent_enabled', :'app_name', :'license_key', :'log_level']
+  DEFAULTS = NewRelic::Agent::Configuration::DEFAULTS
+  # Skip because not configurable via yml
+  SKIP = [:'defer_rails_initialization']
+  # Don't evaluate Procs, instead use set values
+  PROCS = {:'config_path' => 'newrelic.yml',
+           :'process_host.display_name' => 'default hostname',
+           :'transaction_tracer.transaction_threshold' => 1.0}
+
+  HEADER = <<~HEADER
+    #
+    # This file configures the New Relic agent.  New Relic monitors Ruby, Java,
+    # .NET, PHP, Python, Node, and Go applications with deep visibility and low
+    # overhead.  For more information, visit www.newrelic.com.
+
+    # Generated <%= Time.now.strftime('%B %d, %Y') %><%= ", for version \#{@agent_version}" if @agent_version %>
+    #<%= "\\n# \#{generated_for_user}\\n#" if generated_for_user %>
+    # For full documentation of agent configuration options, please refer to
+    # https://docs.newrelic.com/docs/agents/ruby-agent/installation-configuration/ruby-agent-configuration
+
+    common: &default_settings
+      # Required license key associated with your New Relic account.
+      license_key: <%= license_key %>
+
+      # Your application name. Renaming here affects where data displays in New
+      # Relic. For more details, see https://docs.newrelic.com/docs/apm/new-relic-apm/maintenance/renaming-applications
+      app_name: <%= app_name %>
+
+      # To disable the agent regardless of other settings, uncomment the following:
+      # agent_enabled: false
+
+      # Logging level for log/newrelic_agent.log; options are error, warn, info, or
+      # debug.
+      log_level: info
+
+      # All of the following configuration options are optional. Review them, and
+      # uncomment or edit them if they appear relevant to your application needs.
+
+  HEADER
+
+  FOOTER = <<~FOOTER
+    # Environment-specific settings are in this section.
+    # RAILS_ENV or RACK_ENV (as appropriate) is used to determine the environment.
+    # If your application has other named environments, configure them here.
+    development:
+      <<: *default_settings
+      app_name: <%= app_name %> (Development)
+
+    test:
+      <<: *default_settings
+      # It doesn't make sense to report to New Relic from automated test runs.
+      monitor_mode: false
+
+    staging:
+      <<: *default_settings
+      app_name: <%= app_name %> (Staging)
+
+    production:
+      <<: *default_settings
+  FOOTER
+
+  def self.get_configs(defaults)
+    defaults.sort.each_with_object({}) do |(key, value), final_configs|
+      next if CRITICAL.include?(key) || SKIP.include?(key)
+
+      next unless public_config?(value) && !deprecated?(value)
+
+      sanitized_description = sanitize_description(value[:description])
+      description = format_description(sanitized_description)
+      default = default_value(key, value)
+      final_configs[key] = {description: description, default: default}
+    end
+  end
+
+  def self.public_config?(value)
+    value[:public] == true
+  end
+
+  def self.deprecated?(value)
+    value[:deprecated] == true
+  end
+
+  def self.sanitize_description(description)
+    # remove callouts
+    description = description.split("\n").reject { |line| line.match?('</?Callout') }.join("\n")
+    # remove InlinePopover, keep the text inside type
+    description.gsub!(/<InlinePopover type="(.*)" \/>/, '\1')
+    # remove hyperlinks
+    description.gsub!(/\[([^\]]+)\]\([^\)]+\)/, '\1')
+    # remove single pairs of backticks
+    description.gsub!(/`([^`]+)`/, '\1')
+    # removed href links
+    description.gsub!(/<a href="(.*)">(.*)<\/a>/, '\2')
+
+    description
+  end
+
+  def self.format_description(description)
+    # remove leading and trailing whitespace
+    description.strip!
+    # wrap text after 80 characters
+    description.gsub!(/(.{1,80})(\s+|\Z)/, "\\1\n")
+    # add hashtags to lines
+    description = description.split("\n").map { |line| "  # #{line}" }.join("\n")
+
+    description
+  end
+
+  def self.default_value(key, config_hash)
+    if PROCS.include?(key)
+      PROCS[key]
+    else
+      default = config_hash[:documentation_default].nil? ? config_hash[:default] : config_hash[:documentation_default]
+      default = 'nil' if default.nil?
+      default = '""' if default == ''
+
+      default
+    end
+  end
+
+  def self.build_string(defaults)
+    configs = get_configs(defaults)
+    yml_string = ''
+
+    configs.each do |key, value|
+      yml_string += "#{value[:description]}\n  # #{key}: #{value[:default]}\n\n"
+    end
+
+    yml_string
+  end
+
+  # :nocov:
+  def self.write_file(defaults = DEFAULTS)
+    File.write('newrelic.yml', HEADER + build_string(defaults) + FOOTER)
+  end
+  # :nocov:
+end

data/lib/tasks/helpers/prompt.rb

@@ -0,0 +1,24 @@
+# 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 Prompt
+  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.casecmp('y') == 0
+      system(command)
+    else
+      puts 'Cancelled'
+    end
+  end
+end

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