plain_apm 0.8.3 → 0.8.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d86c0595be8ac7a6b538a81136b6c5c17baa0d32c975cd51866f189d0b19f6ca
-  data.tar.gz: e28e7b234659abaa0e0659f7b55dc5acdaa561ecafbdddb65b403eb392411363
+  metadata.gz: ff5ddab9e3475ec09d7ef20f6bc5c6ae64ffa0e3ffa946d84def56c33eb41cde
+  data.tar.gz: '085a3004d655b642bbd63b295ce7c41531d2264709820b8f9ab35e31bdfe987d'
 SHA512:
-  metadata.gz: 32422cfac6f7d9bd3fc73c5720be2e6ec0f85c34c5c4a1a6b4b073cd203fc387c472b1c9a17ae217a4fa0046665dcf73835ec0c9ae92a523bab6a162190a48df
-  data.tar.gz: 30181e92f6df8e2717f6a0265504ccf5db16eb34c0c6d061b7682e437434b4338edf145f9d8dd8a334f6528a13d5fdc175c14c3c1798c42730ca204800b27603
+  metadata.gz: 960c5aad1354d5cc97e43d537807afeac46cdb41db125e9a832447912d2d7b0934041c8e39965bd7f8727fe9d7e4b9600250ce9c687559bfb02347afe90205b4
+  data.tar.gz: 7985afc06387dbfca63c0a69665516ebb3d54cdf88cd4532fba427d03594ab9e0e65c7a4dab08b9e1c1f63d912fb68afad22c62f7348b87d5f09c38ef146c117

data/README.md

@@ -13,11 +13,38 @@ gem 'plain_apm'
 
 And then execute:
 
-    $ bundle install
+    bundle install
 
 Or install it yourself as:
 
-    $ gem install plain_apm
+    gem install plain_apm
+
+### Ractor and TracePoint issues on Ruby 3.0
+
+PlainAPM extension to track object allocation on a per-thread basis is
+built on top of Ruby's TracePoint API.
+
+However, Rubies 3.0, 3.1, 3.2 and 3.3 as of January 2024 contain bugs
+which, when Tracepoints are used in together with Ractors, can cause
+crashes or inconsistent tracing results.
+
+Build process for the native extension contains checks for presence of
+these bugs and disables object allocation tracing accordingly.
+
+If you are sure your app is not using Ractors, you can override this by
+installing plain_apm with --enable-object-tracing-override flag:
+
+    gem install plain_apm -- --enable-object-tracing-override
+
+When using bundler, you can configure it to pass this flag to the gem
+install by running:
+
+    bundle config set --global build.plain_apm --enable-object-tracing-override
+
+See also:
+
+- https://bugs.ruby-lang.org/issues/18464
+- https://bugs.ruby-lang.org/issues/19112
 
 ## Usage
 

data/ext/object_tracing/bug18464.rb

@@ -0,0 +1,8 @@
+exit 0 if !defined?(Ractor)
+
+require "objspace"
+
+ObjectSpace.trace_object_allocations do
+  r = Ractor.new { 10 }
+  r.take
+end

data/ext/object_tracing/bug19112.rb

@@ -0,0 +1,33 @@
+exit 0 if !defined?(Ractor)
+
+# This affects all tracepoints, including internal ones
+
+def hello
+  "world"
+end
+
+traced_calls = 0
+
+# Enable tracing
+tracepoint = TracePoint.trace(:call) do |tp|
+  traced_calls += 1 if tp.callee_id == :hello
+end
+
+5.times { hello }
+
+# Create a ractor and let it be garbage collected
+r = Ractor.new { 10 }
+r.take
+r_id = r.object_id
+r = nil
+
+until (ObjectSpace._id2ref(r_id) rescue nil).nil?
+  GC.start
+end
+
+# Trigger extra calls to be traced, w/ Ractor enabled, they won't be.
+5.times { hello }
+
+tracepoint.disable
+
+exit traced_calls == 10 ? 0 : 1

data/ext/object_tracing/extconf.rb

@@ -1,6 +1,84 @@
 require "mkmf"
 
-have_header("ruby/ruby.h") or missing("ruby/ruby.h")
-have_header("ruby/debug.h") or missing("ruby/debug.h")
+def abort_on_missing_ruby_header(name)
+  abort(
+  <<-MSG
+
+      PlainAPM extension needs #{name} Ruby library header to compile.
+
+      If Ruby is installed from a package on your system, please ensure the
+      corresponding Ruby development package is installed as well.
+
+      E.g. on Debian/Ubuntu, this would be achieved by running
+
+      sudo apt install ruby-dev
+
+      on CentOS/Fedora, run
+
+      sudo yum install ruby-devel
+
+      etc...
+  MSG
+  )
+end
+
+def warn_on_ruby_ractor_bugs
+  warn(
+  <<-MSG
+
+     PlainAPM extension to track object allocation on a per-thread basis is
+     built on top of Ruby's TracePoint API.
+
+     However, the currently running Ruby version contains bugs which,
+     when Tracepoints are used in together with Ractors, can cause
+     crashes or inconsistent tracing results.
+
+     Per-thread object allocation tracing will be disabled.
+
+     If you are sure your app is not using Ractors, you can override this by
+     installing plain_apm with --enable-object-tracing-override flag:
+
+     gem install plain_apm -- --enable-object-tracing-override
+
+     When using bundler, you can configure it to pass this flag to the gem
+     install by running:
+
+     bundle config set --global build.plain_apm --enable-object-tracing-override
+
+     See also:
+
+     https://bugs.ruby-lang.org/issues/18464
+     https://bugs.ruby-lang.org/issues/19112
+
+  MSG
+  )
+end
+
+def try_ruby(file)
+  system("ruby", "-W0", File.join(__dir__, file), [:out, :err] => File::NULL)
+end
+
+def enable_object_tracing
+  $defs.push("-DOBJECT_TRACING_ENABLED") unless $defs.include? "-DOBJECT_TRACING_ENABLED"
+end
+
+%w(
+  ruby/ruby.h
+  ruby/debug.h
+).each do |header|
+  have_header(header) or abort_on_missing_ruby_header(header)
+end
+
+if enable_config("object-tracing-override", false)
+  enable_object_tracing
+else
+  bugs = %w(bug18464.rb bug19112).count { |f| !try_ruby(f) }
+
+  if bugs.zero?
+    enable_object_tracing
+  else
+    warn_on_ruby_ractor_bugs
+  end
+end
 
 create_makefile("object_tracing")

data/ext/object_tracing/object_tracing.c

@@ -1,25 +1,56 @@
 #include <ruby/ruby.h>
 #include <ruby/debug.h>
 
+static VALUE rb_mPlainApm = Qnil;
+static VALUE rb_mObjTracing = Qnil;
+
 static __thread uint64_t allocated_objects = 0;
 
-static VALUE rb_mPlainApm;
-static VALUE rb_mObjTracing;
-
-static VALUE total_thread_allocated_objects(VALUE self) {
-  return ULL2NUM(allocated_objects);
-}
+#ifdef OBJECT_TRACING_ENABLED
+static int object_tracing_active = 0;
 
 static void track_thread_allocated_objects(VALUE tpval, void *data) {
   allocated_objects++;
 }
+#endif
+
+static VALUE total_thread_allocated_objects(VALUE self) {
+  return ULL2NUM(allocated_objects);
+}
 
 void Init_object_tracing(void) {
   rb_mPlainApm = rb_define_module("PlainApm");
+  rb_gc_register_address(&rb_mPlainApm);
+
   rb_mObjTracing = rb_define_module_under(rb_mPlainApm, "ObjectTracing");
+  rb_gc_register_address(&rb_mObjTracing);
 
   rb_define_singleton_method(rb_mObjTracing, "total_thread_allocated_objects", total_thread_allocated_objects, 0);
 
+#ifdef OBJECT_TRACING_ENABLED
+  /* Ensure the tracepoint is attached only once. */
+  if (object_tracing_active) { return; }
+
+  object_tracing_active = 1;
+
+  /* Object allocation tracing is impacted by these bugs:
+   *
+   * https://bugs.ruby-lang.org/issues/19112 in Rubies 3.x.x
+   * https://bugs.ruby-lang.org/issues/18464 in Rubies 3.0, 3.1, and 3.2
+   *
+   * According to
+   *
+   * https://www.ruby-lang.org/en/downloads/branches/
+   *
+   * 3.0 goes out of maintenance mid 2024. The latter bug was backported to the
+   * other branches.
+   *
+   * For the former, there's https://github.com/ruby/ruby/pull/7184 open,
+   * unmerged as of Dec 2023.
+   *
+   */
+
   VALUE tpval = rb_tracepoint_new(0, RUBY_INTERNAL_EVENT_NEWOBJ, track_thread_allocated_objects, NULL);
   rb_tracepoint_enable(tpval);
+#endif
 }

data/lib/plain_apm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PlainApm
-  VERSION = "0.8.3"
+  VERSION = "0.8.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: plain_apm
 version: !ruby/object:Gem::Version
-  version: 0.8.3
+  version: 0.8.4
 platform: ruby
 authors:
 - PlainAPM Team
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-12-29 00:00:00.000000000 Z
+date: 2024-01-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -92,6 +92,8 @@ files:
 - Gemfile
 - LICENSE.txt
 - README.md
+- ext/object_tracing/bug18464.rb
+- ext/object_tracing/bug19112.rb
 - ext/object_tracing/extconf.rb
 - ext/object_tracing/object_tracing.c
 - lib/plain_apm.rb
@@ -130,7 +132,11 @@ metadata:
   source_code_uri: https://github.com/plainapm/plainapm-ruby
   changelog_uri: https://github.com/plainapm/plainapm-ruby/blob/main/CHANGELOG.md
   github_repo: git@github.com:plainapm/plainapm-ruby.git
-post_install_message: 
+post_install_message: "\n      PlainAPM object tracing is affected by Ractor related
+  bugs,\n      so it is not enabled by default on Ruby 3.\n\n      If you are sure
+  your app does not use Ractors, this can be overridden by\n      installing the gem
+  with --enable-object-tracing-override flag.\n\n      Please see https://github.com/plainapm/plainapm-ruby/#installation
+  for\n      more details.\n    "
 rdoc_options: []
 require_paths:
 - lib
@@ -138,7 +144,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="