NH-110595: update readme.

.gitignore

@@ -19,36 +19,11 @@ builds/
 config/
 coverage/
 doc/
-ext/oboe_metal/*.o
-ext/oboe_metal/Makefile
-ext/oboe_metal/lib/liboboe*so*
-ext/oboe_metal/mkmf.log
-ext/oboe_metal/oboe_metal.so
-ext/oboe_metal/oboe_noop.so
-ext/oboe_metal/src/bson/
-ext/oboe_metal/src/oboe_api.cpp
-ext/oboe_metal/src/oboe.h
-ext/oboe_metal/src/oboe_api.h
-ext/oboe_metal/src/oboe_debug.h
-ext/oboe_metal/src/oboe_swig_wrap.cc
-ext/oboe_metal/src/oboe.i
-ext/oboe_metal/src/VERSION_latest
-ext/oboe_metal/test/build/
-ext/oboe_metal/test/MakeFile
-ext/oboe_metal/.DS_Store
 gemfiles/*.lock
 gemfiles/.bundle/
 gemfiles/vendor*
-lib/libsolarwinds_apm.so
 vendor/
 *.DS_Store
-apm.collector.st-ssp.solarwinds.com
-appoptics.com
-test/clib/Makefile
-*.so
-*.o
-ext/oboe_metal/extconf_local.rb
-Makefile
 
 # test script
 install_gem.sh

CONFIGURATION.md

@@ -16,19 +16,19 @@ Settings specific to `solarwinds_apm` are prefixed by `SW_APM_` and described in
 
 ### Exporter
 
-The default `solarwinds` exporter which communicates with the SolarWinds Observability backend is always configured. Additional exporters can be configured via the `OTEL_TRACES_EXPORTER` environment variable. For example, console exporter is part of standard installation and can be enabled via:
+The default `solarwinds` exporter which communicates with the SolarWinds Observability backend is always configured as OTLP Exporter. Additional exporters can be configured via the `OTEL_TRACES_EXPORTER` environment variable. For example, console exporter is part of standard installation and can be enabled via:
 
 ```bash
 export OTEL_TRACES_EXPORTER=console
 ```
 
-Other exporters must first be installed and required before loading `solarwinds_apm`. For example, if dependencies are loaded by `Bundler.require`, add the OTLP exporter to the Gemfile:
+Other exporters (e.g. Jaeger) must first be installed and required before loading `solarwinds_apm`. For example, if dependencies are loaded by `Bundler.require`, add the OTLP exporter to the Gemfile:
 
 ```ruby
 # application dependencies, eg
 # gem "rails", "~> 7.0.5", ">= 7.0.5.1"
 
-gem "opentelemetry-exporter-otlp"
+gem 'opentelemetry-exporter-jaeger'
 
 # end of Gemfile
 gem 'solarwinds_apm'
@@ -37,19 +37,17 @@ gem 'solarwinds_apm'
 And set the environment variable:
 
 ```bash
-export OTEL_TRACES_EXPORTER=otlp
+export OTEL_TRACES_EXPORTER=jaeger
 ```
 
 ### Service Name
 
 By default the service name portion of the service key is used, e.g. `my-service` if the service key is `SW_APM_SERVICE_KEY=api-token:my-service`. If the `OTEL_SERVICE_NAME` or `OTEL_RESOURCE_ATTRIBUTES` environment variable is used to specify a service name, it will take precedence over the default.
 
 ```bash
+# service name for instrumented app will be 'bar', not 'foo'
 export SW_APM_SERVICE_KEY=<api-token>:foo
 export OTEL_SERVICE_NAME=bar
-
-# service name for instrumented app will be "bar"
-ruby application.rb
 ```
 
 ### Instrumentation Libraries
@@ -85,7 +83,7 @@ Below is an example that disables Dalli instrumentation and sets the Rack instru
 
 require 'solarwinds_apm'
 
-SolarWindsAPM::OTelConfig.initialize_with_config do |config|
+SolarWindsAPM::OTelNativeConfig.initialize_with_config do |config|
   config["OpenTelemetry::Instrumentation::Dalli"] = {:enabled => false}
   config["OpenTelemetry::Instrumentation::Rack"]  = {:allowed_request_headers => ['header1', 'header2']}
 end
@@ -119,17 +117,12 @@ Environment Variable | Config File Key | Description | Default
 `SW_APM_COLLECTOR` | N/A | Override the default collector endpoint to which the library connects and exports data. It should be defined using the format host:port. | `apm.collector.na-01.cloud.solarwinds.com:443`
 `SW_APM_CONFIG_RUBY` | N/A | Override the default location for the configuration file. This can be an absolute or relative filename, or the directory under which the `solarwinds_apm_config.rb` file would be looked for. | None
 `SW_APM_DEBUG_LEVEL` | `:debug_level` | Set the library's logging level, valid values are -1 through 6 (least to most verbose). <br> Setting -1 disables logging from the library. | 3
-`SW_APM_EC2_METADATA_TIMEOUT` | `:ec2_metadata_timeout` | Timeout for AWS IMDS metadata retrieval in milliseconds. | 1000
 `SW_APM_ENABLED` | N/A | Enable/disable the library, setting `false` is an alternative to uninstalling `solarwinds_apm` since it will prevent the library from loading. | `true`
-`SW_APM_LOG_FILEPATH` | N/A | Configure the log file path for the C extension, e.g. `export SW_APM_LOG_FILEPATH=/path/file_path.log`. If set, messages from the C extension are written to the specified file instead of stderr.  | None
-`SW_APM_PROXY` | `:http_proxy` | Configure an HTTP proxy through which the library connects to the collector. | None
 `SW_APM_SERVICE_KEY` | `:service_key` | API token and service name in the form of `token:service_name`, **required**. | None
 `SW_APM_TAG_SQL` | `:tag_sql` | Enable/disable injecting trace context into supported SQL statements. Set to boolean true or (or string `true` in env var) to enable, see [Tag Query with Trace Context](#tag-query-with-trace-context) for details.| `false`
 `SW_APM_TRIGGER_TRACING_MODE` | `:trigger_tracing_mode` | Enable/disable trigger tracing for the service.  Setting to `disabled` may impact DEM visibility into the service. | `enabled`
-`SW_APM_TRUSTEDPATH` | N/A | The library uses the host system's default trusted CA certificates to verify the TLS connection to the collector. To override the default, define the trusted certificate path configuration option with an absolute path to a specific trusted certificate file in PEM format. | None
 `SW_APM_LAMBDA_PRELOAD_DEPS` | N/A | This option only takes effect in the AWS Lambda runtime. Set to `false` to disable the attempt to preload function dependencies and install instrumentations. | `true`
 `SW_APM_TRANSACTION_NAME` | N/A | Customize the transaction name for all traces, typically used to target specific instrumented lambda functions. _Precedence order_: custom SDK > `SW_APM_TRANSACTION_NAME` > automatic naming | None
-`SW_APM_ENABLE_AFTER_FORK` | N/A | For background job systems (e.g. resque) that fork child processes as jobs are received. This option delays the library initialization to the start of the child process, to avoid issues associated with gRPC's weak support of forking and cleanup. | false
 N/A | `:log_args` | Enable/disable the collection of URL query parameters, set to boolean false to disable. | true
 N/A | `:log_traceId` | Configure the insertion of trace context into application logs, setting `:traced` would include the available context fields such as trace_id, span_id into log messages. | `:never`
 N/A | `:tracing_mode` | Enable/disable the tracing mode for this service, setting `:disabled` would suppress all trace spans and metrics. | `:enabled`
@@ -176,31 +169,16 @@ SELECT * FROM SAMPLE_TABLE WHERE user_id = 1; /* traceparent=7435a9fe510ae453341
 
 [Resque](https://github.com/resque/resque) is a Redis-backed library for creating background jobs, queuing them on multiple queues, and processing them later.
 
-When starting the Resque worker, it is necessary to set two options: `SW_APM_ENABLE_AFTER_FORK=true` and `RUN_AT_EXIT_HOOKS=1`.
+When starting the Resque worker, it is necessary to set: `RUN_AT_EXIT_HOOKS=1`.
 
 For example:
 
 ```console
-SW_APM_ENABLE_AFTER_FORK=true RUN_AT_EXIT_HOOKS=1 QUEUE=${QUEUE_NAME} ${EXTRA_OPTIONS} bundle exec rake resque:work
+RUN_AT_EXIT_HOOKS=1 QUEUE=${QUEUE_NAME} ${EXTRA_OPTIONS} bundle exec rake resque:work
 ```
 
 Explanation:
 
-* `SW_APM_ENABLE_AFTER_FORK`: This option delays initialization of the library's C extension and gRPC-based reporter from the start of the parent worker process to the start of the child process, which is crucial to avoid issues associated with gRPC's weak support of forking and cleanup.
-* `RUN_AT_EXIT_HOOKS`: This option, provided by Resque, ensures that the forked processes shut down gracefully (i.e., no immediate `exit!`).
+* `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.
-
-```ruby
-require 'resque'
-
-Resque.after_fork do
-  unless SolarWindsAPM::API.solarwinds_ready?(8_000)
-    puts "SolarWindsAPM is not ready, this job will not be traced."
-  end
-end
-```
-
-Explanation:
-
-* Since Resque forks a new process for each task, `solarwinds_apm` needs a certain amount of time to complete initialization at the start of each child process [before it is ready to trace](https://github.com/solarwinds/apm-ruby/blob/main/README.md#check-if-solarwinds_apm-is-ready). This `solarwinds_ready?` check in the [`after_fork` hook](https://github.com/resque/resque/blob/master/docs/HOOKS.md) ensures the library is ready for instrumentation to collect metrics and sample for traces.

CONTRIBUTING.md

@@ -114,25 +114,6 @@ gem install builds/solarwinds_apm-<version>.gem
 SW_APM_SERVICE_KEY=<api-token:service-name> irb -r solarwinds_apm
 ```
 
-#### Compiling the C Extension
-
-During install, the gem compiles a C extension called oboe which provides core functionality such as sampling and data transmission.  When loading the gem from local source for development, the extension needs to be explicitly compiled:
-
-```bash
-bundle exec rake clean
-bundle exec rake fetch
-bundle exec rake compile
-
-# or use the short version that does it all
-bundle exec rake cfc
-```
-
-Now loading the gem from local source should work:
-
-```bash
-SW_APM_SERVICE_KEY=<api-token:service-name> bundle exec irb -r solarwinds_apm
-```
-
 ### Linting
 
 Use this Rake task to run rubocop inside the development container:
@@ -190,15 +171,13 @@ To run a single test file:
 # most tests require just the unit.gemfile dependencies
 BUNDLE_GEMFILE=gemfiles/unit.gemfile bundle update
 
-BUNDLE_GEMFILE=gemfiles/unit.gemfile bundle exec ruby -I test test/opentelemetry/solarwinds_exporter_test.rb
 BUNDLE_GEMFILE=gemfiles/unit.gemfile bundle exec ruby -I test test/opentelemetry/solarwinds_propagator_test.rb
 ```
 
-To run a specific test (that requires unit.gemfile):
+To run a specific test with 'trace_state_header' inside test case name:
 
 ```bash
 BUNDLE_GEMFILE=gemfiles/unit.gemfile bundle update
 
-BUNDLE_GEMFILE=gemfiles/unit.gemfile bundle exec ruby -I test test/opentelemetry/solarwinds_exporter_test.rb -n /test_build_meta_data/
-BUNDLE_GEMFILE=gemfiles/unit.gemfile bundle exec ruby -I test test/solarwinds_apm/otel_config_test.rb -n /test_resolve_propagators_with_defaults/
+BUNDLE_GEMFILE=gemfiles/unit.gemfile bundle exec ruby -I test test/opentelemetry/solarwinds_propagator_test.rb -n /trace_state_header/
 ```

README.md

@@ -158,7 +158,7 @@ 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
+#### Send Custom Metrics (Depreciated)
 
 Service metrics are automatically collected by this library.  In addition, the following methods support sending two types of custom metrics: