toggly 0.3.0 → 0.5.1

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

data/lib/toggly/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Toggly
-  VERSION = "0.3.0"
+  VERSION = "0.5.1"
 end

data/lib/toggly.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "toggly/version"
+require_relative "toggly/telemetry"
 require_relative "toggly/config"
 require_relative "toggly/request_context"
 require_relative "toggly/http_request_mapper"
@@ -30,6 +31,7 @@ require_relative "toggly/evaluation_engine"
 require_relative "toggly/snapshot_providers/base"
 require_relative "toggly/snapshot_providers/memory"
 require_relative "toggly/snapshot_providers/file"
+require_relative "toggly/definition_cache"
 require_relative "toggly/definitions_provider"
 require_relative "toggly/client"
 
@@ -77,6 +79,7 @@ module Toggly
     def configure
       config = Config.new
       yield(config) if block_given?
+      config.apply_telemetry_defaults!
       @client = Client.new(config)
     end
 

data/proto/metrics.proto

@@ -0,0 +1,60 @@
+syntax = "proto3";
+
+package Metrics;
+
+option go_package = "github.com/ops-ai/Toggly.FeatureManagement/toggly-go/toggly/metrics/metricspb";
+
+import "google/protobuf/timestamp.proto";
+
+message MetricStat {
+  string appKey = 1;
+  string environment = 2;
+  google.protobuf.Timestamp time = 3;
+  repeated MetricStatMessage stats = 4;
+  repeated MetricCounterMessage counters = 5;
+  repeated MetricObservationMessage observations = 6;
+  optional string instanceName = 7;
+}
+
+message MetricStatMessage {
+  string metric = 1;
+  int32 enabledCount = 2 [deprecated = true];
+  int32 disabledCount = 3 [deprecated = true];
+  optional string feature = 4;
+  double value = 5 [deprecated = true];
+  optional double valueDisabled = 6 [deprecated = true];
+
+  // Multi-variate support - Key: variant name (e.g., "enabled", "control")
+  map<string, double> variantValues = 7;
+}
+
+message MetricCounterMessage {
+  string metric = 1;
+  int32 enabledCount = 2 [deprecated = true];
+  int32 disabledCount = 3 [deprecated = true];
+  optional string feature = 4;
+  double value = 5 [deprecated = true];
+  optional double valueDisabled = 6 [deprecated = true];
+
+  map<string, double> variantValues = 7;
+}
+
+message MetricObservationMessage {
+  google.protobuf.Timestamp time = 1;
+  string metric = 2;
+  int32 enabledCount = 3 [deprecated = true];
+  int32 disabledCount = 4 [deprecated = true];
+  optional string feature = 5;
+  double value = 6 [deprecated = true];
+  optional double valueDisabled = 7 [deprecated = true];
+
+  map<string, double> variantValues = 8;
+}
+
+message MetricResult {
+  int32 count = 1;
+}
+
+service Metrics {
+  rpc SendMetrics(MetricStat) returns (MetricResult);
+}

data/proto/usage.proto

@@ -0,0 +1,55 @@
+syntax = "proto3";
+
+package Usage;
+
+option go_package = "github.com/ops-ai/Toggly.FeatureManagement/toggly-go/toggly/usage/usagepb";
+
+import "google/protobuf/timestamp.proto";
+
+message FeatureStat {
+  string appKey = 1;
+  string environment = 2;
+  google.protobuf.Timestamp time = 3;
+  repeated StatMessage stats = 4;
+  int32 totalUniqueUsers = 5;
+  optional string instanceName = 6;
+  optional google.protobuf.Timestamp processStartTime = 7;
+  optional string appVersion = 8;
+  repeated int32 uniqueUserHashes = 9; // Application-level unique user ID hashes
+  optional int32 definitionCacheHits = 10; // SDK-reported definition-refresh cache hits (batch delta)
+  optional int32 definitionCacheMisses = 11; // SDK-reported definition-refresh cache misses (batch delta)
+}
+
+message StatMessage {
+  string feature = 1;
+  int32 enabledCount = 2 [deprecated = true]; // Legacy: use variantStats instead
+  int32 disabledCount = 3 [deprecated = true]; // Legacy: use variantStats instead
+  int32 uniqueContextIdentifierEnabledCount = 4;
+  int32 uniqueContextIdentifierDisabledCount = 5;
+  int32 uniqueRequestEnabledCount = 6 [deprecated = true]; // Legacy: use variantStats instead
+  int32 uniqueRequestDisabledCount = 7 [deprecated = true]; // Legacy: use variantStats instead
+  int32 usedCount = 8 [deprecated = true]; // Legacy: use variantStats instead
+  int32 uniqueUsersUsedCount = 9;
+  repeated int32 uniqueUserHashes = 10; // Unique user ID hashes for "used" tracking
+
+  // Multi-variate support - all new metrics should use this
+  map<string, VariantStats> variantStats = 11; // Key: variant name (e.g., "enabled", "disabled")
+
+  // Unique user tracking for "viewed" metric (per feature, not per variant)
+  repeated int32 uniqueViewedUserHashes = 12;
+}
+
+message VariantStats {
+  int32 checkCount = 1;
+  int32 requestCount = 2;
+  int32 usedCount = 3;
+  int32 viewedCount = 4;
+}
+
+message StatResult {
+  int32 featureCount = 1;
+}
+
+service Usage {
+  rpc SendStats(FeatureStat) returns (StatResult);
+}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toggly
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Ops.ai
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-04 00:00:00.000000000 Z
+date: 2026-09-17 00:00:00.000000000 Z
 dependencies: []
 description: High-performance Ruby SDK for Toggly feature flag management. Works with
   or without Toggly.io.
@@ -23,8 +23,11 @@ files:
 - README.md
 - lib/toggly.rb
 - lib/toggly/client.rb
+- lib/toggly/client/cache_telemetry.rb
+- lib/toggly/client/snapshot_support.rb
 - lib/toggly/config.rb
 - lib/toggly/context.rb
+- lib/toggly/definition_cache.rb
 - lib/toggly/definitions_provider.rb
 - lib/toggly/entity_context.rb
 - lib/toggly/errors.rb
@@ -52,8 +55,20 @@ files:
 - lib/toggly/snapshot_providers/file.rb
 - lib/toggly/snapshot_providers/memory.rb
 - lib/toggly/sticky_hash.rb
+- lib/toggly/telemetry.rb
+- lib/toggly/telemetry/grpc_clients.rb
+- lib/toggly/telemetry/metrics_batcher.rb
+- lib/toggly/telemetry/pb/metrics_pb.rb
+- lib/toggly/telemetry/pb/metrics_services_pb.rb
+- lib/toggly/telemetry/pb/usage_pb.rb
+- lib/toggly/telemetry/pb/usage_services_pb.rb
+- lib/toggly/telemetry/runtime.rb
+- lib/toggly/telemetry/runtime_flush.rb
+- lib/toggly/telemetry/usage_batcher.rb
 - lib/toggly/user_agent_parser.rb
 - lib/toggly/version.rb
+- proto/metrics.proto
+- proto/usage.proto
 homepage: https://toggly.io
 licenses:
 - MIT
@@ -63,7 +78,7 @@ metadata:
   changelog_uri: https://github.com/ops-ai/toggly-ruby/blob/main/CHANGELOG.md
   documentation_uri: https://docs.toggly.io/sdks/ruby
   rubygems_mfa_required: 'true'
-  optional_dependencies: websocket-client-simple
+  optional_dependencies: websocket-client-simple, grpc, google-protobuf
 post_install_message:
 rdoc_options: []
 require_paths: