yes-core 2.4.1 → 2.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32cf1150f338458f687fbda0d60e3a30625636b4664d056d5ff4ebf939f4731b
-  data.tar.gz: 6984f21a84c0053ba4c1c6e38560f10c07d024ec0305734d2146a487ec8ab2a2
+  metadata.gz: 70e0c755ba6b965b16e2331495e59061de1ed745c80bcd4cb4d6da4a5e8cdd8b
+  data.tar.gz: fe6b3f3e8600ecb1c0558850eef7302d1d938296c391c7539c1caa5de69135d8
 SHA512:
-  metadata.gz: 3d9909b27209da6ddc3bcf943d6c255cec3fcec1951eed981c9f84dcd80314dc6e4f704b3bdaad0fe464b81d5adf31bf66a9828178cf806bdc75542c921e398a
-  data.tar.gz: 966d09cc084b81bcef2c4863ebe3419dab9783f360297eecd532652a70deb8a45b7c89f7b167acf176dbf716f832ed5ce30c173ac202b5456f5ac23d1ac33146
+  metadata.gz: 2c0ef42cdb28eb261828d7eb189e03b22fdb154294145aa7966f63fe9ae3f2dcdacef5c6890037ef481420a7460ad02c1f234fcab4c8c1d79a6f1c46529448ee
+  data.tar.gz: fa787ad495b279695b2d1100fcf24237630fef1e426e617e0979231442751e8943893d14eaa3a0902d42580bfddd7fdad2b686f0d59e48f353642e9c10531b20

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [2.4.3] - 2026-09-15
+- See root CHANGELOG.md for details.
+
+## [2.4.2] - 2026-09-15
+- See root CHANGELOG.md for details.
+
 ## [2.4.1] - 2026-09-07
 - See root CHANGELOG.md for details.
 

data/lib/yes/core/command_handling/command_executor.rb

@@ -121,6 +121,8 @@ module Yes
                  Yes::Core::Command::Invalid => e
             command_response_class(cmd).new(cmd: cmd, error: e, batch_id: cmd.batch_id)
           end
+        ensure
+          Yes::Core::OpenTelemetry::OtlSpan.record_retries(retries)
         end
 
         private

data/lib/yes/core/command_handling/command_group_executor.rb

@@ -69,6 +69,8 @@ module Yes
             clear_pending_update_state if aggregate.class.read_model_enabled?
             Yes::Core::Commands::CommandGroupResponse.new(cmd:, error: e)
           end
+        ensure
+          Yes::Core::OpenTelemetry::OtlSpan.record_retries(retries)
         end
 
         private

data/lib/yes/core/command_handling/command_group_handler.rb

@@ -35,6 +35,7 @@ module Yes
         def call(group_name, payload, guards: true, metadata: nil)
           prepared = prepare_payload(payload, metadata)
           cmd = command_utilities.build_group_command(group_name, prepared)
+          otl_record_command(cmd)
           guard_evaluator_class = command_utilities.fetch_guard_evaluator_class_for_group(group_name)
 
           ReadModelRecoveryService.check_and_recover_with_retries(read_model, aggregate:) if aggregate.class.read_model_enabled?
@@ -49,6 +50,17 @@ module Yes
 
         attr_reader :aggregate, :command_utilities, :read_model
 
+        # Records which command group the span ran; see CommandHandler#otl_record_command.
+        #
+        # @param cmd [Object] the built command group
+        # @return [void]
+        def otl_record_command(cmd)
+          name = cmd.class.name
+          return if name.nil?
+
+          self.class.current_span&.add_attributes({ CommandHandler::COMMAND_ATTRIBUTE => name })
+        end
+
         # Prepares the payload before constructing the group command.
         # Mirrors the metadata-injection logic in {CommandHandler#prepare_payload}.
         #

data/lib/yes/core/command_handling/command_handler.rb

@@ -11,6 +11,10 @@ module Yes
       #   response = handler.call(:approve_documents, { document_ids: '123', another: 'value' })
       #
       class CommandHandler
+        # Span attribute naming the command that ran. The span keeps a fixed name so its
+        # latency histogram stays one series per service; this is how the command is identified.
+        COMMAND_ATTRIBUTE = 'command'
+
         include Yes::Core::OpenTelemetry::Trackable
 
         # Initializes a new CommandHandler
@@ -32,6 +36,7 @@ module Yes
         def call(command_name, payload, guards: true, metadata: nil)
           prepared_payload = prepare_payload(command_name, payload, metadata)
           cmd = command_utilities.build_command(command_name, prepared_payload)
+          otl_record_command(cmd)
 
           guard_evaluator_class = command_utilities.fetch_guard_evaluator_class(command_name)
 
@@ -51,6 +56,18 @@ module Yes
 
         attr_reader :aggregate, :command_utilities, :read_model
 
+        # Records which command the span ran. The span itself keeps a fixed name so its latency
+        # histogram stays a single series per service; the command goes on an attribute instead.
+        #
+        # @param cmd [Object] the built command
+        # @return [void]
+        def otl_record_command(cmd)
+          name = cmd.class.name
+          return if name.nil?
+
+          self.class.current_span&.add_attributes({ COMMAND_ATTRIBUTE => name })
+        end
+
         # Prepares the command payload
         #
         # @param command_name [Symbol] The command name

data/lib/yes/core/command_handling/event_publisher.rb

@@ -59,7 +59,10 @@ module Yes
 
         otl_trackable(
           :call,
-          Yes::Core::OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Publish Event', span_kind: :producer, track_sql: true)
+          Yes::Core::OpenTelemetry::OtlSpan::OtlData.new(
+            span_name: 'Publish Event', span_kind: :producer, track_sql: true,
+            tolerated_errors: Yes::Core::OpenTelemetry::OtlSpan::REVISION_CONFLICT
+          )
         )
 
         private

data/lib/yes/core/commands/stateless/handler.rb

@@ -122,7 +122,10 @@ module Yes
               middlewares: Middlewares.for_write
             ).tap { otl_record_response(_1) }
           end
-          otl_trackable :publish_event, OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Publish Event', span_kind: :producer)
+          otl_trackable :publish_event, OpenTelemetry::OtlSpan::OtlData.new(
+            span_name: 'Publish Event', span_kind: :producer,
+            tolerated_errors: OpenTelemetry::OtlSpan::REVISION_CONFLICT
+          )
 
           private
 
@@ -208,7 +211,6 @@ module Yes
             PgEventstore::WrongExpectedRevisionError.new(
               revision:, expected_revision:, stream:, verdict: :unmatched_stream_revision
             ).tap do |error|
-              self.class.current_span&.status = ::OpenTelemetry::Trace::Status.error('Wrong expected revision')
               self.class.current_span&.add_attributes(
                 {
                   current_revision: revision,

data/lib/yes/core/open_telemetry/otl_span.rb

@@ -9,15 +9,29 @@ module Yes
       #   span = OtlSpan.new(otl_data: OtlData.new(span_name: 'MySpan'), otl_tracer: tracer)
       #   span.otl_span(arg1, arg2) { do_work }
       class OtlSpan
+        # Span attribute that names the tolerated error a span ended with (see {OtlData#tolerated_errors}).
+        OUTCOME_ATTRIBUTE = 'outcome'
+
+        # Span attribute with the number of retries a command needed before it settled.
+        RETRIES_ATTRIBUTE = 'retries'
+
+        # A revision conflict is an optimistic-concurrency retry signal, not a failure: the
+        # command is re-run and almost always succeeds. Publishing spans tolerate it so the
+        # span status stays clean and the conflict is countable on its own.
+        REVISION_CONFLICT = { PgEventstore::WrongExpectedRevisionError => 'revision_conflict' }.freeze
+
         # Configuration struct for OpenTelemetry span data
-        OtlData = Struct.new(:span_name, :span_kind, :span_attributes, :links_extractor, :track_sql) do
+        OtlData = Struct.new(:span_name, :span_kind, :span_attributes, :links_extractor, :track_sql,
+                             :tolerated_errors) do
           # @param span_name [String, nil] name of the span
           # @param span_kind [Symbol] kind of span (:internal, :client, :server, :producer, :consumer)
           # @param span_attributes [Hash] additional span attributes
           # @param links_extractor [Proc] extracts OTL context links from arguments
           # @param track_sql [Boolean] whether to track SQL queries within the span
+          # @param tolerated_errors [Hash{Class => String}] errors that are re-raised but do not mark the
+          #   span as failed; the span gets the mapped value as its +outcome+ attribute instead
           def initialize(span_name: nil, span_kind: :internal, span_attributes: {}, links_extractor: proc { [] },
-                         track_sql: false)
+                         track_sql: false, tolerated_errors: {})
             super
           end
         end
@@ -28,6 +42,17 @@ module Yes
         # @return [Object] OpenTelemetry tracer instance
         attr_reader :otl_tracer
 
+        # Stamps the number of retries a command needed on the span it is running in, so
+        # contention shows up per command and not only per publish attempt.
+        #
+        # @param retries [Integer] retries performed before the command settled
+        # @return [void]
+        def self.record_retries(retries)
+          return if retries.zero? || Yes::Core.configuration.otl_tracer.nil?
+
+          ::OpenTelemetry::Trace.current_span.set_attribute(RETRIES_ATTRIBUTE, retries)
+        end
+
         # @param otl_data [OtlData] span configuration
         # @param otl_tracer [Object] OpenTelemetry tracer instance
         def initialize(otl_data:, otl_tracer:)
@@ -37,50 +62,118 @@ module Yes
 
         # Creates a span and executes the given block within it.
         #
+        # A tolerated error (see {OtlData#tolerated_errors}) is recorded on the span as an exception
+        # event and as the +outcome+ attribute, but the span keeps a non-error status. The error is
+        # re-raised once the span has ended, so callers see exactly the same exception as before.
+        #
         # @param args [Array] positional arguments passed to the links extractor
         # @param kwargs [Hash] keyword arguments passed to the links extractor
         # @yield the block to execute within the span
         # @return [Object] the return value of the block
-        def otl_span(*args, **kwargs, &block)
-          links = otl_links(args, kwargs)
-
-          parent_span = ::OpenTelemetry::Trace.current_span.context.valid? ? ::OpenTelemetry::Trace.current_span : nil
-          root_track_sql = parent_span&.try(:attributes)&.[]('root_track_sql') ||
-                           parent_span&.try(:attributes)&.[]('track_sql')
+        def otl_span(*args, **kwargs, &)
+          parent_span = current_parent_span
+          root_track_sql = root_track_sql?(parent_span)
+          tolerated_error = nil
 
-          otl_tracer.in_span(
+          result = otl_tracer.in_span(
             otl_data.span_name || 'UnknownName',
-            links:,
+            links: otl_links(args, kwargs),
             kind: otl_data.span_kind,
-            attributes: {
-              'track_sql' => otl_data.track_sql,
-              'root_track_sql' => root_track_sql || false
-            }.merge(otl_data.span_attributes)
-          ) do
-            next unless block_given?
-            next yield if !root_track_sql && !otl_data.track_sql
-            next yield if parent_span.present? && root_track_sql
-
-            callback = lambda do |sql_event|
-              next if %w[SCHEMA TRANSACTION].include?(sql_event.payload[:name])
-
-              otl_tracer.in_span("SQL #{sql_event.payload[:name]}") do |span|
-                span.set_attribute('db.system', 'postgresql')
-                span.set_attribute('db.statement', sql_event.payload[:sql])
-                span.set_attribute('db.binds', sql_event.payload[:binds].map do |attr|
-                  next { name: attr.name, value: attr.value } if attr.respond_to?(:name) && attr.respond_to?(:value)
-
-                  { name: attr.class.to_s, value: attr }
-                end.to_json)
-                span.set_attribute('db.event_name', sql_event.payload[:name])
-              end
-            end
-            ActiveSupport::Notifications.subscribed(callback, 'sql.active_record', &block)
+            attributes: span_attributes(root_track_sql)
+          ) do |span|
+            run_block(parent_span, root_track_sql, &)
+          rescue StandardError => e
+            tolerated_error = tolerate(span, e)
+            nil
           end
+
+          raise tolerated_error if tolerated_error
+
+          result
         end
 
         private
 
+        # @return [::OpenTelemetry::Trace::Span, nil] the span this one is created under, if any
+        def current_parent_span
+          span = ::OpenTelemetry::Trace.current_span
+          span.context.valid? ? span : nil
+        end
+
+        # @param parent_span [::OpenTelemetry::Trace::Span, nil] the enclosing span, if any
+        # @return [Boolean, nil] whether an enclosing span already tracks SQL
+        def root_track_sql?(parent_span)
+          parent_span&.try(:attributes)&.[]('root_track_sql') || parent_span&.try(:attributes)&.[]('track_sql')
+        end
+
+        # @param root_track_sql [Boolean, nil] whether an enclosing span already tracks SQL
+        # @return [Hash] the attributes the span starts with
+        def span_attributes(root_track_sql)
+          {
+            'track_sql' => otl_data.track_sql,
+            'root_track_sql' => root_track_sql || false
+          }.merge(otl_data.span_attributes)
+        end
+
+        # Runs the traced block, wrapping it in SQL tracking when the span asks for it.
+        #
+        # @param parent_span [OpenTelemetry::Trace::Span, nil] the enclosing span, if any
+        # @param root_track_sql [Boolean, nil] whether an enclosing span already tracks SQL
+        # @yield the block to execute
+        # @return [Object, nil] the return value of the block
+        def run_block(parent_span, root_track_sql, &)
+          return unless block_given?
+          return yield if !root_track_sql && !otl_data.track_sql
+          return yield if parent_span.present? && root_track_sql
+
+          ActiveSupport::Notifications.subscribed(sql_span_callback, 'sql.active_record', &)
+        end
+
+        # @return [Proc] records one child span per SQL statement executed inside the traced block
+        def sql_span_callback
+          lambda do |sql_event|
+            next if %w[SCHEMA TRANSACTION].include?(sql_event.payload[:name])
+
+            record_sql_span(sql_event.payload)
+          end
+        end
+
+        # @param payload [Hash] the +sql.active_record+ notification payload
+        # @return [void]
+        def record_sql_span(payload)
+          otl_tracer.in_span("SQL #{payload[:name]}") do |span|
+            span.set_attribute('db.system', 'postgresql')
+            span.set_attribute('db.statement', payload[:sql])
+            span.set_attribute('db.binds', sql_binds(payload[:binds]))
+            span.set_attribute('db.event_name', payload[:name])
+          end
+        end
+
+        # @param binds [Array] the statement's bind parameters
+        # @return [String] the binds as JSON, one +name+/+value+ pair each
+        def sql_binds(binds)
+          binds.map do |attr|
+            next { name: attr.name, value: attr.value } if attr.respond_to?(:name) && attr.respond_to?(:value)
+
+            { name: attr.class.to_s, value: attr }
+          end.to_json
+        end
+
+        # Records a tolerated error on the span without failing it.
+        #
+        # @param span [OpenTelemetry::Trace::Span] the span the error was raised in
+        # @param error [StandardError] the error raised by the traced block
+        # @return [StandardError] the error, to be re-raised once the span has ended
+        # @raise [StandardError] the error itself when it is not tolerated
+        def tolerate(span, error)
+          outcome = otl_data.tolerated_errors.find { |klass, _outcome| error.is_a?(klass) }&.last
+          raise error unless outcome
+
+          span.record_exception(error)
+          span.set_attribute(OUTCOME_ATTRIBUTE, outcome)
+          error
+        end
+
         # Extracts OpenTelemetry links from arguments using the configured links_extractor.
         #
         # @param args [Array] positional arguments

data/lib/yes/core/version.rb

@@ -2,6 +2,6 @@
 
 module Yes
   module Core
-    VERSION = '2.4.1'
+    VERSION = '2.4.3'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yes-core
 version: !ruby/object:Gem::Version
-  version: 2.4.1
+  version: 2.4.3
 platform: ruby
 authors:
 - Nico Ritsche