bugsnag_performance 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 31cfcfc45215dec768c1e6040c418f63355ea308cf2d8d660ccad2c3f2de3621
+  data.tar.gz: e3868f8cd3341f285e0bd868c3db54e640739ed0a755308162c3dac96cf47b76
+SHA512:
+  metadata.gz: f394a3a656e3bbd76aa825db67b2e6bd156590d666648ca6484df820fc833f8904e24dce311084bcfc64ff4e064f5bbcd181a92e51a60d27c7ccedf7a029ccd4
+  data.tar.gz: 9f8ad547b130279f751169c2305ce57faaf34a566782abca3df7fc307efbab8b14873c6ef0946069a0f49f159d40d8b225969eaf5defa5bb236b402e10afd05d

data/CHANGELOG.md

@@ -0,0 +1,2 @@
+Changelog
+=========

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 BugSnag
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/bugsnag-performance.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "lib/bugsnag_performance/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "bugsnag_performance"
+  spec.version = BugsnagPerformance::VERSION
+  spec.authors = ["BugSnag"]
+  spec.email = ["notifiers@bugsnag.com"]
+
+  spec.summary = "BugSnag integration for the Ruby Open Telemetry SDK"
+  spec.homepage = "https://www.bugsnag.com"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0"
+  spec.require_paths = ["lib"]
+
+  spec.metadata["homepage_uri"] = spec.homepage
+
+  github_url = "https://github.com/bugsnag/bugsnag-ruby-performance"
+
+  spec.metadata["source_code_uri"] = "#{github_url}"
+  spec.metadata["bug_tracker_uri"] = "#{github_url}/issues"
+  spec.metadata["changelog_uri"] = "#{github_url}/blob/v#{BugsnagPerformance::VERSION}/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://docs.bugsnag.com/performance/integration-guides/ruby/"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github .rspec Gemfile])
+    end
+  end
+
+  spec.add_dependency "concurrent-ruby", "~> 1.3"
+  spec.add_dependency "opentelemetry-sdk", "~> 1.2"
+
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "webmock", "~> 3.23"
+end

data/lib/bugsnag_performance/configuration.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module BugsnagPerformance
+  class Configuration
+    attr_reader :open_telemetry_configure_block
+    attr_reader :logger
+
+    attr_accessor :api_key
+    attr_accessor :app_version
+    attr_accessor :release_stage
+    attr_accessor :enabled_release_stages
+    attr_accessor :use_managed_quota
+
+    attr_writer :endpoint
+
+    def initialize(errors_configuration)
+      @open_telemetry_configure_block = proc { |c| }
+      self.logger = errors_configuration.logger || OpenTelemetry.logger
+
+      @api_key = fetch(errors_configuration, :api_key, env: "BUGSNAG_PERFORMANCE_API_KEY")
+      @app_version = fetch(errors_configuration, :app_version)
+      @release_stage = fetch(errors_configuration, :release_stage, env: "BUGSNAG_PERFORMANCE_RELEASE_STAGE", default: "production")
+      @use_managed_quota = true
+
+      @enabled_release_stages = fetch(errors_configuration, :enabled_release_stages, env: "BUGSNAG_PERFORMANCE_ENABLED_RELEASE_STAGES")
+
+      # transform enabled release stages into an array if we read its value from
+      # the environment
+      if @enabled_release_stages.is_a?(String)
+        @enabled_release_stages = @enabled_release_stages.split(",").map(&:strip)
+      end
+    end
+
+    def logger=(logger)
+      @logger =
+        if logger.is_a?(Internal::LoggerWrapper)
+          logger
+        else
+          Internal::LoggerWrapper.new(logger)
+        end
+    end
+
+    def endpoint
+      case
+      when defined?(@endpoint)
+        # if a custom endpoint has been set then use it directly
+        @endpoint
+      when @api_key.nil?
+        # if there's no API key then we can't construct the default URL
+        nil
+      else
+        "https://#{@api_key}.otlp.bugsnag.com/v1/traces"
+      end
+    end
+
+    def configure_open_telemetry(&open_telemetry_configure_block)
+      @open_telemetry_configure_block = open_telemetry_configure_block
+    end
+
+    private
+
+    def fetch(
+      errors_configuration,
+      name,
+      env: nil,
+      default: nil
+    )
+      if env
+        value = ENV[env]
+
+        return value unless value.nil?
+      end
+
+      value = errors_configuration.send(name)
+      return value unless value.nil?
+
+      default
+    end
+  end
+end

data/lib/bugsnag_performance/error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module BugsnagPerformance
+  class Error < StandardError; end
+
+  class MissingApiKeyError < Error
+    def initialize
+      super("No Bugsnag API Key set")
+    end
+  end
+end

data/lib/bugsnag_performance/internal/configuration_validator.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module BugsnagPerformance
+  module Internal
+    class ConfigurationValidator
+      def self.validate(configuration)
+        new(configuration).validate
+      end
+
+      def validate
+        raise MissingApiKeyError.new if @configuration.api_key.nil?
+
+        validate_open_telemetry_configure_block
+        validate_logger
+        validate_api_key
+        validate_string(:app_version, optional: true)
+        validate_string(:release_stage, optional: true)
+        validate_array(:enabled_release_stages, "non-empty strings", optional: true, &method(:valid_string?))
+        validate_boolean(:use_managed_quota, optional: false)
+        valid_endpoint = validate_endpoint
+
+        # if the endpoint is invalid then we shouldn't attempt to send traces
+        Result.new(@messages, @valid_configuration, send_traces: valid_endpoint)
+      end
+
+      private
+
+      def initialize(configuration)
+        @configuration = configuration
+        @valid_configuration = BugsnagPerformance::Configuration.new(BugsnagPerformance::Internal::NilErrorsConfiguration.new)
+        @messages = []
+      end
+
+      def validate_open_telemetry_configure_block
+        value = @configuration.open_telemetry_configure_block
+
+        if value.respond_to?(:call) && value.arity == 1
+          @valid_configuration.configure_open_telemetry(&value)
+        else
+          @messages << "configure_open_telemetry requires a callable with an arity of 1"
+        end
+      end
+
+      def validate_logger
+        value = @configuration.logger
+
+        if value.is_a?(LoggerWrapper) && value.logger.is_a?(::Logger)
+          @valid_configuration.logger = value
+        else
+          @messages << "logger should be a ::Logger, got #{value.logger.inspect}"
+        end
+      end
+
+      def validate_api_key
+        value = @configuration.api_key
+
+        # we always use the provided API key even if it's invalid
+        @valid_configuration.api_key = value
+
+        return if value.is_a?(String) && value =~ /\A[0-9a-f]{32}\z/i
+
+        @messages << "api_key should be a 32 character hexadecimal string, got #{value.inspect}"
+      end
+
+      def validate_string(name, optional:)
+        value = @configuration.send(name)
+
+        if (value.nil? && optional) || valid_string?(value)
+          @valid_configuration.send("#{name}=", value)
+        else
+          @messages << "#{name} should be a non-empty string, got #{value.inspect}"
+        end
+      end
+
+      def validate_boolean(name, optional:)
+        value = @configuration.send(name)
+
+        if (value.nil? && optional) || value == true || value == false
+          @valid_configuration.send("#{name}=", value)
+        else
+          @messages << "#{name} should be a boolean, got #{value.inspect}"
+        end
+      end
+
+      def validate_array(name, description, optional:, &block)
+        value = @configuration.send(name)
+
+        if (value.nil? && optional) || value.is_a?(Array) && value.all?(&block)
+          @valid_configuration.send("#{name}=", value)
+        else
+          @messages << "#{name} should be an array of #{description}, got #{value.inspect}"
+        end
+      end
+
+      def validate_endpoint
+        value = @configuration.endpoint
+
+        # we always use the provided endpoint even if it's invalid to prevent
+        # leaking data to the saas bugsnag instance
+        @valid_configuration.endpoint = value
+
+        if valid_string?(value)
+          true
+        else
+          @messages << "endpoint should be a valid URL, got #{value.inspect}"
+
+          false
+        end
+      end
+
+      def valid_string?(value)
+        value.is_a?(String) && !value.empty?
+      end
+
+      class Result
+        attr_reader :messages
+        attr_reader :configuration
+
+        def initialize(messages, configuration, send_traces:)
+          @messages = messages
+          @configuration = configuration.freeze
+          @send_traces = send_traces
+        end
+
+        def valid?
+          @messages.empty?
+        end
+
+        def send_traces?
+          @send_traces
+        end
+      end
+    end
+  end
+end

data/lib/bugsnag_performance/internal/delivery.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module BugsnagPerformance
+  module Internal
+    class Delivery
+      def initialize(configuration)
+        @uri = URI(configuration.endpoint)
+        @common_headers = {
+          "Bugsnag-Api-Key" => configuration.api_key,
+          "Content-Type" => "application/json",
+        }.freeze
+      end
+
+      def deliver(headers, body)
+        headers = headers.merge(
+          @common_headers,
+          { "Bugsnag-Sent-At" => Time.now.utc.iso8601(3) },
+        )
+
+        raw_response = OpenTelemetry::Common::Utilities.untraced do
+          Net::HTTP.post(@uri, body, headers)
+        end
+
+        Response.new(raw_response)
+      end
+
+      class Response
+        SAMPLING_PROBABILITY_HEADER = "Bugsnag-Sampling-Probability"
+        RETRYABLE_STATUS_CODES = Set[402, 407, 408, 429]
+
+        private_constant :SAMPLING_PROBABILITY_HEADER, :RETRYABLE_STATUS_CODES
+
+        attr_reader :state
+        attr_reader :sampling_probability
+
+        def initialize(raw_response)
+          if raw_response.nil?
+            @state = :failure_retryable
+            @sampling_probability = nil
+          else
+            @state = response_state_from_status_code(raw_response.code)
+            @sampling_probability = parse_sampling_probability(raw_response[SAMPLING_PROBABILITY_HEADER])
+          end
+        end
+
+        def successful?
+          @state == :success
+        end
+
+        def retryable?
+          @state == :failure_retryable
+        end
+
+        private
+
+        def response_state_from_status_code(raw_status_code)
+          case Integer(raw_status_code, exception: false)
+          when 200...300
+            :success
+          when RETRYABLE_STATUS_CODES
+            :failure_retryable
+          when 400...500
+            :failure_discard
+          else
+            :failure_retryable
+          end
+        end
+
+        def parse_sampling_probability(raw_probability)
+          parsed = Float(raw_probability, exception: false)
+
+          if parsed && parsed >= 0.0 && parsed <= 1.0
+            parsed
+          else
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bugsnag_performance/internal/logger_wrapper.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module BugsnagPerformance
+  module Internal
+    class LoggerWrapper
+      attr_reader :logger
+
+      def initialize(logger)
+        @logger = logger
+      end
+
+      def debug(message)
+        @logger.debug("[BugsnagPerformance] #{message}")
+      end
+
+      def info(message)
+        @logger.info("[BugsnagPerformance] #{message}")
+      end
+
+      def warn(message)
+        @logger.warn("[BugsnagPerformance] #{message}")
+      end
+
+      def error(message)
+        @logger.error("[BugsnagPerformance] #{message}")
+      end
+    end
+  end
+end

data/lib/bugsnag_performance/internal/nil_errors_configuration.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module BugsnagPerformance
+  module Internal
+    # this class is used when the bugsnag-ruby (aka "bugsnag errors") gem isn't
+    # installed to provide the API we need in BugsnagPerformance::Configuration
+    class NilErrorsConfiguration
+      attr_accessor :api_key
+      attr_accessor :app_version
+      attr_accessor :release_stage
+      attr_accessor :enabled_release_stages
+      attr_accessor :logger
+    end
+  end
+end

data/lib/bugsnag_performance/internal/payload_encoder.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module BugsnagPerformance
+  module Internal
+    class PayloadEncoder
+      # https://github.com/open-telemetry/opentelemetry-proto/blob/484241a016d7b81f20b6e19d00ffbc4a3b864a22/opentelemetry/proto/trace/v1/trace.proto#L150-L176
+      SPAN_KIND_UNSPECIFIED = 0
+      SPAN_KIND_INTERNAL = 1
+      SPAN_KIND_SERVER = 2
+      SPAN_KIND_CLIENT = 3
+      SPAN_KIND_PRODUCER = 4
+      SPAN_KIND_CONSUMER = 5
+
+      # https://github.com/open-telemetry/opentelemetry-proto/blob/484241a016d7b81f20b6e19d00ffbc4a3b864a22/opentelemetry/proto/trace/v1/trace.proto#L312-L320
+      SPAN_STATUS_OK = 0
+      SPAN_STATUS_UNSET = 1
+      SPAN_STATUS_ERROR = 2
+
+      private_constant :SPAN_KIND_UNSPECIFIED,
+        :SPAN_KIND_INTERNAL,
+        :SPAN_KIND_SERVER,
+        :SPAN_KIND_CLIENT,
+        :SPAN_KIND_PRODUCER,
+        :SPAN_KIND_CONSUMER,
+        :SPAN_STATUS_OK,
+        :SPAN_STATUS_UNSET,
+        :SPAN_STATUS_ERROR
+
+      def initialize(sampler)
+        @sampler = sampler
+      end
+
+      def encode(span_data)
+        {
+          resourceSpans: span_data
+            .filter { |span| @sampler.resample_span?(span) }
+            .group_by(&:resource)
+            .map do |resource, scope_spans|
+              {
+                resource: {
+                  attributes: resource.attribute_enumerator.map(&method(:attribute_to_json)),
+                },
+                scopeSpans: scope_spans
+                  .group_by(&:instrumentation_scope)
+                  .map do |scope, spans|
+                    {
+                      scope: { name: scope.name, version: scope.version },
+                      spans: spans.map(&method(:span_to_json)),
+                    }
+                  end,
+              }
+            end
+        }
+      end
+
+      private
+
+      def span_to_json(span)
+        {
+          name: span.name,
+          kind: kind_to_json(span.kind),
+          spanId: span.hex_span_id,
+          traceId: span.hex_trace_id,
+          parentSpanId: span.parent_span_id == OpenTelemetry::Trace::INVALID_SPAN_ID ? nil : span.hex_parent_span_id,
+          startTimeUnixNano: span.start_timestamp.to_s,
+          endTimeUnixNano: span.end_timestamp.to_s,
+          traceState: span.tracestate.to_s,
+          droppedAttributesCount: calculate_dropped_count(span.total_recorded_attributes, span.attributes),
+          droppedEventsCount: calculate_dropped_count(span.total_recorded_events, span.events),
+          droppedLinksCount: calculate_dropped_count(span.total_recorded_links, span.links),
+          status: { code: span.status.code, message: span.status.description },
+          attributes: span.attributes&.map(&method(:attribute_to_json)),
+          events: span.events&.map do |event|
+            {
+              name: event.name,
+              timeUnixNano: event.timestamp.to_s,
+              attributes: event.attributes&.map(&method(:attribute_to_json))
+              # the OTel SDK doesn't provide dropped_attributes_count for events
+            }.tap(&:compact!)
+          end,
+          links: span.links&.map do |link|
+            context = link.span_context
+
+            {
+              traceId: context.hex_trace_id,
+              spanId: context.hex_span_id,
+              traceState: context.tracestate.to_s,
+              attributes: link.attributes&.map(&method(:attribute_to_json))
+              # the OTel SDK doesn't provide dropped_attributes_count for links
+            }.tap(&:compact!)
+          end,
+        }.tap(&:compact!)
+      end
+
+      def attribute_to_json(key, value)
+        { key: key, value: attribute_value_to_json(value) }
+      end
+
+      def attribute_value_to_json(value)
+        case value
+        when Integer
+          { intValue: value.to_s }
+        when Float
+          { doubleValue: value }
+        when true, false
+          { boolValue: value }
+        when String
+          { stringValue: value }
+        when Array
+          { arrayValue: value.map(&method(:attribute_value_to_json)) }
+        end
+      end
+
+      def kind_to_json(kind)
+        case kind
+        when :internal
+          SPAN_KIND_INTERNAL
+        when :server
+          SPAN_KIND_SERVER
+        when :client
+          SPAN_KIND_CLIENT
+        when :producer
+          SPAN_KIND_PRODUCER
+        when :consumer
+          SPAN_KIND_CONSUMER
+        else
+          SPAN_KIND_UNSPECIFIED
+        end
+      end
+
+      def calculate_dropped_count(total_items, remaining_items)
+        return 0 if remaining_items.nil?
+
+        dropped_count = total_items - remaining_items.length
+        return 0 if dropped_count.negative?
+
+        dropped_count
+      end
+    end
+  end
+end

data/lib/bugsnag_performance/internal/probability_fetcher.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module BugsnagPerformance
+  module Internal
+    class ProbabilityFetcher
+      # the time to wait before retrying a failed request
+      RETRY_SECONDS = 30
+      STALE_PROBABILITY_SECONDS = 60 * 60 * 24 # 24 hours
+      HEADERS = { "Bugsnag-Span-Sampling" => "1.0:0" }
+      BODY = '{"resourceSpans": []}'
+
+      private_constant :RETRY_SECONDS, :STALE_PROBABILITY_SECONDS, :HEADERS, :BODY
+
+      def initialize(logger, delivery, task_scheduler)
+        @logger = logger
+        @delivery = delivery
+        @task_scheduler = task_scheduler
+      end
+
+      def stale_in(seconds)
+        @task.schedule(seconds)
+      end
+
+      def on_new_probability(&on_new_probability_callback)
+        @task = @task_scheduler.now do |done|
+          get_new_probability do |new_probability|
+            on_new_probability_callback.call(new_probability)
+
+            done.call
+          end
+        end
+      end
+
+      private
+
+      def get_new_probability(&block)
+        # keep making requests until we get a new probability from the server
+        loop do
+          begin
+            response = @delivery.deliver(HEADERS, BODY)
+          rescue => exception
+            # do nothing, we'll warn about this shortly...
+          end
+
+          # in theory this should always be present, but it's possible the request
+          # fails or there's a bug on the server side causing it not to be returned
+          if response && new_probability = response.sampling_probability
+            new_probability = Float(new_probability, exception: false)
+
+            if new_probability && new_probability >= 0.0 && new_probability <= 1.0
+              block.call(new_probability)
+
+              break
+            end
+          end
+
+          @logger.warn("Failed to retrieve a probability value from BugSnag. Retrying in 30 seconds.")
+          @logger.warn(exception) if exception
+
+          # wait a bit before trying again
+          sleep(RETRY_SECONDS)
+        end
+      end
+    end
+  end
+end

data/lib/bugsnag_performance/internal/probability_manager.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module BugsnagPerformance
+  module Internal
+    class ProbabilityManager
+      # the duration (in seconds) that a probability value is considered stale
+      # and therefore we need to fetch a new value
+      STALE_PROBABILITY_SECONDS = 60 * 60 * 24 # 24 hours
+      private_constant :STALE_PROBABILITY_SECONDS
+
+      def initialize(probability_fetcher)
+        @probability_fetcher = probability_fetcher
+        @probability = 1.0
+        @lock = Mutex.new
+
+        @probability_fetcher.on_new_probability do |new_probability|
+          self.probability = new_probability
+        end
+      end
+
+      def probability
+        @lock.synchronize do
+          @probability
+        end
+      end
+
+      def probability=(new_probability)
+        @lock.synchronize do
+          @probability = new_probability
+          @probability_fetcher.stale_in(STALE_PROBABILITY_SECONDS)
+        end
+      end
+    end
+  end
+end

data/lib/bugsnag_performance/internal/sampler.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module BugsnagPerformance
+  module Internal
+    class Sampler
+      PROBABILITY_SCALE_FACTOR = 18_446_744_073_709_551_615 # (2 ** 64) - 1
+
+      private_constant :PROBABILITY_SCALE_FACTOR
+
+      def initialize(probability_manager)
+        @probability_manager = probability_manager
+      end
+
+      def should_sample?(trace_id:, parent_context:, links:, name:, kind:, attributes:)
+        # NOTE: the probability could change at any time so we _must_ only read
+        #       it once in this method, otherwise we could use different values
+        #       for the sampling decision & p value attribute which would result
+        #       in inconsistent data
+        probability = @probability_manager.probability
+
+        decision =
+          if sample_using_probability_and_trace_id?(probability, trace_id)
+            OpenTelemetry::SDK::Trace::Samplers::Decision::RECORD_AND_SAMPLE
+          else
+            OpenTelemetry::SDK::Trace::Samplers::Decision::DROP
+          end
+
+        parent_span_context = OpenTelemetry::Trace.current_span(parent_context).context
+
+        OpenTelemetry::SDK::Trace::Samplers::Result.new(
+          decision: decision,
+          tracestate: parent_span_context.tracestate,
+          attributes: { "bugsnag.sampling.p" => probability },
+        )
+      end
+
+      # @api private
+      def resample_span?(span)
+        probability = @probability_manager.probability
+
+        # sample all spans that are missing the p value attribute
+        return true if span.attributes.nil? || span.attributes["bugsnag.sampling.p"].nil?
+
+        # update the p value attribute if it was originally sampled with a larger
+        # probability than the current value
+        if span.attributes["bugsnag.sampling.p"] > probability
+          span.attributes["bugsnag.sampling.p"] = probability
+        end
+
+        sample_using_probability_and_trace_id?(span.attributes["bugsnag.sampling.p"], span.trace_id)
+      end
+
+      private
+
+      def sample_using_probability_and_trace_id?(probability, trace_id)
+        # scale the probability (stored as a float from 0-1) to a u64
+        p_value = (probability * PROBABILITY_SCALE_FACTOR).floor
+
+        # unpack the trace ID as a u64
+        r_value = trace_id.unpack1("@8Q>")
+
+        p_value >= r_value
+      end
+    end
+  end
+end

data/lib/bugsnag_performance/internal/sampling_header_encoder.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module BugsnagPerformance
+  module Internal
+    class SamplingHeaderEncoder
+      def encode(spans)
+        return "1.0:0" if spans.empty?
+
+        spans
+          .group_by do |span|
+            # bail if the atrribute is missing; we'll warn about this later as it
+            # means something has gone wrong
+            return nil if span.attributes.nil?
+
+            probability = span.attributes["bugsnag.sampling.p"]
+            return nil if probability.nil?
+
+            probability
+          end
+          .map { |probability, spans| "#{probability}:#{spans.length}" }
+          .join(";")
+      end
+    end
+  end
+end

data/lib/bugsnag_performance/internal/span_exporter.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module BugsnagPerformance
+  module Internal
+    class SpanExporter
+      def initialize(
+        logger,
+        probability_manager,
+        delivery,
+        payload_encoder,
+        sampling_header_encoder
+      )
+        @logger = logger
+        @probability_manager = probability_manager
+        @delivery = delivery
+        @payload_encoder = payload_encoder
+        @sampling_header_encoder = sampling_header_encoder
+        @disabled = false
+      end
+
+      def disable!
+        @disabled = true
+      end
+
+      def export(span_data, timeout: nil)
+        return OpenTelemetry::SDK::Trace::Export::SUCCESS if @disabled
+
+        with_timeout(timeout) do
+          headers = {}
+          sampling_header = @sampling_header_encoder.encode(span_data)
+
+          if sampling_header.nil?
+            @logger.warn("One or more spans are missing the 'bugsnag.sampling.p' attribute. This trace will be sent as 'unmanaged'.")
+          else
+            headers["Bugsnag-Span-Sampling"] = sampling_header
+          end
+
+          body = JSON.generate(@payload_encoder.encode(span_data))
+
+          response = @delivery.deliver(headers, body)
+
+          if response.sampling_probability
+            @probability_manager.probability = response.sampling_probability
+          end
+
+          OpenTelemetry::SDK::Trace::Export::SUCCESS
+        end
+      rescue => exception
+        @logger.error("Failed to deliver trace to BugSnag.")
+        @logger.error(exception)
+
+        return OpenTelemetry::SDK::Trace::Export::TIMEOUT if exception.is_a?(Timeout::Error)
+
+        OpenTelemetry::SDK::Trace::Export::FAILURE
+      end
+
+      def force_flush(timeout: nil)
+        OpenTelemetry::SDK::Trace::Export::SUCCESS
+      end
+
+      def shutdown(timeout: nil)
+        OpenTelemetry::SDK::Trace::Export::SUCCESS
+      end
+
+      private
+
+      def with_timeout(timeout, &block)
+        if timeout.nil?
+          block.call
+        else
+          Timeout::timeout(timeout) { block.call }
+        end
+      end
+    end
+  end
+end

data/lib/bugsnag_performance/internal/task.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module BugsnagPerformance
+  module Internal
+    # A wrapper around Concurrent::ScheduledTask that is easier to work with when
+    # a task needs to be run repeatedly (a ScheduledTask can only run once)
+    class Task
+      class UnscheduledTaskError < ::BugsnagPerformance::Error
+        def initialize
+          super("Task has not been scheduled")
+        end
+      end
+
+      def initialize(on_finish)
+        @on_finish = on_finish
+        @lock = Mutex.new
+        @scheduled_task = nil
+      end
+
+      def schedule(delay)
+        @lock.synchronize do
+          if @scheduled_task && @scheduled_task.pending?
+            # if we have a pending task we can reschedule it
+            @scheduled_task.reschedule(delay)
+          elsif @scheduled_task && @scheduled_task.processing?
+            # task is currently running so re-schedule when it finishes and remove
+            # any existing reschedules
+            @scheduled_task.delete_observers
+
+            @scheduled_task.add_observer(OnTaskFinish.new(proc do
+              self.schedule(delay)
+            end))
+          else
+            # otherwise make a new task; if there's an existing task and it isn't
+            # pending or processing then it must have already finished so we don't
+            # need to worry about cancelling it
+            @scheduled_task = Concurrent::ScheduledTask.execute(delay) { @on_finish.call }
+          end
+        end
+
+        nil
+      end
+
+      def wait
+        raise UnscheduledTaskError.new if @scheduled_task.nil?
+
+        @scheduled_task.wait
+      end
+
+      def state
+        case @scheduled_task&.state
+        when nil then :unscheduled
+        when :pending then :pending
+        when :processing then :processing
+        else :finished
+        end
+      end
+
+      private
+
+      class OnTaskFinish
+        def initialize(on_finish)
+          @on_finish = on_finish
+        end
+
+        def update(...)
+          @on_finish.call
+        end
+      end
+    end
+  end
+end

data/lib/bugsnag_performance/internal/task_scheduler.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module BugsnagPerformance
+  module Internal
+    class TaskScheduler
+      def now(&on_finish)
+        Task.new(on_finish).tap do |task|
+          task.schedule(0)
+        end
+      end
+    end
+  end
+end

data/lib/bugsnag_performance/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module BugsnagPerformance
+  VERSION = "0.1.0"
+end

data/lib/bugsnag_performance.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "timeout"
+require "net/http"
+require "concurrent-ruby"
+require "opentelemetry-sdk"
+
+require_relative "bugsnag_performance/error"
+require_relative "bugsnag_performance/version"
+require_relative "bugsnag_performance/configuration"
+
+require_relative "bugsnag_performance/internal/task"
+require_relative "bugsnag_performance/internal/sampler"
+require_relative "bugsnag_performance/internal/delivery"
+require_relative "bugsnag_performance/internal/span_exporter"
+require_relative "bugsnag_performance/internal/logger_wrapper"
+require_relative "bugsnag_performance/internal/task_scheduler"
+require_relative "bugsnag_performance/internal/payload_encoder"
+require_relative "bugsnag_performance/internal/probability_fetcher"
+require_relative "bugsnag_performance/internal/probability_manager"
+require_relative "bugsnag_performance/internal/configuration_validator"
+require_relative "bugsnag_performance/internal/sampling_header_encoder"
+require_relative "bugsnag_performance/internal/nil_errors_configuration"
+
+module BugsnagPerformance
+  def self.configure(&block)
+    unvalidated_configuration = Configuration.new(load_bugsnag_errors_configuration)
+
+    block.call(unvalidated_configuration) unless block.nil?
+
+    result = Internal::ConfigurationValidator.validate(unvalidated_configuration)
+    configuration = result.configuration
+
+    log_validation_messages(configuration.logger, result.messages) unless result.valid?
+
+    delivery = Internal::Delivery.new(configuration)
+    task_scheduler = Internal::TaskScheduler.new
+    probability_fetcher = Internal::ProbabilityFetcher.new(configuration.logger, delivery, task_scheduler)
+    probability_manager = Internal::ProbabilityManager.new(probability_fetcher)
+    sampler = Internal::Sampler.new(probability_manager)
+
+    exporter = Internal::SpanExporter.new(
+      configuration.logger,
+      probability_manager,
+      delivery,
+      Internal::PayloadEncoder.new(sampler),
+      Internal::SamplingHeaderEncoder.new,
+    )
+
+    if configuration.enabled_release_stages && !configuration.enabled_release_stages.include?(configuration.release_stage)
+      configuration.logger.info("Not exporting spans as the current release stage is not in the enabled release stages.")
+      exporter.disable!
+    end
+
+    # return the result of the user's configuration block so we don't change
+    # any existing behaviour
+    return_value = nil
+
+    OpenTelemetry::SDK.configure do |otel_configurator|
+      # call the user's OTel configuration block
+      return_value = configuration.open_telemetry_configure_block.call(otel_configurator)
+
+      # add app version and release stage as the 'service.version' and
+      # 'deployment.environment' resource attributes
+      if app_version = configuration.app_version
+        otel_configurator.service_version = app_version
+      end
+
+      otel_configurator.resource = OpenTelemetry::SDK::Resources::Resource.create(
+        OpenTelemetry::SemanticConventions::Resource::DEPLOYMENT_ENVIRONMENT => configuration.release_stage
+      )
+
+      # add batch processor with bugsnag exporter to send payloads
+      otel_configurator.add_span_processor(
+        OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(exporter)
+      )
+    end
+
+    # use our sampler
+    OpenTelemetry.tracer_provider.sampler = sampler
+
+    return_value
+  end
+
+  private
+
+  def self.load_bugsnag_errors_configuration
+    # try to require bugsnag errors and use its configuration
+    require "bugsnag"
+
+    Bugsnag.configuration
+  rescue LoadError
+    # bugsnag errors is not installed
+    Internal::NilErrorsConfiguration.new
+  end
+
+  def self.log_validation_messages(logger, messages)
+    if messages.length == 1
+      logger.warn("Invalid configuration. #{messages.first}")
+    else
+      logger.warn(
+        <<~MESSAGE
+          Invalid configuration:
+            - #{messages.join("\n  - ")}
+        MESSAGE
+      )
+    end
+  end
+end

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: bugsnag_performance
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- BugSnag
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-08-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+description:
+email:
+- notifiers@bugsnag.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- bugsnag-performance.gemspec
+- lib/bugsnag_performance.rb
+- lib/bugsnag_performance/configuration.rb
+- lib/bugsnag_performance/error.rb
+- lib/bugsnag_performance/internal/configuration_validator.rb
+- lib/bugsnag_performance/internal/delivery.rb
+- lib/bugsnag_performance/internal/logger_wrapper.rb
+- lib/bugsnag_performance/internal/nil_errors_configuration.rb
+- lib/bugsnag_performance/internal/payload_encoder.rb
+- lib/bugsnag_performance/internal/probability_fetcher.rb
+- lib/bugsnag_performance/internal/probability_manager.rb
+- lib/bugsnag_performance/internal/sampler.rb
+- lib/bugsnag_performance/internal/sampling_header_encoder.rb
+- lib/bugsnag_performance/internal/span_exporter.rb
+- lib/bugsnag_performance/internal/task.rb
+- lib/bugsnag_performance/internal/task_scheduler.rb
+- lib/bugsnag_performance/version.rb
+homepage: https://www.bugsnag.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.bugsnag.com
+  source_code_uri: https://github.com/bugsnag/bugsnag-ruby-performance
+  bug_tracker_uri: https://github.com/bugsnag/bugsnag-ruby-performance/issues
+  changelog_uri: https://github.com/bugsnag/bugsnag-ruby-performance/blob/v0.1.0/CHANGELOG.md
+  documentation_uri: https://docs.bugsnag.com/performance/integration-guides/ruby/
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: BugSnag integration for the Ruby Open Telemetry SDK
+test_files: []