multiplayer-session-recorder 0.0.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1ca02b61e222654ebd5a78168a2455dd3ed138fe1c61dd30bb7189028568c670
+  data.tar.gz: f97f4949e513ff1fb19477fdbf079de84d4a9619c32c1b9da07430136e514955
+SHA512:
+  metadata.gz: 789daab68f6ff9a9dff8ce56fb9e212a8d4d54340f942040db2481f5f951ecfc12eebf9022750486c895080b895e655d17dc7aee3bccc7c0153a272816ab0d34
+  data.tar.gz: a45acfb3e3163c8ed9c2166a78344a561989c4caa5c0dbc6ec0f4821d588a1605d9d4e15ddb727862bd4248a7aa2b1a9bd888241dc16fee5abeabedde3f6c088

data/lib/session-recorder.rb

@@ -0,0 +1,12 @@
+require "session_recorder/exporters"
+require "session_recorder/middleware"
+require "session_recorder/trace"
+require "session_recorder/type"
+require "session_recorder/constants"
+require "session_recorder/version"
+
+module Multiplayer
+  module SessionRecorder
+    # Main module for Session Recorder functionality
+  end
+end

data/lib/session_recorder/constants.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module SessionRecorder
+  MULTIPLAYER_TRACE_DEBUG_PREFIX = 'debdeb'
+
+  MULTIPLAYER_TRACE_CONTINUOUS_DEBUG_PREFIX = 'cdbcdb'
+
+  MULTIPLAYER_TRACE_DEBUG_SESSION_SHORT_ID_LENGTH = 16
+
+  MULTIPLAYER_OTEL_DEFAULT_TRACES_EXPORTER_HTTP_URL = 'https://otlp.multiplayer.app/v1/traces'
+
+  MULTIPLAYER_OTEL_DEFAULT_LOGS_EXPORTER_HTTP_URL = 'https://otlp.multiplayer.app/v1/logs'
+
+  MULTIPLAYER_OTEL_DEFAULT_TRACES_EXPORTER_GRPC_URL = 'https://otlp.multiplayer.app:4317/v1/traces'
+
+  MULTIPLAYER_OTEL_DEFAULT_LOGS_EXPORTER_GRPC_URL = 'https://otlp.multiplayer.app:4317/v1/logs'
+
+  MULTIPLAYER_BASE_API_URL = 'https://api.multiplayer.app'
+
+  MULTIPLAYER_ATTRIBUTE_PREFIX = 'multiplayer.'
+
+  ATTR_MULTIPLAYER_WORKSPACE_ID = 'multiplayer.workspace.id'
+
+  ATTR_MULTIPLAYER_PROJECT_ID = 'multiplayer.project.id'
+
+  ATTR_MULTIPLAYER_PLATFORM_ID = 'multiplayer.platform.id'
+
+  ATTR_MULTIPLAYER_CONTINUOUS_SESSION_AUTO_SAVE = 'multiplayer.session.auto-save'
+
+  ATTR_MULTIPLAYER_CONTINUOUS_SESSION_AUTO_SAVE_REASON = 'multiplayer.session.auto-save.reason'
+
+  ATTR_MULTIPLAYER_PLATFORM_NAME = 'multiplayer.platform.name'
+
+  ATTR_MULTIPLAYER_CLIENT_ID = 'multiplayer.client.id'
+
+  ATTR_MULTIPLAYER_INTEGRATION_ID = 'multiplayer.integration.id'
+
+  ATTR_MULTIPLAYER_SESSION_ID = 'multiplayer.session.id'
+
+  ATTR_MULTIPLAYER_HTTP_PROXY = 'multiplayer.http.proxy'
+
+  ATTR_MULTIPLAYER_HTTP_PROXY_TYPE = 'multiplayer.http.proxy.type'
+
+  ATTR_MULTIPLAYER_HTTP_REQUEST_BODY = 'multiplayer.http.request.body'
+
+  ATTR_MULTIPLAYER_HTTP_RESPONSE_BODY = 'multiplayer.http.response.body'
+
+  ATTR_MULTIPLAYER_HTTP_REQUEST_HEADERS = 'multiplayer.http.request.headers'
+
+  ATTR_MULTIPLAYER_HTTP_RESPONSE_HEADERS = 'multiplayer.http.response.headers'
+
+  ATTR_MULTIPLAYER_HTTP_RESPONSE_BODY_ENCODING = 'multiplayer.http.response.body.encoding'
+
+  ATTR_MULTIPLAYER_RPC_REQUEST_MESSAGE = 'multiplayer.rpc.request.message'
+
+  ATTR_MULTIPLAYER_RPC_REQUEST_MESSAGE_ENCODING = 'multiplayer.rpc.request.message.encoding'
+
+  ATTR_MULTIPLAYER_RPC_RESPONSE_MESSAGE = 'multiplayer.rpc.response.message'
+
+  ATTR_MULTIPLAYER_GRPC_REQUEST_MESSAGE = 'multiplayer.rpc.grpc.request.message'
+
+  ATTR_MULTIPLAYER_GRPC_REQUEST_MESSAGE_ENCODING = 'multiplayer.rpc.request.message.encoding'
+
+  ATTR_MULTIPLAYER_GRPC_RESPONSE_MESSAGE = 'multiplayer.rpc.grpc.response.message'
+
+  ATTR_MULTIPLAYER_MESSAGING_MESSAGE_BODY = 'multiplayer.messaging.message.body'
+
+  ATTR_MULTIPLAYER_MESSAGING_MESSAGE_BODY_ENCODING = 'multiplayer.messaging.message.body.encoding'
+
+  ATTR_MULTIPLAYER_SESSION_RECORDER_VERSION = 'multiplayer.session-recorder.version'
+
+  MASK_PLACEHOLDER = '***MASKED***'
+
+  # Middleware constants
+  MAX_MASK_DEPTH = 10
+
+  # HTTP request/response size limits
+  MULTIPLAYER_MAX_HTTP_REQUEST_RESPONSE_SIZE = 1024 * 1024 # 1MB
+end

data/lib/session_recorder/exporters/grpc_logs_exporter.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "json"
+require "opentelemetry/sdk"
+require "opentelemetry/exporter/otlp"
+
+module SessionRecorder
+  module Exporters
+    class SessionRecorderGrpcLogsExporter < OpenTelemetry::Exporter::OTLP::Exporter
+      def initialize(config = {})
+        endpoint = config[:endpoint] || SessionRecorder::MULTIPLAYER_OTEL_DEFAULT_LOGS_EXPORTER_GRPC_URL
+        api_key = config[:api_key]
+        
+        raise ArgumentError, "api_key is required" if api_key.nil? || api_key.empty?
+        
+        headers = { "Authorization" => api_key }
+        headers.merge!(config[:headers]) if config[:headers]
+        
+        super(endpoint: endpoint, headers: headers)
+      end
+
+      def export(logs, timeout: nil)
+        # Filter logs by trace ID prefix
+        filtered_logs = logs.select do |log|
+          trace_id = log.trace_id
+          trace_id.start_with?(SessionRecorder::MULTIPLAYER_TRACE_DEBUG_PREFIX) ||
+            trace_id.start_with?(SessionRecorder::MULTIPLAYER_TRACE_CONTINUOUS_DEBUG_PREFIX)
+        end
+
+        return OpenTelemetry::SDK::Trace::Export::SUCCESS if filtered_logs.empty?
+
+        super(filtered_logs, timeout: timeout)
+      end
+    end
+  end
+end

data/lib/session_recorder/exporters/grpc_trace_exporter.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "json"
+require "opentelemetry/sdk"
+require "opentelemetry/exporter/otlp"
+
+module SessionRecorder
+  module Exporters
+    class SessionRecorderGrpcTraceExporter < OpenTelemetry::Exporter::OTLP::Exporter
+      def initialize(config = {})
+        endpoint = config[:endpoint] || SessionRecorder::MULTIPLAYER_OTEL_DEFAULT_TRACES_EXPORTER_GRPC_URL
+        api_key = config[:api_key]
+        
+        raise ArgumentError, "api_key is required" if api_key.nil? || api_key.empty?
+        
+        headers = { "Authorization" => api_key }
+        headers.merge!(config[:headers]) if config[:headers]
+        
+        super(endpoint: endpoint, headers: headers)
+      end
+
+      def export(spans, timeout: nil)
+        # Filter spans by trace ID prefix
+        filtered_spans = spans.select do |span|
+          trace_id = span.trace_id
+          trace_id.start_with?(SessionRecorder::MULTIPLAYER_TRACE_DEBUG_PREFIX) ||
+            trace_id.start_with?(SessionRecorder::MULTIPLAYER_TRACE_CONTINUOUS_DEBUG_PREFIX)
+        end
+
+        return OpenTelemetry::SDK::Trace::Export::SUCCESS if filtered_spans.empty?
+
+        super(filtered_spans, timeout: timeout)
+      end
+    end
+  end
+end

data/lib/session_recorder/exporters/http_logs_exporter.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "json"
+require "opentelemetry/sdk"
+require "opentelemetry/exporter/otlp"
+
+module SessionRecorder
+  module Exporters
+    class SessionRecorderHttpLogsExporter < OpenTelemetry::Exporter::OTLP::Exporter
+      def initialize(config = {})
+        endpoint = config[:endpoint] || SessionRecorder::MULTIPLAYER_OTEL_DEFAULT_LOGS_EXPORTER_HTTP_URL
+        api_key = config[:api_key]
+        
+        raise ArgumentError, "api_key is required" if api_key.nil? || api_key.empty?
+        
+        headers = { "Authorization" => api_key }
+        headers.merge!(config[:headers]) if config[:headers]
+        
+        super(endpoint: endpoint, headers: headers)
+      end
+
+      def export(logs, timeout: nil)
+        # Filter logs by trace ID prefix
+        filtered_logs = logs.select do |log|
+          trace_id = log.trace_id
+          trace_id.start_with?(SessionRecorder::MULTIPLAYER_TRACE_DEBUG_PREFIX) ||
+            trace_id.start_with?(SessionRecorder::MULTIPLAYER_TRACE_CONTINUOUS_DEBUG_PREFIX)
+        end
+
+        return OpenTelemetry::SDK::Trace::Export::SUCCESS if filtered_logs.empty?
+
+        super(filtered_logs, timeout: timeout)
+      end
+    end
+  end
+end

data/lib/session_recorder/exporters/http_trace_exporter.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "json"
+require "opentelemetry/sdk"
+require "opentelemetry/exporter/otlp"
+
+module SessionRecorder
+  module Exporters
+    class SessionRecorderHttpTraceExporter < OpenTelemetry::Exporter::OTLP::Exporter
+      def initialize(config = {})
+        endpoint = config[:endpoint] || SessionRecorder::MULTIPLAYER_OTEL_DEFAULT_TRACES_EXPORTER_HTTP_URL
+        api_key = config[:api_key]
+        
+        raise ArgumentError, "api_key is required" if api_key.nil? || api_key.empty?
+        
+        headers = { "Authorization" => api_key }
+        headers.merge!(config[:headers]) if config[:headers]
+        
+        super(endpoint: endpoint, headers: headers)
+      end
+
+      def export(spans, timeout: nil)
+        # Filter spans by trace ID prefix
+        filtered_spans = spans.select do |span|
+          trace_id = span.trace_id
+          trace_id.start_with?(SessionRecorder::MULTIPLAYER_TRACE_DEBUG_PREFIX) ||
+            trace_id.start_with?(SessionRecorder::MULTIPLAYER_TRACE_CONTINUOUS_DEBUG_PREFIX)
+        end
+
+        return OpenTelemetry::SDK::Trace::Export::SUCCESS if filtered_spans.empty?
+
+        super(filtered_spans, timeout: timeout)
+      end
+    end
+  end
+end

data/lib/session_recorder/exporters/logs_exporter_wrapper.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "opentelemetry/sdk"
+
+module SessionRecorder
+  module Exporters
+    class SessionRecorderLogsExporterWrapper
+      def initialize(exporter)
+        @exporter = exporter
+      end
+
+      def export(logs, timeout: nil)
+        # Filter out multiplayer attributes from logs
+        filtered_logs = logs.map do |log|
+          filtered_log = log.dup
+          filtered_log[:attributes] = filter_attributes(log[:attributes])
+          filtered_log
+        end
+
+        @exporter.export(filtered_logs, timeout: timeout)
+      end
+
+      def shutdown(timeout: nil)
+        @exporter.shutdown(timeout: timeout)
+      end
+
+      def force_flush(timeout: nil)
+        @exporter.force_flush(timeout: timeout)
+      end
+
+      private
+
+      def filter_attributes(attributes)
+        return {} if attributes.nil?
+
+        attributes.each_with_object({}) do |(key, value), filtered|
+          unless key.to_s.start_with?(SessionRecorder::MULTIPLAYER_ATTRIBUTE_PREFIX)
+            filtered[key] = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/session_recorder/exporters/trace_exporter_wrapper.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "opentelemetry/sdk"
+
+module SessionRecorder
+  module Exporters
+    class SessionRecorderTraceExporterWrapper
+      def initialize(exporter)
+        @exporter = exporter
+      end
+
+      def export(spans, timeout: nil)
+        # Filter out multiplayer attributes from spans
+        filtered_spans = spans.map do |span|
+          filtered_span = span.dup
+          filtered_span[:attributes] = filter_attributes(span[:attributes])
+          filtered_span
+        end
+
+        @exporter.export(filtered_spans, timeout: timeout)
+      end
+
+      def shutdown(timeout: nil)
+        @exporter.shutdown(timeout: timeout)
+      end
+
+      def force_flush(timeout: nil)
+        @exporter.force_flush(timeout: timeout)
+      end
+
+      private
+
+      def filter_attributes(attributes)
+        return {} if attributes.nil?
+
+        attributes.each_with_object({}) do |(key, value), filtered|
+          unless key.to_s.start_with?(SessionRecorder::MULTIPLAYER_ATTRIBUTE_PREFIX)
+            filtered[key] = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/session_recorder/exporters.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "exporters/http_trace_exporter"
+require_relative "exporters/http_logs_exporter"
+require_relative "exporters/grpc_trace_exporter"
+require_relative "exporters/grpc_logs_exporter"
+require_relative "exporters/trace_exporter_wrapper"
+require_relative "exporters/logs_exporter_wrapper"
+
+module SessionRecorder
+  module Exporters
+    # Convenience method to create HTTP trace exporter
+    def self.create_http_trace_exporter(config = {})
+      SessionRecorderHttpTraceExporter.new(config)
+    end
+
+    # Convenience method to create HTTP logs exporter
+    def self.create_http_logs_exporter(config = {})
+      SessionRecorderHttpLogsExporter.new(config)
+    end
+
+    # Convenience method to create gRPC trace exporter
+    def self.create_grpc_trace_exporter(config = {})
+      SessionRecorderGrpcTraceExporter.new(config)
+    end
+
+    # Convenience method to create gRPC logs exporter
+    def self.create_grpc_logs_exporter(config = {})
+      SessionRecorderGrpcLogsExporter.new(config)
+    end
+
+    # Convenience method to create trace exporter wrapper
+    def self.create_trace_exporter_wrapper(exporter)
+      SessionRecorderTraceExporterWrapper.new(exporter)
+    end
+
+    # Convenience method to create logs exporter wrapper
+    def self.create_logs_exporter_wrapper(exporter)
+      SessionRecorderLogsExporterWrapper.new(exporter)
+    end
+  end
+end

data/lib/session_recorder/middleware/middleware.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SessionRecorder
+  class Middleware
+    attr_reader :mask_body, :mask_headers, :capture_headers, :capture_body, 
+                :is_mask_body_enabled, :is_mask_headers_enabled, :max_payload_size_bytes
+
+    def initialize(app, options = {})
+      @app = app
+      
+      # Masking functions
+      @mask_body = options[:maskBody] || method(:default_mask_body)
+      @mask_headers = options[:maskHeaders] || method(:default_mask_headers)
+      
+      # Capture flags
+      @capture_headers = options.fetch(:captureHeaders, true)
+      @capture_body = options.fetch(:captureBody, true)
+      
+      # Masking flags
+      @is_mask_body_enabled = options.fetch(:isMaskBodyEnabled, true)
+      @is_mask_headers_enabled = options.fetch(:isMaskHeadersEnabled, true)
+      
+      # Payload size limit
+      @max_payload_size_bytes = options[:maxPayloadSizeBytes] || SessionRecorder::MULTIPLAYER_MAX_HTTP_REQUEST_RESPONSE_SIZE
+    end
+
+    protected
+
+    def default_mask_body(value)
+      return SessionRecorder::MASK_PLACEHOLDER unless @is_mask_body_enabled
+      
+      payload_json = begin
+                       JSON.parse(value)
+                     rescue JSON::ParserError
+                       value
+                     end
+
+      masked_data = mask_primitives(payload_json)
+
+      unless masked_data.is_a?(String)
+        masked_data = masked_data.to_json
+      end
+
+      masked_data
+    end
+
+    def default_mask_headers(headers, custom_header_names_to_mask = [])
+      return headers unless @is_mask_headers_enabled
+      
+      default_header_names_to_mask = ["set-cookie", "cookie", "authorization", "proxy-authorization"]
+      masked_headers = headers.dup
+      headers_to_mask = default_header_names_to_mask + custom_header_names_to_mask
+
+      headers_to_mask.each do |header_name|
+        masked_headers[header_name] = SessionRecorder::MASK_PLACEHOLDER if masked_headers.key?(header_name)
+      end
+
+      masked_headers
+    end
+
+    def mask_primitives(input, current_depth = 0)
+      return SessionRecorder::MASK_PLACEHOLDER if current_depth >= SessionRecorder::MAX_MASK_DEPTH
+
+      case input
+      when Hash
+        input.transform_values { |value| mask_primitives(value, current_depth + 1) }
+      when Array
+        input.map { |value| mask_primitives(value, current_depth + 1) }
+      when String, Numeric, TrueClass, FalseClass, NilClass, Symbol
+        SessionRecorder::MASK_PLACEHOLDER
+      else
+        input
+      end
+    end
+
+    # Extracts request headers from the Rack environment
+    def extract_request_headers(env)
+      return {} unless @capture_headers
+      
+      env.select { |k, _| k.start_with?("HTTP_") }
+         .transform_keys { |k| k.sub(/^HTTP_/, "").split("_").map(&:downcase).join("-") }
+    end
+
+    # Reads the request body safely
+    def extract_request_body(request)
+      return nil unless @capture_body
+      
+      body = request.body.read
+      request.body.rewind # Rewind the stream for downstream middlewares
+      body
+    end
+
+    # Reads the response body safely
+    def extract_response_body(response)
+      return nil unless @capture_body
+      
+      body = []
+      response.each { |part| body << part }
+      body.join
+    end
+
+    # Truncates payload if maxPayloadSizeBytes is set
+    def truncate_if_needed(data)
+      return data unless data.to_s.size > @max_payload_size_bytes
+      "#{data[0...@max_payload_size_bytes]}...[TRUNCATED]"
+    end
+  end
+end

data/lib/session_recorder/middleware/request_middleware.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module SessionRecorder
+  class RequestMiddleware < SessionRecorder::Middleware
+    def call(env)
+      current_span = OpenTelemetry::Trace.current_span
+      trace_id = current_span.context.trace_id.unpack1("H*")
+      request = Rack::Request.new(env)
+
+      request_headers = extract_request_headers(env)
+      masked_headers = @mask_headers.call(request_headers, current_span)
+      current_span.set_attribute(SessionRecorder::ATTR_MULTIPLAYER_HTTP_REQUEST_HEADERS, masked_headers.to_json)
+
+      if request_headers.key?("content-type") && request_headers["content-type"] == "application/json"
+        request_body = extract_request_body(request)
+
+        if request_body
+          masked_body = @mask_body.call(request_body, current_span)
+          masked_body = truncate_if_needed(masked_body)
+
+          current_span.set_attribute(SessionRecorder::ATTR_MULTIPLAYER_HTTP_REQUEST_BODY, 
+                                   masked_body.is_a?(String) ? masked_body : masked_body.to_json)
+        end
+      end
+
+      @app.call(env)
+    end
+  end
+end

data/lib/session_recorder/middleware/response_middleware.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SessionRecorder
+  class ResponseMiddleware < SessionRecorder::Middleware
+    def call(env)
+      status, headers, response = @app.call(env)
+
+      begin
+        current_span = OpenTelemetry::Trace.current_span
+        trace_id = current_span.context.trace_id.unpack1("H*")
+
+        headers["x-trace-id"] = trace_id
+
+        masked_headers = @mask_headers.call(headers, current_span)
+        response_body = extract_response_body(response)
+
+        if response_body
+          masked_body = @mask_body.call(response_body, current_span)
+          masked_body = truncate_if_needed(masked_body)
+
+          current_span.set_attribute(SessionRecorder::ATTR_MULTIPLAYER_HTTP_RESPONSE_HEADERS, masked_headers.to_json)
+          current_span.set_attribute(SessionRecorder::ATTR_MULTIPLAYER_HTTP_RESPONSE_BODY, 
+                                   masked_body.is_a?(String) ? masked_body : masked_body.to_json)
+        end
+
+        [status, headers, response]
+      rescue
+        [status, headers, response]
+      end
+    end
+  end
+end

data/lib/session_recorder/trace/id_generator.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "opentelemetry-sdk"
+require_relative "../type/session_type"
+
+module SessionRecorder
+  module Trace
+    class SessionRecorderIdGenerator
+      include OpenTelemetry::Trace
+      
+      attr_accessor :session_short_id, :session_type
+      attr_reader :generate_long_id, :generate_short_id
+
+      def initialize
+        @generate_long_id = self.class.get_id_generator(16)
+        @generate_short_id = self.class.get_id_generator(8)
+        @session_short_id = ''
+        @session_type = SessionType::PLAIN
+      end
+
+      def generate_trace_id
+        trace_id = @generate_long_id.call
+
+        if @session_short_id && !@session_short_id.empty?
+          session_type_prefix = case @session_type
+                               when SessionType::CONTINUOUS
+                                 SessionRecorder::MULTIPLAYER_TRACE_CONTINUOUS_DEBUG_PREFIX
+                               else
+                                 SessionRecorder::MULTIPLAYER_TRACE_DEBUG_PREFIX
+                               end
+
+          prefix = "#{session_type_prefix}#{@session_short_id}"
+          session_trace_id = "#{prefix}#{trace_id[prefix.length..-1]}"
+
+          return session_trace_id
+        end
+
+        trace_id
+      end
+
+      def generate_span_id
+        @generate_short_id.call
+      end
+
+      def set_session_id(session_short_id, session_type = SessionType::PLAIN)
+        @session_short_id = session_short_id
+        @session_type = session_type
+      end
+
+      private
+
+      def self.get_id_generator(bytes)
+        lambda do
+          (0...(bytes * 2)).map do |i|
+            char_code = rand(16) + 48
+            # valid hex characters in the range 48-57 and 97-102
+            if char_code >= 58
+              char_code += 39
+            end
+            char_code.chr
+          end.join
+        end
+      end
+    end
+  end
+end

data/lib/session_recorder/trace/trace_id_ratio_based_sampler.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "opentelemetry-sdk"
+
+module SessionRecorder
+  module Trace
+    class TraceIdRatioBasedSampler < OpenTelemetry::SDK::Trace::Samplers::TraceIdRatioBased
+      def initialize(ratio = 0)
+        @ratio = normalize(ratio)
+        @upper_bound = (@ratio * 0xffffffff).floor
+        super(@ratio)
+      end
+
+      def should_sample?(trace_id:, parent_context:, links:, name:, kind:, attributes:)
+        tracestate = OpenTelemetry::Trace.current_span(parent_context).context.tracestate
+        
+        # Convert trace_id to hex string for comparison
+        trace_id_hex = trace_id.unpack1("H*")
+        
+        # Always sample if trace ID begins with debug prefixes
+        if trace_id_hex.start_with?(SessionRecorder::MULTIPLAYER_TRACE_DEBUG_PREFIX) ||
+           trace_id_hex.start_with?(SessionRecorder::MULTIPLAYER_TRACE_CONTINUOUS_DEBUG_PREFIX)
+          return OpenTelemetry::SDK::Trace::Samplers::Result.new(
+            decision: OpenTelemetry::SDK::Trace::Samplers::Decision::RECORD_AND_SAMPLE, 
+            tracestate: tracestate
+          )
+        end
+        
+        # For all other trace IDs, use the provided sampling ratio
+        if valid_trace_id?(trace_id_hex) && accumulate(trace_id_hex) < @upper_bound
+          OpenTelemetry::SDK::Trace::Samplers::Result.new(
+            decision: OpenTelemetry::SDK::Trace::Samplers::Decision::RECORD_AND_SAMPLE, 
+            tracestate: tracestate
+          )
+        else
+          OpenTelemetry::SDK::Trace::Samplers::Result.new(
+            decision: OpenTelemetry::SDK::Trace::Samplers::Decision::DROP, 
+            tracestate: tracestate
+          )
+        end
+      end
+
+      def description
+        "SessionRecorderTraceIdRatioBasedSampler{ratio=#{@ratio}}"
+      end
+
+      private
+
+      def valid_trace_id?(trace_id)
+        trace_id.is_a?(String) && trace_id.length == 32 && trace_id =~ /^([0-9a-f]{32})$/i
+      end
+
+      def normalize(ratio)
+        return 0 unless defined?(ratio) && ratio.is_a?(Numeric)
+        return 1 if ratio >= 1
+        return 0 if ratio <= 0
+
+        ratio
+      end
+
+      def accumulate(trace_id)
+        accumulation = 0
+        (0...trace_id.length / 8).each do |i|
+          pos = i * 8
+          part = trace_id[pos, 8].to_i(16)
+          accumulation = (accumulation ^ part) & 0xffffffff
+        end
+        accumulation
+      end
+    end
+  end
+end

data/lib/session_recorder/type/session_type.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module SessionRecorder
+  module Trace
+    module SessionType
+      PLAIN = 'plain'
+      CONTINUOUS = 'continuous'
+    end
+  end
+end

data/lib/session_recorder/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Multiplayer
+  module SessionRecorder
+    VERSION = "0.0.6"
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: multiplayer-session-recorder
+version: !ruby/object:Gem::Version
+  version: 0.0.6
+platform: ruby
+authors:
+- Multiplayer Inc.
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-09-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-exporter-otlp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.29.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.29.1
+description:
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/session-recorder.rb
+- lib/session_recorder/constants.rb
+- lib/session_recorder/exporters.rb
+- lib/session_recorder/exporters/grpc_logs_exporter.rb
+- lib/session_recorder/exporters/grpc_trace_exporter.rb
+- lib/session_recorder/exporters/http_logs_exporter.rb
+- lib/session_recorder/exporters/http_trace_exporter.rb
+- lib/session_recorder/exporters/logs_exporter_wrapper.rb
+- lib/session_recorder/exporters/trace_exporter_wrapper.rb
+- lib/session_recorder/middleware/middleware.rb
+- lib/session_recorder/middleware/request_middleware.rb
+- lib/session_recorder/middleware/response_middleware.rb
+- lib/session_recorder/trace/id_generator.rb
+- lib/session_recorder/trace/trace_id_ratio_based_sampler.rb
+- lib/session_recorder/type/session_type.rb
+- lib/session_recorder/version.rb
+homepage: https://rubygems.org/gems/multiplayer_session_recorder
+licenses:
+- MIT
+metadata: {}
+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.5.22
+signing_key:
+specification_version: 4
+summary: Multiplayer Fullstack Session Recorder
+test_files: []