orange_tap 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98d5bfa7c39f556f24bccb7eb24e8cb76ca2d0ae53d892fa834d050956d37fc0
-  data.tar.gz: 5db4e456e34c6aa0cec5bff1682d2cce332a0ff448eede068ba60591b40e10ec
+  metadata.gz: ca009ebd31ae0ff1849d7975d602f1f87dccbada30458cd4943e6a526aa35647
+  data.tar.gz: 662aa3e960659b36c5febb1b1f59e2d39d2010146a208584155f7e860206b77a
 SHA512:
-  metadata.gz: bf88ab0dfacc03ca122b46973c6101ed6ebdfa293667bd1ec8c41e113cd810e82c6973c781f577fff1e0233d1e65fab51cffe338a210dbe48eded8701fcd43be
-  data.tar.gz: 925d22853cf17afdaecdda5091a6c8b2c0feda44b57d0599f581180aa5c540234e9407b8ab270415e46776eeb62daec61de687fc1206bf027918198d20fee310
+  metadata.gz: bdd6c3f5b6158f7df4dd462c4aa6be2b38bd060d5a9c26596487c93510b03d3c9259efbeee60d1d5c960060f05265608b56e1edea922a3de534414ef5578934f
+  data.tar.gz: bbc112874962e22531f59e7fca2b5569831fbb956a690692c24f219fb32c67295d48aaf632ecb276f2ac6c22e4122e3992d8942f9976a96a9e6f5238a044b7f8

data/README.md

@@ -46,7 +46,13 @@ at once) works without any extra bookkeeping.
   Block-based method bodies (`define_method`, `define_singleton_method`) have
   an ISeq of type `:block`, which `TracePoint#enable(target:)` cannot target
   and raises `ArgumentError` — attempting to trace one will fail at `open`
-  time, not at `trace_method` time.
+  time, not at `trace_method` time. (The
+  [trace-all-application-methods mode](#tracing-all-application-methods-opt-in)
+  captures these, since it uses a global hook rather than a per-ISeq target.)
+- **C-implemented methods, unless explicitly opted in.** Methods with no Ruby
+  ISeq are rejected by default. They can be traced via a global hook by
+  setting `config.trace_c_methods = true`, at a process-wide performance cost
+  — see [Tracing C-implemented methods](#tracing-c-implemented-methods-opt-in).
 - **Errors inside the Worker thread.** If the worker thread raises while
   assembling spans, `Session#stop` re-raises that error via `Thread#value`'s
   standard behavior. TracePoints are always disabled *before* the worker is
@@ -96,6 +102,46 @@ tape.open
 path = tape.stop
 ```
 
+The root (session) span is named `"orange_tap session"` by default. Pass a
+name to override it — handy for telling sessions apart when the output is
+imported into a trace viewer:
+
+```ruby
+OrangeTap.open("checkout-flow") { ... }
+
+tape = OrangeTap.new
+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
@@ -116,6 +162,70 @@ Output location is configurable:
 OrangeTap.config.output_dir = "/path/to/traces"
 ```
 
+### Tracing all application methods (opt-in)
+
+Instead of registering methods one by one, you can trace **every non-builtin
+Ruby method call** in the process by enabling a single flag before opening a
+session:
+
+```ruby
+OrangeTap.config.trace_all_app_methods = true
+
+OrangeTap.open("request") do
+  # every application (and gem) method called here is captured automatically
+  MyApp.handle(request)
+end
+```
+
+In this mode a session installs one global `:call`/`:return` `TracePoint` (no
+`target:`) and decides what to keep by the **definition path** of each called
+method:
+
+- **Excluded:** Ruby core internals (`<internal:...>`) and the standard library
+  (under Ruby's `rubylibdir`/`rubyarchdir`), plus OrangeTap's own code.
+- **Excluded automatically:** all C-implemented methods (`String#upcase`,
+  `Array#each`, `Integer#+`, …) — `TracePoint(:call)` never fires for them.
+- **Traced:** everything else, i.e. your application code **and gems**.
+
+Because it needs no ISeq target, this mode also captures methods defined via
+`define_method` / `define_singleton_method`, which the per-method
+`trace_method` API cannot target.
+
+When enabled, this mode **supersedes** explicit `trace_method` registration:
+per-method (and C-method opt-in) hooks are not installed for that session.
+
+> **Performance warning:** the hook fires on **every Ruby method call in the
+> process**, running a (memoized) path check each time. This is the heaviest
+> mode OrangeTap offers — use it for focused debugging sessions, not always-on
+> production tracing. Concurrent sessions each add their own global hook.
+
+### Tracing C-implemented methods (opt-in)
+
+By default, registering a C-implemented method (one with no Ruby ISeq, e.g.
+`String#upcase`) raises `OrangeTap::UntraceableMethodError`, because the
+low-overhead `TracePoint#enable(target:)` mechanism requires an ISeq.
+
+You can opt in to tracing C methods through the same `trace_method` API by
+enabling a config flag **before** registering them:
+
+```ruby
+OrangeTap.config.trace_c_methods = true
+OrangeTap.trace_method(String.instance_method(:upcase))   # now accepted
+```
+
+**Performance trade-off:** when enabled and at least one C method is
+registered, each session installs a single global `:c_call`/`:c_return`
+`TracePoint` (no `target:`). That hook fires on **every C call in the
+process** — including very hot ones like `Array#each`, `Hash#[]`, `Integer#+`
+— and filters by `[owner, name]` inside the hook. So the "zero overhead for
+unregistered methods" guarantee no longer holds once any C method is traced.
+Concurrent sessions each add their own global hook, compounding the cost.
+Enable it only when you specifically need C-method spans.
+
+A C method that is a *singleton method on a specific object* (rather than a
+class/singleton method like `Foo.bar`) is not supported: it is skipped with a
+warning at registration time.
+
 ### Example
 
 [`examples/order_demo.rb`](examples/order_demo.rb) is a runnable,

data/examples/order_demo.rb

@@ -56,7 +56,7 @@ OrangeTap.trace_method(
 path = nil
 # Avoid YJIT compile overhead in this example by running the code multiple times
 3.times do
-  path = OrangeTap.open do
+  path = OrangeTap.open("DummyController#dummy") do
     order = Order.new(%w[coffee cake tea coffee])
     order.checkout
   end

data/examples/sinatra_trace_all_demo.rb

@@ -0,0 +1,127 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Sinatra demo: enable OrangeTap's "trace all application methods" mode and
+# record ONE OTLP/JSON trace per HTTP request, using before/after filters to
+# open and stop a session around each request.
+#
+# It is self-driving: a handful of in-process requests are issued via
+# Rack::MockRequest, so no server or `curl` is needed. Just run:
+#
+#   ruby examples/sinatra_trace_all_demo.rb
+#
+# The first run installs sinatra (and its rack dependency) via bundler/inline.
+
+require "bundler/inline"
+gemfile do
+  source "https://rubygems.org"
+  gem "sinatra", require: "sinatra/base"
+end
+
+require_relative "../lib/orange_tap"
+require "json"
+require "tmpdir"
+
+# --- application (domain) code --------------------------------------------
+# These are the methods we actually care about seeing in the trace. Nothing
+# here is registered with trace_method: the "trace all" mode picks them up
+# automatically because they are non-builtin Ruby methods.
+
+module Pricing
+  PRICES = { "coffee" => 400, "tea" => 350, "cake" => 500 }.freeze
+
+  def self.price_for(item)
+    PRICES.fetch(item, 0) # Hash#fetch is a C method -> excluded from the trace
+  end
+end
+
+class Order
+  MENUS = { 1 => %w[coffee cake], 2 => %w[tea tea coffee] }.freeze
+
+  def initialize(id)
+    @items = MENUS.fetch(id, [])
+  end
+
+  def total
+    @items.sum { |item| Pricing.price_for(item) }
+  end
+
+  def summary
+    "#{@items.size} item(s), #{total} yen"
+  end
+end
+
+class Greeter
+  def greet(name)
+    "Hello, #{normalize(name)}!"
+  end
+
+  def normalize(name)
+    name.to_s.strip.empty? ? "world" : name.strip
+  end
+end
+
+# --- OrangeTap configuration ----------------------------------------------
+OUTPUT_DIR = Dir.mktmpdir("orange_tap_sinatra")
+OrangeTap.config.output_dir = OUTPUT_DIR
+OrangeTap.config.trace_all_app_methods = true
+
+# --- Sinatra app ----------------------------------------------------------
+class DemoApp < Sinatra::Base
+  # One OrangeTap session per request. In trace_all_app_methods mode every
+  # non-builtin Ruby call between `before` and `after` is captured -- your
+  # domain code AND gem code (Sinatra itself), since gems are traced. C methods
+  # and the standard library are excluded automatically.
+  before do
+    @tape = OrangeTap.new
+    @tape.open("#{request.request_method} #{request.path_info}")
+  end
+
+  after do
+    path = @tape.stop
+    # Surface the trace file so the driver below can report / read it.
+    response.headers["X-Trace-Path"] = path
+  end
+
+  get "/" do
+    Greeter.new.greet(params["name"])
+  end
+
+  get "/orders/:id" do
+    Order.new(params["id"].to_i).summary
+  end
+end
+
+# --- drive a few requests in-process --------------------------------------
+DOMAIN = %w[Greeter Order Pricing].freeze
+
+def domain_spans(names)
+  names.select { |n| DOMAIN.any? { |d| n.start_with?("#{d}#", "#{d}.") } }
+end
+
+def span_names(path)
+  document = JSON.parse(File.read(path))
+  document.fetch("resourceSpans").flat_map do |rs|
+    rs.fetch("scopeSpans").flat_map { |ss| ss.fetch("spans") }
+  end.map { |s| s["name"] }
+end
+
+mock = Rack::MockRequest.new(DemoApp)
+requests = ["/", "/?name=Alice", "/orders/1", "/orders/2"]
+
+puts "Traces written under: #{OUTPUT_DIR}\n\n"
+
+requests.each do |path|
+  response = mock.get(path)
+  trace_path = response["X-Trace-Path"]
+  names = span_names(trace_path)
+
+  puts "GET #{path}"
+  puts "  -> #{response.status} #{response.body.strip.inspect}"
+  puts "  trace: #{trace_path}"
+  puts "  spans: #{names.size} total, #{domain_spans(names.uniq).sort.join(', ')} (domain)"
+  puts
+end
+
+puts "Each request produced its own OTLP/JSON file (open one to see the full,"
+puts "framework-inclusive span tree)."

data/examples/trace_all_app_demo.rb

@@ -0,0 +1,85 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# "Trace all application methods" mode: instead of registering methods one by
+# one, flip a single config flag and every non-builtin Ruby method call is
+# captured automatically. Built-ins are excluded by definition path — Ruby
+# core internals and the standard library are dropped, and C methods
+# (String#upcase, Array#each, ...) never fire the :call hook at all. Your
+# application code (and gems) is traced.
+#
+#   ruby -Ilib examples/trace_all_app_demo.rb
+
+require "orange_tap"
+require "json"
+
+class Order
+  def initialize(items)
+    @items = items
+  end
+
+  def total
+    # Enumerable#sum + the block call into C methods (Array iteration, Integer
+    # addition): those are NOT traced. Pricing.price_for IS (app code).
+    @items.sum { |item| Pricing.price_for(item) }
+  end
+
+  def checkout
+    amount = total
+    label = describe        # app method, traced
+    Receipt.new(amount).print(label)
+    amount
+  end
+
+  # Defined with define_method: the per-method `trace_method` API cannot target
+  # this (its ISeq is a :block), but the global app hook captures it fine.
+  define_method(:describe) do
+    "order of #{@items.size} item(s)"
+  end
+end
+
+module Pricing
+  PRICES = { "coffee" => 400, "tea" => 350, "cake" => 500 }.freeze
+
+  def self.price_for(item)
+    PRICES.fetch(item, 0)   # Hash#fetch is a C method -> not traced
+  end
+end
+
+class Receipt
+  def initialize(amount)
+    @amount = amount
+  end
+
+  def print(label)
+    puts "#{label}: #{@amount} yen"   # Kernel#puts is C -> not traced
+  end
+end
+
+# No OrangeTap.trace_method calls needed: just enable the mode.
+OrangeTap.config.trace_all_app_methods = true
+
+path = nil
+# Avoid YJIT compile overhead in this example by running the code multiple times
+3.times do
+  path = OrangeTap.open("DummyController#dummy") do
+    order = Order.new(%w[coffee cake tea coffee])
+    order.checkout
+  end
+end
+
+puts "\nOTLP/JSON written to: #{path}\n\n"
+
+document = JSON.parse(File.read(path))
+spans = document.fetch("resourceSpans").flat_map do |rs|
+  rs.fetch("scopeSpans").flat_map { |ss| ss.fetch("spans") }
+end
+
+# App methods (Order#total, Order#checkout, Order#describe, Pricing.price_for,
+# Receipt#initialize, Receipt#print) show up automatically; built-ins such as
+# String#upcase, Hash#fetch, and Kernel#puts do not.
+puts "Captured span names:"
+spans.map { |s| s["name"] }.uniq.sort.each { |name| puts "  - #{name}" }
+
+puts "\nFull document:\n\n"
+puts JSON.pretty_generate(document)

data/lib/orange_tap/builtin_filter.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module OrangeTap
+  # Classifies a source path (as given by TracePoint#path, i.e. the definition
+  # file of the called method) into "application code" vs "built-in", for the
+  # trace_all_app_methods mode.
+  #
+  # C-implemented methods never reach here: TracePoint(:call) does not fire for
+  # them, so they are excluded upstream. What remains to filter out are the
+  # Ruby-implemented built-ins, which are identified purely by path prefix:
+  #
+  #   - "<...>"            core internals (e.g. "<internal:array>")
+  #   - rubylibdir/arch   the Ruby standard library
+  #   - OrangeTap itself  so the tracer never traces its own code
+  #
+  # Gems (Gem.path) are intentionally NOT excluded: application-owned gem calls
+  # are considered part of the app for this mode.
+  class BuiltinFilter
+    def initialize
+      @excluded_prefixes = [
+        RbConfig::CONFIG["rubylibdir"],
+        RbConfig::CONFIG["rubyarchdir"],
+        # lib/orange_tap/builtin_filter.rb -> lib/orange_tap -> lib
+        File.expand_path("..", __dir__)
+      ].compact
+      @cache = {}
+      @mutex = Mutex.new
+    end
+
+    # True when `path` looks like application (or gem) code that should be
+    # traced; false for core internals, the standard library, and OrangeTap's
+    # own source. Decisions are memoized per path.
+    def app_method?(path)
+      return false if path.nil? || path.empty?
+      return @cache[path] if @cache.key?(path)
+
+      @mutex.synchronize do
+        # Re-check inside the lock: another thread may have filled it in.
+        return @cache[path] if @cache.key?(path)
+
+        @cache[path] = compute(path)
+      end
+    end
+
+    private
+
+    def compute(path)
+      return false if path.start_with?("<") # "<internal:...>", "<compiled>", etc.
+
+      @excluded_prefixes.none? { |prefix| path.start_with?(prefix) }
+    end
+  end
+end

data/lib/orange_tap/config.rb

@@ -4,12 +4,28 @@ require "tmpdir"
 
 module OrangeTap
   class Config
-    attr_accessor :output_dir, :service_name, :otel_converter
+    attr_accessor :output_dir, :service_name, :otel_converter, :trace_c_methods, :trace_all_app_methods
 
     def initialize
       @output_dir = File.join(Dir.tmpdir, "orange_tap")
       @service_name = "orange_tap"
       @otel_converter = OrangeTap::OtelConverter
+      # Opt-in "trace everything" mode. When true, a session installs a single
+      # global :call/:return TracePoint that records every non-builtin Ruby
+      # method call in the process, instead of the per-method registry hooks.
+      # Built-ins are excluded by definition path (core internals + stdlib);
+      # gems ARE traced, and C methods are always excluded (:call never fires
+      # for them). This fires on every Ruby call process-wide, so it is heavy;
+      # see BuiltinFilter and README. It supersedes explicit trace_method
+      # registration when enabled.
+      @trace_all_app_methods = false
+      # Opt-in flag for tracing C-implemented methods. When false (default),
+      # registering a C method raises UntraceableMethodError, as before. When
+      # true, C methods are traced via a single global :c_call/:c_return
+      # TracePoint per session, filtered by [owner, name] inside the hook.
+      # This trades away the "zero overhead for unregistered methods"
+      # guarantee for every C call in the process. See TODO-c-support.md.
+      @trace_c_methods = false
     end
   end
 end

data/lib/orange_tap/method_registry.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "set"
+
 module OrangeTap
   # Holds the set of methods to be traced, keyed by [owner, name] rather than
   # by Method/UnboundMethod object identity. Method/UnboundMethod instances
@@ -17,6 +19,10 @@ module OrangeTap
 
     def initialize
       @entries = {}
+      # [owner, name] keys for C-implemented (ISeq-less) methods, traced via a
+      # global :c_call/:c_return TracePoint. Only populated when
+      # OrangeTap.config.trace_c_methods is enabled at registration time.
+      @c_entries = Set.new
       @mutex = Mutex.new
     end
 
@@ -40,19 +46,49 @@ module OrangeTap
       @mutex.synchronize { @entries.values.dup }
     end
 
+    # Snapshot of registered C-method keys ([owner, name]), taken once per
+    # Session#open. Empty unless trace_c_methods was enabled at registration
+    # time. Session uses this to decide whether to build a global C TracePoint.
+    def c_targets
+      @mutex.synchronize { @c_entries.dup }
+    end
+
     private
 
     def register_one(method_obj)
       method_obj = resolve(method_obj)
       iseq = RubyVM::InstructionSequence.of(method_obj)
-      raise OrangeTap::UntraceableMethodError, method_obj.inspect unless iseq
+      return register_c_method(method_obj) unless iseq
 
       @mutex.synchronize { @entries[key_for(method_obj)] = iseq }
     end
 
+    # A method with no ISeq is C-implemented. Rejected by default; only
+    # accepted (into the global-hook set) when trace_c_methods is opted in.
+    def register_c_method(method_obj)
+      raise OrangeTap::UntraceableMethodError, method_obj.inspect unless OrangeTap.config.trace_c_methods
+
+      owner = method_obj.owner
+      # A C method that is a singleton method on a specific object (not a
+      # Class/Module) is unsupported: warn and skip rather than register it.
+      # Class/singleton methods ("Foo.bar") have a Module attached_object and
+      # are traced normally.
+      if owner.singleton_class? && !owner.attached_object.is_a?(Module)
+        warn "OrangeTap: singleton C method #{owner}##{method_obj.name} " \
+             "is not supported for C-method tracing; skipping"
+        return
+      end
+
+      @mutex.synchronize { @c_entries << key_for(method_obj) }
+    end
+
     def unregister_one(method_obj)
       method_obj = resolve(method_obj)
-      @mutex.synchronize { @entries.delete(key_for(method_obj)) }
+      key = key_for(method_obj)
+      @mutex.synchronize do
+        @entries.delete(key)
+        @c_entries.delete(key)
+      end
     end
 
     # Accepts a Method/UnboundMethod as-is, or a notation String ("Foo.bar"

data/lib/orange_tap/session.rb

@@ -18,7 +18,7 @@ module OrangeTap
       @tracepoint_targets = nil
     end
 
-    def open
+    def open(session_name = nil)
       raise AlreadyOpenError if @queue
 
       # Anchor monotonic time to wall-clock time once, at session start, so
@@ -30,18 +30,22 @@ module OrangeTap
 
       @queue = Thread::Queue.new
 
-      # One TracePoint per target ISeq: whether a single TracePoint can
-      # safely enable(target:) more than one ISeq is version-dependent, so
-      # each ISeq gets its own TracePoint instance to enable/disable.
-      @tracepoint_targets = @registry.targets.map { |iseq| [build_tracepoint(@queue), iseq] }
-
+      # Start the worker before building the TracePoints so its Thread can be
+      # captured by the global app hook (which must skip the worker's own
+      # calls). Tracing is not active yet, so nothing the worker does now is
+      # recorded.
       ctx = Worker::Context.new(
         queue: @queue, config: @config, trace_id: trace_id,
-        start_mono_ns: start_mono_ns, start_unix_ns: start_unix_ns
+        start_mono_ns: start_mono_ns, start_unix_ns: start_unix_ns,
+        session_name: session_name
       )
       @worker_thread = Thread.new(ctx) { |worker_ctx| Worker.new(worker_ctx).run }
 
-      @tracepoint_targets.each { |tp, iseq| tp.enable(target: iseq) }
+      # Entries are [tracepoint, iseq]; a nil iseq marks a global (targetless)
+      # hook, which is enabled without a target: below.
+      @tracepoint_targets = build_tracepoint_targets
+
+      @tracepoint_targets.each { |tp, iseq| iseq ? tp.enable(target: iseq) : tp.enable }
       self
     end
 
@@ -62,6 +66,27 @@ module OrangeTap
 
     private
 
+    # Global "trace all app methods" mode supersedes per-method registration:
+    # a single :call/:return hook records every non-builtin Ruby method call.
+    # Otherwise, use the registry's per-ISeq hooks plus the optional global
+    # C-method hook. One TracePoint per target ISeq: whether a single
+    # TracePoint can safely enable(target:) more than one ISeq is
+    # version-dependent, so each ISeq gets its own instance.
+    def build_tracepoint_targets
+      if @config.trace_all_app_methods
+        return [[build_global_app_tracepoint(@queue, BuiltinFilter.new, @worker_thread), nil]]
+      end
+
+      targets = @registry.targets.map { |iseq| [build_tracepoint(@queue), iseq] }
+
+      # Opt-in: a single global :c_call/:c_return TracePoint for any registered
+      # C methods, filtered inside the hook. Only added when there is at least
+      # one C method to trace, so the default path keeps zero C-call overhead.
+      c_targets = @registry.c_targets
+      targets << [build_c_tracepoint(@queue, c_targets), nil] unless c_targets.empty?
+      targets
+    end
+
     def build_tracepoint(queue)
       TracePoint.new(:call, :return) do |tp|
         # Hook body stays minimal: push a single Event built from cheap
@@ -75,5 +100,46 @@ module OrangeTap
         )
       end
     end
+
+    # Global hook for C methods. Fires on EVERY C call in the process, so the
+    # first thing it does is filter by [owner, name]; unregistered calls exit
+    # immediately. :c_call/:c_return are normalized to :call/:return so the
+    # Worker's event handling stays uniform. (TracePoint suppresses its own
+    # re-entry, so the C calls made inside this hook do not recurse.)
+    def build_c_tracepoint(queue, c_targets)
+      TracePoint.new(:c_call, :c_return) do |tp|
+        next unless c_targets.include?([tp.defined_class, tp.method_id])
+
+        queue << Event.new(
+          type: tp.event == :c_call ? :call : :return,
+          thread_id: Thread.current.object_id,
+          method_id: tp.method_id,
+          defined_class: tp.defined_class,
+          timestamp_ns: Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+        )
+      end
+    end
+
+    # Global hook for the trace_all_app_methods mode. Fires on EVERY Ruby
+    # method call in the process (C methods never fire :call). Two cheap
+    # guards run first: skip the worker's own thread (so its bookkeeping and
+    # JSON writing are never traced, avoiding a feedback loop), and skip
+    # built-in definition paths via the memoized filter. TracePoint suppresses
+    # its own re-entry, so the Ruby calls in this body (filter.app_method?)
+    # do not recurse.
+    def build_global_app_tracepoint(queue, filter, worker_thread)
+      TracePoint.new(:call, :return) do |tp|
+        next if Thread.current == worker_thread
+        next unless filter.app_method?(tp.path)
+
+        queue << Event.new(
+          type: tp.event,
+          thread_id: Thread.current.object_id,
+          method_id: tp.method_id,
+          defined_class: tp.defined_class,
+          timestamp_ns: Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+        )
+      end
+    end
   end
 end

data/lib/orange_tap/version.rb

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

data/lib/orange_tap/worker.rb

@@ -13,7 +13,9 @@ module OrangeTap
   # tag on Event, because a Worker only ever drains events produced by the
   # TracePoints of the Session that spawned it.
   class Worker
-    Context = Data.define(:queue, :config, :trace_id, :start_mono_ns, :start_unix_ns)
+    Context = Data.define(:queue, :config, :trace_id, :start_mono_ns, :start_unix_ns, :session_name)
+
+    DEFAULT_SESSION_NAME = "orange_tap session"
 
     def initialize(ctx)
       @ctx = ctx
@@ -95,7 +97,7 @@ module OrangeTap
       PendingSpan.new(
         span_id: SecureRandom.hex(8),
         parent_span_id: nil,
-        name: "orange_tap session",
+        name: @ctx.session_name || DEFAULT_SESSION_NAME,
         thread_id: nil,
         start_mono_ns: @ctx.start_mono_ns
       )

data/lib/orange_tap.rb

@@ -5,6 +5,7 @@ require_relative "orange_tap/event"
 require_relative "orange_tap/pending_span"
 require_relative "orange_tap/otel_converter"
 require_relative "orange_tap/config"
+require_relative "orange_tap/builtin_filter"
 require_relative "orange_tap/method_registry"
 require_relative "orange_tap/worker"
 require_relative "orange_tap/session"
@@ -46,9 +47,9 @@ module OrangeTap
     default_registry.register_all_instance_methods(klass)
   end
 
-  def open(&block)
+  def open(name = nil, &block)
     tape = new
-    tape.open
+    tape.open(name)
     return tape unless block
 
     begin
@@ -66,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.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Uchio Kondo
@@ -26,8 +26,11 @@ files:
 - Rakefile
 - examples/jaeger-screenshot.png
 - examples/order_demo.rb
+- examples/sinatra_trace_all_demo.rb
 - examples/trace-example.json
+- examples/trace_all_app_demo.rb
 - lib/orange_tap.rb
+- lib/orange_tap/builtin_filter.rb
 - lib/orange_tap/config.rb
 - lib/orange_tap/event.rb
 - lib/orange_tap/method_registry.rb