Merge pull request #780 from newrelic/el-docs-update

Updated text

CHANGELOG.md

@@ -25,16 +25,15 @@
 
   * **Distributed tracing is enabled by default**
 
-    [Distributed tracing](https://docs.newrelic.com/docs/distributed-tracing/enable-configure/language-agents-enable-distributed-tracing/) tracks and observes service requests as they flow through distributed systems. This is preferred over [cross application tracing](https://docs.newrelic.com/docs/agents/ruby-agent/features/cross-application-tracing-ruby/).
+    [Distributed tracing](https://docs.newrelic.com/docs/distributed-tracing/enable-configure/language-agents-enable-distributed-tracing/) tracks and observes service requests as they flow through distributed systems. Distributed tracing is now enabled by default and replaces [cross application tracing](https://docs.newrelic.com/docs/agents/ruby-agent/features/cross-application-tracing-ruby/).
 
   * **Bugfix: Incorrectly loading configuration options from newrelic.yml**
 
     The agent will now  import the configuration options [`error_collector.ignore_messages`](https://docs.newrelic.com/docs/agents/ruby-agent/configuration/ruby-agent-configuration/#error_collector-ignore_messages) and [`error_collector.expected_messages`](https://docs.newrelic.com/docs/agents/ruby-agent/configuration/ruby-agent-configuration/#error_collector-expected_messages) from the `newrelic.yml` file correctly.
 
+  * **Cross Application is now deprecated, and disabled by default**
 
-  * **Deprecate cross application tracing**
-
-    [Cross application tracing](https://docs.newrelic.com/docs/agents/ruby-agent/features/cross-application-tracing-ruby/) (CAT) is deprecated in favor of [distributed tracing](https://docs.newrelic.com/docs/distributed-tracing/enable-configure/language-agents-enable-distributed-tracing/) and is off by default.
+    [Distributed tracing](https://docs.newrelic.com/docs/distributed-tracing/enable-configure/language-agents-enable-distributed-tracing/) is replacing [cross application tracing](https://docs.newrelic.com/docs/agents/ruby-agent/features/cross-application-tracing-ruby/) as the default means of tracing between services. To continue using it, enable it with `cross_application_tracer.enabled: true` and `distributed_tracing.enabled: false`
 
   * **Update configuration option default value for `span_events.max_samples_stored` from 1000 to 2000**
 
@@ -47,9 +46,9 @@
   * **Remove Ruby 2.0 required kwarg compatibility checks**
 
     Our agent has code that provides compatibility for required keyword arguments in Ruby versions below 2.1. Since the agent now only supports Ruby 2.2+, this code is no longer required.
-    
+
   * **Replace Time.now with Process.clock_gettime**
-  
+
     Calls to `Time.now` have been replaced with calls to `Process.clock_gettime` to leverage the system's built-in clocks for elapsed time (`Process::CLOCK_MONOTONIC`) and wall-clock time (`Process::CLOCK_REALTIME`). This results in fewer object allocations, more accurate elapsed time records, and enhanced performance. Thanks to @sdemjanenko and @viraptor for advocating for this change!
 
   * **Updated generated default newrelic.yml**

lib/new_relic/agent/monitors/cross_app_monitor.rb

@@ -24,11 +24,7 @@ class CrossAppMonitor < InboundRequestMonitor
         def on_finished_configuring(events)
           Deprecator.deprecate('cross_application_tracer')
           ::NewRelic::Agent.logger.warn(
-            "[DEPRECATED] Cross application tracing is enabled. It has been \
-            deprecated in favor of distributed tracing and will be removed in a\
-             future release. Start using distrubted tracing by removing the \
-             'cross_application_tracer.enabled' configuration and setting \
-             'distributed_tracing.enabled' to true."
+            "[DEPRECATED] Cross application tracing is enabled. Distributed tracing is replacing cross application tracing as the default means of tracing between services. To continue using cross application tracing, enable it with `cross_application_tracer.enabled: true` and `distributed_tracing.enabled: false`"
           )
 
           register_event_listeners(events)

newrelic.yml

@@ -78,9 +78,9 @@ common: &default_settings
 # instrument. For example, assets:precompile,db:migrate.
 # autostart.denylisted_rake_tasks: "about,assets:clean,assets:clobber,assets:environment,assets:precompile,assets:precompile:all,db:create,db:drop,db:fixtures:load,db:migrate,db:migrate:status,db:rollback,db:schema:cache:clear,db:schema:cache:dump,db:schema:dump,db:schema:load,db:seed,db:setup,db:structure:dump,db:version,doc:app,log:clear,middleware,notes,notes:custom,rails:template,rails:update,routes,secret,spec,spec:features,spec:requests,spec:controllers,spec:helpers,spec:models,spec:views,spec:routing,spec:rcov,stats,test,test:all,test:all:db,test:recent,test:single,test:uncommitted,time:zones:all,tmp:clear,tmp:create,webpacker:compile"
 
-# Backports the faster ActiveRecord connection lookup introduced in Rails 6,
-# which improves agent performance when instrumenting ActiveRecord. Note that
-# this setting may not be compatible with other gems that patch ActiveRecord.
+# Backports the faster Active Record connection lookup introduced in Rails 6,
+# which improves agent performance when instrumenting Active Record. Note that
+# this setting may not be compatible with other gems that patch Active Record.
 # backport_fast_active_record_connection_lookup: false
 
 # If true, the agent captures attributes from browser monitoring.
@@ -115,7 +115,7 @@ common: &default_settings
 # capture_params setting, the Ruby agent will not attempt to filter secret
 # information. Recommendation: To filter secret information from request
 # parameters,use the attributes.include setting instead. For more information,
-# see the Ruby attributeexamples.
+# see the Ruby attribute examples.
 # capture_params: false
 
 # If true, the agent will clear Tracer::State in Agent.drop_buffered_data.
@@ -126,10 +126,14 @@ common: &default_settings
 # and $HOME/newrelic.yml.
 # config_path: newrelic.yml
 
-# If true, enables cross-application tracing.
+# If true, enables cross application tracing. Cross application tracing is now
+# deprecated, and disabled by default. Distributed tracing is replacing cross
+# application tracing as the default means of tracing between services.
+# To continue using it, set `cross_application_tracer.enabled: true` and
+# `distributed_tracing.enabled: false`
 # cross_application_tracer.enabled: false
 
-# If false, custom attributes will not be sent on Insights events.
+# If false, custom attributes will not be sent on New Relic Insights events.
 # custom_attributes.enabled: true
 
 # If true, the agent captures New Relic Insights custom events.
@@ -150,16 +154,16 @@ common: &default_settings
 # If true, disables Action Cable instrumentation.
 # disable_action_cable_instrumentation: false
 
-# If true, disables instrumentation for ActiveRecord 4, 5, and 6.
+# If true, disables instrumentation for Active Record 4, 5, and 6.
 # disable_active_record_notifications: false
 
-# If true, disables ActiveStorage instrumentation.
+# If true, disables Active Storage instrumentation.
 # disable_active_storage: false
 
-# If true, disables ActiveJob instrumentation.
+# If true, disables Active Job instrumentation.
 # disable_activejob: false
 
-# If true, disables active record instrumentation.
+# If true, disables Active Record instrumentation.
 # disable_active_record_instrumentation: false
 
 # If true, the agent won't sample the CPU usage of the host process.
@@ -193,7 +197,7 @@ common: &default_settings
 # disable_sidekiq: false
 
 # If true, disables agent middleware for Sinatra. This middleware is responsible
-# for advanced feature support such as cross application tracing, page load
+# for advanced feature support such as distributed tracing, page load
 # timing, and error collection.
 # disable_sinatra_auto_middleware: false
 
@@ -203,11 +207,9 @@ common: &default_settings
 # If true, the agent won't sample performance measurements from the Ruby VM.
 # disable_vm_sampler: false
 
-# Distributed tracing lets you see the path that a request takes through your
-# distributed system. Enabling distributed tracing changes the behavior of some
-# New Relic features, so carefully consult the transition guide before you
-# enable this feature.
-# distributed_tracing.enabled: false
+# Distributed tracing tracks and observes service requests as they flow through distributed systems.
+# With distributed tracing data, you can quickly pinpoint failures or performance issues and fix them.
+# distributed_tracing.enabled: true
 
 # The Entity GUID for the entity that is running this agent.
 # entity_guid: nil
@@ -274,7 +276,7 @@ common: &default_settings
 
 # Forces the exit handler that sends all cached data to collector before
 # shutting down to be installed regardless of detecting scenarios where it
-# generally should bot be.Known use-case for this option is where Sinatra is
+# generally should bot be. Known use-case for this option is where Sinatra is
 # running as an embedded service within another framework and the agent is
 # detecting the Sinatra app and skipping the at_exit handler as a result.
 # Sinatra classically runs the entire application in an at_exit block and would
@@ -293,7 +295,7 @@ common: &default_settings
 
 # If true, enables high security mode. Ensure that you understand the
 # implication of enabling high security mode before enabling this setting.
-# https://docs.# newrelic.com/docs/agents/manage-apm-agents/configuration/high-security-mode/
+# https://docs.newrelic.com/docs/agents/manage-apm-agents/configuration/high-security-mode/
 # high_security: false
 
 # Configures the hostname for the Trace Observer Host. When configured, enables
@@ -325,11 +327,11 @@ common: &default_settings
 # instrumentation.grape: auto
 
 # Controls auto-instrumentation of HTTPClient at start up.
-# May be one of [auto|# prepend|chain|disabled].
+# May be one of [auto|prepend|chain|disabled].
 # instrumentation.httpclient: auto
 
 # Controls auto-instrumentation of http.rb gem at start up.
-# May be one of [auto|# prepend|chain|disabled].
+# May be one of [auto|prepend|chain|disabled].
 # instrumentation.httprb: auto
 
 # Controls auto-instrumentation of memcache-client gem for Memcache at start up.
@@ -345,11 +347,11 @@ common: &default_settings
 # instrumentation.memcached: auto
 
 # Controls auto-instrumentation of Mongo at start up.
-# May be one of [enabled|# disabled].
+# May be one of [enabled|disabled].
 # instrumentation.mongo: auto
 
 # Controls auto-instrumentation of Net::HTTP at start up.
-# May be one of [auto|# prepend|chain|disabled].
+# May be one of [auto|prepend|chain|disabled].
 # instrumentation.net_http: auto
 
 # Controls auto-instrumentation of Puma::Rack::URLMap at start up.
@@ -362,7 +364,7 @@ common: &default_settings
 # instrumentation.puma_rack: auto
 
 # Controls auto-instrumentation of Rack::URLMap at start up.
-# May be one of [auto|# prepend|chain|disabled].
+# May be one of [auto|prepend|chain|disabled].
 # instrumentation.rack_urlmap: auto
 
 # Controls auto-instrumentation of Rack. When enabled, the agent hooks into the
@@ -371,23 +373,23 @@ common: &default_settings
 # instrumentation.rack: auto
 
 # Controls auto-instrumentation of rake at start up.
-# May be one of [auto|prepend|# chain|disabled].
+# May be one of [auto|prepend|chain|disabled].
 # instrumentation.rake: auto
 
 # Controls auto-instrumentation of Redis at start up.
-# May be one of [auto|prepend|# chain|disabled].
+# May be one of [auto|prepend|chain|disabled].
 # instrumentation.redis: auto
 
 # Controls auto-instrumentation of resque at start up.
-# May be one of [auto|# prepend|chain|disabled].
+# May be one of [auto|prepend|chain|disabled].
 # instrumentation.resque: auto
 
 # Controls auto-instrumentation of Sinatra at start up.
-# May be one of [auto|# prepend|chain|disabled].
+# May be one of [auto|prepend|chain|disabled].
 # instrumentation.sinatra: auto
 
 # Controls auto-instrumentation of Typhoeus at start up.
-# May be one of [auto|# prepend|chain|disabled].
+# May be one of [auto|prepend|chain|disabled].
 # instrumentation.typhoeus: auto
 
 # A dictionary of label names and values that will be applied to the data sent
@@ -419,7 +421,7 @@ common: &default_settings
 # When true, the agent transmits data about your app to the New Relic collector.
 # monitor_mode: true
 
-# If true, uses Module#prepend rather than alias_method for ActiveRecord
+# If true, uses Module#prepend rather than alias_method for Active Record
 # instrumentation.
 # prepend_active_record_instrumentation: false
 
@@ -473,7 +475,7 @@ common: &default_settings
 # slow_sql.explain_threshold: 1.0
 
 # Defines an obfuscation level for slow SQL queries.
-# Valid options are obfuscated, raw, or none).
+# Valid options are obfuscated, raw, or none.
 # slow_sql.record_sql: none
 
 # Generate a longer sql_id for slow SQL traces. sql_id is used for aggregation
@@ -484,7 +486,9 @@ common: &default_settings
 # span_events_attributes.enabled: true
 
 # Defines the maximum number of span events reported from a single harvest.
-# span_events_max_samples_stored: 1000
+# This can be any integer between 1 and 10000. Increasing this value may impact
+# memory usage.
+# span_events.max_samples_stored: 2000
 
 # Prefix of attributes to exclude from span events. Allows * as wildcard at end.
 # span_events.attributes.exclude: []
@@ -574,10 +578,10 @@ common: &default_settings
 # Obfuscation level for SQL queries reported in transaction trace nodes.
 # By default, this is set to obfuscated, which strips out the numeric and string
 # literals. If you do not want the agent to capture query information, set this
-# to : none: . If you want the agent to capture all query information in its
-# original form, set this to : raw: . When you enable [high security mode](/docs/# agents/manage-apm-agents/configuration/high-security-mode), this is
-# automatically set to : obfuscated:
-# transaction_tracer.record_sql: "obfuscated"
+# to 'none'. If you want the agent to capture all query information in its
+# original form, set this to 'raw'. When you enable high security mode this is
+# automatically set to 'obfuscated'
+# transaction_tracer.record_sql: 'obfuscated'
 
 # Specify a threshold in seconds. The agent includes stack traces in transaction
 # trace nodes when the stack trace duration exceeds this threshold.