brut 0.10.0 → 0.11.0

data/lib/brut/instrumentation/methods.rb

@@ -0,0 +1,153 @@
+require "set"
+require "opentelemetry-sdk"
+
+# Allows instrumentation of methods via a class method. While Pages, Handlers, and Components are generally
+# instrumented, this module can be used for your back-end classes (or private methods of pages, handlers, or
+# component).
+#
+# @example Instrument specific methods
+#   class Widget
+#     include Brut::Instrumentation::Methods
+#
+#     def save
+#       # ...
+#     end
+#
+#     def search
+#       # ...
+#     end
+#
+#     instrument :save # search is not instrumented
+#   end
+#
+# @example Instrument all methods
+#   class Widget
+#     include Brut::Instrumentation::Methods
+#
+#     instrument_all!
+#
+#     def save
+#       # ...
+#     end
+#
+#     def search
+#       # ...
+#     end
+#
+#   private
+#
+#     def delete_orphans
+#     end
+#   end
+module Brut::Instrumentation::Methods
+
+  # @!visibility private
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  module ClassMethods
+
+    def __module_for_instrumented_methods
+      @__module_for_instrumented_methods ||= begin
+        mod = Module.new
+        prepend mod
+        mod
+      end
+    end
+
+    # Instrument methods that have already been defined.
+    #
+    # @param method_names [Array<Symbol>] the method names to instrument.  They must
+    #                     exist and they must not already have been instrumented.
+    # @raise [ArgumentError] if any method does not exist or has already been instrumented
+    def instrument(*method_names)
+
+      method_names.each do |method_name|
+        if __module_for_instrumented_methods.method_defined?(method_name)
+          raise ArgumentError, "Method #{method_name} is already instrumented in #{self}"
+        end
+
+        method_defined = method_defined?(method_name) ||
+                         private_method_defined?(method_name) ||
+                         protected_method_defined?(method_name)
+
+        if !method_defined
+          raise ArgumentError, "Method #{method_name} is not defined in #{self.name}"
+        end
+
+        visibility = if private_method_defined?(method_name)
+                       :private
+                     elsif protected_method_defined?(method_name)
+                       :protected
+                     else
+                       :public
+                     end
+
+        __module_for_instrumented_methods.module_eval do
+          define_method(method_name) do |*args, **kwargs, &blk|
+            span_name = "#{self.class.name}##{method_name}"
+            span_attrs = {
+              "brut.class" => self.class.name,
+              "brut.method"  => method_name.to_s,
+            }
+
+            Brut.container.instrumentation.span(span_name, attributes: span_attrs) do |span|
+              super(*args, **kwargs, &blk)
+            end
+          end
+
+          # match original visibility
+          send(visibility, method_name)
+        end
+      end
+      nil
+    end
+
+    # Instrument all methods, public, protected, and private, other than `initialize`.
+    # This will also instrument any methods defined in this class after it's called, meaning
+    # you can it at the top of the class.  Do note that this will not instrument any
+    # methods brought in via modules.
+    def instrument_all
+      @__instrument_all = true
+      method_names = instance_methods(false) + private_instance_methods(false) - [ :initialize ]
+
+      instrument(*method_names)
+
+      nil
+    end
+
+    # Instrument all public and protected methods, other than `initialize`.
+    # This will also instrument any public or protected methods defined in this class after it's called,
+    # meaning you can it at the top of the class.  Do note that this will not instrument any
+    # methods brought in via modules.
+    def instrument_public
+      @__instrument_public = true
+      method_names = instance_methods(false) - [ :initialize ]
+
+      instrument(*method_names)
+
+      nil
+    end
+
+    def method_added(meth)
+      if !@__instrument_all && !@__instrument_public
+        return
+      end
+      if @__adding__
+        return
+      end
+      if meth == :initialize
+        return
+      end
+      if !@__instrument_all && private_instance_methods(false).include?(meth)
+        return
+      end
+
+      @__adding__ = true
+      instrument(meth)
+      @__adding__ = false
+    end
+  end
+end
+

data/lib/brut/instrumentation/open_telemetry.rb

@@ -25,6 +25,7 @@ class Brut::Instrumentation::OpenTelemetry
         result = block.(wrapped_span)
       rescue => ex
         span.record_exception(ex)
+        span.status = OpenTelemetry::Trace::Status.error("Unhandled exception: #{ex.class}")
         raise
       end
     end

data/lib/brut/instrumentation.rb

@@ -4,5 +4,6 @@
 module Brut::Instrumentation
   autoload(:OpenTelemetry,"brut/instrumentation/open_telemetry")
   autoload(:LoggerSpanExporter,"brut/instrumentation/logger_span_exporter")
+  autoload(:Methods,"brut/instrumentation/methods")
 end
 

data/lib/brut/version.rb

@@ -1,4 +1,4 @@
 module Brut
   # @!visibility private
-  VERSION = "0.10.0"
+  VERSION = "0.11.0"
 end

data/mkbrut/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mkbrut (0.10.0)
+    mkbrut (0.11.0)
 
 GEM
   remote: https://rubygems.org/

data/mkbrut/bin/publish

@@ -67,7 +67,7 @@ setup_docker_buildx() {
 detect_gem_version() {
 
   GEM_VERSION=$( rake -T | grep "rake install " | sed 's/^.*mkbrut-//g' | sed 's/\.gem.*$//g')
-  if [[ "$GEM_VERSION" =~ ^[0-9]+\.[0-9]\.[0-9]+$ ]]; then
+  if [[ "$GEM_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
     log "Releasing version ${GEM_VERSION}"
   else
     log "Version '${GEM_VERSION}' does not look like a version: X.Y.Z"

data/mkbrut/lib/mkbrut/version.rb

@@ -1,3 +1,3 @@
 module MKBrut
-  VERSION = "0.10.0"
+  VERSION = "0.11.0"
 end

data/specs/brut/instrumentation/methods.spec.rb

@@ -0,0 +1,399 @@
+require "spec_helper"
+
+RSpec.describe Brut::Instrumentation::Methods do
+  describe "#instrument" do
+    it "instruments only those methods specified" do
+      mock_container = double("Brut::Framework::Container")
+      instrumentation = instance_double(Brut::Instrumentation::OpenTelemetry)
+      allow(Brut).to receive(:container).and_return(mock_container)
+      allow(mock_container).to receive(:instrumentation).and_return(instrumentation)
+      allow(instrumentation).to receive(:span).and_yield(double("span that should not be used"))
+
+      class_to_instrument = Class.new do
+        include Brut::Instrumentation::Methods
+
+        def save
+          @save_called = true
+        end
+
+        def search
+          @search_called = true
+        end
+
+        def self.name # since this is an anonymous class, need some name to show up
+          "TestClass"
+        end
+
+        private
+
+        def delete
+          @delete_called = true
+        end
+
+        instrument :save, :delete
+      end
+      object = class_to_instrument.new
+
+      object.save
+      object.search
+      object.send(:delete)
+
+      expect(object.instance_variable_get(:@save_called)).to   eq(true)
+      expect(object.instance_variable_get(:@search_called)).to eq(true)
+      expect(object.instance_variable_get(:@delete_called)).to eq(true)
+      expect(instrumentation).to have_received(:span).with(
+        "TestClass#save",
+        attributes: {
+          "brut.class" => "TestClass",
+          "brut.method" => "save",
+        }
+      )
+      expect(instrumentation).to have_received(:span).with(
+        "TestClass#delete",
+        attributes: {
+          "brut.class" => "TestClass",
+          "brut.method" => "delete",
+        }
+      )
+      expect(instrumentation).not_to have_received(:span).with(
+        /\#search/,
+        attributes: kind_of(Hash)
+      )
+    end
+    it "works when called on a method definition" do
+      mock_container = double("Brut::Framework::Container")
+      instrumentation = instance_double(Brut::Instrumentation::OpenTelemetry)
+      allow(Brut).to receive(:container).and_return(mock_container)
+      allow(mock_container).to receive(:instrumentation).and_return(instrumentation)
+      allow(instrumentation).to receive(:span).and_yield(double("span that should not be used"))
+
+      class_to_instrument = Class.new do
+        include Brut::Instrumentation::Methods
+
+        instrument def save
+          @save_called = true
+        end
+
+        def search
+          @search_called = true
+        end
+
+        def self.name # since this is an anonymous class, need some name to show up
+          "TestClass"
+        end
+
+        private
+
+        instrument def delete
+          @delete_called = true
+        end
+      end
+      object = class_to_instrument.new
+
+      object.save
+      object.search
+      object.send(:delete)
+
+      expect(object.instance_variable_get(:@save_called)).to   eq(true)
+      expect(object.instance_variable_get(:@search_called)).to eq(true)
+      expect(object.instance_variable_get(:@delete_called)).to eq(true)
+      expect(instrumentation).to have_received(:span).with(
+        "TestClass#save",
+        attributes: {
+          "brut.class" => "TestClass",
+          "brut.method" => "save",
+        }
+      )
+      expect(instrumentation).to have_received(:span).with(
+        "TestClass#delete",
+        attributes: {
+          "brut.class" => "TestClass",
+          "brut.method" => "delete",
+        }
+      )
+      expect(instrumentation).not_to have_received(:span).with(
+        /\#search/,
+        attributes: kind_of(Hash)
+      )
+    end
+
+    it "calling it twice raises an error" do
+      expect {
+        Class.new do
+          include Brut::Instrumentation::Methods
+
+          def save
+            @save_called = true
+          end
+
+          def self.name # since this is an anonymous class, need some name to show up
+            "TestClass"
+          end
+
+          instrument :save
+          instrument :save
+        end
+      }.to raise_error(ArgumentError, /already instrumented/)
+    end
+
+    it "instrumenting a nonexistent method raises an error" do
+      expect {
+        Class.new do
+          include Brut::Instrumentation::Methods
+
+          def save
+            @save_called = true
+          end
+
+          def self.name # since this is an anonymous class, need some name to show up
+            "TestClass"
+          end
+
+          instrument :foo
+        end
+      }.to raise_error(ArgumentError)
+    end
+  end
+  describe "#instrument_all" do
+    it "instruments all methods" do
+      mock_container = double("Brut::Framework::Container")
+      instrumentation = instance_double(Brut::Instrumentation::OpenTelemetry)
+      allow(Brut).to receive(:container).and_return(mock_container)
+      allow(mock_container).to receive(:instrumentation).and_return(instrumentation)
+      allow(instrumentation).to receive(:span).and_yield(double("span that should not be used"))
+
+      class_to_instrument = Class.new do
+        include Brut::Instrumentation::Methods
+
+        def save
+          @save_called = true
+        end
+
+        def search
+          @search_called = true
+        end
+
+        def self.name # since this is an anonymous class, need some name to show up
+          "TestClass"
+        end
+
+        private
+
+        def delete
+          @delete_called = true
+        end
+
+        instrument_all
+      end
+      object = class_to_instrument.new
+
+      object.save
+      object.search
+      object.send(:delete)
+
+      expect(object.instance_variable_get(:@save_called)).to   eq(true)
+      expect(object.instance_variable_get(:@search_called)).to eq(true)
+      expect(object.instance_variable_get(:@delete_called)).to eq(true)
+      expect(instrumentation).to have_received(:span).with(
+        "TestClass#save",
+        attributes: {
+          "brut.class" => "TestClass",
+          "brut.method" => "save",
+        }
+      )
+      expect(instrumentation).to have_received(:span).with(
+        "TestClass#delete",
+        attributes: {
+          "brut.class" => "TestClass",
+          "brut.method" => "delete",
+        }
+      )
+      expect(instrumentation).to have_received(:span).with(
+        "TestClass#search",
+        attributes: {
+          "brut.class" => "TestClass",
+          "brut.method" => "search",
+        }
+      )
+    end
+    it "instruments all methods defined after it is called" do
+      mock_container = double("Brut::Framework::Container")
+      instrumentation = instance_double(Brut::Instrumentation::OpenTelemetry)
+      allow(Brut).to receive(:container).and_return(mock_container)
+      allow(mock_container).to receive(:instrumentation).and_return(instrumentation)
+      allow(instrumentation).to receive(:span).and_yield(double("span that should not be used"))
+
+      class_to_instrument = Class.new do
+        include Brut::Instrumentation::Methods
+        instrument_all
+
+        def save
+          @save_called = true
+        end
+
+        def search
+          @search_called = true
+        end
+
+        def self.name # since this is an anonymous class, need some name to show up
+          "TestClass"
+        end
+
+        private
+
+        def delete
+          @delete_called = true
+        end
+      end
+      object = class_to_instrument.new
+
+      object.save
+      object.search
+      object.send(:delete)
+
+      expect(object.instance_variable_get(:@save_called)).to   eq(true)
+      expect(object.instance_variable_get(:@search_called)).to eq(true)
+      expect(object.instance_variable_get(:@delete_called)).to eq(true)
+      expect(instrumentation).to have_received(:span).with(
+        "TestClass#save",
+        attributes: {
+          "brut.class" => "TestClass",
+          "brut.method" => "save",
+        }
+      )
+      expect(instrumentation).to have_received(:span).with(
+        "TestClass#delete",
+        attributes: {
+          "brut.class" => "TestClass",
+          "brut.method" => "delete",
+        }
+      )
+      expect(instrumentation).to have_received(:span).with(
+        "TestClass#search",
+        attributes: {
+          "brut.class" => "TestClass",
+          "brut.method" => "search",
+        }
+      )
+    end
+  end
+  describe "#instrument_public" do
+    it "instruments only public methods" do
+      mock_container = double("Brut::Framework::Container")
+      instrumentation = instance_double(Brut::Instrumentation::OpenTelemetry)
+      allow(Brut).to receive(:container).and_return(mock_container)
+      allow(mock_container).to receive(:instrumentation).and_return(instrumentation)
+      allow(instrumentation).to receive(:span).and_yield(double("span that should not be used"))
+
+      class_to_instrument = Class.new do
+        include Brut::Instrumentation::Methods
+
+        def save
+          @save_called = true
+        end
+
+        def search
+          @search_called = true
+        end
+
+        def self.name # since this is an anonymous class, need some name to show up
+          "TestClass"
+        end
+
+        private
+
+        def delete
+          @delete_called = true
+        end
+
+        instrument_public
+
+      end
+      object = class_to_instrument.new
+
+      object.save
+      object.search
+      object.send(:delete)
+
+      expect(object.instance_variable_get(:@save_called)).to   eq(true)
+      expect(object.instance_variable_get(:@search_called)).to eq(true)
+      expect(object.instance_variable_get(:@delete_called)).to eq(true)
+      expect(instrumentation).to have_received(:span).with(
+        "TestClass#save",
+        attributes: {
+          "brut.class" => "TestClass",
+          "brut.method" => "save",
+        }
+      )
+      expect(instrumentation).to have_received(:span).with(
+        "TestClass#search",
+        attributes: {
+          "brut.class" => "TestClass",
+          "brut.method" => "search",
+        }
+      )
+      expect(instrumentation).not_to have_received(:span).with(
+        "TestClass#delete",
+        attributes: kind_of(Hash)
+      )
+    end
+    it "instruments only public methods defined after it is called" do
+      mock_container = double("Brut::Framework::Container")
+      instrumentation = instance_double(Brut::Instrumentation::OpenTelemetry)
+      allow(Brut).to receive(:container).and_return(mock_container)
+      allow(mock_container).to receive(:instrumentation).and_return(instrumentation)
+      allow(instrumentation).to receive(:span).and_yield(double("span that should not be used"))
+
+      class_to_instrument = Class.new do
+        include Brut::Instrumentation::Methods
+        instrument_public
+
+        def save
+          @save_called = true
+        end
+
+        def search
+          @search_called = true
+        end
+
+        def self.name # since this is an anonymous class, need some name to show up
+          "TestClass"
+        end
+
+        private
+
+        def delete
+          @delete_called = true
+        end
+
+      end
+      object = class_to_instrument.new
+
+      object.save
+      object.search
+      object.send(:delete)
+
+      expect(object.instance_variable_get(:@save_called)).to   eq(true)
+      expect(object.instance_variable_get(:@search_called)).to eq(true)
+      expect(object.instance_variable_get(:@delete_called)).to eq(true)
+      expect(instrumentation).to have_received(:span).with(
+        "TestClass#save",
+        attributes: {
+          "brut.class" => "TestClass",
+          "brut.method" => "save",
+        }
+      )
+      expect(instrumentation).to have_received(:span).with(
+        "TestClass#search",
+        attributes: {
+          "brut.class" => "TestClass",
+          "brut.method" => "search",
+        }
+      )
+      expect(instrumentation).not_to have_received(:span).with(
+        "TestClass#delete",
+        attributes: kind_of(Hash)
+      )
+    end
+  end
+end