newrelic_rpm 9.2.0 → 9.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1eb606235173b437a2991d23d5f23b7715ab8025263f134f11454dcadf0bac9e
-  data.tar.gz: 4e468d079bd47f57a7dd2185039dc15f29a139e278b5d133a5a0b08e301f85f0
+  metadata.gz: e5e1f4605a4afe166aa2035486a2433f91f4d0432666b787e6d9c5af9e5ee717
+  data.tar.gz: 16e7707b8c81774ea0c2bea54825d023c2849d0a03ab553e25800c131d9c2972
 SHA512:
-  metadata.gz: 11835787018b19326041e1f10f8a72befeb8ba9345e793ceb30e4cbd57b6ffa678da13f833fe05f17148b8beb6e9e77f4dc2ab7eda573ecc4aa62060e71ee05b
-  data.tar.gz: 1f0e60f9d9aef77edd656a6cc55b7e735cfbaf6a7006ed0724303b52d9cbb71bc740899de335ff45bece28f551bb0053a3077fee65863d5c355666c323150ac0
+  metadata.gz: 8180f7caa158ce2ea794914376f441f5f912f46fbce8caca074b8c2c9a06fb84ca5e290eab2aa63dfa68f5385e6f7f9f3ede8ee00ee97fbc30d692b93721ec8e
+  data.tar.gz: 21062253bf9236563dcd226ccc4e5e2f8d1fceaed24f6047fb6ed23f485f8b0e4607bbe9b7985c4a63809767c2f4b5785e4ec52c25ff6d2ac186ff7fb8a149f7

data/.build_ignore

@@ -0,0 +1,26 @@
+.github/
+.gitignore
+.project
+.rubocop.yml
+.rubocop_todo.yml
+.simplecov
+.snyk
+.yardopts
+Brewfile
+CONTRIBUTING.md
+Dockerfile
+DOCKER.md
+docker-compose.yml
+config/
+config.dot
+infinite_tracing/
+Guardfile
+lefthook.yml
+log/
+README.md
+test/
+lib/tasks/bump_version.rb
+lib/tasks/coverage_report.rb
+lib/tasks/multiverse.rake
+lib/tasks/multiverse.rb
+lib/tasks/tests.rb

data/CHANGELOG.md

@@ -1,15 +1,210 @@
 # New Relic Ruby Agent Release Notes
 
+## v9.5.0
+
+Version 9.5.0 introduces Stripe instrumentation, allows the agent to record additional response information on a transaction when middleware instrumentation is disabled, introduces new `:'sidekiq.args.include'` and `:'sidekiq.args.exclude:` configuration options to permit capturing only certain Sidekiq job arguments, updates Elasticsearch datastore instance metrics, and fixes a bug in `NewRelic::Rack::AgentHooks.needed?`.
+
+- **Feature: Add Stripe instrumentation**
+
+  [Stripe](https://stripe.com/) calls are now automatically instrumented. Additionally, new `:'stripe.user_data.include'` and `:'stripe.user_data.exclude'` configuration options permit capturing custom `user_data` key-value pairs that can be stored in [Stripe events](https://github.com/stripe/stripe-ruby#instrumentation). No `user_data` key-value pairs are captured by default. The agent currently supports Stripe versions 5.38.0+. [PR#2180](https://github.com/newrelic/newrelic-ruby-agent/pull/2180)
+
+- **Feature: Report transaction HTTP status codes when middleware instrumentation is disabled**
+
+  Previously, when `disable_middleware_instrumentation` was set to `true`, the agent would not record the value of the response code or content type on the transaction. This was due to the possibility that a middleware could alter the response, which would not be captured by the agent when the middleware instrumentation was disabled. However, based on customer feedback, the agent will now report the HTTP status code and content type on a transaction when middleware instrumentation is disabled. [PR#2175](https://github.com/newrelic/newrelic-ruby-agent/pull/2175)
+
+- **Feature: Permit capturing only certain Sidekiq job arguments**
+
+  New `:'sidekiq.args.include'` and `:'sidekiq.args.exclude'` configuration options have been introduced to permit fine grained control over which Sidekiq job arguments (args) are reported to New Relic. By default, no Sidekiq args are reported. To report any Sidekiq options, the `:'attributes.include'` array must include the string `'jobs.sidekiq.args.*'`. With that string in place, all arguments will be reported unless one or more of the new include/exclude options are used. The `:'sidekiq.args.include'` option can be set to an array of strings. Each of those strings will be passed to `Regexp.new` and collectively serve as an allowlist for desired args. For job arguments that are hashes, if a hash's key matches one of the include patterns, then both the key and its corresponding value will be included. For scalar arguments, the string representation of the scalar will need to match one of the include patterns to be captured. The `:'sidekiq.args.exclude'` option works similarly. It can be set to an array of strings that will each be passed to `Regexp.new` to create patterns. These patterns will collectively serve as a denylist for unwanted job args. Any hash key, hash value, or scalar that matches an exclude pattern will be excluded (not sent to New Relic). [PR#2177](https://github.com/newrelic/newrelic-ruby-agent/pull/2177)
+
+  `newrelic.yml` examples:
+
+  Any string in the `:'sidekiq.args.include'` or `:'sidekiq.args.exclude'` arrays will be turned into a regular expression. Knowledge of [Ruby regular expression support](https://ruby-doc.org/3.2.2/Regexp.html) can be leveraged but is not required. If regular expression syntax is not used, inexact matches will be performed and the string "Fortune" will match both "Fortune 500" and "Fortune and Glory". For exact matches, use [regular expression anchors](https://ruby-doc.org/3.2.2/Regexp.html#class-Regexp-label-Anchors).
+
+  ```yaml
+  # Include any argument whose string representation matches either "apple" or "banana"
+  # The "apple" pattern will match both "green apple" and "red apple"
+  sidekiq.args.include:
+    - apple
+    - banana
+
+  # Exclude any arguments that match either "grape", "orange", or "pear"
+  sidekiq.args.exclude:
+    - grape
+    - orange
+    - pear
+
+  # Exclude any argument that is a 9 digit number
+  sidekiq.args.exclude:
+    - '\d{9}'
+
+  # Include anything that starts with "blue" but exclude anything that ends in "green"
+  sidekiq.args.include
+    - '^blue'
+
+  sidekiq.args.exclude
+    - 'green$'
+  ```
+
+- **Bugfix: Update Elasticsearch datastore instance metric to use port instead of path**
+
+  Previously, the Elasticsearch datastore instance metric (`Datastore/instance/Elasticsearch/<host>/*`) used the path as the final value. This caused a [metrics grouping issue](https://docs.newrelic.com/docs/new-relic-solutions/solve-common-issues/troubleshooting/metric-grouping-issues) for some users, as every document ID created a unique metric. Now, the datastore instance metric has been updated to use the port as the final value. This also has the benefit of being more accurate for datastore instance metrics, as this port is directly associated with the already listed host.
+
+- **Bugfix: Resolve inverted logic of NewRelic::Rack::AgentHooks.needed?**
+
+  Previously, `NewRelic::Rack::AgentHooks.needed?` incorrectly used inverted logic. This has now been resolved, allowing AgentHooks to be installed when `disable_middleware_instrumentation` is set to true. [PR#2175](https://github.com/newrelic/newrelic-ruby-agent/pull/2175)
+
+
+## v9.4.2
+
+Version 9.4.2 of the agent re-addresses the 9.4.0 issue of `NoMethodError` seen when using the `uppy-s3_multipart` gem.
+
+- **Bugfix: Resolve NoMethodError**
+
+  Ruby agent 9.4.1 attempted to fix a `NoMethodError` introduced in 9.4.0. A missing `require` prevented a method from scoping appropriately and has now been added. Thanks to [@spickermann](https://github.com/spickermann) and [@ColinOrr](https://github.com/ColinOrr) for working with us to get this resolved. [PR#2167](https://github.com/newrelic/newrelic-ruby-agent/pull/2167)
+
+## v9.4.1
+
+Version 9.4.1 of the agent resolves a `NoMethodError` introduced in 9.4.0.
+
+- **Bugfix: Resolve NoMethodError**
+
+  Ruby agent 9.4.0 introduced [Roda instrumentation](https://github.com/newrelic/newrelic-ruby-agent/pull/2144), which caused a `NoMethodError` to be raised when attempting to name a Roda transaction. This has been fixed. Thanks to [@spickermann](https://github.com/spickermann) for reporting this issue. [PR#2167](https://github.com/newrelic/newrelic-ruby-agent/pull/2167)
+
+## v9.4.0
+
+Version 9.4.0 of the agent adds [Roda](https://roda.jeremyevans.net/) instrumentation, adds a new `allow_all_headers` configuration option to permit capturing all HTTP headers, introduces improved error tracking functionality by associating a transaction id with each error, and uses more reliable network timeout logic.
+
+- **Feature: Add Roda instrumentation**
+
+  [Roda](https://roda.jeremyevans.net/) is a now an instrumented framework. The agent currently supports Roda versions 3.19.0+. [PR#2144](https://github.com/newrelic/newrelic-ruby-agent/pull/2144)
+
+- **Feature: New allow_all_headers configuration option**
+
+  A new `allow_all_headers` configuration option brings parity with the [Node.js agent](https://docs.newrelic.com/docs/release-notes/agent-release-notes/nodejs-release-notes/node-agent-270/) to capture all HTTP request headers.
+
+  This configuration option:
+    * Defaults to `false`
+    * Is not compatible with high security mode
+    * Requires Rack version 2 or higher (as does Ruby on Rails version 5 and above)
+    * Respects all existing behavior for the `attributes.include` and `attributes.exclude` [configuration options](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration/#attributes)
+    * Captures the additional headers as attributes prefixed with `request.headers.`
+
+  This work was done in response to a feature request submitted by community member [@jamesarosen](https://github.com/jamesarosen). Thank you very much, @jamesarosen! [Issue#1029](https://github.com/newrelic/newrelic-ruby-agent/issues/1029)
+
+- **Feature: Improved error tracking transaction linking**
+
+  Errors tracked and sent to the New Relic errors inbox will now be associated with a transaction id to enable improved UI/UX associations between transactions and errors. [PR#2035](https://github.com/newrelic/newrelic-ruby-agent/pull/2035)
+
+- **Feature: Use Net::HTTP native timeout logic**
+
+  In line with current Ruby best practices, make use of Net::HTTP's own timeout logic and avoid the use of `Timeout.timeout()` when possible. The agent's data transmissions and cloud provider detection routines have been updated accordingly. [PR#2147](https://github.com/newrelic/newrelic-ruby-agent/pull/2147)
+
+## v9.3.1
+
+Version 9.3.1 of the agent fixes `NewRelic::Agent.require_test_helper`.
+
+- **Bugfix: Fix NewRelic::Agent.require_test_helper**
+
+  Version 9.3.0 of the agent made a change to the files distributed with the gem. This change unintentionally broke the `NewRelic::Agent.require_test_helper` API by removing the `test/agent_helper.rb` file. The file has been added back to the gem. This change also removes the `lib/new_relic/build.rb` file from the list because it is no longer created with our current release process.
+
+  Our thanks go to [@ajesler](https://github.com/ajesler) for reporting this issue and writing a test for the bug. [Issue#2113](https://github.com/newrelic/newrelic-ruby-agent/issues/2113), [PR#2115](https://github.com/newrelic/newrelic-ruby-agent/pull/2115), [Issue#2117](https://github.com/newrelic/newrelic-ruby-agent/issues/2117), [PR#2118](https://github.com/newrelic/newrelic-ruby-agent/pull/2118)
+
+- **Source Documentation: update the Rack spec URL**
+
+  Community member [@olleolleolle](https://github.com/olleolleolle) noticed that our source code was referencing a now defunct URL for the Rack specification and submitted [PR#2121](https://github.com/newrelic/newrelic-ruby-agent/pull/2121) to update it. He also provided a terrific recommendation that we automate the checking of links to proactively catch defunct ones in future. Thanks, @olleolleolle!
+
+## v9.3.0
+
+Version 9.3.0 of the agent adds log-level filtering, adds custom attributes for log events, and updates instrumentation for Action Cable. It also provides fixes for how `Fiber` args are treated, Code-Level Metrics, unnecessary files being included in the gem, and `NewRelic::Agent::Logging::DecoratingFormatter#clear_tags!` being incorrectly private.
+
+- **Feature: Filter forwarded logs based on level**
+
+  Previously, all log events, regardless of their level, were forwarded to New Relic when log forwarding was enabled. Now, you may specify the lowest log level you'd like forwarded to New Relic.
+
+  | Configuration name          | Default | Behavior                                               | Valid values |
+  | --------------------------- | ------- | ------------------------------------------------------ | ------ |
+  | `application_logging.forwarding.log_level` | `debug` | Sets the minimum log level for events forwarded to New Relic | `debug`, `info`, `warn`, `error`, `fatal`, `unknown` |
+
+  This setting uses [Ruby's Logger::Severity constants integer values](https://github.com/ruby/ruby/blob/master/lib/logger/severity.rb#L6-L17) to determine precedence.
+
+- **Feature: Custom attributes for logs**
+
+  You can now add custom attributes to log events forwarded to New Relic! You can pass these attributes using an API and/or a configuration option.
+
+  | Configuration name          | Default | Behavior                                               |
+  | --------------------------- | ------- | ------------------------------------------------------ |
+  | `application_logging.forwarding.custom_attributes` | `{}` | A hash with key/value pairs to add as custom attributes to all log events forwarded to New Relic. If sending using an environment variable, the value must be formatted like: "key1=value1,key2=value2" |
+
+
+  Call the API using `NewRelic::Agent.add_custom_log_attributes` and passing your attributes as a hash. For example, you could call: `NewRelic::Agent.add_custom_log_attributes(dyno: ENV['DYNO'], pod_name: ENV['POD_NAME'])`, to add the attributes `dyno` and `pod_name` to your log events.
+
+  Attributes passed to the API or the configuration will be added to all log events.
+
+  Thanks to [@rajpawar02](https://github.com/rajpawar02) for raising this issue and [@askreet](https://github.com/askreet) for helping us with the solution. [Issue#1141](https://github.com/newrelic/newrelic-ruby-agent/issues/1141), [PR#2084](https://github.com/newrelic/newrelic-ruby-agent/pull/2084), [PR#2087](https://github.com/newrelic/newrelic-ruby-agent/pull/2087)
+
+- **Feature: Instrument transmit_subscription-related Action Cable actions**
+
+  This change subscribes the agent to the Active Support notifications for:
+    * `transmit_subscription_confirmation.action_cable`
+    * `transmit_subscription_rejection.action_cable`
+
+- **Bugfix: Removed unwanted files from being included in file_list in gemspec**
+
+  Previously, the agent was including some files in the gem that were not needed but added to the size of the gem. These files will no longer be included. Thanks to [@manuraj17](https://github.com/manuraj17) for the contribution! [PR#2089](https://github.com/newrelic/newrelic-ruby-agent/pull/2089)
+
+- **Bugfix: Report Code-Level Metrics for Rails controller methods**
+
+  Controllers in Rails automatically render views with names that correspond to valid routes. This means that a controller method may not have a corresponding method in the controller class. Code-Level Metrics now report on these methods and don't log false warnings. Thanks to [@jcrisp](https://github.com/jcrisp) for reporting this issue. [PR#2061](https://github.com/newrelic/newrelic-ruby-agent/pull/2061)
+
+- **Bugfix: Code-Level Metrics for ActiveRecord models**
+
+  Classes that inherit from ActiveRecord were not reporting Code-Level Metrics due to an error in the agent when identifying the class name. This has been fixed and Code-Level Metrics will now report for ActiveRecord models. Thanks to [@abigail-rolling](https://github.com/abigail-rolling) for reporting this issue. [PR#2092](https://github.com/newrelic/newrelic-ruby-agent/pull/2092).
+
+- **Bugfix: Private method `clear_tags!` for NewRelic::Agent::Logging::DecoratingFormatter**
+
+  As part of a refactor included in a previous release of the agent, the method `NewRelic::Agent::Logging::DecoratingFormatter#clear_tags!` was incorrectly made private. This method is now public again. Thanks to [@dark-panda](https://github.com/dark-panda) for reporting this issue. [PR#](https://github.com/newrelic/newrelic-ruby-agent/pull/2078)
+
+- **Bugfix: Fix the way args are handled for Fibers**
+
+  Previously, the agent treated Fiber args the same as it was treating Thread args, which is not correct. Args are passed to `Fiber#resume`, and not `Fiber.new`. This has been fixed, and the agent will properly preserve args for both Fiber and Thread classes. This also caused an error to occur when using Async 2.6.2, due to mismatching initalize definitions for Fiber prepended modules. This has been fixed as well. Thanks to [@travisbell](https://github.com/travisbell) for bringing this to our attention. [PR#2083](https://github.com/newrelic/newrelic-ruby-agent/pull/2083)
+
+## v9.2.2
+
+  Version 9.2.2 of the agent fixes a bug with the `Transaction#finished?` method.
+
+- **Bugfix: Transaction#finished? no longer throws a NoMethodError when initial_segment is nil**
+
+  This change adds a safe navigation operator to `Transaction#finished?` to prevent `NoMethodErrors` when a transaction does not have any segments. Our thanks goes to [@JulienDefrance](https://github.com/JulienDefrance) for reporting this issue. [PR#1983](https://github.com/newrelic/newrelic-ruby-agent/pull/1983)
+
+## v9.2.1
+
+  Version 9.2.1 fixes a bug causing the agent to continue storing data on finished transactions, and a bug preventing errors from being expected.
+
+- **Bugfix: Finished transactions continue to store data on different threads**
+
+  Previously, when a new thread was spawned the agent would continue using the current transaction to record data on, even if this transaction had finished already in a different thread. Now the agent will only use the current transaction in the new thread if it is not yet finished. Thank you to [@fcheung](https://github.com/fcheung) for reporting this bug and providing us with an extremely helpful reproduction to debug. [PR#1969](https://github.com/newrelic/newrelic-ruby-agent/pull/1969)
+
+
+- **Bugfix: Expected Errors passed to notice_error are expected again**
+
+  A bug was introduced in 9.1.0 that caused to agent not to mark errors as expected if the error was passed in to `notice_error` using the `expected: true` parameter. This has been fixed and errors will now be marked as expected, as expected. Thank you very much to [@eiskrenkov](https://github.com/eiskrenkov) for finding this bug and contributing a fix for it! [PR#1954](https://github.com/newrelic/newrelic-ruby-agent/pull/1954)
+
+
+
 ## v9.2.0
 
   Version 9.2.0 of the agent introduces some performance improvements for working with high numbers of nested actions, and deprecates instrumentation for the `memcached` and `memcache-client` gems (with `dalli` still being supported).
 
 - **Feature: Enhance performance for handling high numbers of nested actions**
 
-  With [Issue#1910](https://github.com/newrelic/newrelic-ruby-agent/issues/1910) community members [@parkerfinch](https://github.com/parkerfinch) and [@travisbell](https://github.com/travisbell) informed us of some CPU spikes and process hangs seen only when using the agent's thread instrumentation, which was enabled by default with v9.0. When thread instrumentation is enabled, instrumented actions taking place within threads are seen and reported on by the agent whereas they would have previously gone unnoticed. This is a great improvement to the agent's usefulness in an async context, and also makes it easier for higher numbers of nested actions to be observed. 
-  For example, if an instrumented background job framework (Sidekiq, Resque) kicks off a job that the agent notices and then that job in turn performs actions such as database queries that the agent also instruments, nested actions are seen. However, with very high (10,000+) numbers of actions nested within a single instrumented outer action, the agent would struggle to efficiently crunch through all of the collected data at the time when the outer action finished. 
+  With [Issue#1910](https://github.com/newrelic/newrelic-ruby-agent/issues/1910) community members [@parkerfinch](https://github.com/parkerfinch) and [@travisbell](https://github.com/travisbell) informed us of some CPU spikes and process hangs seen only when using the agent's thread instrumentation, which was enabled by default with v9.0. When thread instrumentation is enabled, instrumented actions taking place within threads are seen and reported on by the agent whereas they would have previously gone unnoticed. This is a great improvement to the agent's usefulness in an async context, and also makes it easier for higher numbers of nested actions to be observed.
+  For example, if an instrumented background job framework (Sidekiq, Resque) kicks off a job that the agent notices and then that job in turn performs actions such as database queries that the agent also instruments, nested actions are seen. However, with very high (10,000+) numbers of actions nested within a single instrumented outer action, the agent would struggle to efficiently crunch through all of the collected data at the time when the outer action finished.
   The agent should now be much more efficient when any observed action with lots of nested actions is finished. Our performance testing was conducted with hundreds of thousands of nested actions taking place, and we hope that the benefits of thread tracing can now be enjoyed without any drawbacks. Thanks very much [@parkerfinch](https://github.com/parkerfinch) and [@travisbell](https://github.com/travisbell)! [PR#1927](https://github.com/newrelic/newrelic-ruby-agent/pull/1927)
 
+- **Feature: The agent configuration will now reflect whether module prepending or method chaining was used for instrumentation**
+
+  For `:'instrumentation.*'` configuration parameters that are set to :auto (the default), the agent will automatically determine whether to use module prepending or method chaining. The agent will now update its in-memory configuration to give each relevant parameter a value of either :prepend or :chain so that the result of the determination can be introspected. This is intended to help 3rd party libraries that wish to further enhance the agent's instrumentation capabilities by prepending or chaining additional logic. Environment variable, YAML file, and server-side configuration based values are not impacted. [PR#1930](https://github.com/newrelic/newrelic-ruby-agent/pull/1930)
+
 - **Feature: Deprecate memcached and memcache-client instrumentation**
 
   Instrumentation for the memcached and memcache-client libraries is deprecated and will be removed during the next major release.

data/README.md

@@ -9,7 +9,7 @@ You can also extend the agent's performance monitoring to
 to help you improve the customer experience and make data-driven business decisions.
 
 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).
+hosted on [GitHub](https://github.com/newrelic/newrelic-ruby-agent).
 
 This code is actively maintained by New Relic engineering teams and delivered here in GitHub. See below for troubleshooting and defect reporting instructions.
 
@@ -25,7 +25,7 @@ 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)
+The latest released gem for the Ruby agent can be found at [RubyGems.org](https://rubygems.org/gems/newrelic_rpm)
 
 ### Quick Start
 
@@ -88,7 +88,7 @@ for more information.
 
 Should you need assistance with New Relic products, you are in good hands with several support diagnostic tools and support channels.
 
-This [troubleshooting framework](https://discuss.newrelic.com/t/ruby-troubleshooting-framework-install/108685) steps you through common troubleshooting questions.
+This [troubleshooting framework](https://forum.newrelic.com/s/hubtopic/aAX8W0000008bSgWAI/ruby-troubleshooting-framework-install) steps you through common troubleshooting questions.
 
 New Relic offers NRDiag, [a client-side diagnostic utility](https://docs.newrelic.com/docs/using-new-relic/cross-product-functions/troubleshooting/new-relic-diagnostics) that automatically detects common problems with New Relic agents. If NRDiag detects a problem, it suggests troubleshooting steps. NRDiag can also automatically attach troubleshooting data to a New Relic Support ticket.
 
@@ -97,7 +97,7 @@ If the issue has been confirmed as a bug or is a Feature request, please file a
 **Support Channels**
 
 * [New Relic Documentation](https://docs.newrelic.com/docs/agents/ruby-agent): Comprehensive guidance for using our platform
-* [New Relic Community](https://discuss.newrelic.com/tags/rubyagent): The best place to engage in troubleshooting questions
+* [New Relic Community](https://forum.newrelic.com): The best place to engage in troubleshooting questions
 * [New Relic Developer](https://developer.newrelic.com/): Resources for building a custom observability applications
 * [New Relic University](https://learn.newrelic.com/): A range of online training for New Relic users of every level
 * [New Relic Technical Support](https://support.newrelic.com/) 24/7/365 ticketed support. Read more about our [Technical Support Offerings](https://docs.newrelic.com/docs/licenses/license-information/general-usage-licenses/support-plan).
@@ -134,6 +134,10 @@ The New Relic Ruby agent may use source code from third-party libraries. When us
 
 ## Thank You
 
+We always look forward to connecting with the community. We welcome [contributions](https://github.com/newrelic/newrelic-ruby-agent#contributing) to our source code and suggestions for improvements, and would love to hear about what you like and want to see in the future. 
+
+Visit our [project board](https://github.com/orgs/newrelic/projects/84/) to see what's upcoming in a future release, what we're currently working on, and what we're planning next.
+
 Thank you,
 
 New Relic Ruby agent team

data/lib/new_relic/agent/attribute_pre_filtering.rb

@@ -0,0 +1,109 @@
+# 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
+  module Agent
+    module AttributePreFiltering
+      module_function
+
+      PRE_FILTER_KEYS = %i[include exclude].freeze
+      DISCARDED = :nr_discarded
+
+      def formulate_regexp_union(option)
+        return if NewRelic::Agent.config[option].empty?
+
+        Regexp.union(NewRelic::Agent.config[option].map { |p| string_to_regexp(p) }.uniq.compact).freeze
+      rescue StandardError => e
+        NewRelic::Agent.logger.warn("Failed to formulate a Regexp union from the '#{option}' configuration option " +
+                                    "- #{e.class}: #{e.message}")
+      end
+
+      def string_to_regexp(str)
+        Regexp.new(str)
+      rescue StandardError => e
+        NewRelic::Agent.logger.warn("Failed to initialize Regexp from string '#{str}' - #{e.class}: #{e.message}")
+      end
+
+      # attribute filtering suppresses data that has already been flattened
+      # and coerced (serialized as text) via #flatten_and_coerce, and is
+      # restricted to basic text matching with a single optional wildcard.
+      # pre filtering operates on raw Ruby objects beforehand and uses full
+      # Ruby regex syntax
+      def pre_filter(values = [], options = {})
+        return values unless !options.empty? && PRE_FILTER_KEYS.any? { |k| options.key?(k) }
+
+        # if there's a prefix in play for (non-pre) attribute filtration and
+        # attribute filtration won't allow that prefix, then don't even bother
+        # with pre filtration that could only result in values that would be
+        # blocked
+        if options.key?(:attribute_namespace) &&
+            !NewRelic::Agent.instance.attribute_filter.might_allow_prefix?(options[:attribute_namespace])
+          return values
+        end
+
+        values.each_with_object([]) do |element, filtered|
+          object = pre_filter_object(element, options)
+          filtered << object unless discarded?(object)
+        end
+      end
+
+      def pre_filter_object(object, options)
+        if object.is_a?(Hash)
+          pre_filter_hash(object, options)
+        elsif object.is_a?(Array)
+          pre_filter_array(object, options)
+        else
+          pre_filter_scalar(object, options)
+        end
+      end
+
+      def pre_filter_hash(hash, options)
+        filtered_hash = hash.each_with_object({}) do |(key, value), filtered|
+          filtered_key = pre_filter_object(key, options)
+          next if discarded?(filtered_key)
+
+          # If the key is permitted, skip include filtration for the value
+          # but still apply exclude filtration
+          if options.key?(:exclude)
+            exclude_only = options.dup
+            exclude_only.delete(:include)
+            filtered_value = pre_filter_object(value, exclude_only)
+            next if discarded?(filtered_value)
+          else
+            filtered_value = value
+          end
+
+          filtered[filtered_key] = filtered_value
+        end
+
+        filtered_hash.empty? && !hash.empty? ? DISCARDED : filtered_hash
+      end
+
+      def pre_filter_array(array, options)
+        filtered_array = array.each_with_object([]) do |element, filtered|
+          filtered_element = pre_filter_object(element, options)
+          next if discarded?(filtered_element)
+
+          filtered.push(filtered_element)
+        end
+
+        filtered_array.empty? && !array.empty? ? DISCARDED : filtered_array
+      end
+
+      def pre_filter_scalar(scalar, options)
+        return DISCARDED if options.key?(:include) && !scalar.to_s.match?(options[:include])
+        return DISCARDED if options.key?(:exclude) && scalar.to_s.match?(options[:exclude])
+
+        scalar
+      end
+
+      # `nil`, empty enumerable objects, and `false` are all valid in their
+      # own right as application data, so pre-filtering uses a special value
+      # to indicate that filtered out data has been discarded
+      def discarded?(object)
+        object == DISCARDED
+      end
+    end
+  end
+end