solarwinds_apm 5.1.9 → 6.0.0.preV2

data/lib/rails/generators/solarwinds_apm/install_generator.rb

@@ -2,6 +2,7 @@
 # All rights reserved.
 
 module SolarWindsAPM
+  # InstallGenerator
   class InstallGenerator < ::Rails::Generators::Base
     source_root File.join(File.dirname(__FILE__), 'templates')
     desc "Copies a SolarWindsAPM gem initializer file to your application."
@@ -9,9 +10,6 @@ module SolarWindsAPM
     @namespace = "solarwinds_apm:install"
 
     def copy_initializer
-      # Set defaults
-      @verbose = 'false'
-
       print_header
       print_footer
 
@@ -20,7 +18,6 @@ module SolarWindsAPM
 
     private
 
-    # rubocop:disable Metrics/MethodLength
     def print_header
       say ""
       say shell.set_color "Welcome to the SolarWindsAPM Ruby instrumentation setup.", :green, :bold
@@ -34,7 +31,6 @@ module SolarWindsAPM
       say "More information on instrumenting Ruby applications can be found here:"
       say "https://documentation.solarwinds.com/en/success_center/observability/default.htm#cshid=config-ruby-agent"
     end
-    # rubocop:enable Metrics/MethodLength
 
     def print_footer
       say ""

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

@@ -3,11 +3,11 @@
 # Copyright (c) 2019 SolarWinds, LLC.
 # All rights reserved.
 
-# SolarWindsAPM Configuration for the Ruby Library aka solarwinds_apm gem
+# SolarWindsAPM Configuration for the Ruby Agent aka solarwinds_apm gem
 # https://cloud.solarwinds.com/
 #
-# More information on configuring the Ruby Library can be found here:
-# https://documentation.solarwinds.com/en/success_center/observability/default.htm#cshid=config-ruby-agent
+# More information on configuring the Ruby Agent can be found here:
+# https://documentation.solarwinds.com/en/success_center/swaas/default.htm#cshid=config-ruby-agent
 #
 # The initial settings in this file represent the defaults
 
@@ -46,11 +46,9 @@ if defined?(SolarWindsAPM::Config)
   # to SolarWinds is still encrypted using SSL/TLS.
   #
   # It is recommended to configure the proxy in this file or as SW_APM_PROXY
-  # environment variable. However, the underlying network library for the Ruby 
-  # Instrumentation Library will use a system-wide proxy defined in the environment 
-  # variables grpc_proxy, https_proxy or http_proxy if no SolarWindsAPM-specific 
-  # configuration is set.
-  # 
+  # environment variable. However, the agent's underlying network library will
+  # use a system-wide proxy defined in the environment variables grpc_proxy,
+  # https_proxy or http_proxy if no SolarWindsAPM-specific configuration is set.
   # Please refer to gRPC environment variables for more information.
   #
   # SolarWindsAPM::Config[:http_proxy] = http://<proxyHost>:<proxyPort>
@@ -71,15 +69,6 @@ if defined?(SolarWindsAPM::Config)
   # The Ruby logger can afterwards be changed to a different level, e.g:
   # SolarWindsAPM.logger.level = Logger::INFO
 
-  #
-  # Set SW_APM_GEM_VERBOSE
-  # This setting will be overridden if SW_APM_GEM_VERBOSE is set as an environment variable
-  #
-  # On startup the components that are being instrumented will be reported if this is set to true.
-  # If true and the log level is 4 or higher this may create extra debug log messages
-  #
-  SolarWindsAPM::Config[:verbose] = false
-
   #
   # Turn Tracing on or off
   #
@@ -88,19 +77,8 @@ if defined?(SolarWindsAPM::Config)
   # sampling rate and metrics are reported.
   # :disabled means that there is no sampling and metrics are not reported.
   #
-  # The values :always and :never are deprecated
-  #
   SolarWindsAPM::Config[:tracing_mode] = :enabled
 
-  #
-  # Turn Trigger Tracing on or off
-  #
-  # By default trigger tracing is :enabled, the other option is :disabled.
-  # It allows to use the X-Trace-Options header to force a request to be
-  # traced (within rate limits set for trigger tracing)
-  #
-  SolarWindsAPM::Config[:trigger_tracing_mode] = :enabled
-
   #
   # Trace Context in Logs
   #
@@ -109,123 +87,25 @@ if defined?(SolarWindsAPM::Config)
   # the current Trace ID in log messages.
   #
   # The added string will look like:
-  # "trace_id=7435a9fe510ae4533414d425dadf4e18 span_id=49e60702469db05f trace_flags=00"
+  # "trace_id=7435a9fe510ae4533414d425dadf4e18 span_id=49e60702469db05f trace_flags=00 resource.service.name=service_name"
   #
   # The following options are available:
   # :never    (default)
   # :sampled  only include the Trace ID of sampled requests
   # :traced   include the Trace ID for all traced requests
   # :always   always add a Trace ID, it will be
-  #           "trace_id=00000000000000000000000000000000 span_id=0000000000000000 trace_flags=00"
+  #           "trace_id=00000000000000000000000000000000 span_id=0000000000000000 trace_flags=00 resource.service.name=otel_service_name"
   #           when there is no tracing context.
   #
   SolarWindsAPM::Config[:log_traceId] = :never
 
-  #
-  # Trace Context in Queries (sql only)
-  #
-  # Configure to add the trace context to sql queries so that queries and
-  # transactions can be linked in the SolarWinds dashboard
-  #
-  # This option can add a small overhead for queries that use prepared
-  # statements as those statements will be recompiled whenever the trace context
-  # is added (about 10% of the requests)
-  #
-  # the options are:
-  # - true   (default) no trace context is added
-  # - false  the tracecontext is added as comment to the start of the query, e.g:
-  #          "/*traceparent='00-268748089f148899e29fc5711aca7760-7c6c704dcbba6682-01'*/SELECT `widgets`.* FROM `widgets` WHERE ..."
-  #
-  SolarWindsAPM::Config[:tag_sql] = false
-
-  #
-  # Sanitize SQL Statements
-  #
-  # The SolarWindsAPM Ruby client has the ability to sanitize query literals
-  # from SQL statements.  By default this is enabled.  Disable to
-  # collect and report query literals to SolarWindsAPM.
-  #
-  SolarWindsAPM::Config[:sanitize_sql] = true
-  SolarWindsAPM::Config[:sanitize_sql_regexp] = '(\'[^\']*\'|\d*\.\d+|\d+|NULL)'
-  SolarWindsAPM::Config[:sanitize_sql_opts]   = Regexp::IGNORECASE
-
-  #
-  # Prepend Domain to Transaction Name
-  #
-  # If this is set to `true` transaction names will be composed as
-  # `my.host.com/controller.action` instead of `controller.action`.
-  # This configuration applies to all transaction names, whether deduced by the
-  # instrumentation or implicitly set.
-  #
-  SolarWindsAPM::Config[:transaction_name][:prepend_domain] = false
-
-  #
-  # Do Not Trace - DNT
-  #
-  # DEPRECATED
-  # Please comment out if no filtering is desired, e.g. your static
-  # assets are served by the web server and not the application
-  #
-  # This configuration allows creating a regexp for paths that should be excluded
-  # from solarwinds_apm processing.
-  #
-  # For example:
-  # - static assets that aren't served by the web server, or
-  # - healthcheck endpoints that respond to a heart beat.
-  #
-  # :dnt_regexp is the regular expression that is applied to the incoming path
-  # to determine whether the request should be measured and traced or not.
-  #
-  # :dnt_opts can be commented out, nil, or Regexp::IGNORECASE
-  #
-  # The matching happens before routes are applied.
-  # The path originates from the rack layer and is retrieved as follows:
-  #   req = ::Rack::Request.new(env)
-  #   path = URI.unescape(req.path)
-  #
-  SolarWindsAPM::Config[:dnt_regexp] = '\.(jpg|jpeg|gif|png|ico|css|zip|tgz|gz|rar|bz2|pdf|txt|tar|wav|bmp|rtf|js|flv|swf|otf|eot|ttf|woff|woff2|svg|less)(\?.+){0,1}$'
-  SolarWindsAPM::Config[:dnt_opts] = Regexp::IGNORECASE
-
-  #
-  # GraphQL
-  #
-  # Enable tracing for GraphQL.
-  # (true | false, default: true)
-  SolarWindsAPM::Config[:graphql][:enabled] = true
-  # Replace query arguments with a '?' when sent with a trace.
-  # (true | false, default: true)
-  SolarWindsAPM::Config[:graphql][:sanitize] = true
-  # Remove comments from queries when sent with a trace.
-  # (true | false, default: true)
-  SolarWindsAPM::Config[:graphql][:remove_comments] = true
-  # Create a transaction name by combining
-  # "query" or "mutation" with the first word of the query.
-  # This overwrites the default transaction name, which is a combination of
-  # controller + action and would be the same for all graphql queries.
-  # (true | false, default: true)
-  SolarWindsAPM::Config[:graphql][:transaction_name] = true
-
-  #
-  # Rack::Cache
-  #
-  # Create a transaction name like `rack-cache.<cache-store>`,
-  # e.g. `rack-cache.memcached`
-  # This can reduce the number of transaction names, when many requests are
-  # served directly from the cache without hitting a controller action.
-  # When set to `false` the path will be used for the transaction name.
-  #
-  SolarWindsAPM::Config[:rack_cache] = { transaction_name: true }
-
   #
   # Transaction Settings
   #
   # Use this configuration to add exceptions to the global tracing mode and
   # disable/enable metrics and traces for certain transactions.
   #
-  # Currently allowed hash keys:
-  # :url to apply listed filters to urls.
-  #      The matching of settings to urls happens before routes are applied.
-  #      The url is extracted from the env argument passed to rack: `env['PATH_INFO']`
+  # Currently allowed array of hash
   #
   # and the hashes within the :url list either:
   #   :extensions  takes an array of strings for filtering (not regular expressions!)
@@ -240,31 +120,20 @@ if defined?(SolarWindsAPM::Config)
   # Be careful not to add too many :regexp configurations as they will slow
   # down execution.
   #
-  SolarWindsAPM::Config[:transaction_settings] = {
-    url: [
-      #   {
-      #     extensions: %w['long_job'],
-      #     tracing: :disabled
-      #   },
-      #   {
-      #     regexp: '^.*\/long_job\/.*$',
-      #     opts: Regexp::IGNORECASE,
-      #     tracing: :disabled
-      #   },
-      #   {
-      #     regexp: /batch/,
-      #   }
-    ]
-  }
-
-  #
-  # Rails Exception Logging
-  #
-  # In Rails, raised exceptions with rescue handlers via
-  # <tt>rescue_from</tt> are not reported to the SolarWinds   # dashboard by default.  Setting this value to true will
-  # report all raised exceptions regardless.
-  #
-  SolarWindsAPM::Config[:report_rescued_errors] = false
+  SolarWindsAPM::Config[:transaction_settings] = [
+    #   {
+    #     extensions: %w[long_job],
+    #     tracing: :disabled
+    #   },
+    #   {
+    #     regexp: '^.*\/long_job\/.*$',
+    #     opts: Regexp::IGNORECASE,
+    #     tracing: :disabled
+    #   },
+    #   {
+    #     regexp: /batch/,
+    #   }
+  ]
 
   #
   # EC2 Metadata Fetching Timeout
@@ -276,131 +145,37 @@ if defined?(SolarWindsAPM::Config)
   #
   SolarWindsAPM::Config[:ec2_metadata_timeout] = 1000
 
-
-  #############################################
-  ## SETTINGS FOR INDIVIDUAL GEMS/FRAMEWORKS ##
-  #############################################
-
-  #
-  # Bunny Controller and Action
   #
-  # The bunny (Rabbitmq) instrumentation can optionally report
-  # Controller and Action values to allow filtering of bunny
-  # message handling in # the UI.  Use of Controller and Action
-  # for filters is temporary until the UI is updated with
-  # additional filters.
+  # Trigger Trace Mode
   #
-  # These values identify which properties of
-  # Bunny::MessageProperties to report as Controller
-  # and Action.  The defaults are to report :app_id (as
-  # Controller) and :type (as Action).  If these values
-  # are not specified in the publish, then nothing
-  # will be reported here.
+  # Trace options is a custom HTTP header X-Trace-Options that can be set on a request to carry additional information
+  # to the agents, one such option being trigger-trace which we’ll call a trigger trace request.
   #
-  SolarWindsAPM::Config[:bunnyconsumer][:controller] = :app_id
-  SolarWindsAPM::Config[:bunnyconsumer][:action] = :type
-
-  #
-  # Enabling/Disabling Instrumentation
-  #
-  # If you're having trouble with one of the instrumentation libraries, they
-  # can be individually disabled here by setting the :enabled
-  # value to false.
-  #
-  # :enabled settings are read on startup and can't be changed afterwards
-  #
-  SolarWindsAPM::Config[:action_controller][:enabled] = true
-  SolarWindsAPM::Config[:action_controller_api][:enabled] = true
-  SolarWindsAPM::Config[:action_view][:enabled] = true
-  SolarWindsAPM::Config[:active_record][:enabled] = true
-  SolarWindsAPM::Config[:bunnyclient][:enabled] = true
-  SolarWindsAPM::Config[:bunnyconsumer][:enabled] = true
-  SolarWindsAPM::Config[:curb][:enabled] = true
-  SolarWindsAPM::Config[:dalli][:enabled] = true
-  SolarWindsAPM::Config[:delayed_jobclient][:enabled] = true
-  SolarWindsAPM::Config[:delayed_jobworker][:enabled] = true
-  SolarWindsAPM::Config[:excon][:enabled] = true
-  SolarWindsAPM::Config[:faraday][:enabled] = true
-  SolarWindsAPM::Config[:grpc_client][:enabled] = true
-  SolarWindsAPM::Config[:grpc_server][:enabled] = true
-  SolarWindsAPM::Config[:grape][:enabled] = true
-  SolarWindsAPM::Config[:httpclient][:enabled] = true
-  SolarWindsAPM::Config[:memcached][:enabled] = true
-  SolarWindsAPM::Config[:mongo][:enabled] = true
-  SolarWindsAPM::Config[:moped][:enabled] = true
-  SolarWindsAPM::Config[:nethttp][:enabled] = true
-  SolarWindsAPM::Config[:padrino][:enabled] = true
-  SolarWindsAPM::Config[:rack][:enabled] = true
-  SolarWindsAPM::Config[:redis][:enabled] = true
-  SolarWindsAPM::Config[:resqueclient][:enabled] = true
-  SolarWindsAPM::Config[:resqueworker][:enabled] = true
-  SolarWindsAPM::Config[:rest_client][:enabled] = true
-  SolarWindsAPM::Config[:sequel][:enabled] = true
-  SolarWindsAPM::Config[:sidekiqclient][:enabled] = true
-  SolarWindsAPM::Config[:sidekiqworker][:enabled] = true
-  SolarWindsAPM::Config[:sinatra][:enabled] = true
-  SolarWindsAPM::Config[:typhoeus][:enabled] = true
+  SolarWindsAPM::Config[:trigger_tracing_mode] = 'enabled'
 
   #
   # Argument logging
   #
-  #
   # For http requests:
   # By default the query string parameters are included in the URLs reported.
   # Set :log_args to false and instrumentation will stop collecting
   # and reporting query arguments from URLs.
   #
-  SolarWindsAPM::Config[:bunnyconsumer][:log_args] = true
-  SolarWindsAPM::Config[:curb][:log_args] = true
-  SolarWindsAPM::Config[:excon][:log_args] = true
-  SolarWindsAPM::Config[:httpclient][:log_args] = true
-  SolarWindsAPM::Config[:mongo][:log_args] = true
-  SolarWindsAPM::Config[:nethttp][:log_args] = true
-  SolarWindsAPM::Config[:rack][:log_args] = true
-  SolarWindsAPM::Config[:resqueclient][:log_args] = true
-  SolarWindsAPM::Config[:resqueworker][:log_args] = true
-  SolarWindsAPM::Config[:sidekiqclient][:log_args] = true
-  SolarWindsAPM::Config[:sidekiqworker][:log_args] = true
-  SolarWindsAPM::Config[:typhoeus][:log_args] = true
+  SolarWindsAPM::Config[:log_args] = true
 
   #
-  # Enabling/Disabling Backtrace Collection
-  #
-  # Instrumentation can optionally collect backtraces as they collect
-  # performance metrics.  Note that this has a negative impact on
-  # performance but can be useful when trying to locate the source of
-  # a certain call or operation.
-  #
-  SolarWindsAPM::Config[:action_controller][:collect_backtraces] = true
-  SolarWindsAPM::Config[:action_controller_api][:collect_backtraces] = true
-  SolarWindsAPM::Config[:action_view][:collect_backtraces] = true
-  SolarWindsAPM::Config[:active_record][:collect_backtraces] = true
-  SolarWindsAPM::Config[:bunnyclient][:collect_backtraces] = false
-  SolarWindsAPM::Config[:bunnyconsumer][:collect_backtraces] = false
-  SolarWindsAPM::Config[:curb][:collect_backtraces] = true
-  SolarWindsAPM::Config[:dalli][:collect_backtraces] = false
-  SolarWindsAPM::Config[:delayed_jobclient][:collect_backtraces] = false
-  SolarWindsAPM::Config[:delayed_jobworker][:collect_backtraces] = false
-  SolarWindsAPM::Config[:excon][:collect_backtraces] = true
-  SolarWindsAPM::Config[:faraday][:collect_backtraces] = false
-  SolarWindsAPM::Config[:grape][:collect_backtraces] = true
-  SolarWindsAPM::Config[:grpc_client][:collect_backtraces] = false
-  SolarWindsAPM::Config[:grpc_server][:collect_backtraces] = false
-  SolarWindsAPM::Config[:httpclient][:collect_backtraces] = true
-  SolarWindsAPM::Config[:memcached][:collect_backtraces] = false
-  SolarWindsAPM::Config[:mongo][:collect_backtraces] = true
-  SolarWindsAPM::Config[:moped][:collect_backtraces] = true
-  SolarWindsAPM::Config[:nethttp][:collect_backtraces] = true
-  SolarWindsAPM::Config[:padrino][:collect_backtraces] = true
-  SolarWindsAPM::Config[:rack][:collect_backtraces] = true
-  SolarWindsAPM::Config[:redis][:collect_backtraces] = false
-  SolarWindsAPM::Config[:resqueclient][:collect_backtraces] = true
-  SolarWindsAPM::Config[:resqueworker][:collect_backtraces] = true
-  SolarWindsAPM::Config[:rest_client][:collect_backtraces] = true
-  SolarWindsAPM::Config[:sequel][:collect_backtraces] = true
-  SolarWindsAPM::Config[:sidekiqclient][:collect_backtraces] = false
-  SolarWindsAPM::Config[:sidekiqworker][:collect_backtraces] = false
-  SolarWindsAPM::Config[:sinatra][:collect_backtraces] = true
-  SolarWindsAPM::Config[:typhoeus][:collect_backtraces] = false
-
+  # Tracecontext in sql
+  #
+  # Appending trace contenxt (i.e. traceparent) as an sql comment
+  # at the beginning or end of sql. This modified sql will be
+  # sent to sql server for trace correlation.
+  #
+  # Example:
+  #   SELECT `posts`.* FROM `posts` /*traceparent=00-a448f096d441e167d12ebd32a927c1a5-a29655a47e430119-01*/
+  #
+  # This option can add a small overhead for prepared statements since the traceparent value is unique per execution.
+  # This feature uses marginalia, see its caveat and possible workaround
+  # https://github.com/basecamp/marginalia/blob/master/README.md#prepared-statements
+  #
+  SolarWindsAPM::Config[:tag_sql] = false
 end

data/lib/solarwinds_apm/api/current_trace_info.rb

@@ -0,0 +1,148 @@
+#--
+# Copyright (c) SolarWinds, LLC.
+# All rights reserved.
+#++
+module SolarWindsAPM
+  module API
+    module CurrentTraceInfo
+      # Creates an instance of {TraceInfo} with instance methods:<br>
+      # {TraceInfo#trace_id}<br>
+      # {TraceInfo#span_id}<br>
+      # {TraceInfo#trace_flags}<br>
+      # {TraceInfo#for_log}<br>
+      # {TraceInfo#hash_for_log}
+      # 
+      # The <tt>SolarWindsAPM::Config[:log_traceId]</tt> configuration setting for automatic trace context in logs affects the 
+      # return value of methods in this module.
+      #
+      # The following options are available:<br>
+      # <tt>:never</tt>    (default)<br>
+      # <tt>:sampled</tt>  only include the Trace ID of sampled requests<br>
+      # <tt>:traced</tt>   include the Trace ID for all traced requests<br>
+      # <tt>:always</tt>   always add a Trace ID, it will be "trace_id=00000000000000000000000000000000 span_id=0000000000000000 trace_flags=00 resource.service.name=otel_service_name" when there is no tracing context.
+      #
+      # === Example:
+      #
+      #   trace = SolarWindsAPM::API.current_trace_info
+      #   trace.for_log        # 'trace_id=7435a9fe510ae4533414d425dadf4e18 span_id=49e60702469db05f trace_flags=01 resource.service.name=otel_service_name' or '' depends on Config
+      #   trace.hash_for_log   # { trace_id: '7435a9fe510ae4533414d425dadf4e18',
+      #                            span_id: '49e60702469db05f',
+      #                            trace_flags: '',
+      #                            resource.service.name: 'otel_service_name' }  or {} depends on Config
+      #
+      #
+      # Configure trace info injection with lograge:
+      #
+      #    Lograge.custom_options = lambda do |event|
+      #       SolarWindsAPM::API.current_trace_info.hash_for_log
+      #    end
+      #
+      def current_trace_info
+        TraceInfo.new
+      end
+
+      # @attr [String] tracestring
+      # @attr [String] trace_id
+      # @attr [String] span_id
+      # @attr [String] trace_flags
+      # @attr [Boolean] do_log
+      class TraceInfo
+        attr_reader :tracestring, :trace_id, :span_id, :trace_flags, :do_log
+
+        REGEXP = /^(?<tracestring>(?<version>[a-f0-9]{2})-(?<trace_id>[a-f0-9]{32})-(?<span_id>[a-f0-9]{16})-(?<flags>[a-f0-9]{2}))$/
+        private_constant :REGEXP
+
+        def initialize
+          @trace_id, @span_id, @trace_flags, @tracestring = current_span
+          @service_name = ENV['OTEL_SERVICE_NAME']
+          @do_log = log? # true if the tracecontext should be added to logs
+        end
+
+        # for_log returns a string in the format
+        # 'trace_id=<trace_id> span_id=<span_id> trace_flags=<trace_flags>' or empty string.
+        # 
+        # An empty string is returned depending on the setting for
+        # <tt>SolarWindsAPM::Config[:log_traceId]</tt>, which can be :never,
+        # :sampled, :traced, or :always.
+        #
+        # === Example:
+        #
+        #   trace = SolarWindsAPM::API.current_trace_info
+        #   trace.for_log  # 'trace_id=7435a9fe510ae4533414d425dadf4e18 span_id=49e60702469db05f trace_flags=01 resource.service.name=otel_service_name' or '' depends on Config
+        #
+        # === Returns:
+        # * String
+        #
+        def for_log
+          @for_log ||= @do_log ? "trace_id=#{@trace_id} span_id=#{@span_id} trace_flags=#{@trace_flags} resource.service.name=#{@service_name}" : ''
+        end
+
+        # Construct the trace_id, span_id, trace_flags and resource.service.name for log insertion.
+        #
+        # === Example:
+        #
+        #   trace = SolarWindsAPM::API.current_trace_info
+        #   trace.hash_for_log   # { trace_id: '7435a9fe510ae4533414d425dadf4e18',
+        #                            span_id: '49e60702469db05f',
+        #                            trace_flags: 01,
+        #                            resource.service.name: 'otel_service_name' }  or {} depends on Config
+        #   
+        #   # For lograge:
+        #   Lograge.custom_options = lambda do |event|
+        #     SolarWindsAPM::API.current_trace_info.hash_for_log
+        #   end
+        #
+        # === Returns:
+        # * Hash
+        #
+        def hash_for_log
+          @hash_for_log = {}
+          @hash_for_log = {trace_id: @trace_id, span_id: @span_id, trace_flags: @trace_flags, service_name: @service_name} if @do_log
+        end
+
+        private
+
+        def current_span
+          span     = ::OpenTelemetry::Trace.current_span if defined?(::OpenTelemetry::Trace)
+          trace_id = span.context.hex_trace_id
+          span_id  = span.context.hex_span_id
+          trace_flags = span.context.trace_flags.sampled?? '01' : '00'
+          tracestring = "00-#{trace_id}-#{span_id}-#{trace_flags}"
+          
+          [trace_id, span_id, trace_flags, tracestring]
+        end
+
+        # if true the trace info should be added to the log message
+        def log?
+          case SolarWindsAPM::Config[:log_traceId]
+          when :never, nil
+            false
+          when :always
+            true
+          when :traced
+            valid?(@tracestring)
+          when :sampled
+            sampled?(@tracestring)
+          end
+        end
+
+        # un-initialized (all 0 trace-id) tracestrings are not valid
+        def valid?(tracestring)
+          matches = REGEXP.match(tracestring)
+
+          matches && matches[:trace_id] != ("0" * 32)
+        end
+
+        def sampled?(tracestring)
+          matches = REGEXP.match(tracestring)
+
+          matches && matches[:flags][-1].to_i & 1 == 1
+        end
+
+        def split(tracestring)
+          REGEXP.match(tracestring)
+        end
+      end
+    end
+  end
+end

data/lib/solarwinds_apm/api/tracing.rb

@@ -0,0 +1,30 @@
+module SolarWindsAPM
+  module API
+    module Tracing
+      # Wait for SolarWinds to be ready to send traces.
+      #
+      # This may be useful in short lived background processes when it is important to capture
+      # information during the whole time the process is running. Usually SolarWinds doesn't block an
+      # application while it is starting up.
+      #
+      # === Argument:
+      #
+      # * +wait_milliseconds+ - (int, default 3000) the maximum time to wait in milliseconds
+      #
+      # === Example:
+      #
+      #   unless SolarWindsAPM::API.solarwinds_ready?(10_000)
+      #     Logger.info "SolarWindsAPM not ready after 10 seconds, no metrics will be sent"
+      #   end
+      # 
+      # === Returns:
+      # * Boolean
+      #
+      def solarwinds_ready?(wait_milliseconds=3000)
+        return false unless SolarWindsAPM.loaded
+
+        SolarWindsAPM::Context.isReady(wait_milliseconds) == 1
+      end
+    end
+  end
+end

data/lib/solarwinds_apm/api/transaction_name.rb

@@ -0,0 +1,58 @@
+module SolarWindsAPM
+  module API
+    module TransactionName
+      # Provide a custom transaction name
+      #
+      # The SolarWindsAPM gem tries to create meaningful transaction names from controller+action
+      # or something similar depending on the framework used. However, you may want to override the
+      # transaction name to better describe your instrumented operation.
+      #
+      # === Argument:
+      #
+      # * +custom_name+ - A non-empty string with the custom transaction name
+      #
+      # === Example:
+      #
+      #   class DogfoodsController < ApplicationController
+      #
+      #     def create
+      #       @dogfood = Dogfood.new(params.permit(:brand, :name))
+      #       @dogfood.save
+      #
+      #       SolarWindsAPM::API.set_transaction_name("dogfoodscontroller.create_for_#{params[:brand]}")
+      #
+      #       redirect_to @dogfood
+      #     end
+      #
+      #   end
+      #
+      # === Returns:
+      # * Boolean
+      #
+      def set_transaction_name(custom_name=nil)
+        
+        return false if custom_name.nil? || custom_name.empty? 
+        return true  if SolarWindsAPM::Context.toString == '00-00000000000000000000000000000000-0000000000000000-00' # noop
+
+        solarwinds_processor = SolarWindsAPM::OTelConfig.class_variable_get(:@@config)[:span_processor]
+        if solarwinds_processor.nil?
+          SolarWindsAPM.logger.warn {"[#{name}/#{__method__}] Solarwinds processor is missing. Set transaction name failed."}
+          return false
+        end
+
+        entry_trace_id = ::OpenTelemetry::Baggage.value(::SolarWindsAPM::Constants::INTL_SWO_CURRENT_TRACE_ID)
+        entry_span_id  = ::OpenTelemetry::Baggage.value(::SolarWindsAPM::Constants::INTL_SWO_CURRENT_SPAN_ID)
+
+        if entry_trace_id.nil? || entry_span_id.nil? 
+          SolarWindsAPM.logger.warn {"[#{name}/#{__method__}] Cannot cache custom transaction name #{custom_name} because OTel service entry span not started; ignoring"}
+          return false
+        end
+
+        trace_span_id = "#{entry_trace_id}-#{entry_span_id}"
+        solarwinds_processor.txn_manager.set(trace_span_id,custom_name) 
+        SolarWindsAPM.logger.debug {"[#{name}/#{__method__}] Cached custom transaction name for #{trace_span_id} as #{custom_name}"}
+        true
+      end
+    end
+  end
+end