opera 0.3.3 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66df118360280b866b0d104645f8f837d6046536167999f14fb4fdd97bb082a8
-  data.tar.gz: cfe3b8d4d05f8e28900bf0339a70a5bb648ad26ee92c2c449eccb0ecee492887
+  metadata.gz: bc70b6a1f69200a0b37229ed04034c3bcc12c66c94dc9a5d0c066ceaf9971cdb
+  data.tar.gz: 7b369d14c001a62b07d91c43efd52e23ddb65749aae9a1a19e3cf49105e190a7
 SHA512:
-  metadata.gz: b5bae55e20de7a7759b600050874bba4b14612635bb0616941317898ba0c537828131e24a145626b08c6d8d783ed38059dae8c55d59895dd705174aa385bfaae
-  data.tar.gz: 2eb1c3540d2a855a9e71046499ef38f7fc9477d4acc76f92a7f0f3148daadb95cb8d4166a1e7d18a151f9a0107e42a4db50e965b232ef3228f0c61fb2dfa1962
+  metadata.gz: 8ae2fc0df4e8969215716157838de9ce26b4bfc66007c2c62b57e7a2ffd0b918be8974b7513f28d81c14593b41ecff1d573e4fca2ea4502761b9306abc273b4b
+  data.tar.gz: 6abf3cb52cd156ae7e458772842e62b1dbca0e2f93dde5af040e68c8c426c75088ae2ef2f11a164372a6d7535e4a0f6516643a78955a67f5040bf53f81ed6485

data/.gitignore

@@ -7,5 +7,8 @@
 /spec/reports/
 /tmp/
 
+#macos
+.DS_Store
+
 # rspec failure tracking
 .rspec_status

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Opera Changelog
 
+### 0.3.5 - February 24, 2025
+
+- Simplify instrumentation configuration
+- Allow instrumentation logic to be defined at the source
+
+### 0.3.4 - February 19, 2025
+
+- Add support for `benchmark` label
+- Add support for instrumentation
+
 ### 0.3.3 - January 15, 2025
 
 - Fix issue with handling exceptions in nested operations

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    opera (0.3.3)
+    opera (0.3.5)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -37,7 +37,10 @@ Simply initialise the configuration and chose what method you want to use to rep
 Opera::Operation::Config.configure do |config|
   config.transaction_class = ActiveRecord::Base
   config.transaction_method = :transaction
-  config.transaction_options = { requires_new: true }
+  config.transaction_options = { requires_new: true, level: :step } # or level: :operation - default
+  config.instrumentation_class = Datadog::Tracing
+  config.instrumentation_method = :trace
+  config.instrumentation_options = { service: :operation }
   config.mode = :development # Can be set to production too
   config.reporter = defined?(Rollbar) ? Rollbar : Rails.logger
 end
@@ -52,7 +55,6 @@ Once opera gem is in your project you can start to build Operations
 
 ```ruby
 class A < Opera::Operation::Base
-
   configure do |config|
     config.transaction_class = Profile
     config.reporter = Rails.logger
@@ -96,18 +98,44 @@ Start developing your business logic, services and interactions as Opera::Operat
 When using Opera::Operation inside an engine add the following
 configuration to your spec_helper.rb or rails_helper.rb:
 
-```
+```ruby
 Opera::Operation::Config.configure do |config|
   config.transaction_class = ActiveRecord::Base
 end
 ```
 
 Without this extra configuration you will receive:
-```
+```ruby
 NoMethodError:
   undefined method `transaction' for nil:NilClass
 ```
 
+### Instrumentation
+
+When you want to easily instrument your operations you can add this to the opera config:
+
+```ruby
+Rails.application.configure do
+  config.x.instrumentation_class = Datadog::Tracing
+  config.x.instrumentation_method = :trace
+  config.x.instrumentation_options = { service: :opera }
+end
+```
+
+You can also instrument individual operations by adding this to the operation config:
+
+```ruby
+class A < Opera::Operation::Base
+  configure do |config|
+    config.instrumentation_class = Datadog::Tracing
+    config.instrumentation_method = :trace
+    config.instrumentation_options = { service: :opera, level: :step }
+  end
+
+  # steps
+end
+```
+
 ### Debugging
 
 When you want to easily debug exceptions you can add this
@@ -674,10 +702,12 @@ class Profile::Create < Opera::Operation::Base
 
   validate :profile_schema
 
-  step :create
-  step :update
+  benchmark :fast_section do
+    step :create
+    step :update
+  end
 
-  benchmark do
+  benchmark :slow_section do
     step :send_email
     step :output
   end
@@ -717,7 +747,7 @@ Profile::Create.call(params: {
 }, dependencies: {
   current_account: Account.find(1)
 })
-#<Opera::Operation::Result:0x007ff414a01238 @errors={}, @exceptions={}, @information={:real=>1.800013706088066e-05, :total=>0.0}, @executions=[:profile_schema, :create, :update, :send_email, :output], @output={:model=>#<Profile id: 30, user_id: nil, linkedin_uid: nil, picture: nil, headline: nil, summary: nil, first_name: "foo", last_name: "bar", created_at: "2020-08-19 10:46:00", updated_at: "2020-08-18 10:46:00", agree_to_terms_and_conditions: nil, registration_status: "", account_id: 1, start_date: nil, supervisor_id: nil, picture_processing: false, statistics: {}, data: {}, notification_timestamps: {}, suggestions: {}, notification_settings: {}, contact_information: []>}>
+#<Opera::Operation::Result:0x007ff414a01238 @errors={}, @exceptions={}, @information={fast_section: {:real=>0.300013706088066e-05, :total=>0.0}, slow_section: {:real=>1.800013706088066e-05, :total=>0.0}}, @executions=[:profile_schema, :create, :update, :send_email, :output], @output={:model=>#<Profile id: 30, user_id: nil, linkedin_uid: nil, picture: nil, headline: nil, summary: nil, first_name: "foo", last_name: "bar", created_at: "2020-08-19 10:46:00", updated_at: "2020-08-18 10:46:00", agree_to_terms_and_conditions: nil, registration_status: "", account_id: 1, start_date: nil, supervisor_id: nil, picture_processing: false, statistics: {}, data: {}, notification_timestamps: {}, suggestions: {}, notification_settings: {}, contact_information: []>}>
 ```
 
 ### Success

data/lib/opera/operation/base.rb

@@ -33,7 +33,9 @@ module Opera
         def call(args = {})
           operation = new(params: args.fetch(:params, {}), dependencies: args.fetch(:dependencies, {}))
           executor = Executor.new(operation)
-          executor.evaluate_instructions(instructions)
+          Instrumentation.new(operation).instrument(name: self.name, level: :operation) do
+            executor.evaluate_instructions(instructions)
+          end
           executor.result
         end
 

data/lib/opera/operation/builder.rb

@@ -35,6 +35,7 @@ module Opera
             instructions << if !blk.nil?
                               {
                                 kind: instruction,
+                                label: method,
                                 instructions: InnerBuilder.new(&blk).instructions
                               }
                             else

data/lib/opera/operation/config.rb

@@ -6,12 +6,16 @@ module Opera
       DEVELOPMENT_MODE = :development
       PRODUCTION_MODE = :production
 
-      attr_accessor :transaction_class, :transaction_method, :transaction_options, :reporter, :mode
+      attr_accessor :transaction_class, :transaction_method, :transaction_options, :instrumentation_class,
+                    :mode, :reporter
 
       def initialize
         @transaction_class = self.class.transaction_class
         @transaction_method = self.class.transaction_method || :transaction
         @transaction_options = self.class.transaction_options
+
+        @instrumentation_class = self.class.instrumentation_class
+
         @mode = self.class.mode || DEVELOPMENT_MODE
         @reporter = custom_reporter || self.class.reporter
 
@@ -35,7 +39,8 @@ module Opera
       end
 
       class << self
-        attr_accessor :transaction_class, :transaction_method, :transaction_options, :reporter, :mode
+        attr_accessor :transaction_class, :transaction_method, :transaction_options, :instrumentation_class,
+                      :mode, :reporter
 
         def configure
           yield self

data/lib/opera/operation/instructions/executors/benchmark.rb

@@ -7,10 +7,17 @@ module Opera
         class Benchmark < Executor
           def call(instruction)
             benchmark = ::Benchmark.measure do
+              instruction[:kind] = :step
               super
             end
 
-            result.add_information(real: benchmark.real, total: benchmark.total)
+            result.add_information(benchmark_key(instruction) => { real: benchmark.real, total: benchmark.total })
+          end
+
+          private
+
+          def benchmark_key(instruction)
+            instruction[:method] || instruction[:label] || instruction[:instructions].map { |e| e[:method] }.join('-').to_sym
           end
         end
       end

data/lib/opera/operation/instructions/executors/step.rb

@@ -8,8 +8,10 @@ module Opera
           def call(instruction)
             method = instruction[:method]
 
-            operation.result.add_execution(method) unless production_mode?
-            operation.send(method)
+            Instrumentation.new(operation).instrument(name: "##{method}", level: :step) do
+              operation.result.add_execution(method) unless production_mode?
+              operation.send(method)
+            end
           rescue StandardError => exception
             reporter&.error(exception)
             operation.result.add_exception(method, "#{exception.message}, for #{operation.inspect}", classname: operation.class.name)

data/lib/opera/operation/instrumentation.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Opera
+  module Operation
+    class Instrumentation
+      class Base
+        def self.instrument(operation, name:, level: :operation)
+          raise NotImplementedError, "#{self.class} must implement #instrument"
+        end
+      end
+
+      attr_reader :operation
+
+      def initialize(operation)
+        @operation = operation
+      end
+
+      def instrument(name:, level: :operation)
+        return yield if !instrumentation_enabled?
+        return yield if !instrumentation_compatible?
+
+        instrumentation_class.instrument(operation, name: name, level: level) do
+          yield
+        end
+      end
+
+      private
+
+      def config
+        operation.config
+      end
+
+      def instrumentation_class
+        config.instrumentation_class
+      end
+
+      def instrumentation_enabled?
+        !!config.instrumentation_class
+      end
+
+      def instrumentation_compatible?
+        config.instrumentation_class.ancestors.include?(Opera::Operation::Instrumentation::Base)
+      end
+    end
+  end
+end

data/lib/opera/operation.rb

@@ -4,6 +4,7 @@ require 'opera/operation/attributes_dsl'
 require 'opera/operation/builder'
 require 'opera/operation/base'
 require 'opera/operation/executor'
+require 'opera/operation/instrumentation'
 require 'opera/operation/result'
 require 'opera/operation/config'
 require 'opera/operation/instructions/executors/success'

data/lib/opera/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Opera
-  VERSION = '0.3.3'
+  VERSION = '0.3.5'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opera
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.5
 platform: ruby
 authors:
 - ProFinda Development Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-01-15 00:00:00.000000000 Z
+date: 2025-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-validation
@@ -91,6 +91,7 @@ files:
 - lib/opera/operation/instructions/executors/success.rb
 - lib/opera/operation/instructions/executors/transaction.rb
 - lib/opera/operation/instructions/executors/validate.rb
+- lib/opera/operation/instrumentation.rb
 - lib/opera/operation/result.rb
 - lib/opera/version.rb
 - opera.gemspec