Merge pull request #200 from solarwinds/NH-113148-docs

NH-113148 docs

Author: cheempz

CONFIGURATION.md

@@ -70,7 +70,7 @@ ENV['OTEL_RUBY_INSTRUMENTATION_MYSQL2_CONFIG_OPTS'] = 'db_statement=include;'
 
 ## Programmatic Configuration
 
-Many OpenTelemetry instrumentation library configurations can be set within the `SolarWindsAPM::OTelConfig.initialize_with_config ... end` block, please consult the individual [instrumentation](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation) README pages for the options available. Note this takes lower precedence than the [environment varable](#instrumentation-libraries) settings.
+Many OpenTelemetry instrumentation library configurations can be set within the `SolarWindsAPM::OTelNativeConfig.initialize_with_config ... end` block, please consult the individual [instrumentation](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation) README pages for the options available. Note this takes lower precedence than the [environment varable](#instrumentation-libraries) settings.
 
 > [!IMPORTANT]
 > this feature is only enabled if auto-config is disabled via `SW_APM_AUTO_CONFIGURE=false`.
@@ -159,7 +159,7 @@ SELECT * FROM SAMPLE_TABLE WHERE user_id = 1; /* traceparent=7435a9fe510ae453341
 
 #### Limitation
 
-> [!NOTE]  
+> [!NOTE]
 > This feature currently does not support prepared statements. For `mysql2` the `query` operation is supported, for `pg` the "[exec-ish](https://github.com/solarwinds/apm-ruby/blob/main/lib/solarwinds_apm/patch/tag_sql/sw_pg_patch.rb#L15)" operations like `exec` and `query` are supported.
 
 ### Background Jobs
@@ -180,4 +180,14 @@ Explanation:
 
 * `RUN_AT_EXIT_HOOKS`: This option, provided by Resque, ensures that the forked processes shut down gracefully (i.e., no immediate `exit!`). This allows the background processes that handle signal (trace, metrics, etc.) transmission to complete their tasks.
 
-Additionally, you need to configure the Resque initializer in your Rails application by adding the following code to `config/initializers/resque.rb`. It's recommended to have a upper bound time (e.g. 8 seconds) to avoid infinited loop if something wrong with `solarwinds_apm` initialization.
+### Proxy
+
+Starting with version 7.0.0, the environment variable `SW_APM_PROXY` and configuration file option `:http_proxy` are deprecated since telemetry is exported with standard OTLP exporters. These exporters use Ruby's `Net::HTTP`, which supports configuring an [HTTP proxy](https://docs.ruby-lang.org/en/master/Net/HTTP.html#class-Net::HTTPSession-label-Proxy+Server). The examples below set the `http_proxy` environment variable for the Ruby process to configure the proxy:
+
+```bash
+# proxy server with no authentication
+http_proxy=http://<proxyHost>:<proxyPort> ruby my.app
+
+# proxy server that requires basic authentication
+http_proxy=http://<username>:<password>@<proxyHost>:<proxyPort> ruby my.app
+```

README.md

@@ -3,8 +3,10 @@
 The `solarwinds_apm` gem starting from version 6.0.0 is an [OpenTelemetry Ruby](https://opentelemetry.io/docs/instrumentation/ruby/) distribution. It provides automatic instrumentation and custom SolarWinds Observability features for Ruby applications.
 
 ## Requirements
+> [!NOTE]
+> Versions before 7.0.0 only support Linux and will go into no-op mode on other platforms.
 
-Only Linux is supported, the gem will go into no-op mode on other platforms. MRI Ruby version 3 or above is required. The [SolarWinds Observability documentation website](https://documentation.solarwinds.com/en/success_center/observability/content/configure/services/ruby/install.htm) has details on the supported platforms and system dependencies.
+MRI Ruby version 3 or above is required. The [SolarWinds Observability documentation website](https://documentation.solarwinds.com/en/success_center/observability/content/configure/services/ruby/install.htm) has details on the supported platforms and system dependencies.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for how to build for development.
 
@@ -32,7 +34,7 @@ The only required configuration is the service key, which can be set in the `SW_
 
 ## Custom Instrumentation
 
-`solarwinds_apm` supports the standard OpenTelemetry API for tracing and includes a helper to ease its use in manual instrumentation.  Additionally, a set of SolarWindsAPM APIs are provided for features specific to SolarWinds Observability.
+`solarwinds_apm` supports the standard OpenTelemetry API and includes a few convenience methods for manual instrumentation.  Additionally, a set of SolarWindsAPM APIs are provided for features specific to SolarWinds Observability.
 
 ### Using the OpenTelemetry API
 
@@ -60,6 +62,25 @@ current_span = ::OpenTelemetry::Trace.current_span
 
 Note that if `OpenTelemetry::SDK.configure` is used to set up a `TracerProvider`, it will not be configured with our distribution's customizations and manual instrumentation made with its `Tracer` object will not be reported to SolarWinds Observability.
 
+This gem also initializes a global `MeterProvider`, so your application can create Meters and Metric Instruments as follows to collect custom metrics, which will be exported every 60 seconds.
+
+```ruby
+# set up meter and create a counter instrument
+MyAppMeter = ::OpenTelemetry.meter_provider.meter('myapp')
+counter = MyAppMeter.create_counter('password.resets',
+  description: 'Count of password reset requests to myapp',
+  unit: '{request}'
+)
+
+# increment counter
+def reset
+  counter.add(1, attributes: {'user.id' => user_id})
+  # do things
+end
+```
+
+See the [OTel Ruby Metrics README](https://github.com/open-telemetry/opentelemetry-ruby/blob/main/metrics_api/README.md) for more information on the API and links to examples.
+
 ### Using the SolarWindsAPM API
 
 Several convenience and vendor-specific APIs are availabe to an application where `solarwinds_apm` has been loaded, below is a quick overview of the features provided. The full reference can be found at the [RubyDoc page for this gem](https://rubydoc.info/github/solarwinds/apm-ruby).
@@ -158,7 +179,10 @@ By default, transaction names are constructed based on attributes such as the re
 result = SolarWindsAPM::API.set_transaction_name('my-custom-trace-name')
 ```
 
-#### Send Custom Metrics (Depreciated)
+#### Send Custom Metrics (Deprecated)
+
+> [!NOTE]
+> Starting from version 7.0.0 these are no-op, standard OTel API should be used instead.
 
 Service metrics are automatically collected by this library.  In addition, the following methods support sending two types of custom metrics:
 

lambda/otel/layer/Gemfile

@@ -6,4 +6,4 @@ source 'https://rubygems.org'
 # source 'https://rubygems.pkg.github.com/solarwinds' do
 # end
 
-gem 'solarwinds_apm', '7.0.0.prev1'
+gem 'solarwinds_apm'

lib/rails/generators/solarwinds_apm/templates/solarwinds_apm_initializer.rb

@@ -35,13 +35,12 @@
   # It sets the log level and takes the following values:
   # -1 disabled, 0 fatal, 1 error, 2 warning, 3 info (the default), 4 debug low, 5 debug medium, 6 debug high.
   # Values out of range (< -1 or > 6) are ignored and the log level is set to the default (info).
-  #
-  SolarWindsAPM::Config[:debug_level] = 3
-
   #
   # :debug_level will map the Ruby logger as DISABLED, FATAL, ERROR, WARN, INFO, or DEBUG
   # The Ruby logger can afterwards be changed to a different level, e.g:
   # SolarWindsAPM.logger.level = Logger::INFO
+  #
+  SolarWindsAPM::Config[:debug_level] = 3
 
   #
   # Turn Tracing on or off
@@ -101,16 +100,6 @@
     #   }
   ]
 
-  #
-  # EC2 Metadata Fetching Timeout
-  #
-  # The timeout can be in the range 0 - 3000 (milliseconds)
-  # Setting to 0 milliseconds effectively disables fetching from
-  # the metadata URL (not waiting), and should only be used if
-  # not running on EC2 / Openstack to minimize agent start up time.
-  #
-  SolarWindsAPM::Config[:ec2_metadata_timeout] = 1000
-
   #
   # Trigger Trace Mode
   #

lib/solarwinds_apm/api/custom_metrics.rb

@@ -33,7 +33,7 @@ module CustomMetrics
       # * Boolean
       #
       def increment_metric(_name, _count = 1, _with_hostname = false, _tags_kvs = {}) # rubocop:disable Style/OptionalBooleanParameter
-        SolarWindsAPM.logger.warn { 'increment_metric have been deprecated. Please use opentelemetry metrics-sdk to log metrics data.' }
+        SolarWindsAPM.logger.warn { 'increment_metric is deprecated, please use the OpenTelemetry API instead.' }
         false
       end
 
@@ -64,7 +64,7 @@ def increment_metric(_name, _count = 1, _with_hostname = false, _tags_kvs = {})
       # * Boolean
       #
       def summary_metric(_name, _value, _count = 1, _with_hostname = false, _tags_kvs = {}) # rubocop:disable Style/OptionalBooleanParameter
-        SolarWindsAPM.logger.warn { 'summary_metric have been deprecated. Please use opentelemetry metrics-sdk to log metrics data.' }
+        SolarWindsAPM.logger.warn { 'summary_metric is deprecated, please use the OpenTelemetry API instead.' }
         false
       end
 

lib/solarwinds_apm/config.rb

@@ -226,6 +226,9 @@ def self.[]=(key, value)
       when :tag_sql
         enable_disable_config('SW_APM_TAG_SQL', key, value, false, bool: true)
 
+      when :ec2_metadata_timeout
+        SolarWindsAPM.logger.warn { ':ec2_metadata_timeout is deprecated' }
+
       when :http_proxy
         SolarWindsAPM.logger.warn { ':http_proxy is deprecated' }
 

lib/solarwinds_apm/noop/api.rb

@@ -56,12 +56,12 @@ def hash_for_log
   # CustomMetrics
   module CustomMetrics
     def increment_metric(*)
-      SolarWindsAPM.logger.warn { 'increment_metric have been deprecated. Please use opentelemetry metrics-sdk to log metrics data.' }
+      SolarWindsAPM.logger.warn { 'increment_metric is deprecated, please use the OpenTelemetry API instead.' }
       false
     end
 
     def summary_metric(*)
-      SolarWindsAPM.logger.warn { 'summary_metric have been deprecated. Please use opentelemetry metrics-sdk to log metrics data.' }
+      SolarWindsAPM.logger.warn { 'summary_metric is deprecated, please use the OpenTelemetry API instead.' }
       false
     end
   end