perfetto 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6642fce9318093a63a3d77565697ae113b3482aebd5408ec017eaedc6329c359
-  data.tar.gz: d92d38f6e5c3a177bc160677bc1c6a7a5334cf899a68724a7ff686266aaef71f
+  metadata.gz: 6a32a441d8046750cb3a306de9a3081e07fecd7c1223d53f7151db609d23f43d
+  data.tar.gz: 8dc578f6032ef6fb709b5a60b2fddf38afea8aa8f877cc27964f0db37dc52948
 SHA512:
-  metadata.gz: 12d78ef7a12958fe60be11128014f0327a6aae91543acefdf9c1d473438ad858d79830638699afa80684fedafda2b294f5b6ab486f6ffc9b6166b84c33f91cdf
-  data.tar.gz: 471b51999fd8a7b93aa7dc5d2ed3722193f7d4beb02a74db265db437ab220ef99fb62a23ce437afb734c7385757feacf2b7a27a6112ea1fdec73450750a07e1f
+  metadata.gz: 29d28eb4c2153d6d798d0f9e17cd91e20dc68c6eb30af3d30210b39d96570a8494adedb0a2b01f9fddf68325bbdb365eb90b731d7c5560f9234a526455003b93
+  data.tar.gz: 585e6f74925e4c56cf1b524f1960d479ca9b5641dd7dff779225553512a51d7a4b970ba523de3554fa8f8debd5a975a8f71d817b59ecd10af34144d7548c0221

data/README.md

@@ -3,3 +3,69 @@
 ## Visualization
 
 https://ui.perfetto.dev/
+
+# Usage
+
+```ruby
+
+require "perfetto"
+
+Perfetto.setup enable_tracing: true
+
+Perfetto.start_tracing
+
+# Slice
+# Stack frame is inferred from the begin event with the same category 'cpu_work'
+Perfetto.trace_event_begin "cpu_work", "example_task"
+sleep 0.1
+Perfetto.trace_event_end "cpu_work"
+
+# Slice with debug info
+# Same as above, but "key"=>"value" is added to the event details
+Perfetto.trace_event_begin_with_debug_info "cpu_work", "example_task2", "key", "value"
+sleep 0.1
+Perfetto.trace_event_end "cpu_work"
+
+# Counter
+10.times do |n|
+  Perfetto.trace_counter "rendering", "frame_rate", n.even? ? 60 : 30
+  sleep 0.1
+end
+Perfetto.trace_counter "rendering", "frame_rate", 0
+
+# Instant
+Perfetto.trace_event_instant "cpu_work", "example_instant"
+
+sleep 0.1
+
+# Instant with debug info
+Perfetto.trace_event_instant_with_debug_info "cpu_work", "example_instant2", "key", "value"
+
+sleep 0.1
+
+class Foo
+  def bar(a, b = 1, c: 2)
+    yield(a + b + c)
+  end
+
+  def baz(x)
+    puts x
+    sleep 0.1
+  end
+
+  # Intercept instance methods
+  include Perfetto::Interceptor
+  pftrace_all
+end
+
+f = Foo.new
+f.bar(1, 2, c: 3) do |n|
+  n.times do |x|
+    f.baz x + n
+  end
+end
+
+Perfetto.stop_tracing "example.pftrace"
+```
+
+![example](./example/example.png)

data/example/example.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# rubocop:disable Naming/MethodParameterName
+
+require "perfetto"
+
+Perfetto.setup enable_tracing: true
+
+Perfetto.start_tracing
+
+# Slice
+# Stack frame is inferred from the begin event with the same category 'cpu_work'
+Perfetto.trace_event_begin "cpu_work", "example_task"
+sleep 0.1
+Perfetto.trace_event_end "cpu_work"
+
+# Slice with debug info
+# Same as above, but "key"=>"value" is added to the event details
+Perfetto.trace_event_begin_with_debug_info "cpu_work", "example_task2", "key", "value"
+sleep 0.1
+Perfetto.trace_event_end "cpu_work"
+
+# Counter
+10.times do |n|
+  Perfetto.trace_counter "rendering", "frame_rate", n.even? ? 60 : 30
+  sleep 0.1
+end
+Perfetto.trace_counter "rendering", "frame_rate", 0
+
+# Instant
+Perfetto.trace_event_instant "cpu_work", "example_instant"
+
+sleep 0.1
+
+# Instant with debug info
+Perfetto.trace_event_instant_with_debug_info "cpu_work", "example_instant2", "key", "value"
+
+sleep 0.1
+
+class Foo
+  def bar(a, b = 1, c: 2)
+    yield(a + b + c)
+  end
+
+  def baz(x)
+    puts x
+    sleep 0.1
+  end
+
+  # Intercept instance methods
+  include Perfetto::Interceptor
+  pftrace_all
+end
+
+f = Foo.new
+f.bar(1, 2, c: 3) do |n|
+  n.times do |x|
+    f.baz x + n
+  end
+end
+
+Perfetto.stop_tracing "example.pftrace"
+
+# rubocop:enable Naming/MethodParameterName

data/lib/perfetto/configure.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Perfetto
+  # Global configuration
+  class Configure
+    extend Configurable
+
+    set :enable_tracing, false
+    set :buffer_size_kb, 1024
+  end
+end

data/lib/perfetto/core_ext/configurable.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Copy-pasted from https://github.com/midori-rb/midori.rb/blob/master/lib/midori/core_ext/configurable.rb
+# rubocop:disable Style/OptionalBooleanParameter
+# rubocop:disable Style/DocumentDynamicEvalDefinition
+module Configurable
+  # Sets an option to the given value.
+  # @param [Symbol] option the name of config
+  # @param [Object] value value to the name
+  # @param [Boolean] read_only Generate option= method or not
+  # @return [nil] nil
+  def set(option, value = (not_set = true), read_only = false)
+    raise ArgumentError if not_set
+
+    setter = proc { |val| set option, val }
+    getter = proc { value }
+
+    define_singleton("#{option}=", setter) unless read_only
+    define_singleton(option, getter)
+    define_singleton("#{option}?", "!!#{option}") unless method_defined? "#{option}?"
+
+    self
+  end
+
+  private
+
+  # Dynamically defines a method on settings.
+  # @param [String] name method name
+  # @param [Proc] content method content
+  # @return [nil] nil
+  def define_singleton(name, content = Proc.new)
+    singleton_class.class_eval do
+      undef_method(name) if method_defined? name
+      if content.is_a?(String)
+        class_eval("def #{name}() #{content}; end", __FILE__,
+                   __LINE__ - 1)
+      else
+        define_method(name, &content)
+      end
+    end
+  end
+end
+
+# rubocop:enable Style/OptionalBooleanParameter
+# rubocop:enable Style/DocumentDynamicEvalDefinition

data/lib/perfetto/interceptor.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Perfetto
+  # To intercept method calls in other classes
+  module Interceptor
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class methods for the interceptor
+    module ClassMethods
+      if Perfetto::Configure.enable_tracing
+        def pftrace(method_name)
+          original_method = instance_method(method_name)
+          alias_method "pftrace_#{method_name}", method_name
+          define_method(method_name) do |*args, **kwargs, &block|
+            Perfetto.trace_event_begin self.class.name, method_name.to_s
+            original_method.bind(self).call(*args, **kwargs, &block)
+            Perfetto.trace_event_end self.class.name
+          end
+        end
+
+        def pftrace_all
+          instance_methods(false).each do |method_name|
+            pftrace method_name
+          end
+        end
+      else # When tracing is disabled
+        def pftrace(_method_name); end
+        def pftrace_all; end
+      end
+    end
+  end
+end

data/lib/perfetto/perfetto.rb

@@ -7,11 +7,39 @@ module Perfetto
     alias stop_tracing_native stop_tracing
   end
 
-  def self.start_tracing(buffer_size_kb = 1024)
-    start_tracing_native buffer_size_kb
-  end
+  if Perfetto::Configure.enable_tracing
+    # Default arguments implemented in this wrapper
+    def self.start_tracing
+      start_tracing_native Configure.buffer_size_kb
+    end
+
+    def self.stop_tracing(trace_file_name = "#{Time.now.strftime("%Y%m%d%H%M%S")}.pftrace")
+      stop_tracing_native trace_file_name
+    end
 
-  def self.stop_tracing(trace_file_name = "perfetto.pftrace")
-    stop_tracing_native trace_file_name
+    # Methods implemented in native extension
+    # We don't want to proxy these methods because they are called very frequently on hot paths
+    #   def self.start_tracing; end
+    #   def self.stop_tracing(_trace_file_name); end
+    #   def self.trace_event_begin(_class_name, _method_name); end
+    #   def self.trace_event_end(_class_name); end
+    #   def self.trace_counter(_class_name, _counter_name, _counter_value); end
+    #   def self.trace_counter_i64(_class_name, _counter_name, _counter_value); end
+    #   def self.trace_counter_double(_class_name, _counter_name, _counter_value); end
+    #   def self.trace_event_instant(_class_name, _method_name); end
+    #   def self.trace_event_begin_with_debug_info(_class_name, _method_name, _debug_key, _debug_value); end
+    #   def self.trace_event_instant_with_debug_info(_class_name, _method_name, _debug_key, _debug_value); end
+  else
+    # Stub methods
+    def self.start_tracing; end
+    def self.stop_tracing(_trace_file_name); end
+    def self.trace_event_begin(_class_name, _method_name); end
+    def self.trace_event_end(_class_name); end
+    def self.trace_counter(_class_name, _counter_name, _counter_value); end
+    def self.trace_counter_i64(_class_name, _counter_name, _counter_value); end
+    def self.trace_counter_double(_class_name, _counter_name, _counter_value); end
+    def self.trace_event_instant(_class_name, _method_name); end
+    def self.trace_event_begin_with_debug_info(_class_name, _method_name, _debug_key, _debug_value); end
+    def self.trace_event_instant_with_debug_info(_class_name, _method_name, _debug_key, _debug_value); end
   end
 end

data/lib/perfetto/version.rb

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

data/lib/perfetto.rb

@@ -2,8 +2,23 @@
 
 require_relative "perfetto/version"
 
-# Native extension
-require_relative "perfetto/perfetto_native"
+require_relative "perfetto/core_ext/configurable"
+require_relative "perfetto/configure"
 
-# Ruby wrapper
-require_relative "perfetto/perfetto"
+# To minimize the overhead of tracing at runtime
+# we determine whether to enable instrumentations
+# at the first call to 'setup' method instead of
+# every call to bussiness logics being traced.
+module Perfetto
+  def self.setup(enable_tracing: nil, buffer_size_kb: nil)
+    Configure.enable_tracing = enable_tracing unless enable_tracing.nil?
+    Configure.buffer_size_kb = buffer_size_kb unless buffer_size_kb.nil?
+
+    # Native extension
+    require_relative "perfetto/perfetto_native"
+    # Ruby wrapper
+    require_relative "perfetto/perfetto"
+    # Instrumentation Helper
+    require_relative "perfetto/interceptor"
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: perfetto
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Kowalski Dark
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-01-01 00:00:00.000000000 Z
+date: 2024-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Yet another event tracing library for Ruby.
 email:
@@ -21,6 +21,8 @@ files:
 - ".rubocop.yml"
 - README.md
 - Rakefile
+- example/example.png
+- example/example.rb
 - ext/perfetto/LICENSE
 - ext/perfetto/README.md
 - ext/perfetto/extconf.rb
@@ -30,6 +32,9 @@ files:
 - ext/perfetto/sdk.cc
 - ext/perfetto/sdk.h
 - lib/perfetto.rb
+- lib/perfetto/configure.rb
+- lib/perfetto/core_ext/configurable.rb
+- lib/perfetto/interceptor.rb
 - lib/perfetto/perfetto.rb
 - lib/perfetto/version.rb
 - sig/perfetto.rbs