bugsnag_performance 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31cfcfc45215dec768c1e6040c418f63355ea308cf2d8d660ccad2c3f2de3621
-  data.tar.gz: e3868f8cd3341f285e0bd868c3db54e640739ed0a755308162c3dac96cf47b76
+  metadata.gz: e9bc8d797c0a3b633e73e88a5d4f399df04bb2fb8063b1a11c42bec974dfec5c
+  data.tar.gz: 4554ce3963bc8b4861d586c539b7186ab4550a871586cbe7ad646af5b3b35cbc
 SHA512:
-  metadata.gz: f394a3a656e3bbd76aa825db67b2e6bd156590d666648ca6484df820fc833f8904e24dce311084bcfc64ff4e064f5bbcd181a92e51a60d27c7ccedf7a029ccd4
-  data.tar.gz: 9f8ad547b130279f751169c2305ce57faaf34a566782abca3df7fc307efbab8b14873c6ef0946069a0f49f159d40d8b225969eaf5defa5bb236b402e10afd05d
+  metadata.gz: 1467c6a19cf3766d3e5794714c2ad36f145c00b4a23b66a55c1375f72aafd9168c70495a2b57e053f28d7a9d9029825e2ea35051e615bf5c5fa5fbd11298e6be
+  data.tar.gz: c6fcb31b7d1ac9cba893c8600a0624662a15e64b6e82ba822da113388238c8772d85e0a585ee50683906f99bbb3b596bdcf8501f1b6628c915f9ba2922585a5c

data/.yardopts

@@ -0,0 +1,11 @@
+--charset UTF-8
+--fail-on-warning
+--hide-api private
+--no-private
+--protected
+--title "BugSnag Ruby Performance API Documentation"
+--embed-mixins
+--exclude /internal/
+-
+README.md
+CHANGELOG.md

data/CHANGELOG.md

@@ -1,2 +1,10 @@
 Changelog
 =========
+
+## 0.3.0 (2024-11-13)
+
+### Enhancements
+
+* Temporarily disable `Bugsnag-Sent-At` header. Add attributes with SDK name.
+[#42](https://github.com/bugsnag/bugsnag-ruby-performance/pull/42)
+[#43](https://github.com/bugsnag/bugsnag-ruby-performance/pull/43)

data/CONTRIBUTING.md

@@ -0,0 +1,69 @@
+## How to contribute
+
+We are glad you're here! First-time and returning contributors are welcome to add bug fixes and new integrations. If you are unsure about the direction of an enhancement or if it would be generally useful, feel free to open an issue or a work-in-progress pull request and ask for input.
+
+Thank you!
+
+### Getting started
+
+* [Fork](https://help.github.com/articles/fork-a-repo) the [library on github](https://github.com/bugsnag/bugsnag-ruby-performance)
+* Commit and push until you are happy with your contribution
+
+### Polish
+
+* Install the test dependencies
+
+    ```
+    bundle install
+    ```
+
+* Run the tests and make sure they all pass
+
+    ```
+    bundle exec rspec
+    ```
+    
+* Further information on installing and running the tests can be found in [the testing guide](./TESTING.md)
+
+### Document
+
+* Write API docs for your contributions using [YARD](https://yardoc.org/)
+* Generate the API documentation locally
+    ```
+    bin/rake yard
+    ```
+* Review your changes by opening `doc/index.html`
+
+### Ship it!
+
+* [Make a pull request](https://help.github.com/articles/using-pull-requests)
+
+## How to release
+
+If you're a member of the core team, follow these instructions for releasing bugsnag-ruby-performance.
+
+### First time setup
+
+* Create a Rubygems account
+* Get someone to add you as contributor on bugsnag-ruby-performance in Rubygems
+
+### Every time
+
+* Create a new release branch named in the format `release/v1.x.x`
+* Update the version number in [`lib/bugsnag_performance/version.rb`](./lib/bugsnag_performance/version.rb)
+* Update [`CHANGELOG.md`](./CHANGELOG.md) with any changes
+* Open a pull request into `main` and get it approved
+* Merge the pull request using the message "Release v1.x.x"
+* Make a GitHub release
+* Release to rubygems:
+
+    ```
+    gem build bugsnag-performance.gemspec
+    gem push bugsnag_performance-1.x.x.gem
+    ```
+
+* Update the version running in the bugsnag-website project
+
+### Update docs.bugsnag.com
+
+Update the setup guides for Ruby (and its frameworks) with any new content.

data/README.md

@@ -0,0 +1,33 @@
+<div align="center">
+  <a href="https://www.bugsnag.com/distributed-tracing">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://assets.smartbear.com/m/3dab7e6cf880aa2b/original/BugSnag-Repository-Header-Dark.svg">
+      <img alt="SmartBear BugSnag logo" src="https://assets.smartbear.com/m/3945e02cdc983893/original/BugSnag-Repository-Header-Light.svg">
+    </picture>
+  </a>
+  <h1>Performance monitoring for Ruby</h1>
+</div>
+
+[![Documentation](https://img.shields.io/badge/documentation-latest-blue.svg)](https://docs.bugsnag.com/performance/ruby/)
+[![Build status](https://github.com/bugsnag/bugsnag-ruby-performance/actions/workflows/maze-runner.yml/badge.svg?branch=main)](https://github.com/bugsnag/bugsnag-ruby-performance/actions/workflows/maze-runner.yml)
+
+Convenience SDK for using the [Ruby Otel SDK](https://github.com/open-telemetry/opentelemetry-ruby) with BugSnag.
+
+## Features
+
+- Simple configuration using BugSnag API key
+- Control sampling using BugSnag's probability-based sampler
+
+## Getting started
+
+For integration instructions, see our online docs: [docs.bugsnag.com/performance/ruby](https://docs.bugsnag.com/performance/ruby)
+
+## Support
+
+* [Read the integration guide](https://docs.bugsnag.com/performance/ruby)
+* [Search open and closed issues](https://github.com/bugsnag/bugsnag-ruby-performance/issues?=is%3Aissue) for similar problems
+* [Report a bug or request a feature](https://github.com/bugsnag/bugsnag-ruby-performance/issues/new)
+
+## License
+
+The BugSnag Ruby performance SDK is free software released under the MIT License. See [LICENSE.txt](LICENSE.txt) for details.

data/TESTING.md

@@ -0,0 +1,38 @@
+# Testing the Ruby BugSnag performance SDK
+
+## Unit tests
+
+```
+bundle install
+bundle exec rspec
+```
+
+## End-to-end tests
+
+These tests are implemented with our internal testing tool [Maze Runner](https://github.com/bugsnag/maze-runner).
+
+End to end tests are written in cucumber-style `.feature` files, and need Ruby-backed "steps" in order to know what to run. The tests are located in the top level [`features`](./features/) directory.
+
+The Maze Runner test fixtures are containerised so you'll need Docker and Docker Compose to run them.
+
+### Running the end to end tests
+
+Install Maze Runner:
+
+```sh
+$ BUNDLE_GEMFILE=Gemfile-maze-runner bundle install
+```
+
+Configure the tests to be run in the following way:
+
+- Determine the Ruby version to be tested using the environment variable `RUBY_TEST_VERSION`, e.g. `RUBY_TEST_VERSION=3.3`
+- Determine the Open Telemetry SDK version using the environment variable `OPEN_TELEMETRY_SDK_TEST_VERSION`, e.g. `OPEN_TELEMETRY_SDK_TEST_VERSION="~> 1.5"`
+
+Use the Maze Runner CLI to run the tests:
+
+```sh
+$ RUBY_TEST_VERSION=3.3 \
+  OPEN_TELEMETRY_SDK_TEST_VERSION="~> 1.5" \
+  BUNDLE_GEMFILE=Gemfile-maze-runner \
+  bundle exec maze-runner
+```

data/bugsnag-performance.gemspec

@@ -34,6 +34,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "concurrent-ruby", "~> 1.3"
   spec.add_dependency "opentelemetry-sdk", "~> 1.2"
 
+  spec.add_development_dependency "yard", "~> 0.9"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "webmock", "~> 3.23"
 end

data/lib/bugsnag_performance/configuration.rb

@@ -2,14 +2,52 @@
 
 module BugsnagPerformance
   class Configuration
+    # @api private
     attr_reader :open_telemetry_configure_block
+
+    # The logger BugSnag Performance will write messages to
+    #
+    # If not set, this will default to the BugSnag Errors logger or the Open
+    # Telemetry SDK logger
+    #
+    # @return [Logger]
     attr_reader :logger
 
+    # Your BugSnag API Key
+    #
+    # If not set, this will be read from the "BUGSNAG_PERFORMANCE_API_KEY" and
+    # "BUGSNAG_API_KEY" environment variables or BugSnag Errors configuration.
+    # If none of these returns an API key, a {MissingApiKeyError} will be raised
+    #
+    # @return [String, nil]
     attr_accessor :api_key
+
+    # The current version of the application, for example "1.2.3"
+    #
+    # If not set, this will be read from the "BUGSNAG_PERFORMANCE_APP_VERSION"
+    # and "BUGSNAG_APP_VERSION" environment variables or BugSnag Errors
+    # configuration
+    #
+    # @return [String]
     attr_accessor :app_version
+
+    # The current stage of the release process, for example "development" or "production"
+    #
+    # If not set, this will be read from the "BUGSNAG_PERFORMANCE_RELEASE_STAGE"
+    # and "BUGSNAG_RELEASE_STAGE" environment variables or BugSnag Errors
+    # configuration and defaults to "production"
+    #
+    # @return [String]
     attr_accessor :release_stage
+
+    # Which release stages to send traces for, for example ["staging", production"]
+    #
+    # If not set, this will be read from the "BUGSNAG_PERFORMANCE_ENABLED_RELEASE_STAGES"
+    # and "BUGSNAG_ENABLED_RELEASE_STAGES" environment variables or BugSnag Errors
+    # configuration and defaults to allow any release stage
+    #
+    # @return [Array<String>, nil]
     attr_accessor :enabled_release_stages
-    attr_accessor :use_managed_quota
 
     attr_writer :endpoint
 
@@ -18,9 +56,8 @@ module BugsnagPerformance
       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)
+      @app_version = fetch(errors_configuration, :app_version, env: "BUGSNAG_PERFORMANCE_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")
 
@@ -40,6 +77,11 @@ module BugsnagPerformance
         end
     end
 
+    # The URL to send traces to
+    #
+    # If not set this defaults to "https://<api_key>.otlp.bugsnag.com/v1/traces"
+    #
+    # @return [String, nil]
     def endpoint
       case
       when defined?(@endpoint)
@@ -53,6 +95,9 @@ module BugsnagPerformance
       end
     end
 
+    # Apply configuration for the Open Telemetry SDK
+    #
+    # This block should *replace* any calls to OpenTelemetry::SDK.configure
     def configure_open_telemetry(&open_telemetry_configure_block)
       @open_telemetry_configure_block = open_telemetry_configure_block
     end

data/lib/bugsnag_performance/internal/configuration_validator.rb

@@ -16,7 +16,6 @@ module BugsnagPerformance
         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
@@ -72,16 +71,6 @@ module BugsnagPerformance
         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)
 

data/lib/bugsnag_performance/internal/delivery.rb

@@ -3,9 +3,12 @@
 module BugsnagPerformance
   module Internal
     class Delivery
+      attr_reader :uri
+
       def initialize(configuration)
         @uri = URI(configuration.endpoint)
         @common_headers = {
+          "User-Agent" => "#{BugsnagPerformance::SDK_NAME} v#{BugsnagPerformance::VERSION}",
           "Bugsnag-Api-Key" => configuration.api_key,
           "Content-Type" => "application/json",
         }.freeze
@@ -14,7 +17,8 @@ module BugsnagPerformance
       def deliver(headers, body)
         headers = headers.merge(
           @common_headers,
-          { "Bugsnag-Sent-At" => Time.now.utc.iso8601(3) },
+        # TODO - can be restored after https://smartbear.atlassian.net/browse/PIPE-7498
+        #  { "Bugsnag-Sent-At" => Time.now.utc.iso8601(3) },
         )
 
         raw_response = OpenTelemetry::Common::Utilities.untraced do

data/lib/bugsnag_performance/internal/nil_errors_configuration.rb

@@ -10,6 +10,15 @@ module BugsnagPerformance
       attr_accessor :release_stage
       attr_accessor :enabled_release_stages
       attr_accessor :logger
+
+      def initialize
+        # if bugsnag errors is not installed we still want to read from the
+        # environment variables it supports
+        @api_key = ENV["BUGSNAG_API_KEY"]
+        @app_version = ENV["BUGSNAG_APP_VERSION"]
+        @release_stage = ENV["BUGSNAG_RELEASE_STAGE"]
+        @enabled_release_stages = ENV["BUGSNAG_ENABLED_RELEASE_STAGES"]
+      end
     end
   end
 end

data/lib/bugsnag_performance/internal/parsed_tracestate.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module BugsnagPerformance
+  module Internal
+    class ParsedTracestate
+      attr_reader :version
+      attr_reader :r_value
+
+      def initialize(version, r_value, r_value_32_bit:)
+        @version = version
+        @r_value = r_value
+        @r_value_32_bit = r_value_32_bit
+      end
+
+      def valid?
+        !!(@version && @r_value)
+      end
+
+      def r_value_32_bit?
+        @r_value_32_bit
+      end
+    end
+  end
+end

data/lib/bugsnag_performance/internal/payload_encoder.rb

@@ -26,14 +26,9 @@ module BugsnagPerformance
         :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|
               {

data/lib/bugsnag_performance/internal/probability_attribute_span_processor.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module BugsnagPerformance
+  module Internal
+    class ProbabilityAttributeSpanProcessor
+      def initialize(probability_manager)
+        @probability_manager = probability_manager
+      end
+
+      def on_start(span, parent_context)
+        # avoid overwriting the attribute if the sampler has already set it
+        if span.attributes.nil? || span.attributes["bugsnag.sampling.p"].nil?
+          span.set_attribute("bugsnag.sampling.p", @probability_manager.probability)
+        end
+
+        OpenTelemetry::SDK::Trace::Export::SUCCESS
+      end
+
+      def on_finish(span)
+        OpenTelemetry::SDK::Trace::Export::SUCCESS
+      end
+
+      def force_flush(timeout: nil)
+        OpenTelemetry::SDK::Trace::Export::SUCCESS
+      end
+
+      def shutdown(timeout: nil)
+        OpenTelemetry::SDK::Trace::Export::SUCCESS
+      end
+    end
+  end
+end

data/lib/bugsnag_performance/internal/sampler.rb

@@ -3,12 +3,17 @@
 module BugsnagPerformance
   module Internal
     class Sampler
-      PROBABILITY_SCALE_FACTOR = 18_446_744_073_709_551_615 # (2 ** 64) - 1
+      # the scale factor to use with a 64 bit r value
+      PROBABILITY_SCALE_FACTOR_64 = 18_446_744_073_709_551_615 # (2 ** 64) - 1
 
-      private_constant :PROBABILITY_SCALE_FACTOR
+      # the scale factor to use with a 32 bit r value
+      PROBABILITY_SCALE_FACTOR_32 = 4_294_967_295 # (2 ** 32) - 1
 
-      def initialize(probability_manager)
+      private_constant :PROBABILITY_SCALE_FACTOR_64, :PROBABILITY_SCALE_FACTOR_32
+
+      def initialize(probability_manager, tracestate_parser)
         @probability_manager = probability_manager
+        @tracestate_parser = tracestate_parser
       end
 
       def should_sample?(trace_id:, parent_context:, links:, name:, kind:, attributes:)
@@ -17,47 +22,63 @@ module BugsnagPerformance
         #       for the sampling decision & p value attribute which would result
         #       in inconsistent data
         probability = @probability_manager.probability
+        parent_span_context = OpenTelemetry::Trace.current_span(parent_context).context
+        tracestate = parent_span_context.tracestate
 
         decision =
-          if sample_using_probability_and_trace_id?(probability, trace_id)
+          if sample_using_probability_and_trace?(probability, tracestate, 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,
+          tracestate: 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?
 
+        probability = @probability_manager.probability
+
         # 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)
+        sample_using_probability_and_trace?(
+          span.attributes["bugsnag.sampling.p"],
+          span.tracestate,
+          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
+      def sample_using_probability_and_trace?(probability, tracestate, trace_id)
+        # parse the r value from tracestate or generate from the trace ID by
+        # unpacking it as a u64
+        parsed_tracestate = @tracestate_parser.parse(tracestate)
+
+        if parsed_tracestate.valid?
+          # the JS SDK will send a u32 as the r value so we need to scale the
+          # probability value to the same range for comparisons to work
+          r_value = parsed_tracestate.r_value
+          scale_factor = parsed_tracestate.r_value_32_bit? ? PROBABILITY_SCALE_FACTOR_32 : PROBABILITY_SCALE_FACTOR_64
+        else
+          r_value = trace_id.unpack1("@8Q>")
+          scale_factor = PROBABILITY_SCALE_FACTOR_64
+        end
 
-        # unpack the trace ID as a u64
-        r_value = trace_id.unpack1("@8Q>")
+        # scale the probability (stored as a float from 0-1) to the appropriate
+        # size int (u32 or u64)
+        p_value = (probability * scale_factor).floor
 
         p_value >= r_value
       end

data/lib/bugsnag_performance/internal/span_exporter.rb

@@ -7,36 +7,67 @@ module BugsnagPerformance
         logger,
         probability_manager,
         delivery,
+        sampler,
         payload_encoder,
         sampling_header_encoder
       )
         @logger = logger
         @probability_manager = probability_manager
         @delivery = delivery
+        @sampler = sampler
         @payload_encoder = payload_encoder
         @sampling_header_encoder = sampling_header_encoder
         @disabled = false
+        @unmanaged_mode = false
+        @logged_first_batch_destination = false
       end
 
       def disable!
         @disabled = true
       end
 
+      def unmanaged_mode!
+        @unmanaged_mode = true
+      end
+
+      def unmanaged_mode?
+        @unmanaged_mode
+      end
+
       def export(span_data, timeout: nil)
         return OpenTelemetry::SDK::Trace::Export::SUCCESS if @disabled
 
         with_timeout(timeout) do
+          # ensure we're in the correct managed or unmanaged mode
+          maybe_enter_unmanaged_mode
+          managed_status = unmanaged_mode? ? "unmanaged" : "managed"
+
           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
+          # resample the spans and attach the Bugsnag-Span-Sampling header only
+          # if we're in managed mode
+          unless unmanaged_mode?
+            span_data = span_data.filter { |span| @sampler.resample_span?(span) }
+
+            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")
+              managed_status = "unmanaged"
+            else
+              headers["Bugsnag-Span-Sampling"] = sampling_header
+            end
           end
 
           body = JSON.generate(@payload_encoder.encode(span_data))
 
+          # log whether we're sending managed or unmanaged spans on the first
+          # batch only
+          unless @logged_first_batch_destination
+            @logger.info("Sending #{managed_status} spans to #{@delivery.uri}")
+            @logged_first_batch_destination = true
+          end
+
           response = @delivery.deliver(headers, body)
 
           if response.sampling_probability
@@ -64,6 +95,18 @@ module BugsnagPerformance
 
       private
 
+      def maybe_enter_unmanaged_mode
+        # we're in unmanaged mode already so don't need to do anything
+        return if unmanaged_mode?
+
+        # our sampler is in use so we're in managed mode
+        return if OpenTelemetry.tracer_provider.sampler.is_a?(Sampler)
+
+        # the user has changed the sampler from ours to a custom one; enter
+        # unmanaged mode
+        unmanaged_mode!
+      end
+
       def with_timeout(timeout, &block)
         if timeout.nil?
           block.call

data/lib/bugsnag_performance/internal/tracestate_parser.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module BugsnagPerformance
+  module Internal
+    class TracestateParser
+      def parse(tracestate)
+        smartbear_values = tracestate.value("sb")
+        return ParsedTracestate.new(nil, nil, r_value_32_bit: false) if smartbear_values.nil?
+
+        version = nil
+        r_value_32 = nil
+        r_value_64 = nil
+
+        smartbear_values.split(";").each do |field|
+          key, value = field.split(":", 2)
+
+          case key
+          when "v"
+            version = value
+          when "r32"
+            r_value_32 = Integer(value, exception: false)
+          when "r64"
+            r_value_64 = Integer(value, exception: false)
+          end
+        end
+
+        ParsedTracestate.new(
+          version,
+          # a 64 bit value should take precedence over a 32 bit one if both are
+          # present in the tracestate
+          r_value_64 || r_value_32,
+          r_value_32_bit: r_value_64.nil? && !r_value_32.nil?
+        )
+      end
+    end
+  end
+end

data/lib/bugsnag_performance/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module BugsnagPerformance
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
+  SDK_NAME = "Ruby Bugsnag Performance SDK"
 end

data/lib/bugsnag_performance.rb

@@ -18,13 +18,21 @@ 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/parsed_tracestate"
+require_relative "bugsnag_performance/internal/tracestate_parser"
 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"
+require_relative "bugsnag_performance/internal/probability_attribute_span_processor"
 
 module BugsnagPerformance
+  # Configure BugSnag Performance
+  #
+  # Yields a {Configuration} object to use to set application settings.
+  #
+  # @yieldparam configuration [Configuration]
   def self.configure(&block)
     unvalidated_configuration = Configuration.new(load_bugsnag_errors_configuration)
 
@@ -39,16 +47,23 @@ module BugsnagPerformance
     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)
+    sampler = Internal::Sampler.new(probability_manager, Internal::TracestateParser.new)
 
     exporter = Internal::SpanExporter.new(
       configuration.logger,
       probability_manager,
       delivery,
-      Internal::PayloadEncoder.new(sampler),
+      sampler,
+      Internal::PayloadEncoder.new,
       Internal::SamplingHeaderEncoder.new,
     )
 
+    # enter unmanaged mode if the OTel sampler environment variable has been set
+    # note: we assume any value means a non-default sampler will be used because
+    #       we don't control what the valid values are
+    user_has_custom_sampler = ENV.key?("OTEL_TRACES_SAMPLER")
+    exporter.unmanaged_mode! if user_has_custom_sampler
+
     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!
@@ -69,17 +84,29 @@ module BugsnagPerformance
       end
 
       otel_configurator.resource = OpenTelemetry::SDK::Resources::Resource.create(
-        OpenTelemetry::SemanticConventions::Resource::DEPLOYMENT_ENVIRONMENT => configuration.release_stage
+        {
+          OpenTelemetry::SemanticConventions::Resource::DEPLOYMENT_ENVIRONMENT => configuration.release_stage,
+          "bugsnag.telemetry.sdk.name" => SDK_NAME,
+          "bugsnag.telemetry.sdk.version" => VERSION,
+        }
       )
 
       # add batch processor with bugsnag exporter to send payloads
       otel_configurator.add_span_processor(
         OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(exporter)
       )
+
+      # ensure the "bugsnag.sampling.p" attribute is set on all spans even when
+      # our sampler is not in use
+      otel_configurator.add_span_processor(
+        Internal::ProbabilityAttributeSpanProcessor.new(probability_manager)
+      )
     end
 
-    # use our sampler
-    OpenTelemetry.tracer_provider.sampler = sampler
+    # don't use our sampler if the user has configured a sampler via the OTel
+    # environment variable
+    # note: the user can still replace our sampler with their own after this
+    OpenTelemetry.tracer_provider.sampler = sampler unless user_has_custom_sampler
 
     return_value
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bugsnag_performance
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - BugSnag
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-21 00:00:00.000000000 Z
+date: 2024-11-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -73,8 +87,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
+- CONTRIBUTING.md
 - LICENSE.txt
+- README.md
+- TESTING.md
 - bugsnag-performance.gemspec
 - lib/bugsnag_performance.rb
 - lib/bugsnag_performance/configuration.rb
@@ -83,7 +101,9 @@ files:
 - 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/parsed_tracestate.rb
 - lib/bugsnag_performance/internal/payload_encoder.rb
+- lib/bugsnag_performance/internal/probability_attribute_span_processor.rb
 - lib/bugsnag_performance/internal/probability_fetcher.rb
 - lib/bugsnag_performance/internal/probability_manager.rb
 - lib/bugsnag_performance/internal/sampler.rb
@@ -91,6 +111,7 @@ files:
 - lib/bugsnag_performance/internal/span_exporter.rb
 - lib/bugsnag_performance/internal/task.rb
 - lib/bugsnag_performance/internal/task_scheduler.rb
+- lib/bugsnag_performance/internal/tracestate_parser.rb
 - lib/bugsnag_performance/version.rb
 homepage: https://www.bugsnag.com
 licenses:
@@ -99,7 +120,7 @@ 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
+  changelog_uri: https://github.com/bugsnag/bugsnag-ruby-performance/blob/v0.3.0/CHANGELOG.md
   documentation_uri: https://docs.bugsnag.com/performance/integration-guides/ruby/
   rubygems_mfa_required: 'true'
 post_install_message:
@@ -117,7 +138,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: BugSnag integration for the Ruby Open Telemetry SDK