orange_tap 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44504ce4b47d41f26a788f14a8ca53379ebaaa97e2f50e7e45b1af6c833a20f2
-  data.tar.gz: 5f4b54c1ce9984c1cc42e9eed43231d56be3f0f63d25d085d9236b7a17cfd652
+  metadata.gz: ca009ebd31ae0ff1849d7975d602f1f87dccbada30458cd4943e6a526aa35647
+  data.tar.gz: 662aa3e960659b36c5febb1b1f59e2d39d2010146a208584155f7e860206b77a
 SHA512:
-  metadata.gz: 1b418033fa327fc2b95866552f64316e0d642d711578df92200c7736efcd7740d5a314d2047f531aced963b5cdce507f1a90e7257676bd45385ab0354bb27f0c
-  data.tar.gz: d42a4780a31e34c525d1471470634f1c5584fbdc722eb15b59cf56a628354b4de0c0fcddd3af85914c0f73489ef9e465bd53148eb675c60be18efb83ef11d765
+  metadata.gz: bdd6c3f5b6158f7df4dd462c4aa6be2b38bd060d5a9c26596487c93510b03d3c9259efbeee60d1d5c960060f05265608b56e1edea922a3de534414ef5578934f
+  data.tar.gz: bbc112874962e22531f59e7fca2b5569831fbb956a690692c24f219fb32c67295d48aaf632ecb276f2ac6c22e4122e3992d8942f9976a96a9e6f5238a044b7f8

data/README.md

@@ -115,6 +115,33 @@ tape.open("checkout-flow")
 tape.stop
 ```
 
+### `record`: measure a block with config and error handling taken care of
+
+`OrangeTap.record` wraps a single session for the common "measure this block
+once" case (e.g. a Rails `around_action`). Compared to `open`, it handles two
+things every caller otherwise re-implements by hand:
+
+- **`config_overrides`** are applied for the duration of the block and
+  restored afterwards, *even on error*. `OrangeTap.config` is a process-global
+  singleton, so a leaked `trace_all_app_methods = true` would keep every later
+  session in the heaviest mode — `record` guarantees it is reset.
+- **`on_output`** is called with the written JSON path in an `ensure`, so you
+  receive the path on **both success and failure**. (Block-form `open` cannot
+  return the path when the block raises.) The trace file is written either way,
+  since the worker drains on `stop`.
+
+```ruby
+OrangeTap.record(
+  "checkout-flow",
+  trace_all_app_methods: true,                       # applied, then restored
+  on_output: ->(path) { Rails.logger.info("OrangeTap: #{path}") }
+) do
+  MyApp.handle(request)
+end
+# => output path on success; the original error is re-raised on failure
+#    (an on_output that itself raises is swallowed so it never masks it)
+```
+
 Other registration entry points:
 
 ```ruby

data/lib/orange_tap/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OrangeTap
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/orange_tap.rb

@@ -67,4 +67,52 @@ module OrangeTap
       raise
     end
   end
+
+  # A batteries-included wrapper around a single session, meant for the
+  # common "measure this block once" case (e.g. a Rails around_action):
+  #
+  #   OrangeTap.record("checkout", trace_all_app_methods: true,
+  #                    on_output: ->(path) { Rails.logger.info(path) }) { do_work }
+  #
+  # It handles the two things every caller otherwise has to re-implement by
+  # hand around #open:
+  #
+  # * config_overrides are applied for the duration of the block and restored
+  #   afterwards, even on error. OrangeTap.config is a process-global
+  #   singleton, so a leaked `trace_all_app_methods = true` would keep every
+  #   later session in the heaviest mode; this guarantees it is reset.
+  # * on_output is called with the written JSON path in the ensure, so the
+  #   path is delivered on BOTH success and failure. (Block form #open cannot
+  #   return the path when the block raises.) The trace file is written either
+  #   way, since the worker drains on stop.
+  #
+  # Returns the output path on success; re-raises the original error on
+  # failure (an on_output that raises is swallowed so it never masks it).
+  def record(name = nil, on_output: nil, **config_overrides)
+    previous = config_overrides.to_h { |key, _| [key, config.public_send(key)] }
+    config_overrides.each { |key, value| config.public_send("#{key}=", value) }
+
+    tape = new
+    tape.open(name)
+    path = nil
+    begin
+      yield
+      path = tape.stop
+    rescue Exception # rubocop:disable Lint/RescueException
+      path = begin
+        tape.stop
+      rescue StandardError
+        nil
+      end
+      raise
+    ensure
+      previous.each { |key, value| config.public_send("#{key}=", value) }
+      begin
+        on_output&.call(path)
+      rescue StandardError
+        nil
+      end
+    end
+    path
+  end
 end

data/sig/orange_tap.rbs

@@ -1,4 +1,48 @@
 module OrangeTap
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  class Error < StandardError
+  end
+
+  class AlreadyOpenError < Error
+  end
+
+  class NotOpenError < Error
+  end
+
+  class UntraceableMethodError < Error
+  end
+
+  # A Method/UnboundMethod, or a "Foo#bar" / "Foo.bar" notation String.
+  type method_obj = Method | UnboundMethod | String
+
+  def self.new: (**untyped opts) -> Session
+
+  def self.default_registry: () -> MethodRegistry
+
+  def self.config: () -> Config
+
+  def self.trace_method: (*method_obj method_objs) -> void
+
+  def self.untrace_method: (*method_obj method_objs) -> void
+
+  def self.trace_all_instance_methods: (Class klass) -> void
+
+  # Block form returns the output path; blockless form returns the Session.
+  def self.open: (?String? name) ?{ () -> void } -> (String | Session)
+
+  # Runs the block in a single session, applying config_overrides for its
+  # duration (restored afterwards, even on error) and delivering the output
+  # path to on_output on both success and failure. Returns the path on success.
+  def self.record: (?String? name, ?on_output: (^(String?) -> void)?, **untyped config_overrides) { () -> void } -> String?
+
+  class Config
+    attr_accessor output_dir: String
+    attr_accessor service_name: String
+    attr_accessor otel_converter: untyped
+    attr_accessor trace_c_methods: bool
+    attr_accessor trace_all_app_methods: bool
+
+    def initialize: () -> void
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: orange_tap
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Uchio Kondo