toggly 0.3.0 → 0.5.0

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.0"
 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"
 

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.0
 platform: ruby
 authors:
 - Ops.ai
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-04 00:00:00.000000000 Z
+date: 2026-09-10 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: