toggly 0.2.1 → 0.5.0

data/lib/toggly/telemetry/runtime.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require_relative "runtime_flush"
+
+module Toggly
+  module Telemetry
+    # Owns usage + metrics batchers, flush timers, and process-exit handlers.
+    class Runtime
+      include RuntimeFlush
+
+      TIMER_JOIN_TIMEOUT_SECONDS = 2.0
+
+      # rubocop:disable Metrics/ParameterLists -- mirrors other SDK telemetry config surfaces
+      def initialize(
+        app_key:,
+        environment:,
+        metrics_base_url: nil,
+        enable_usage_tracking: nil,
+        enable_metrics: nil,
+        usage_flush_interval: nil,
+        metrics_flush_interval: nil,
+        instance_name: nil,
+        app_version: nil,
+        usage_client: nil,
+        metrics_client: nil,
+        usage_client_provided: false,
+        metrics_client_provided: false,
+        logger: nil
+      )
+        # rubocop:enable Metrics/ParameterLists
+        has_app_key = !app_key.nil? && !app_key.to_s.empty?
+        telemetry_env_disabled = ENV["TOGGLY_DISABLE_TELEMETRY"] == "1"
+        default_on = has_app_key && !telemetry_env_disabled
+
+        @app_key = app_key
+        @environment = environment
+        @metrics_base_url = normalize_url(metrics_base_url || GrpcClients::DEFAULT_METRICS_BASE_URL)
+        @enable_usage = default_on
+        @enable_usage = enable_usage_tracking ? true : false unless enable_usage_tracking.nil?
+        @enable_metrics = default_on
+        @enable_metrics = enable_metrics ? true : false unless enable_metrics.nil?
+        @usage_flush_interval = usage_flush_interval.nil? ? GrpcClients::DEFAULT_TELEMETRY_FLUSH_SECONDS : usage_flush_interval.to_f
+        @metrics_flush_interval = metrics_flush_interval.nil? ? GrpcClients::DEFAULT_TELEMETRY_FLUSH_SECONDS : metrics_flush_interval.to_f
+        @instance_name = instance_name
+        @app_version = app_version
+        @injected_usage = usage_client
+        @injected_metrics = metrics_client
+        @usage_client_provided = usage_client_provided
+        @metrics_client_provided = metrics_client_provided
+        @logger = logger
+
+        @usage_batcher = nil
+        @metrics_batcher = nil
+        @clients = nil
+        @usage_timer = nil
+        @metrics_timer = nil
+        @sending_usage = false
+        @sending_metrics = false
+        @closed = false
+        @mutex = Mutex.new
+        @timer_cv = ConditionVariable.new
+        @process_start_time = Time.now.utc
+        @atexit_registered = false
+        @warned_missing_grpc = false
+      end
+
+      def usage_enabled?
+        @enable_usage && !@closed
+      end
+
+      def metrics_enabled?
+        @enable_metrics && !@closed
+      end
+
+      def start
+        return if @closed
+        return unless @enable_usage || @enable_metrics
+
+        if @usage_client_provided || @metrics_client_provided
+          @clients = GrpcClients::Clients.new(usage: @injected_usage, metrics: @injected_metrics)
+        elsif !GrpcClients.grpc_available?
+          warn_missing_grpc
+        end
+
+        if @enable_usage
+          @usage_batcher = UsageBatcher.new(
+            @app_key,
+            @environment,
+            instance_name: @instance_name,
+            app_version: @app_version,
+            process_start_time: @process_start_time
+          )
+          schedule_usage_flush if @usage_flush_interval.positive?
+        end
+
+        if @enable_metrics
+          @metrics_batcher = MetricsBatcher.new(
+            @app_key,
+            @environment,
+            instance_name: @instance_name
+          )
+          schedule_metrics_flush if @metrics_flush_interval.positive?
+        end
+
+        attach_exit_handlers
+      end
+
+      def record_check(feature, enabled, identity = nil, variant: nil, unique_request: false)
+        batcher = @mutex.synchronize { @usage_batcher }
+        batcher&.record_check(feature, enabled, identity, variant: variant, unique_request: unique_request)
+      end
+
+      def record_usage(feature, identity = nil, variant: "enabled")
+        batcher = @mutex.synchronize { @usage_batcher }
+        batcher&.record_usage(feature, identity, variant: variant)
+      end
+
+      def record_view(feature, identity = nil, variant: "enabled")
+        batcher = @mutex.synchronize { @usage_batcher }
+        batcher&.record_view(feature, identity, variant: variant)
+      end
+
+      def record_definition_cache_hit
+        batcher = @mutex.synchronize { @usage_batcher }
+        batcher&.record_definition_cache_hit
+      end
+
+      def record_definition_cache_miss
+        batcher = @mutex.synchronize { @usage_batcher }
+        batcher&.record_definition_cache_miss
+      end
+
+      def measure(metric, value, options = nil)
+        batcher = @mutex.synchronize { @metrics_batcher }
+        batcher&.measure(metric, value, options)
+      end
+
+      def increment_counter(metric, value = 1.0, options = nil)
+        batcher = @mutex.synchronize { @metrics_batcher }
+        batcher&.increment_counter(metric, value, options)
+      end
+
+      def observe(metric, value, options = nil)
+        batcher = @mutex.synchronize { @metrics_batcher }
+        batcher&.observe(metric, value, options)
+      end
+
+      def close
+        timers = nil
+        @mutex.synchronize do
+          return if @closed
+
+          @closed = true
+          @timer_cv.broadcast
+          timers = [@usage_timer, @metrics_timer].compact
+          @usage_timer = nil
+          @metrics_timer = nil
+        end
+
+        # Wait for flush loops (including in-flight sends) — do not Thread#kill.
+        timers.each { |thread| join_timer(thread) }
+
+        begin
+          flush_all
+        ensure
+          clients = @clients
+          @clients = nil
+          @usage_batcher = nil
+          @metrics_batcher = nil
+          [clients&.usage, clients&.metrics].compact.uniq.each do |side|
+            side.close if side.respond_to?(:close)
+          rescue StandardError
+            # best-effort
+          end
+        end
+      end
+
+      private
+
+      def normalize_url(url)
+        u = url.to_s
+        u.end_with?("/") ? u : "#{u}/"
+      end
+
+      def warn_missing_grpc
+        return if @warned_missing_grpc
+
+        @warned_missing_grpc = true
+        log_warn(
+          "Usage/metrics enabled but the optional grpc gem is not installed. " \
+          "Install `grpc` (and google-protobuf) to send telemetry."
+        )
+      end
+
+      def schedule_usage_flush
+        return if @closed || @usage_flush_interval <= 0
+
+        @usage_timer = Thread.new do
+          loop do
+            wait_for_interval_or_stop(@usage_flush_interval)
+            break if @closed
+
+            flush_usage
+          end
+        end
+        @usage_timer.abort_on_exception = false
+      end
+
+      def schedule_metrics_flush
+        return if @closed || @metrics_flush_interval <= 0
+
+        @metrics_timer = Thread.new do
+          loop do
+            wait_for_interval_or_stop(@metrics_flush_interval)
+            break if @closed
+
+            flush_metrics
+          end
+        end
+        @metrics_timer.abort_on_exception = false
+      end
+
+      # Interruptible interval wait — close broadcasts to wake early.
+      def wait_for_interval_or_stop(interval)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + interval
+        @mutex.synchronize do
+          until @closed
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            break if remaining <= 0
+
+            @timer_cv.wait(@mutex, remaining)
+          end
+        end
+      end
+
+      def join_timer(thread)
+        return if thread.nil? || !thread.alive?
+
+        thread.join(TIMER_JOIN_TIMEOUT_SECONDS)
+      end
+
+      def attach_exit_handlers
+        return if @atexit_registered
+
+        at_exit do
+          close
+        rescue StandardError
+          # best-effort flush on exit
+        end
+        @atexit_registered = true
+      end
+
+      def log_warn(message)
+        @logger&.warn("[Toggly] #{message}")
+      end
+
+      def log_error(message)
+        @logger&.error("[Toggly] #{message}")
+      end
+    end
+  end
+end

data/lib/toggly/telemetry/runtime_flush.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Telemetry
+    # Usage/metrics flush + native gRPC client bootstrap for Runtime.
+    module RuntimeFlush
+      def flush_usage
+        client = nil
+        batcher = nil
+        snapshot = nil
+        payload = nil
+        @mutex.synchronize do
+          return if @usage_batcher.nil? || @sending_usage
+          return if @usage_batcher.empty?
+
+          ensure_native_clients
+          client = @clients&.usage
+          return if client.nil? || !client.respond_to?(:send_stats)
+
+          # Hold a local reference: close() may null @usage_batcher during send.
+          batcher = @usage_batcher
+          drained = batcher.export_and_reset
+          return if drained.nil?
+
+          payload = drained.payload
+          snapshot = drained.snapshot
+          @sending_usage = true
+        end
+
+        begin
+          client.send_stats(payload)
+        rescue StandardError => e
+          log_error("Failed to send usage stats: #{e.message}")
+          begin
+            batcher&.restore(snapshot)
+          rescue StandardError => restore_error
+            log_error("Failed to restore usage batch after send failure: #{restore_error.message}")
+          end
+        ensure
+          @mutex.synchronize { @sending_usage = false }
+        end
+      end
+
+      def flush_metrics
+        client = nil
+        payload = nil
+        @mutex.synchronize do
+          return if @metrics_batcher.nil? || @sending_metrics
+          return if @metrics_batcher.empty?
+
+          ensure_native_clients
+          client = @clients&.metrics
+          return if client.nil? || !client.respond_to?(:send_metrics)
+
+          payload = @metrics_batcher.build_and_reset
+          return if payload.nil?
+
+          @sending_metrics = true
+        end
+
+        begin
+          client.send_metrics(payload)
+        rescue StandardError => e
+          log_error("Failed to send metrics: #{e.message}")
+        ensure
+          @mutex.synchronize { @sending_metrics = false }
+        end
+      end
+
+      def flush_all
+        flush_usage
+        flush_metrics
+      end
+
+      private
+
+      def ensure_native_clients
+        return if @clients
+        return if @usage_client_provided || @metrics_client_provided
+        return unless GrpcClients.grpc_available?
+
+        @clients = GrpcClients.create(@metrics_base_url)
+        return if @clients
+
+        log_warn("Failed to create Toggly gRPC clients; telemetry send disabled")
+      end
+    end
+  end
+end

data/lib/toggly/telemetry/usage_batcher.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Telemetry
+    # In-memory feature usage aggregator (Usage.SendStats payload shape).
+    class UsageBatcher
+      VariantStatsAgg = Struct.new(:check_count, :request_count, :used_count, :viewed_count, keyword_init: true) do
+        def initialize(check_count: 0, request_count: 0, used_count: 0, viewed_count: 0)
+          super
+        end
+
+        def to_wire
+          {
+            checkCount: check_count,
+            requestCount: request_count,
+            usedCount: used_count,
+            viewedCount: viewed_count
+          }
+        end
+
+        def clone
+          VariantStatsAgg.new(
+            check_count: check_count,
+            request_count: request_count,
+            used_count: used_count,
+            viewed_count: viewed_count
+          )
+        end
+      end
+
+      FeatureUsageAgg = Struct.new(
+        :variant_stats,
+        :unique_users_enabled,
+        :unique_users_disabled,
+        :unique_users_used,
+        :unique_user_hashes,
+        :unique_viewed_user_hashes,
+        keyword_init: true
+      ) do
+        def initialize(
+          variant_stats: {},
+          unique_users_enabled: Set.new,
+          unique_users_disabled: Set.new,
+          unique_users_used: Set.new,
+          unique_user_hashes: Set.new,
+          unique_viewed_user_hashes: Set.new
+        )
+          super
+        end
+
+        def clone
+          FeatureUsageAgg.new(
+            variant_stats: variant_stats.transform_values(&:clone),
+            unique_users_enabled: unique_users_enabled.dup,
+            unique_users_disabled: unique_users_disabled.dup,
+            unique_users_used: unique_users_used.dup,
+            unique_user_hashes: unique_user_hashes.dup,
+            unique_viewed_user_hashes: unique_viewed_user_hashes.dup
+          )
+        end
+      end
+
+      # Restoreable copy of drained batcher state.
+      BatchSnapshot = Struct.new(
+        :per_feature,
+        :app_unique,
+        :definition_cache_hits,
+        :definition_cache_misses,
+        keyword_init: true
+      )
+
+      # Wire payload plus snapshot for failed-send restore.
+      DrainedBatch = Struct.new(:payload, :snapshot, keyword_init: true)
+
+      def initialize(app_key, environment, instance_name: nil, app_version: nil, process_start_time: nil)
+        @app_key = app_key
+        @environment = environment
+        @instance_name = instance_name
+        @app_version = app_version
+        @process_start_time = process_start_time || Time.now.utc
+        @per_feature = {}
+        @app_unique = Set.new
+        @definition_cache_hits = 0
+        @definition_cache_misses = 0
+        @mutex = Mutex.new
+      end
+
+      def record_definition_cache_hit
+        @mutex.synchronize { @definition_cache_hits += 1 }
+      end
+
+      def record_definition_cache_miss
+        @mutex.synchronize { @definition_cache_misses += 1 }
+      end
+
+      def record_check(feature, enabled, identity = nil, variant: nil, unique_request: false)
+        @mutex.synchronize do
+          agg = get_feature(feature)
+          name = if variant.nil?
+                   enabled ? "enabled" : "disabled"
+                 else
+                   variant.to_s
+                 end
+          stats = get_variant(agg, name)
+          stats.check_count += 1
+          stats.request_count += 1 if unique_request
+
+          if identity && !identity.to_s.empty?
+            hashed = GrpcClients.hash_identity(identity)
+            @app_unique.add(hashed)
+            if enabled
+              agg.unique_users_enabled.add(hashed)
+            else
+              agg.unique_users_disabled.add(hashed)
+            end
+          end
+        end
+      end
+
+      def record_usage(feature, identity = nil, variant: "enabled")
+        @mutex.synchronize do
+          agg = get_feature(feature)
+          get_variant(agg, variant.to_s).used_count += 1
+          track_identity(identity, agg.unique_users_used)
+          agg.unique_user_hashes.add(GrpcClients.hash_identity(identity)) if identity && !identity.to_s.empty?
+        end
+      end
+
+      def record_view(feature, identity = nil, variant: "enabled")
+        @mutex.synchronize do
+          agg = get_feature(feature)
+          get_variant(agg, variant.to_s).viewed_count += 1
+          if identity && !identity.to_s.empty?
+            hashed = GrpcClients.hash_identity(identity)
+            @app_unique.add(hashed)
+            agg.unique_viewed_user_hashes.add(hashed)
+          end
+        end
+      end
+
+      def empty?
+        @mutex.synchronize { empty_unlocked? }
+      end
+
+      # Build the SendStats payload, clear pending state, and return a restore snapshot.
+      #
+      # @return [DrainedBatch, nil]
+      def export_and_reset
+        @mutex.synchronize do
+          return nil if empty_unlocked?
+
+          snapshot = clone_snapshot_unlocked
+          payload = build_payload_unlocked
+          clear_unlocked
+          DrainedBatch.new(payload: payload, snapshot: snapshot)
+        end
+      end
+
+      def build_and_reset
+        drained = export_and_reset
+        drained&.payload
+      end
+
+      # Merge a drained snapshot after send_stats failure (additive).
+      #
+      # @param snapshot [BatchSnapshot, nil]
+      def restore(snapshot)
+        return if snapshot.nil?
+
+        @mutex.synchronize do
+          @definition_cache_hits += snapshot.definition_cache_hits
+          @definition_cache_misses += snapshot.definition_cache_misses
+          @app_unique.merge(snapshot.app_unique)
+
+          snapshot.per_feature.each do |feature, snap_agg|
+            agg = get_feature(feature)
+            snap_agg.variant_stats.each do |name, snap_stats|
+              stats = get_variant(agg, name)
+              stats.check_count += snap_stats.check_count
+              stats.request_count += snap_stats.request_count
+              stats.used_count += snap_stats.used_count
+              stats.viewed_count += snap_stats.viewed_count
+            end
+            agg.unique_users_enabled.merge(snap_agg.unique_users_enabled)
+            agg.unique_users_disabled.merge(snap_agg.unique_users_disabled)
+            agg.unique_users_used.merge(snap_agg.unique_users_used)
+            agg.unique_user_hashes.merge(snap_agg.unique_user_hashes)
+            agg.unique_viewed_user_hashes.merge(snap_agg.unique_viewed_user_hashes)
+          end
+        end
+      end
+
+      private
+
+      def empty_unlocked?
+        @per_feature.empty? &&
+          @app_unique.empty? &&
+          @definition_cache_hits.zero? &&
+          @definition_cache_misses.zero?
+      end
+
+      def clone_snapshot_unlocked
+        BatchSnapshot.new(
+          per_feature: @per_feature.transform_values(&:clone),
+          app_unique: @app_unique.dup,
+          definition_cache_hits: @definition_cache_hits,
+          definition_cache_misses: @definition_cache_misses
+        )
+      end
+
+      def build_payload_unlocked
+        payload = {
+          appKey: @app_key,
+          environment: @environment,
+          time: GrpcClients.to_protobuf_timestamp,
+          stats: drain_feature_stats,
+          totalUniqueUsers: @app_unique.size,
+          uniqueUserHashes: @app_unique.to_a,
+          processStartTime: GrpcClients.to_protobuf_timestamp(@process_start_time)
+        }
+        payload[:instanceName] = @instance_name if @instance_name
+        payload[:appVersion] = @app_version if @app_version
+        payload[:definitionCacheHits] = @definition_cache_hits if @definition_cache_hits.positive?
+        payload[:definitionCacheMisses] = @definition_cache_misses if @definition_cache_misses.positive?
+        payload
+      end
+
+      def clear_unlocked
+        @per_feature = {}
+        @app_unique = Set.new
+        @definition_cache_hits = 0
+        @definition_cache_misses = 0
+      end
+
+      def drain_feature_stats
+        @per_feature.map do |feature, agg|
+          {
+            feature: feature,
+            uniqueContextIdentifierEnabledCount: agg.unique_users_enabled.size,
+            uniqueContextIdentifierDisabledCount: agg.unique_users_disabled.size,
+            uniqueUsersUsedCount: agg.unique_users_used.size,
+            uniqueUserHashes: agg.unique_user_hashes.to_a,
+            uniqueViewedUserHashes: agg.unique_viewed_user_hashes.to_a,
+            variantStats: wire_variant_stats(agg)
+          }
+        end
+      end
+
+      def wire_variant_stats(agg)
+        variant_stats = {}
+        agg.variant_stats.each do |name, vs|
+          next unless vs.check_count.positive? || vs.request_count.positive? ||
+                      vs.used_count.positive? || vs.viewed_count.positive?
+
+          variant_stats[name] = vs.to_wire
+        end
+        variant_stats
+      end
+
+      def get_feature(feature)
+        @per_feature[feature] ||= FeatureUsageAgg.new
+      end
+
+      def get_variant(agg, variant)
+        agg.variant_stats[variant] ||= VariantStatsAgg.new
+      end
+
+      def track_identity(identity, into)
+        return if identity.nil? || identity.to_s.empty?
+
+        hashed = GrpcClients.hash_identity(identity)
+        @app_unique.add(hashed)
+        into.add(hashed)
+      end
+    end
+  end
+end

data/lib/toggly/telemetry.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "telemetry/grpc_clients"
+require_relative "telemetry/usage_batcher"
+require_relative "telemetry/metrics_batcher"
+require_relative "telemetry/runtime"
+
+module Toggly
+  # Usage and business-metrics telemetry (optional gRPC transport).
+  module Telemetry
+    DEFAULT_METRICS_BASE_URL = GrpcClients::DEFAULT_METRICS_BASE_URL
+    DEFAULT_TELEMETRY_FLUSH_SECONDS = GrpcClients::DEFAULT_TELEMETRY_FLUSH_SECONDS
+    GRPC_USER_AGENT_METADATA_KEY = GrpcClients::GRPC_USER_AGENT_METADATA_KEY
+
+    module_function
+
+    def hash_identity(identity)
+      GrpcClients.hash_identity(identity)
+    end
+
+    def feature_stat_from_payload(payload)
+      GrpcClients.feature_stat_from_payload(payload)
+    end
+
+    def metric_stat_from_payload(payload)
+      GrpcClients.metric_stat_from_payload(payload)
+    end
+
+    def grpc_available?
+      GrpcClients.grpc_available?
+    end
+
+    def resolve_user_agent(override = nil)
+      GrpcClients.resolve_user_agent(override)
+    end
+  end
+end