solarwinds_apm 6.1.1 → 7.0.0.prev1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ab7453d8ca9dc042ac880b99dd8cd11d6344e3372bb84b2fab1e6b4fa3d65ab
-  data.tar.gz: '009803a9d3ad0f678824c57dca3031ef3b9f79989c00fecb16946962cb641f1e'
+  metadata.gz: 2d66514bebfccf2f3c5a2b2e6924fe7fc7abe6a33fa90ce2dcc94de968e64018
+  data.tar.gz: 55cd6df597c8db22130b6322ede1deae4911c1409674734cb11ccf9223734dcb
 SHA512:
-  metadata.gz: d80d9759f1050927d249d9ac1264eb6bd5407603cf2fee8c09ce27137c6b39773ea3f7b57dd7e5c428890a9ee27f7ba1cc02d20672bef43cfb0470f04de0b70c
-  data.tar.gz: 664ade107e0f49a1709d0d5b87012ea6766094d469b3942afb10100a63c066735f512bb7d2aafae5925b99f4a305f4d2f2a31101090f3bddeee68e722e6efafd
+  metadata.gz: fa5dd5bb46399211d816833f257b69fec64a325cb6ee3c256d612d64be0e4cb50e5b1e195025afad69dee4d5c79726d9e5b6ff8f5a25d952724b01521e8d9331
+  data.tar.gz: 6b9e3f5bc1e8e35b419d9a2c04c43bca23268ea9fed3832368d5f0c708925abd1e46d9f2e215833fae5e6154fa77c7ec696e3819a0ff37188c1c407aa4965522

data/README.md

@@ -64,9 +64,11 @@ Note that if `OpenTelemetry::SDK.configure` is used to set up a `TracerProvider`
 
 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).
 
-#### Convenience Method for in_span
+#### Convenience Method: `in_span` and `add_tracer`
 
-This method acquires the correct `Tracer` so a new span can be created in a single call, below is a simple Rails controller example:
+`in_span` acquires the correct `Tracer` so a new span can be created in a single call.
+
+For example, using it in a Rails controller:
 
 ```ruby
 class StaticController < ApplicationController
@@ -78,6 +80,53 @@ class StaticController < ApplicationController
 end
 ```
 
+`add_tracer` can add a custom span to the specified instance or class method that is already defined. It can optionally set the span kind and additional attributes provided in hash format:
+
+```ruby
+add_tracer :method_name, 'custom_span_name', { attributes: { 'any' => 'attributes' }, kind: :span_kind }
+```
+
+For example, if you want to instrument class or instance method `create_session` inside an application controller:
+
+To instrument instance method
+
+```ruby
+class SessionsController < ApplicationController
+  include SolarWindsAPM::API::Tracer
+
+  def create
+    user = User.find_by(email: params[:session][:email].downcase)
+    create_session(user)
+  end
+
+  def create_session(user)
+  end
+
+  # instrument instance method create_session
+  add_tracer :create_session, 'custom_name', { attributes: { 'foo' => 'bar' }, kind: :consumer }
+end
+```
+
+To instrument class method
+
+```ruby
+class SessionsController < ApplicationController
+  def create
+    user = User.find_by(email: params[:session][:email].downcase)
+    create_session(user)
+  end
+
+  def self.create_session(user)
+  end
+
+  # instrument class method create_session
+  class << self
+    include SolarWindsAPM::API::Tracer
+    add_tracer :create_session, 'custom_name', { attributes: { 'foo' => 'bar' }, kind: :consumer }
+  end
+end
+```
+
 #### Get Curent Trace Context Information
 
 The `current_trace_info` method returns a `TraceInfo` object containing string representations of the current trace context that can be used in logging or manual propagation of context. This is a convenience method that wraps the OTel API `::OpenTelemetry::Trace.current_span`.
@@ -95,10 +144,10 @@ trace.trace_flags    # 01
 
 On startup, this library initializes and maintains a connection to a SolarWinds Observability collector, and receives settings used for making tracing decisions. This process can take up to a few seconds depending on the connection. If the application receives requests before initialization has completed, these requests will not be traced. While this is not critical for long-running server processes, it might be a problem for short-running apps such as cron jobs or CLI apps.
 
-A call to the `solarwinds_ready` method allows the application to block until initialization has completed and the library is ready for tracing. The method accepts an optional timeout parameter in milliseconds.
+A call to the `solarwinds_ready?` method allows the application to block until initialization has completed and the library is ready for tracing. The method accepts an optional timeout parameter in milliseconds.
 
 ```ruby
-SolarWindsAPM::API.solarwinds_ready(wait_milliseconds=3000)
+SolarWindsAPM::API.solarwinds_ready?(wait_milliseconds=3000)
 ```
 
 #### Set a Custom Transaction Name

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

@@ -169,9 +169,5 @@ if defined?(SolarWindsAPM::Config)
   # 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

@@ -111,12 +111,16 @@ module SolarWindsAPM
         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]
+          if defined?(::OpenTelemetry::Trace)
+            span     = ::OpenTelemetry::Trace.current_span
+            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]
+          else
+            %w[00000000000000000000000000000000 00000000 00 00-00000000000000000000000000000000-00000000-00]
+          end
         end
 
         # if true the trace info should be added to the log message

data/lib/solarwinds_apm/api/custom_instrumentation.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# © 2024 SolarWinds Worldwide, LLC. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at:http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+module SolarWindsAPM
+  module API
+    module Tracer
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Helper method to instrument custom method
+        #
+        # `add_tracer` can add a custom span to the specified instance or class method that is already defined.
+        # It requires the custom span name and optionally takes the span kind and additional attributes
+        # in hash format.
+        #
+        # === Argument:
+        #
+        # * +method_name+ - (String) A non-empty string that match the method name that need to be instrumented
+        # * +span_name+ - (String, optional, default = method_name) A non-empty string that define the span name (default to method_name)
+        # * +options+ - (Hash, optional, default = {}) A hash with desired options include attributes and span kind e.g. {attributes: {}, kind: :consumer}
+        #
+        # === Example:
+        #
+        #   class DogfoodsController < ApplicationController
+        #     include SolarWindsAPM::API::Tracer
+        #
+        #     def create
+        #       @dogfood = Dogfood.new(params.permit(:brand, :name))
+        #       @dogfood.save
+        #       custom_method
+        #     end
+        #
+        #     def custom_method
+        #     end
+        #     add_tracer :custom_method, 'custom_name', { attributes: { 'foo' => 'bar' }, kind: :consumer }
+        #
+        #   end
+        #
+        #   class DogfoodsController < ApplicationController
+        #     def create
+        #       @dogfood = Dogfood.new(params.permit(:brand, :name))
+        #       @dogfood.save
+        #       custom_method
+        #     end
+        #
+        #     def self.custom_method
+        #     end
+        #
+        #     class << self
+        #       include SolarWindsAPM::API::Tracer
+        #       add_tracer :custom_method, 'custom_name', { attributes: { 'foo' => 'bar' }, kind: :consumer }
+        #     end
+        #
+        #   end
+        #
+        # === Returns:
+        # * nil
+        #
+        def add_tracer(method_name, span_name = nil, options = {})
+          span_name = name.nil? ? "#{to_s.split(':').last&.tr('>', '')}/#{__method__}" : "#{name}/#{__method__}" if span_name.nil?
+
+          original_method = instance_method(method_name)
+
+          define_method(method_name) do |*args, &block|
+            SolarWindsAPM::API.in_span(span_name, **options) do |_span|
+              original_method.bind_call(self, *args, &block)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/solarwinds_apm/api/custom_metrics.rb

@@ -32,12 +32,9 @@ module SolarWindsAPM
       # === Returns:
       # * Boolean
       #
-      def increment_metric(name, count = 1, with_hostname = false, tags_kvs = {}) # rubocop:disable Style/OptionalBooleanParameter
-        return true unless SolarWindsAPM.loaded
-
-        with_hostname = with_hostname ? 1 : 0
-        tags, tags_count = make_tags(tags_kvs)
-        SolarWindsAPM::CustomMetrics.increment(name.to_s, count, with_hostname, nil, tags, tags_count).zero?
+      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.' }
+        false
       end
 
       # Send values with counts
@@ -66,29 +63,15 @@ module SolarWindsAPM
       # === Returns:
       # * Boolean
       #
-      def summary_metric(name, value, count = 1, with_hostname = false, tags_kvs = {}) # rubocop:disable Style/OptionalBooleanParameter
-        return true unless SolarWindsAPM.loaded
-
-        with_hostname = with_hostname ? 1 : 0
-        tags, tags_count = make_tags(tags_kvs)
-        SolarWindsAPM::CustomMetrics.summary(name.to_s, value, count, with_hostname, nil, tags, tags_count).zero?
+      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.' }
+        false
       end
 
       private
 
-      def make_tags(tags_kvs)
-        unless tags_kvs.is_a?(Hash)
-          SolarWindsAPM.logger.warn("[solarwinds_apm/metrics] CustomMetrics received tags_kvs that are not a Hash (found #{tags_kvs.class}), setting tags_kvs = {}")
-          tags_kvs = {}
-        end
-        count = tags_kvs.size
-        tags = SolarWindsAPM::MetricTags.new(count)
-
-        tags_kvs.each_with_index do |(k, v), i|
-          tags.add(i, k.to_s, v.to_s)
-        end
-
-        [tags, count]
+      def make_tags(_tags_kvs)
+        nil
       end
     end
   end

data/lib/solarwinds_apm/api/tracing.rb

@@ -12,22 +12,12 @@ module SolarWindsAPM
       # 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. It returns boolean if <tt>integer_response</tt> is false,
-      # and it will return integer if setting <tt>integer_response</tt> as true.
+      # information during the whole time the process is running.
       # Usually SolarWinds doesn't block an application while it is starting up.
       #
-      # For status code reference:
-      #   0: unknown error
-      #   1: is ready
-      #   2: not ready yet, try later
-      #   3: limit exceeded
-      #   4: invalid API key
-      #   5: connection error
-      #
       # === Argument:
       #
       # * +wait_milliseconds+ - (int, default 3000) the maximum time to wait in milliseconds
-      # * +integer_response+  - (boolean, default false) determine whether return status code of reporter or not
       #
       # === Example:
       #
@@ -35,24 +25,19 @@ module SolarWindsAPM
       #     Logger.info "SolarWindsAPM not ready after 10 seconds, no metrics will be sent"
       #   end
       #
-      #   # with status code print out
-      #   status = SolarWindsAPM::API.solarwinds_ready?(10_000, integer_response: true)
-      #   unless status == 1
-      #     Logger.info "SolarWindsAPM not ready after 10 seconds, no metrics will be sent. Error code "#{status}"
-      #   end
-      #
       # === Returns:
-      # * Boolean (if integer_response: false)
-      # * Integer (if integer_response: true)
-      #
-      def solarwinds_ready?(wait_milliseconds = 3000, integer_response: false)
-        return false unless SolarWindsAPM.loaded
-
-        is_ready = SolarWindsAPM::Context.isReady(wait_milliseconds)
-
-        return is_ready if integer_response
+      # * Boolean
+      #
+      def solarwinds_ready?(wait_milliseconds = 3000, integer_response: nil)
+        unless integer_response.nil?
+          SolarWindsAPM.logger.warn do
+            'Deprecation: solarwinds_ready? no longer accepts integer_response, this parameter will be removed in the next release.'
+          end
+        end
 
-        is_ready == 1
+        root_sampler = ::OpenTelemetry.tracer_provider.sampler.instance_variable_get(:@root)
+        is_ready = root_sampler.wait_until_ready(wait_milliseconds / 1000)
+        !!is_ready
       end
     end
   end

data/lib/solarwinds_apm/api/transaction_name.rb

@@ -39,23 +39,19 @@ module SolarWindsAPM
       #
       def set_transaction_name(custom_name = nil)
         status = true
-        if ENV.fetch('SW_APM_ENABLED', 'true') == 'false' ||
-           SolarWindsAPM::Context.toString == '99-00000000000000000000000000000000-0000000000000000-00'
-          # library disabled or noop, just log and skip work.
-          # TODO: can we have a single indicator that the API is in noop mode?
+        if ENV.fetch('SW_APM_ENABLED', 'true') == 'false'
           SolarWindsAPM.logger.debug { "[#{name}/#{__method__}] SolarWindsAPM is in disabled or noop mode." }
-        elsif custom_name.nil? || custom_name.empty?
+        elsif SolarWindsAPM::OTelNativeConfig[:metrics_processor].nil?
           SolarWindsAPM.logger.warn do
-            "[#{name}/#{__method__}] Set transaction name failed: custom_name is either nil or empty string."
+            "[#{name}/#{__method__}] Set transaction name failed: Solarwinds processor is missing. Noop mode."
           end
-          status = false
-        elsif SolarWindsAPM::OTelConfig[:metrics_processor].nil?
+        elsif custom_name.nil? || custom_name.empty?
           SolarWindsAPM.logger.warn do
-            "[#{name}/#{__method__}] Set transaction name failed: Solarwinds processor is missing."
+            "[#{name}/#{__method__}] Set transaction name failed: custom_name is either nil or empty string."
           end
           status = false
         else
-          solarwinds_processor = SolarWindsAPM::OTelConfig[:metrics_processor]
+          solarwinds_processor = SolarWindsAPM::OTelNativeConfig[:metrics_processor]
           current_span = ::OpenTelemetry::Trace.current_span
 
           if current_span.context.valid?

data/lib/solarwinds_apm/api.rb

@@ -11,6 +11,7 @@ require_relative 'api/current_trace_info'
 require_relative 'api/tracing'
 require_relative 'api/opentelemetry'
 require_relative 'api/custom_metrics'
+require_relative 'api/custom_instrumentation'
 
 module SolarWindsAPM
   module API
@@ -19,5 +20,6 @@ module SolarWindsAPM
     extend SolarWindsAPM::API::Tracing
     extend SolarWindsAPM::API::OpenTelemetry
     extend SolarWindsAPM::API::CustomMetrics
+    extend SolarWindsAPM::API::Tracer
   end
 end

data/lib/solarwinds_apm/config.rb

@@ -212,7 +212,7 @@ module SolarWindsAPM
 
         # Assure value is an integer
         @@config[key.to_sym] = new_value.to_i
-        SolarWindsAPM.sample_rate(new_value) if SolarWindsAPM.loaded
+        SolarWindsAPM.sample_rate(new_value)
 
       when :transaction_settings
         compile_settings(value)

data/lib/solarwinds_apm/constants.rb

@@ -32,5 +32,6 @@ module SolarWindsAPM
     INTL_SWO_OTEL_STATUS             = 'otel.status_code'
     INTL_SWO_OTEL_STATUS_DESCRIPTION = 'otel.status_description'
     INTERNAL_TRIGGERED_TRACE         = 'TriggeredTrace'
+    MAX_TXN_NAME_LENGTH              = 256
   end
 end

data/lib/solarwinds_apm/noop/api.rb

@@ -19,8 +19,9 @@ module NoopAPI
   # Tracing
   module Tracing
     # (wait_milliseconds=3000, integer_response: false)
-    def solarwinds_ready?(*_args, **options)
-      options && options[:integer_response] ? 0 : false
+    def solarwinds_ready?(_wait_milliseconds = 3000, integer_response: false)
+      _noop = integer_response
+      false
     end
   end
 
@@ -55,10 +56,12 @@ module NoopAPI
   # CustomMetrics
   module CustomMetrics
     def increment_metric(*)
+      SolarWindsAPM.logger.warn { 'increment_metric have been deprecated. Please use opentelemetry metrics-sdk to log metrics data.' }
       false
     end
 
     def summary_metric(*)
+      SolarWindsAPM.logger.warn { 'summary_metric have been deprecated. Please use opentelemetry metrics-sdk to log metrics data.' }
       false
     end
   end

data/lib/solarwinds_apm/noop.rb

@@ -6,28 +6,4 @@
 #
 # Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 
-require_relative 'noop/context'
-require_relative 'noop/metadata'
-require_relative 'noop/span'
 require_relative 'noop/api'
-
-module SolarWindsAPM
-  include Oboe_metal
-  # Reporter noop
-  class Reporter
-    ##
-    # noop version of :send_report
-    #
-    def self.send_report(event, with_system_timestamp: false); end
-
-    ##
-    # noop version of :send_status
-    #
-    def self.send_status(event, context = nil, with_system_timestamp: false); end
-
-    ##
-    # noop version of :start
-    #
-    def self.start; end
-  end
-end