openfeature-sdk 0.6.1 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac3b2793c1b6453e2525dcc04d7646fd4e5d61a87e6ade8b257754cf9b9c991c
-  data.tar.gz: c5aeedfe23851ef99e26024bf1db5f4ba38d7f669b9ea6b3e1e5f63d0693c1a6
+  metadata.gz: 304772054cf10c0cc02870fdeb7a1a7412342912e3f8a08d80c33fe25bd99849
+  data.tar.gz: 6a27c2a8bf23074292594f4eec0ecd4dd9df11ddc1e3e48c4c7ff245e76a6381
 SHA512:
-  metadata.gz: 9aa41845c24248cf6eec381f4531fbfc301196ea748f3b3189333c4879c64a2dc1eda8a935e3514291dcbb5100c1668260e1b87bec837952e1eb1777ae083501
-  data.tar.gz: c162a21b0a5b4ee91f132e676440b84cf7862afccd689416f97e9b41f9284bf8b86de5050a1c32a3c98096ec39074cbb0ae1dcbe0d85d4db905d447f3baccd3d
+  metadata.gz: bcaacd882ecdf0ebd0643e1a839bae3d4efb02deb30f2128c5feca91c93e85bee65b755147cf4bef6edabc010875746b777cd4570f26161451a620db396e02e8
+  data.tar.gz: 5a6ba82992f4d8e960d350a573e48a5e015c9b8eb953737354a4573d0a9f89ca6c4615553d0240a91c1490aad8fc3e1c2ca4bfeddc64d0b1203835ede55e1c77

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.6.1"
+  ".": "0.6.2"
 }

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.6.2](https://github.com/open-feature/ruby-sdk/compare/v0.6.1...v0.6.2) (2026-03-07)
+
+
+### Features
+
+* add logging hook (spec Appendix A) ([#229](https://github.com/open-feature/ruby-sdk/issues/229)) ([2f681c9](https://github.com/open-feature/ruby-sdk/commit/2f681c910198d2bfa16389018f42ca9dc3270936))
+* add transaction context propagation (spec 3.3) ([#230](https://github.com/open-feature/ruby-sdk/issues/230)) ([0aff30f](https://github.com/open-feature/ruby-sdk/commit/0aff30f77a0b680341cfd3d1f43e9d1f0ede1b75))
+
 ## [0.6.1](https://github.com/open-feature/ruby-sdk/compare/v0.6.0...v0.6.1) (2026-03-05)
 
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    openfeature-sdk (0.6.1)
+    openfeature-sdk (0.6.2)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -17,8 +17,8 @@
   </a>
   <!-- x-release-please-start-version -->
 
-  <a href="https://github.com/open-feature/ruby-sdk/releases/tag/v0.6.1">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.6.1&color=blue&style=for-the-badge" />
+  <a href="https://github.com/open-feature/ruby-sdk/releases/tag/v0.6.2">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.6.2&color=blue&style=for-the-badge" />
   </a>
 
   <!-- x-release-please-end -->
@@ -101,12 +101,12 @@ object = client.fetch_object_value(flag_key: 'object_value', default_value: { na
 | ✅      | [Providers](#providers)                                             | Integrate with a commercial, open source, or in-house feature management tool.                                                                               |
 | ✅      | [Targeting](#targeting)                                             | Contextually-aware flag evaluation using [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context).                           |
 | ✅      | [Hooks](#hooks)                                                     | Add functionality to various stages of the flag evaluation life-cycle.                                                                                       |
-| ❌      | [Logging](#logging)                                                 | Integrate with popular logging packages.                                                                                                                     |
+| ✅      | [Logging](#logging)                                                 | Integrate with popular logging packages.                                                                                                                     |
 | ✅      | [Domains](#domains)                                                 | Logically bind clients with providers.                                                                                                                       |
 | ✅      | [Eventing](#eventing)                                               | React to state changes in the provider or flag management system.                                                                                            |
 | ✅      | [Shutdown](#shutdown)                                               | Gracefully clean up a provider during application shutdown.                                                                                                  |
 | ✅      | [Tracking](#tracking)                                               | Associate user actions with feature flag evaluations for experimentation.                                                                                    |
-| ❌      | [Transaction Context Propagation](#transaction-context-propagation) | Set a specific [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context) for a transaction (e.g. an HTTP request or a thread) |
+| ✅      | [Transaction Context Propagation](#transaction-context-propagation) | Set a specific [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context) for a transaction (e.g. an HTTP request or a thread) |
 | ✅      | [Extending](#extending)                                             | Extend OpenFeature with custom providers and hooks.                                                                                                          |
 
 <sub>Implemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌</sub>
@@ -247,9 +247,27 @@ client.fetch_boolean_value(
 
 ### Logging
 
-Coming Soon! [Issue available](https://github.com/open-feature/ruby-sdk/issues/148) to work on.
+The SDK includes a built-in `LoggingHook` that provides structured log output for flag evaluations. It logs at the `before`, `after`, and `error` stages of the hook lifecycle.
 
-<!-- TODO: talk about logging config and include a code example -->
+```ruby
+# Use the SDK's default logger (from Configuration)
+OpenFeature::SDK.hooks << OpenFeature::SDK::Hooks::LoggingHook.new
+
+# Or provide your own logger
+logger = Logger.new($stdout)
+OpenFeature::SDK.hooks << OpenFeature::SDK::Hooks::LoggingHook.new(logger: logger)
+
+# Optionally include evaluation context in log output
+OpenFeature::SDK.hooks << OpenFeature::SDK::Hooks::LoggingHook.new(
+  logger: logger,
+  include_evaluation_context: true
+)
+```
+
+Log output uses a structured key=value format:
+- **before** (DEBUG): `stage=before domain=my-domain provider_name=my-provider flag_key=my-flag default_value=false`
+- **after** (DEBUG): includes `reason`, `variant`, and `value`
+- **error** (ERROR): includes `error_code` and `error_message`
 
 ### Domains
 
@@ -361,12 +379,44 @@ Check the documentation for your [provider](#providers) for more information.
 
 ### Transaction Context Propagation
 
-Coming Soon! [Issue available](https://github.com/open-feature/ruby-sdk/issues/150) to be worked on.
+Transaction context is a container for transaction-specific evaluation context (e.g. user id, user agent, IP).
+Transaction context can be set where specific data is available (e.g. an auth service or request handler) and by using the transaction context propagator it will automatically be applied to all flag evaluations within a transaction (e.g. a request or thread).
+
+The SDK ships with a `ThreadLocalTransactionContextPropagator` that stores context in `Thread.current`:
+
+```ruby
+# Set up the propagator
+OpenFeature::SDK.set_transaction_context_propagator(
+  OpenFeature::SDK::ThreadLocalTransactionContextPropagator.new
+)
+
+# Set transaction context (e.g. in a request middleware)
+OpenFeature::SDK.set_transaction_context(
+  OpenFeature::SDK::EvaluationContext.new(targeting_key: "user-123", "email" => "user@example.com")
+)
+
+# Transaction context is automatically merged during flag evaluation.
+# Merge precedence: invocation > client > transaction > API (global)
+client = OpenFeature::SDK.build_client
+client.fetch_boolean_value(flag_key: "my-flag", default_value: false)
+```
+
+You can implement a custom propagator by including the `TransactionContextPropagator` module:
 
-<!-- Transaction context is a container for transaction-specific evaluation context (e.g. user id, user agent, IP).
-Transaction context can be set where specific data is available (e.g. an auth service or request handler) and by using the transaction context propagator it will automatically be applied to all flag evaluations within a transaction (e.g. a request or thread). -->
+```ruby
+class MyRequestScopedPropagator
+  include OpenFeature::SDK::TransactionContextPropagator
 
-<!-- TODO: code example for global shutdown -->
+  def set_transaction_context(evaluation_context)
+    # Store context in your request-scoped storage
+    RequestStore[:openfeature_context] = evaluation_context
+  end
+
+  def get_transaction_context
+    RequestStore[:openfeature_context]
+  end
+end
+```
 
 ## Extending
 

data/lib/open_feature/sdk/api.rb

@@ -70,6 +70,15 @@ module OpenFeature
         configuration.logger = new_logger
       end
 
+      def set_transaction_context_propagator(propagator)
+        configuration.transaction_context_propagator = propagator
+      end
+
+      def set_transaction_context(evaluation_context)
+        propagator = configuration.transaction_context_propagator
+        propagator&.set_transaction_context(evaluation_context)
+      end
+
       def shutdown
         configuration.shutdown
       end

data/lib/open_feature/sdk/client.rb

@@ -49,11 +49,7 @@ module OpenFeature
       def track(tracking_event_name, evaluation_context: nil, tracking_event_details: nil)
         return unless @provider.respond_to?(:track)
 
-        built_context = EvaluationContextBuilder.new.call(
-          api_context: OpenFeature::SDK.evaluation_context,
-          client_context: self.evaluation_context,
-          invocation_context: evaluation_context
-        )
+        built_context = build_evaluation_context(evaluation_context)
 
         @provider.track(tracking_event_name, evaluation_context: built_context, tracking_event_details: tracking_event_details)
       end
@@ -86,11 +82,7 @@ module OpenFeature
           end
         end
 
-        built_context = EvaluationContextBuilder.new.call(
-          api_context: OpenFeature::SDK.evaluation_context,
-          client_context: self.evaluation_context,
-          invocation_context: evaluation_context
-        )
+        built_context = build_evaluation_context(evaluation_context)
 
         # Assemble ordered hooks: API → Client → Invocation → Provider (spec 4.4.2)
         provider_hooks = @provider.respond_to?(:hooks) ? Array(@provider.hooks) : []
@@ -148,6 +140,18 @@ module OpenFeature
         end
       end
 
+      def build_evaluation_context(invocation_context)
+        propagator = OpenFeature::SDK.configuration.transaction_context_propagator
+        transaction_context = propagator&.get_transaction_context
+
+        EvaluationContextBuilder.new.call(
+          api_context: OpenFeature::SDK.evaluation_context,
+          transaction_context: transaction_context,
+          client_context: evaluation_context,
+          invocation_context: invocation_context
+        )
+      end
+
       def validate_default_value_type(type, default_value)
         expected_classes = TYPE_CLASS_MAP[type]
         unless expected_classes.any? { |klass| default_value.is_a?(klass) }

data/lib/open_feature/sdk/configuration.rb

@@ -17,7 +17,7 @@ module OpenFeature
     class Configuration
       extend Forwardable
 
-      attr_accessor :evaluation_context, :hooks
+      attr_accessor :evaluation_context, :hooks, :transaction_context_propagator
       attr_reader :logger
 
       def initialize

data/lib/open_feature/sdk/evaluation_context_builder.rb

@@ -4,8 +4,8 @@ module OpenFeature
   module SDK
     # Used to combine evaluation contexts from different sources
     class EvaluationContextBuilder
-      def call(api_context:, client_context:, invocation_context:)
-        available_contexts = [api_context, client_context, invocation_context].compact
+      def call(api_context:, client_context:, invocation_context:, transaction_context: nil)
+        available_contexts = [api_context, transaction_context, client_context, invocation_context].compact
 
         return nil if available_contexts.empty?
 

data/lib/open_feature/sdk/hooks/logging_hook.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module OpenFeature
+  module SDK
+    module Hooks
+      class LoggingHook
+        include Hook
+
+        def initialize(logger: nil, include_evaluation_context: false)
+          @logger = logger
+          @include_evaluation_context = include_evaluation_context
+        end
+
+        def before(hook_context:, hints:)
+          logger&.debug { build_before_message(hook_context) }
+          nil
+        end
+
+        def after(hook_context:, evaluation_details:, hints:)
+          logger&.debug { build_after_message(hook_context, evaluation_details) }
+          nil
+        end
+
+        def error(hook_context:, exception:, hints:)
+          logger&.error { build_error_message(hook_context, exception) }
+          nil
+        end
+
+        private
+
+        def logger
+          @logger || OpenFeature::SDK.configuration.logger
+        end
+
+        def build_before_message(hook_context)
+          parts = base_parts("before", hook_context)
+          parts << "evaluation_context=#{format_context(hook_context.evaluation_context)}" if @include_evaluation_context
+          parts.join(" ")
+        end
+
+        def build_after_message(hook_context, evaluation_details)
+          parts = base_parts("after", hook_context)
+          parts << "reason=#{sanitize(evaluation_details.reason)}" if evaluation_details.reason
+          parts << "variant=#{sanitize(evaluation_details.variant)}" if evaluation_details.variant
+          parts << "value=#{sanitize(evaluation_details.value)}"
+          parts << "evaluation_context=#{format_context(hook_context.evaluation_context)}" if @include_evaluation_context
+          parts.join(" ")
+        end
+
+        def build_error_message(hook_context, exception)
+          parts = base_parts("error", hook_context)
+          error_code = exception.respond_to?(:error_code) ? exception.error_code : Provider::ErrorCode::GENERAL
+          parts << "error_code=#{sanitize(error_code)}"
+          parts << "error_message=#{sanitize(exception.message)}"
+          parts << "evaluation_context=#{format_context(hook_context.evaluation_context)}" if @include_evaluation_context
+          parts.join(" ")
+        end
+
+        def base_parts(stage, hook_context)
+          domain = hook_context.client_metadata&.domain
+          provider_name = hook_context.provider_metadata&.name
+          [
+            "stage=#{stage}",
+            "domain=#{sanitize(domain)}",
+            "provider_name=#{sanitize(provider_name)}",
+            "flag_key=#{sanitize(hook_context.flag_key)}",
+            "default_value=#{sanitize(hook_context.default_value)}"
+          ]
+        end
+
+        def format_context(evaluation_context)
+          return "" unless evaluation_context
+          fields = evaluation_context.fields.dup
+          fields["targeting_key"] = evaluation_context.targeting_key if evaluation_context.targeting_key
+          fields.map { |k, v| "#{sanitize(k)}=#{sanitize(v)}" }.join(", ")
+        end
+
+        def sanitize(value)
+          value.to_s.gsub(/[\n\r]/, " ")
+        end
+      end
+    end
+  end
+end

data/lib/open_feature/sdk/hooks.rb

@@ -4,3 +4,4 @@ require_relative "hooks/hints"
 require_relative "hooks/hook"
 require_relative "hooks/hook_context"
 require_relative "hooks/hook_executor"
+require_relative "hooks/logging_hook"

data/lib/open_feature/sdk/thread_local_transaction_context_propagator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module OpenFeature
+  module SDK
+    class ThreadLocalTransactionContextPropagator
+      include TransactionContextPropagator
+
+      THREAD_KEY = :openfeature_transaction_context
+
+      def set_transaction_context(evaluation_context)
+        Thread.current[THREAD_KEY] = evaluation_context
+      end
+
+      def get_transaction_context
+        Thread.current[THREAD_KEY]
+      end
+    end
+  end
+end

data/lib/open_feature/sdk/transaction_context_propagator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OpenFeature
+  module SDK
+    module TransactionContextPropagator
+      def set_transaction_context(evaluation_context)
+        raise NotImplementedError
+      end
+
+      def get_transaction_context
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/open_feature/sdk/version.rb

@@ -2,6 +2,6 @@
 
 module OpenFeature
   module SDK
-    VERSION = "0.6.1"
+    VERSION = "0.6.2"
   end
 end

data/lib/open_feature/sdk.rb

@@ -2,6 +2,8 @@
 
 require_relative "sdk/version"
 require_relative "sdk/api"
+require_relative "sdk/transaction_context_propagator"
+require_relative "sdk/thread_local_transaction_context_propagator"
 
 module OpenFeature
   # TODO: Add documentation

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openfeature-sdk
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.2
 platform: ruby
 authors:
 - OpenFeature Authors
@@ -173,6 +173,7 @@ files:
 - lib/open_feature/sdk/hooks/hook.rb
 - lib/open_feature/sdk/hooks/hook_context.rb
 - lib/open_feature/sdk/hooks/hook_executor.rb
+- lib/open_feature/sdk/hooks/logging_hook.rb
 - lib/open_feature/sdk/provider.rb
 - lib/open_feature/sdk/provider/error_code.rb
 - lib/open_feature/sdk/provider/event_emitter.rb
@@ -185,7 +186,9 @@ files:
 - lib/open_feature/sdk/provider_initialization_error.rb
 - lib/open_feature/sdk/provider_state.rb
 - lib/open_feature/sdk/provider_state_registry.rb
+- lib/open_feature/sdk/thread_local_transaction_context_propagator.rb
 - lib/open_feature/sdk/tracking_event_details.rb
+- lib/open_feature/sdk/transaction_context_propagator.rb
 - lib/open_feature/sdk/version.rb
 - release-please-config.json
 - renovate.json