solarwinds_apm 6.1.2 → 7.0.0.prev1

data/lib/solarwinds_apm/sampling/oboe_sampler.rb

@@ -0,0 +1,348 @@
+# frozen_string_literal: true
+
+# © 2023 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
+  class OboeSampler
+    SW_KEYS_ATTRIBUTE = 'SWKeys'
+    # SW_TRACESTATE_CAPTURE_KEY  = 'sw.w3c.tracestate'
+    PARENT_ID_ATTRIBUTE = 'sw.tracestate_parent_id' # used in parent_base_algo
+    SAMPLE_RATE_ATTRIBUTE = 'SampleRate'
+    SAMPLE_SOURCE_ATTRIBUTE = 'SampleSource'
+    BUCKET_CAPACITY_ATTRIBUTE = 'BucketCapacity'
+    BUCKET_RATE_ATTRIBUTE = 'BucketRate'
+    TRIGGERED_TRACE_ATTRIBUTE = 'TriggeredTrace'
+
+    TRACESTATE_REGEXP = /^[0-9a-f]{16}-[0-9a-f]{2}$/
+    BUCKET_INTERVAL = 1000
+    DICE_SCALE = 1_000_000
+
+    OTEL_SAMPLING_DECISION = ::OpenTelemetry::SDK::Trace::Samplers::Decision
+    OTEL_SAMPLING_RESULT   = ::OpenTelemetry::SDK::Trace::Samplers::Result
+    DEFAULT_TRACESTATE     = ::OpenTelemetry::Trace::Tracestate::DEFAULT
+
+    def initialize(logger)
+      @logger = logger
+      @counters = SolarWindsAPM::Metrics::Counter.new
+      @buckets = {
+        SolarWindsAPM::BucketType::DEFAULT =>
+          SolarWindsAPM::TokenBucket.new(SolarWindsAPM::TokenBucketSettings.new(nil, nil, BUCKET_INTERVAL)),
+        SolarWindsAPM::BucketType::TRIGGER_RELAXED =>
+          SolarWindsAPM::TokenBucket.new(SolarWindsAPM::TokenBucketSettings.new(nil, nil, BUCKET_INTERVAL)),
+        SolarWindsAPM::BucketType::TRIGGER_STRICT =>
+          SolarWindsAPM::TokenBucket.new(SolarWindsAPM::TokenBucketSettings.new(nil, nil, BUCKET_INTERVAL))
+      }
+      @settings = {} # parsed setting from swo backend
+
+      @buckets.each_value(&:start)
+    end
+
+    # return sampling result
+    # params: {:trace_id=>, :parent_context=>, :links=>, :name=>, :kind=>, :attributes=>}
+    # propagator -> processor -> sampler
+    def should_sample?(params)
+      @logger.debug { "should_sample? params: #{params.inspect}" }
+      _, parent_context, _, _, _, attributes = params.values
+
+      parent_span = ::OpenTelemetry::Trace.current_span(parent_context)
+      type = SolarWindsAPM::SpanType.span_type(parent_span)
+
+      @logger.debug { "[#{self.class}/#{__method__}] span type is #{type}" }
+
+      # For local spans, we always trust the parent
+      if type == SolarWindsAPM::SpanType::LOCAL
+        return OTEL_SAMPLING_RESULT.new(decision: OTEL_SAMPLING_DECISION::RECORD_AND_SAMPLE, tracestate: DEFAULT_TRACESTATE) if parent_span.context.trace_flags.sampled?
+
+        return OTEL_SAMPLING_RESULT.new(decision: OTEL_SAMPLING_DECISION::DROP, tracestate: DEFAULT_TRACESTATE)
+      end
+
+      sample_state = SampleState.new(OTEL_SAMPLING_DECISION::DROP,
+                                     attributes || {},
+                                     params,
+                                     get_settings(params),
+                                     parent_span.context.tracestate['sw'], # get tracestate with sw=xxxx
+                                     request_headers(params),
+                                     nil) # this is either TriggerTraceOptions or TraceOptionsResponse
+
+      @logger.debug { "[#{self.class}/#{__method__}] sample_state at start: #{sample_state.inspect}" }
+
+      @counters[:request_count].add(1)
+
+      # adding trigger trace attributes to sample_state attribute as part of decision
+      if sample_state.headers['X-Trace-Options']
+
+        # TraceOptions.parse_trace_options return TriggerTraceOptions
+        sample_state.trace_options = ::SolarWindsAPM::TraceOptions.parse_trace_options(sample_state.headers['X-Trace-Options'], @logger)
+
+        @logger.debug { "X-Trace-Options present: #{sample_state.trace_options}" }
+
+        if sample_state.headers['X-Trace-Options-Signature']
+          @logger.debug { 'X-Trace-Options-Signature present; validating' }
+
+          # this validate_signature is the function from trace_options file
+          sample_state.trace_options.response.auth = TraceOptions.validate_signature(
+            sample_state.headers['X-Trace-Options'],
+            sample_state.headers['X-Trace-Options-Signature'],
+            sample_state.settings[:signature_key],
+            sample_state.trace_options.timestamp
+          )
+
+          # If the request has an invalid signature, drop the trace
+          if sample_state.trace_options.response.auth != Auth::OK # Auth::OK is a string from trace_options.rb: 'ok'
+            @logger.debug { 'X-Trace-Options-Signature invalid; tracing disabled' }
+
+            xtracestate = generate_new_tracestate(parent_span, sample_state)
+            return OTEL_SAMPLING_RESULT.new(decision: OTEL_SAMPLING_DECISION::DROP, tracestate: xtracestate, attributes: sample_state.attributes)
+          end
+        end
+
+        unless sample_state.trace_options.trigger_trace
+          sample_state.trace_options.response.trigger_trace = TriggerTrace::NOT_REQUESTED # 'not-requested'
+        end
+
+        # Apply trace options to span attributes
+        sample_state.attributes[SW_KEYS_ATTRIBUTE] = sample_state.trace_options[:sw_keys] if sample_state.trace_options[:sw_keys]
+
+        sample_state.trace_options.custom.each do |k, v|
+          sample_state.attributes[k] = v
+        end
+
+        # List ignored keys in response
+        sample_state.trace_options.response.ignored = sample_state.trace_options[:ignored].map { |k, _| k } if sample_state.trace_options[:ignored].any?
+      end
+
+      unless sample_state.settings
+        @logger.debug { 'settings unavailable; sampling disabled' }
+
+        if sample_state.trace_options&.trigger_trace
+          @logger.debug { 'trigger trace requested but unavailable' }
+          sample_state.trace_options.response.trigger_trace = TriggerTrace::SETTINGS_NOT_AVAILABLE # 'settings-not-available'
+        end
+
+        xtracestate = generate_new_tracestate(parent_span, sample_state)
+
+        return OTEL_SAMPLING_RESULT.new(decision: OTEL_SAMPLING_DECISION::DROP,
+                                        tracestate: xtracestate,
+                                        attributes: sample_state.attributes)
+      end
+
+      @logger.debug { "[#{self.class}/#{__method__}] sample_state before deciding sampling algo: #{sample_state.inspect}" }
+      # Decide which sampling algo to use and add sampling attribute to decision attributes
+      # https://swicloud.atlassian.net/wiki/spaces/NIT/pages/3815473156/Tracing+Decision+Tree
+      if sample_state.trace_state && TRACESTATE_REGEXP.match?(sample_state.trace_state)
+        @logger.debug { 'context is valid for parent-based sampling' }
+        parent_based_algo(sample_state)
+
+      elsif sample_state.settings[:flags].anybits?(Flags::SAMPLE_START)
+        if sample_state.trace_options&.trigger_trace
+          @logger.debug { 'trigger trace requested' }
+          trigger_trace_algo(sample_state)
+        else
+          @logger.debug { 'defaulting to dice roll' }
+          dice_roll_algo(sample_state)
+        end
+      else
+        @logger.debug { 'SAMPLE_START is unset; sampling disabled' }
+        disabled_algo(sample_state)
+      end
+
+      @logger.debug { "final sampling state: #{sample_state.inspect}" }
+
+      xtracestate = generate_new_tracestate(parent_span, sample_state)
+
+      # if need to set 'sw.w3c.tracestate' to attributes
+      # sample_state.attributes['sw.w3c.tracestate'] = ::SolarWindsAPM::Utils.trace_state_header(xtracestate)
+
+      OTEL_SAMPLING_RESULT.new(decision: sample_state.decision,
+                               tracestate: xtracestate,
+                               attributes: sample_state.attributes)
+    end
+
+    def parent_based_algo(sample_state)
+      # original js code: const [context] = s.params
+      # the context is used for metrics e.g. this.#counters.throughTraceCount.add(1, {}, context)
+
+      # compare the parent_id
+      sample_state.attributes[PARENT_ID_ATTRIBUTE] = sample_state.trace_state[0, 16]
+
+      if sample_state.trace_options&.trigger_trace # need to implement trace_options
+        @logger.debug { 'trigger trace requested but ignored' }
+        sample_state.trace_options.response.trigger_trace = TriggerTrace::IGNORED # 'ignored'
+      end
+
+      if sample_state.settings[:flags].nobits?(Flags::SAMPLE_THROUGH_ALWAYS)
+        @logger.debug { 'SAMPLE_THROUGH_ALWAYS is unset; sampling disabled' }
+
+        if sample_state.settings[:flags].nobits?(Flags::SAMPLE_START)
+          @logger.debug { 'SAMPLE_START is unset; don\'t record' }
+          sample_state.decision = OTEL_SAMPLING_DECISION::DROP
+        else
+          @logger.debug { 'SAMPLE_START is set; record' }
+          sample_state.decision = OTEL_SAMPLING_DECISION::RECORD_ONLY
+        end
+      else
+        @logger.debug { 'SAMPLE_THROUGH_ALWAYS is set; parent-based sampling' }
+
+        flags = sample_state.trace_state[-2, 2].to_i(16)
+        sampled = flags & (::OpenTelemetry::Trace::TraceFlags::SAMPLED.sampled? ? 1 : 0)
+
+        if sampled.zero?
+          @logger.debug { 'parent is not sampled; record only' }
+
+          sample_state.decision = OTEL_SAMPLING_DECISION::RECORD_ONLY
+        else
+          @logger.debug { 'parent is sampled; record and sample' }
+
+          @counters[:trace_count].add(1)
+          @counters[:through_trace_count].add(1) # ruby metrics only add incremented value and attributes
+
+          sample_state.decision = OTEL_SAMPLING_DECISION::RECORD_AND_SAMPLE
+        end
+      end
+    end
+
+    def trigger_trace_algo(sample_state)
+      if sample_state.settings[:flags].nobits?(Flags::TRIGGERED_TRACE)
+        @logger.debug { 'TRIGGERED_TRACE unset; record only' }
+
+        sample_state.trace_options.response.trigger_trace = TriggerTrace::TRIGGER_TRACING_DISABLED # 'trigger-tracing-disabled'
+        sample_state.decision = OTEL_SAMPLING_DECISION::RECORD_ONLY
+      else
+        @logger.debug { 'TRIGGERED_TRACE set; trigger tracing' }
+        # If there's an auth response present, it's a valid signed request
+        # Otherwise, this code wouldn't be reached
+        if sample_state.trace_options.response.auth
+          @logger.debug { 'signed request; using relaxed rate' }
+
+          bucket = @buckets[BucketType::TRIGGER_RELAXED]
+        else
+          @logger.debug { 'unsigned request; using strict rate' }
+
+          bucket = @buckets[BucketType::TRIGGER_STRICT]
+        end
+
+        @logger.debug { "trigger_trace_algo bucket: #{bucket.inspect}" }
+        sample_state.attributes[TRIGGERED_TRACE_ATTRIBUTE] = true
+        sample_state.attributes[BUCKET_CAPACITY_ATTRIBUTE] = bucket.capacity
+        sample_state.attributes[BUCKET_RATE_ATTRIBUTE] = bucket.rate
+
+        if bucket.consume
+          @logger.debug { 'sufficient capacity; record and sample' }
+          @counters[:triggered_trace_count].add(1)
+          @counters[:trace_count].add(1)
+
+          sample_state.trace_options.response.trigger_trace = TriggerTrace::OK
+          sample_state.decision = OTEL_SAMPLING_DECISION::RECORD_AND_SAMPLE
+        else
+          @logger.debug { 'insufficient capacity; record only' }
+
+          sample_state.trace_options.response.trigger_trace = TriggerTrace::RATE_EXCEEDED
+          sample_state.decision = OTEL_SAMPLING_DECISION::RECORD_ONLY
+        end
+      end
+    end
+
+    def dice_roll_algo(sample_state)
+      dice = SolarWindsAPM::Dice.new(rate: sample_state.settings[:sample_rate], scale: DICE_SCALE)
+      sample_state.attributes[SAMPLE_RATE_ATTRIBUTE] = dice.rate
+      sample_state.attributes[SAMPLE_SOURCE_ATTRIBUTE] = sample_state.settings[:sample_source]
+
+      @counters[:sample_count].add(1)
+
+      if dice.roll
+        @logger.debug { 'dice roll success; checking capacity' }
+
+        bucket = @buckets[BucketType::DEFAULT]
+        sample_state.attributes[BUCKET_CAPACITY_ATTRIBUTE] = bucket.capacity
+        sample_state.attributes[BUCKET_RATE_ATTRIBUTE] = bucket.rate
+
+        @logger.debug { "dice_roll_algo bucket: #{bucket.inspect}" }
+        if bucket.consume
+          @logger.debug { 'sufficient capacity; record and sample' }
+
+          @counters[:trace_count].add(1)
+
+          sample_state.decision = OTEL_SAMPLING_DECISION::RECORD_AND_SAMPLE
+        else
+          @logger.debug { 'insufficient capacity; record only' }
+
+          @counters[:token_bucket_exhaustion_count].add(1)
+
+          sample_state.decision = OTEL_SAMPLING_DECISION::RECORD_ONLY
+        end
+      else
+        @logger.debug { 'dice roll failure; record only' }
+        sample_state.decision = OTEL_SAMPLING_DECISION::RECORD_ONLY
+      end
+    end
+
+    def disabled_algo(sample_state)
+      if sample_state.trace_options&.trigger_trace
+        @logger.debug { 'trigger trace requested but tracing disabled' }
+        sample_state.trace_options.response.trigger_trace = TriggerTrace::TRACING_DISABLED
+      end
+
+      if sample_state.settings[:flags].nobits?(Flags::SAMPLE_THROUGH_ALWAYS)
+        @logger.debug { "SAMPLE_THROUGH_ALWAYS is unset; don't record" }
+        sample_state.decision = OTEL_SAMPLING_DECISION::DROP
+      else
+        @logger.debug { 'SAMPLE_THROUGH_ALWAYS is set; record' }
+        sample_state.decision = OTEL_SAMPLING_DECISION::RECORD_ONLY
+      end
+    end
+
+    def update_settings(settings)
+      return unless settings[:timestamp] > (@settings[:timestamp] || 0)
+
+      @settings = settings
+      @buckets.each do |type, bucket|
+        bucket.update(@settings[:buckets][type]) if @settings[:buckets][type]
+      end
+    end
+
+    # old sampler seems set the  response headers through tracestate
+    # handle_response_headers functionality is replace by generate_new_tracestate
+    def generate_new_tracestate(parent_span, sample_state)
+      if !parent_span.context.valid? || parent_span.context.tracestate.nil?
+        @logger.debug { 'create new tracestate' }
+        decision = sw_from_span_and_decision(parent_span, sample_state.decision)
+        trace_state = ::OpenTelemetry::Trace::Tracestate.from_hash({ 'sw' => decision })
+      else
+        @logger.debug { 'update tracestate' }
+        decision = sw_from_span_and_decision(parent_span, sample_state.decision)
+        trace_state = parent_span.context.tracestate.set_value('sw', decision)
+      end
+
+      stringified_trace_options = SolarWindsAPM::TraceOptions.stringify_trace_options_response(sample_state.trace_options&.response)
+      @logger.debug { "[#{self.class}/#{__method__}] stringified_trace_options: #{stringified_trace_options}" }
+
+      trace_state = trace_state.set_value('xtrace_options_response', stringified_trace_options)
+      @logger.debug { "[#{self.class}/#{__method__}] new trace_state: #{trace_state.inspect}" }
+      trace_state
+    end
+
+    def sw_from_span_and_decision(parent_span, otel_decision)
+      trace_flag = otel_decision == OTEL_SAMPLING_DECISION::RECORD_AND_SAMPLE ? '01' : '00'
+      [parent_span.context.hex_span_id, trace_flag].join('-')
+    end
+
+    def get_settings(params)
+      return if @settings.empty?
+
+      expiry = (@settings[:timestamp] + @settings[:ttl]) * 1000
+      time_now = Time.now.to_i * 1000
+      if time_now > expiry
+        @logger.debug { 'settings expired, removing' }
+        @settings = nil
+        return
+      end
+      sampling_setting = SolarWindsAPM::SamplingSettings.merge(@settings, local_settings(params))
+      @logger.debug { "sampling_setting: #{sampling_setting.inspect}" }
+      sampling_setting
+    end
+  end
+end

data/lib/solarwinds_apm/sampling/sampler.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+# © 2023 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
+  class Sampler < OboeSampler
+    RUBY_SEM_CON = ::OpenTelemetry::SemanticConventions::Trace
+
+    ATTR_HTTP_REQUEST_METHOD = 'http.request.method'
+    ATTR_HTTP_METHOD = RUBY_SEM_CON::HTTP_METHOD
+    ATTR_HTTP_RESPONSE_STATUS_CODE = 'http.response.status_code'
+    ATTR_HTTP_STATUS_CODE = RUBY_SEM_CON::HTTP_STATUS_CODE
+    ATTR_URL_SCHEME = 'url.scheme'
+    ATTR_HTTP_SCHEME = RUBY_SEM_CON::HTTP_SCHEME
+    ATTR_SERVER_ADDRESS = 'server.address'
+    ATTR_NET_HOST_NAME = RUBY_SEM_CON::NET_HOST_NAME
+    ATTR_URL_PATH = 'url.path'
+    ATTR_HTTP_TARGET = RUBY_SEM_CON::HTTP_TARGET
+
+    # tracing_mode is getting from SolarWindsAPM::Config
+    def initialize(config, logger)
+      super(logger)
+      @tracing_mode = resolve_tracing_mode(config)
+      @trigger_mode = config[:trigger_trace_enabled]
+      @transaction_settings = config[:transaction_settings]
+      @ready = false
+    end
+
+    # wait for getting the first settings
+    def wait_until_ready(timeout = 10)
+      thread = Thread.new { settings_ready }
+      thread.join(timeout) || (thread.kill
+                               false)
+      @ready
+    end
+
+    def settings_ready(timeout = 10)
+      deadline = Time.now
+      loop do
+        break unless @settings.empty?
+
+        sleep 0.1
+        break if (Time.now - deadline).round(0) >= timeout
+      end
+      @ready = true unless @settings[:signature_key].nil?
+    end
+
+    def resolve_tracing_mode(config)
+      return unless config.key?(:tracing_mode) && !config[:tracing_mode].nil?
+
+      config[:tracing_mode] ? TracingMode::ALWAYS : TracingMode::NEVER
+    end
+
+    def local_settings(params)
+      _trace_id, _parent_context, _links, span_name, span_kind, attributes = params.values
+      settings = { tracing_mode: @tracing_mode, trigger_mode: @trigger_mode }
+      return settings if @transaction_settings.nil? || @transaction_settings.empty?
+
+      @logger.debug { "Current @transaction_settings: #{@transaction_settings.inspect}" }
+      http_metadata = http_span_metadata(span_kind, attributes)
+      @logger.debug { "http_metadata: #{http_metadata.inspect}" }
+
+      # below is for filter out unwanted transaction
+      trans_settings = ::SolarWindsAPM::TransactionSettings.new(url_path: http_metadata[:url], name: span_name, kind: span_kind)
+      tracing_mode   = trans_settings.calculate_trace_mode == 1 ? TracingMode::ALWAYS : TracingMode::NEVER
+
+      settings[:tracing_mode] = tracing_mode
+      settings
+    end
+
+    # if context have sw-related value, it should be stored in context
+    # named sw_xtraceoptions in header propagator
+    # original x_trace_options will parse headers in the class, apm-js separate the task
+    # apm-js will make headers as hash
+    def request_headers(params)
+      parent_context = params[:parent_context]
+      header = obtain_sw_value(parent_context, 'sw_xtraceoptions')
+      signature = obtain_sw_value(parent_context, 'sw_signature')
+      @logger.debug { "[#{self.class}/#{__method__}] trace_options option_header: #{header}; trace_options sw_signature: #{signature}" }
+
+      {
+        'X-Trace-Options' => header,
+        'X-Trace-Options-Signature' => signature
+      }
+    end
+
+    def obtain_sw_value(context, type)
+      sw_value = nil
+      instance_variable = context&.instance_variable_get('@entries')
+      instance_variable&.each do |key, value|
+        next unless key.instance_of?(::String)
+
+        sw_value = value if key == type
+      end
+      sw_value
+    end
+
+    def update_settings(settings)
+      parsed = parse_settings(settings)
+      if parsed
+        @logger.debug { "valid settings #{parsed.inspect} from setting #{settings.inspect}" }
+
+        super(parsed) # call oboe_sampler update_settings function to update the buckets
+
+        @logger.warn { "Warning from parsed settings: #{parsed[:warning]}" } if parsed[:warning]
+
+        parsed
+      else
+        @logger.debug { "invalid settings: #{settings.inspect}" }
+        nil
+      end
+    end
+
+    def http_span_metadata(kind, attributes)
+      return { http: false } unless kind == ::OpenTelemetry::Trace::SpanKind::SERVER &&
+                                    (attributes.key?(ATTR_HTTP_REQUEST_METHOD) || attributes.key?(ATTR_HTTP_METHOD))
+
+      method_ = (attributes[ATTR_HTTP_REQUEST_METHOD] || attributes[ATTR_HTTP_METHOD]).to_s
+      status = (attributes[ATTR_HTTP_RESPONSE_STATUS_CODE] || attributes[ATTR_HTTP_STATUS_CODE] || 0).to_i
+      scheme = (attributes[ATTR_URL_SCHEME] || attributes[ATTR_HTTP_SCHEME] || 'http').to_s
+      hostname = (attributes[ATTR_SERVER_ADDRESS] || attributes[ATTR_NET_HOST_NAME] || 'localhost').to_s
+      path = (attributes[ATTR_URL_PATH] || attributes[ATTR_HTTP_TARGET]).to_s
+      url = "#{scheme}://#{hostname}#{path}"
+
+      http_metadata = {
+        http: true,
+        method: method_,
+        status: status,
+        scheme: scheme,
+        hostname: hostname,
+        path: path,
+        url: url
+      }
+
+      @logger.debug { "Retrieved http metadata: #{http_metadata.inspect}" }
+      http_metadata
+    end
+
+    def parse_settings(unparsed)
+      return unless unparsed.is_a?(Hash)
+
+      return unless unparsed['value'].is_a?(Numeric) &&
+                    unparsed['timestamp'].is_a?(Numeric) &&
+                    unparsed['ttl'].is_a?(Numeric)
+
+      sample_rate = unparsed['value']
+      timestamp = unparsed['timestamp']
+      ttl = unparsed['ttl']
+
+      return unless unparsed['flags'].is_a?(String)
+
+      flags = unparsed['flags'].split(',').reduce(Flags::OK) do |final_flag, f|
+        flag = {
+          'OVERRIDE' => Flags::OVERRIDE,
+          'SAMPLE_START' => Flags::SAMPLE_START,
+          'SAMPLE_THROUGH_ALWAYS' => Flags::SAMPLE_THROUGH_ALWAYS,
+          'TRIGGER_TRACE' => Flags::TRIGGERED_TRACE
+        }[f]
+
+        final_flag |= flag if flag
+        final_flag
+      end
+
+      buckets = {}
+      signature_key = nil
+
+      if unparsed['arguments'].is_a?(Hash)
+        args = unparsed['arguments']
+
+        buckets[BucketType::DEFAULT] = { capacity: args['BucketCapacity'], rate: args['BucketRate'] } if args['BucketCapacity'].is_a?(Numeric) && args['BucketRate'].is_a?(Numeric)
+
+        buckets['trigger_relaxed'] = { capacity: args['TriggerRelaxedBucketCapacity'], rate: args['TriggerRelaxedBucketRate'] } if args['TriggerRelaxedBucketCapacity'].is_a?(Numeric) && args['TriggerRelaxedBucketRate'].is_a?(Numeric)
+
+        buckets['trigger_strict'] = { capacity: args['TriggerStrictBucketCapacity'], rate: args['TriggerStrictBucketRate'] } if args['TriggerStrictBucketCapacity'].is_a?(Numeric) && args['TriggerStrictBucketRate'].is_a?(Numeric)
+
+        signature_key = args['SignatureKey'] if args['SignatureKey'].is_a?(String)
+      end
+
+      warning = unparsed['warning'] if unparsed['warning'].is_a?(String)
+
+      {
+        sample_source: SampleSource::REMOTE,
+        sample_rate: sample_rate,
+        flags: flags,
+        timestamp: timestamp,
+        ttl: ttl,
+        buckets: buckets,
+        signature_key: signature_key,
+        warning: warning
+      }
+    end
+  end
+end

data/lib/solarwinds_apm/sampling/sampling_constants.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+# © 2023 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
+  TriggerTraceOptions = Struct.new(
+    :trigger_trace,
+    :timestamp,
+    :sw_keys,
+    :custom,      # Hash
+    :ignored,     # Array
+    :response     # TraceOptionsResponse
+  )
+
+  TraceOptionsResponse = Struct.new(
+    :auth,           # Auth
+    :trigger_trace,  # TriggerTrace
+    :ignored         # Array
+  )
+
+  module Auth
+    OK = 'ok'
+    BAD_TIMESTAMP = 'bad-timestamp'
+    BAD_SIGNATURE = 'bad-signature'
+    NO_SIGNATURE_KEY = 'no-signature-key'
+  end
+
+  module TriggerTrace
+    OK = 'ok'
+    NOT_REQUESTED = 'not-requested'
+    IGNORED = 'ignored'
+    TRACING_DISABLED = 'tracing-disabled'
+    TRIGGER_TRACING_DISABLED = 'trigger-tracing-disabled'
+    RATE_EXCEEDED = 'rate-exceeded'
+    SETTINGS_NOT_AVAILABLE = 'settings-not-available'
+  end
+
+  Settings = Struct.new(:sample_rate,
+                        :sample_source,
+                        :flags,
+                        :buckets,           # BucketSettings
+                        :signature_key,
+                        :timestamp,
+                        :ttl)
+
+  LocalSettings = Struct.new(:tracing_mode, # TracingMode
+                             :trigger_mode) # {:enabled, :disabled}
+
+  BucketSettings = Struct.new(:capacity, # Number
+                              :rate) # Number
+
+  TokenBucketSettings = Struct.new(:capacity,    # Number
+                                   :rate,        # Number
+                                   :interval) # Number
+
+  module SampleSource
+    LOCAL_DEFAULT = 2
+    REMOTE = 6
+  end
+
+  module Flags
+    OK = 0x0
+    INVALID = 0x1
+    OVERRIDE = 0x2
+    SAMPLE_START = 0x4
+    SAMPLE_THROUGH_ALWAYS = 0x10
+    TRIGGERED_TRACE = 0x20
+  end
+
+  module TracingMode
+    ALWAYS = Flags::SAMPLE_START | Flags::SAMPLE_THROUGH_ALWAYS
+    NEVER = 0x0
+  end
+
+  module BucketType
+    DEFAULT = ''
+    TRIGGER_RELAXED = 'trigger_relaxed'
+    TRIGGER_STRICT = 'trigger_strict'
+  end
+
+  module SpanType
+    ROOT = 'root'
+    ENTRY = 'entry'
+    LOCAL = 'local'
+
+    VALID_TRACEID_REGEX = /^[0-9a-f]{32}$/i
+    VALID_SPANID_REGEX = /^[0-9a-f]{16}$/i
+
+    INVALID_SPANID = '0000000000000000'
+    INVALID_TRACEID = '00000000000000000000000000000000'
+
+    def self.span_type(parent_span)
+      parent_span_context = parent_span&.context
+      if parent_span_context.nil? || !span_context_valid?(parent_span_context)
+        ROOT
+      elsif parent_span_context.remote?
+        ENTRY
+      else
+        LOCAL
+      end
+    end
+
+    def self.valid_trace_id?(trace_id)
+      !!(trace_id =~ VALID_TRACEID_REGEX) && trace_id != INVALID_TRACEID
+    end
+
+    def self.valid_span_id?(span_id)
+      !!(span_id =~ VALID_SPANID_REGEX) && span_id != INVALID_SPANID
+    end
+
+    def self.span_context_valid?(span_context)
+      valid_trace_id?(span_context.hex_trace_id) && valid_span_id?(span_context.hex_span_id)
+    end
+  end
+
+  SampleState = Struct.new(:decision,     # SamplingDecision
+                           :attributes,   # Attributes
+                           :params,       # SampleParams
+                           :settings,     # Settings
+                           :trace_state, # String
+                           :headers, # RequestHeaders
+                           :trace_options) # TraceOptions & { response: TraceOptionsResponse })
+end