lowlevel-toolkit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 05352e9b9bcf1c5e9edd57e688fc408ce72897baa33aaeb193a951be63729509
+  data.tar.gz: 379bd52a3d6a5d4f4fe85a907db67b4bcc32dffe758594031caf28b6eb3befe3
+SHA512:
+  metadata.gz: 1126decf4abb9208ac5da0c32aad2be86dbd8cbf017f7074087f7066dbe9e22330ccd0b7400e7add3a40ce5f9c896b640e55d2a08a53da2cf58ea3d5ada62a73
+  data.tar.gz: 90bf7dbbe6e8d22a0c608c1a371b0861add4d57e8ecd7804706c6c7ad340fb9580966f94f88ac300223adbbb488065c047ca50222e31b3c9e30f99179564569a

data/CODE_OF_CONDUCT.adoc

@@ -0,0 +1,134 @@
+
+= Contributor Covenant Code of Conduct
+
+== Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+== Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+== Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+== Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+== Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+ivo@ivoanjo.me.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+== Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+=== 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+=== 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+=== 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+=== 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+== Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant,
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by
+Mozilla's code of conduct enforcement ladder.
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.
+
+
+
+
+
+
+

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ivo Anjo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.adoc

@@ -0,0 +1,86 @@
+= `lowlevel-toolkit`
+:toc:
+:toc-placement: macro
+:toclevels: 4
+:toc-title:
+
+A Ruby gem that provides access to low-level observability APIs for Ruby applications, allowing you to track and analyze various aspects of your Ruby program's behavior.
+
+More than the individual APIs provided, the objective of this gem is to be a repository of examples on **how to use these APIs for doing analysis**. It's expected to be a starting point when building tools.
+
+== Quickest start
+
+Here's a simple example of tracking GVL (Global VM Lock) usage in your application:
+
+[source,ruby]
+----
+require 'lowlevel-toolkit'
+
+def counter_loop(counter = 0) = (counter += 1 while counter < 150_000_000)
+
+pp(LowlevelToolkit.track_wants_gvl do
+  t1 = Thread.new { counter_loop }.tap { |it| it.name = 't1' }
+  t2 = Thread.new { counter_loop }.tap { |it| it.name = 't2' }
+
+  t1.join; t2.join
+end.map { |thread, wants_gvl_ns| [thread, wants_gvl_ns / 1_000_000_000.0] })
+----
+
+== Installation
+
+Install the gem and add to the application's `Gemfile` or `gems.rb` file by executing:
+
+[source,bash]
+----
+$ bundle add lowlevel-toolkit
+----
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+[source,bash]
+----
+$ gem install lowlevel-toolkit
+----
+
+== Usage
+
+Use `require "lowlevel-toolkit"` to load the gem.
+
+The gem provides several low-level observability features:
+
+* `track_wants_gvl`: Track when threads want to acquire the Global VM Lock
+* `track_objects_created`: Monitor object creation in your application
+* `last_allocation_at`: Get information about the last object allocation
+* `on_gc_finish`: Set up callbacks for when garbage collection finishes
+* `who_called_me`: Track the call stack of method invocations
+* `release_gvl_profiler`: Profile GVL release patterns
+
+== Examples
+
+The gem comes with several examples in the `examples/` directory:
+
+* `track_wants_gvl.rb`: Shows how to track GVL usage across threads
+* `track_objects_created.rb`: Demonstrates object creation tracking
+* `last_allocation_at.rb`: Shows how to get information about the last allocation
+* `on_gc_finish.rb`: Example of setting up GC finish callbacks
+* `who_called_me.rb`: Demonstrates call stack tracking
+* `print_gc_timing.rb`: Shows GC timing information
+* `release_gvl_profiler.rb`: Example of GVL release profiling
+
+== Requirements
+
+This gem requires Ruby 3.3.0 or above. Patches welcome to extend support for older Rubies :)
+
+== Development
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to https://rubygems.org[rubygems.org]. To run specs, run `bundle exec rake spec`.
+
+To run all actions (build the extension, check linting, and run specs), run `bundle exec rake`.
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ivoanjo/lowlevel-toolkit. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the https://github.com/ivoanjo/lowlevel-toolkit/blob/master/CODE_OF_CONDUCT.adoc[code of conduct].
+
+== Code of Conduct
+
+Everyone interacting in the lowlevel-toolkit project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the https://github.com/ivoanjo/lowlevel-toolkit/blob/master/CODE_OF_CONDUCT.adoc[code of conduct].

data/ext/lowlevel_toolkit_native_extension/extconf.rb

@@ -0,0 +1,43 @@
+# lowlevel-toolkit: Ruby gem for calling observability APIs
+# Copyright (c) 2025 Ivo Anjo <ivo@ivoanjo.me>
+#
+# This file is part of lowlevel-toolkit.
+#
+# MIT License
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+if ["jruby", "truffleruby"].include?(RUBY_ENGINE)
+  raise \
+    "\n#{"-" * 80}\nSorry! This gem is unsupported on #{RUBY_ENGINE}. Since it relies on a lot of guts of MRI Ruby, " \
+    "it's impossible to make a direct port.\n" \
+    "Perhaps a #{RUBY_ENGINE} equivalent could be created -- help is welcome! :)\n#{"-" * 80}"
+end
+
+require "mkmf"
+
+append_cflags("-Werror-implicit-function-declaration")
+append_cflags("-Wunused-parameter")
+append_cflags("-Wold-style-definition")
+append_cflags("-Wall")
+append_cflags("-Wextra")
+append_cflags("-Werror") if ENV["ENABLE_WERROR"] == "true"
+
+create_header
+create_makefile "lowlevel_toolkit_native_extension"

data/ext/lowlevel_toolkit_native_extension/last_allocation_at.c

@@ -0,0 +1,42 @@
+#include <ruby/ruby.h>
+#include <ruby/debug.h>
+
+int rb_objspace_internal_object_p(VALUE obj);
+
+#define MAX_DEPTH 1000
+static VALUE stack = Qnil;
+
+static void on_newobj_event(VALUE tpval, RB_UNUSED_VAR(void *_)) {
+  if (stack == Qnil ||
+    rb_objspace_internal_object_p(rb_tracearg_object(rb_tracearg_from_tracepoint(tpval)))) return;
+  VALUE buffer[MAX_DEPTH];
+  int depth = rb_profile_frames(0, MAX_DEPTH, buffer, NULL);
+  rb_ary_clear(stack);
+  for (int i = 0; i < depth; i++) rb_ary_push(stack, buffer[i]);
+}
+
+static VALUE track_last_allocation_at(RB_UNUSED_VAR(VALUE _)) {
+  stack = rb_ary_new_capa(MAX_DEPTH);
+  VALUE tp = rb_tracepoint_new(0, RUBY_INTERNAL_EVENT_NEWOBJ, on_newobj_event, NULL);
+  rb_tracepoint_enable(tp); rb_yield(Qnil); rb_tracepoint_disable(tp);
+  return Qnil;
+}
+
+static VALUE last_allocation_at(RB_UNUSED_VAR(VALUE _)) {
+  VALUE raw_stack = stack;
+  stack = Qnil; // Pause recording of stacks while we're doing the copying below
+  VALUE result = rb_ary_new();
+  for (int i = 0; i < RARRAY_LEN(raw_stack); i++) {
+    VALUE entry = rb_ary_entry(raw_stack, i);
+    VALUE file = rb_profile_frame_path(entry);
+    if (file != Qnil) rb_ary_push(result, rb_ary_new_from_args(2, file, rb_profile_frame_base_label(entry)));
+  }
+  stack = raw_stack; // Resume recording again
+  return result;
+}
+
+void init_last_allocation_at(VALUE lowlevel_toolkit_module) {
+  rb_global_variable(&stack);
+  rb_define_singleton_method(lowlevel_toolkit_module, "track_last_allocation_at", track_last_allocation_at, 0);
+  rb_define_singleton_method(lowlevel_toolkit_module, "last_allocation_at", last_allocation_at, 0);
+}

data/ext/lowlevel_toolkit_native_extension/lowlevel_toolkit.c

@@ -0,0 +1,47 @@
+// lowlevel-toolkit: Ruby gem for calling observability APIs
+// Copyright (c) 2025 Ivo Anjo <ivo@ivoanjo.me>
+//
+// This file is part of lowlevel-toolkit.
+//
+// MIT License
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+#include <ruby/ruby.h>
+#include <ruby/debug.h>
+
+void init_track_objects_created(VALUE lowlevel_toolkit_module);
+void init_print_gc_timing(VALUE lowlevel_toolkit_module);
+void init_on_gc_finish(VALUE lowlevel_toolkit_module);
+void init_who_called_me(VALUE lowlevel_toolkit_module);
+void init_last_allocation_at(VALUE lowlevel_toolkit_module);
+void init_track_wants_gvl(VALUE lowlevel_toolkit_module);
+void init_release_gvl_profiler(VALUE lowlevel_toolkit_module);
+
+void Init_lowlevel_toolkit_native_extension(void) {
+  VALUE lowlevel_toolkit_module = rb_define_module("LowlevelToolkit");
+
+  init_track_objects_created(lowlevel_toolkit_module);
+  init_print_gc_timing(lowlevel_toolkit_module);
+  init_on_gc_finish(lowlevel_toolkit_module);
+  init_last_allocation_at(lowlevel_toolkit_module);
+  init_who_called_me(lowlevel_toolkit_module);
+  init_track_wants_gvl(lowlevel_toolkit_module);
+  init_release_gvl_profiler(lowlevel_toolkit_module);
+}

data/ext/lowlevel_toolkit_native_extension/on_gc_finish.c

@@ -0,0 +1,22 @@
+#include <ruby/ruby.h>
+#include <ruby/debug.h>
+
+static VALUE callback = Qnil;
+static rb_postponed_job_handle_t postponed_id = 0;
+
+static void postponed(RB_UNUSED_VAR(void *data)) { rb_funcall(callback, rb_intern("call"), 0); }
+static void on_gc_finish_event(RB_UNUSED_VAR(VALUE _), RB_UNUSED_VAR(void *__)) { rb_postponed_job_trigger(postponed_id); }
+
+static VALUE on_gc_finish(RB_UNUSED_VAR(VALUE _), VALUE user_callback) {
+  callback = user_callback;
+  VALUE tp = rb_tracepoint_new(0, RUBY_INTERNAL_EVENT_GC_EXIT, on_gc_finish_event, NULL);
+  rb_tracepoint_enable(tp); rb_yield(Qnil); rb_tracepoint_disable(tp);
+  return Qnil;
+}
+
+void init_on_gc_finish(VALUE lowlevel_toolkit_module) {
+  postponed_id = rb_postponed_job_preregister(0, postponed, NULL);
+  if (postponed_id == POSTPONED_JOB_HANDLE_INVALID) rb_raise(rb_eRuntimeError, "Failed to register postponed job");
+  rb_global_variable(&callback);
+  rb_define_singleton_method(lowlevel_toolkit_module, "on_gc_finish", on_gc_finish, 1);
+}

data/ext/lowlevel_toolkit_native_extension/print_gc_timing.c

@@ -0,0 +1,29 @@
+#include <ruby/ruby.h>
+#include <ruby/debug.h>
+
+static uint64_t get_monotonic_time_ns(void) {
+  struct timespec ts;
+  clock_gettime(CLOCK_MONOTONIC, &ts);
+  return (uint64_t) ts.tv_sec * 1000000000ULL + (uint64_t) ts.tv_nsec;
+}
+
+static void on_gc_event(VALUE tpval, RB_UNUSED_VAR(void *_)) {
+  static uint64_t gc_start_time = 0;
+  rb_event_flag_t event = rb_tracearg_event_flag(rb_tracearg_from_tracepoint(tpval));
+
+  if (event == RUBY_INTERNAL_EVENT_GC_ENTER) {
+    gc_start_time = get_monotonic_time_ns();
+  } else if (event == RUBY_INTERNAL_EVENT_GC_EXIT) {
+    fprintf(stdout, "GC worked for %.2f ms\n", ((get_monotonic_time_ns() - gc_start_time) / 1000000.0));
+  }
+}
+
+static VALUE print_gc_timing(RB_UNUSED_VAR(VALUE _)) {
+  VALUE tp = rb_tracepoint_new(0, RUBY_INTERNAL_EVENT_GC_ENTER | RUBY_INTERNAL_EVENT_GC_EXIT, on_gc_event, NULL);
+  rb_tracepoint_enable(tp); rb_yield(Qnil); rb_tracepoint_disable(tp);
+  return Qnil;
+}
+
+void init_print_gc_timing(VALUE lowlevel_toolkit_module) {
+  rb_define_singleton_method(lowlevel_toolkit_module, "print_gc_timing", print_gc_timing, 0);
+}

data/ext/lowlevel_toolkit_native_extension/release_gvl_profiler.c

@@ -0,0 +1,108 @@
+#include <ruby/ruby.h>
+#include <ruby/thread.h>
+#include <ruby/debug.h>
+#include <time.h>
+
+int ruby_thread_has_gvl_p(void);
+
+#define MAX_STACK_DEPTH 1000
+static int release_gvl_at_key;
+
+static uint64_t get_monotonic_time_ns(void) {
+  struct timespec ts;
+  clock_gettime(CLOCK_MONOTONIC, &ts);
+  return (uint64_t) ts.tv_sec * 1000000000ULL + (uint64_t) ts.tv_nsec;
+}
+
+static void on_thread_event(rb_event_flag_t event_id, const rb_internal_thread_event_data_t *event_data, void *data) {
+  VALUE thread = event_data->thread;
+
+  if (event_id == RUBY_INTERNAL_THREAD_EVENT_SUSPENDED && !ruby_thread_has_gvl_p()) {
+    rb_internal_thread_specific_set(thread, release_gvl_at_key, (void *) get_monotonic_time_ns());
+  } else if (event_id == RUBY_INTERNAL_THREAD_EVENT_RESUMED) {
+    uint64_t release_gvl_at = (uint64_t) rb_internal_thread_specific_get(thread, release_gvl_at_key);
+    if (release_gvl_at == 0) return;
+    rb_internal_thread_specific_set(thread, release_gvl_at_key, 0);
+
+    // If we wanted to delay processing the backtrace, we could switch to rb_profile_frames() here
+    VALUE frames = rb_make_backtrace();
+    VALUE result = (VALUE) data;
+
+    VALUE stats = rb_hash_aref(result, frames);
+    if (stats == Qnil) {
+      stats = rb_ary_new_from_args(2, INT2FIX(0), INT2FIX(0));
+      rb_hash_aset(result, frames, stats);
+    }
+
+    uint64_t time_spent = get_monotonic_time_ns() - release_gvl_at;
+    rb_ary_store(stats, 0, ULL2NUM(NUM2ULL(rb_ary_entry(stats, 0)) + time_spent));
+    rb_ary_store(stats, 1, ULL2NUM(NUM2ULL(rb_ary_entry(stats, 1)) + 1));
+  }
+}
+
+static void write_stacks(VALUE filename_prefix, VALUE result) {
+  VALUE time_filename = rb_str_concat(rb_str_dup(filename_prefix), rb_str_new_cstr("_time.folded"));
+  VALUE counts_filename = rb_str_concat(rb_str_dup(filename_prefix), rb_str_new_cstr("_counts.folded"));
+
+  VALUE clean_prefix = rb_hash_aref(rb_const_get(rb_const_get(rb_cObject, rb_intern("RbConfig")), rb_intern("CONFIG")), rb_str_new_cstr("rubylibdir"));
+  VALUE prefix_replacement = rb_str_new_cstr("ruby");
+
+  FILE *time_file = fopen(StringValueCStr(time_filename), "w");
+  FILE *counts_file = fopen(StringValueCStr(counts_filename), "w");
+
+  if (!time_file || !counts_file) {
+    if (time_file) fclose(time_file);
+    if (counts_file) fclose(counts_file);
+    rb_raise(rb_eIOError, "Failed to open output files");
+  }
+
+  VALUE keys = rb_funcall(result, rb_intern("keys"), 0);
+  long key_count = RARRAY_LEN(keys);
+  for (long i = 0; i < key_count; i++) {
+    VALUE frames = rb_ary_entry(keys, i);
+    VALUE stats = rb_hash_aref(result, frames);
+
+    long frame_count = RARRAY_LEN(frames);
+    for (long j = frame_count - 1; j >= 0; j--) {
+      if (j < frame_count - 1) {
+        fprintf(time_file, ";");
+        fprintf(counts_file, ";");
+      }
+
+      VALUE frame = rb_ary_entry(frames, j);
+      if (clean_prefix != Qnil) rb_funcall(frame, rb_intern("sub!"), 2, clean_prefix, prefix_replacement); // Make files in ruby stdlib a bit neater
+      fprintf(time_file, "%s", StringValueCStr(frame));
+      fprintf(counts_file, "%s", StringValueCStr(frame));
+    }
+
+    fprintf(time_file, " %llu\n", NUM2ULL(rb_ary_entry(stats, 0)));
+    fprintf(counts_file, " %llu\n", NUM2ULL(rb_ary_entry(stats, 1)));
+  }
+
+  fclose(time_file);
+  fclose(counts_file);
+}
+
+static VALUE release_gvl_profiler(int argc, VALUE *argv, RB_UNUSED_VAR(VALUE _)) {
+  VALUE options;
+  rb_scan_args(argc, argv, "0:", &options);
+  if (options == Qnil) options = rb_hash_new();
+  VALUE filename_prefix = rb_hash_fetch(options, ID2SYM(rb_intern("filename_prefix")));
+
+  VALUE result = rb_hash_new();
+  rb_internal_thread_event_hook_t *hook = rb_internal_thread_add_event_hook(
+    on_thread_event,
+    RUBY_INTERNAL_THREAD_EVENT_SUSPENDED | RUBY_INTERNAL_THREAD_EVENT_RESUMED,
+    (void *) result
+  );
+  rb_yield(Qnil);
+  rb_internal_thread_remove_event_hook(hook);
+
+  write_stacks(filename_prefix, result);
+  return result;
+}
+
+void init_release_gvl_profiler(VALUE lowlevel_toolkit_module) {
+  release_gvl_at_key = rb_internal_thread_specific_key_create();
+  rb_define_singleton_method(lowlevel_toolkit_module, "release_gvl_profiler", release_gvl_profiler, -1);
+}

data/ext/lowlevel_toolkit_native_extension/track_objects_created.c

@@ -0,0 +1,26 @@
+#include <ruby/ruby.h>
+#include <ruby/debug.h>
+
+int rb_objspace_internal_object_p(VALUE obj);
+
+static void on_newobj_event(VALUE tpval, void *data) {
+  VALUE obj = rb_tracearg_object(rb_tracearg_from_tracepoint(tpval));
+  if (!rb_objspace_internal_object_p(obj)) rb_ary_push((VALUE) data, obj);
+}
+
+static VALUE filter_hidden_objects(VALUE result) {
+  for (int i = 0; i < RARRAY_LEN(result); i++)
+    if (!RBASIC_CLASS(rb_ary_entry(result, i))) rb_ary_store(result, i, Qnil);
+  return result;
+}
+
+static VALUE track_objects_created(RB_UNUSED_VAR(VALUE _)) {
+  VALUE result = rb_ary_new();
+  VALUE tp = rb_tracepoint_new(0, RUBY_INTERNAL_EVENT_NEWOBJ, on_newobj_event, (void *) result);
+  rb_tracepoint_enable(tp); rb_yield(Qnil); rb_tracepoint_disable(tp);
+  return filter_hidden_objects(result);
+}
+
+void init_track_objects_created(VALUE lowlevel_toolkit_module) {
+  rb_define_singleton_method(lowlevel_toolkit_module, "track_objects_created", track_objects_created, 0);
+}

data/ext/lowlevel_toolkit_native_extension/track_wants_gvl.c

@@ -0,0 +1,48 @@
+#include <ruby/ruby.h>
+#include <ruby/debug.h>
+#include <ruby/thread.h>
+
+static uint64_t get_monotonic_time_ns(void) {
+  struct timespec ts;
+  clock_gettime(CLOCK_MONOTONIC, &ts);
+  return (uint64_t) ts.tv_sec * 1000000000ULL + (uint64_t) ts.tv_nsec;
+}
+
+static int wants_gvl_at_key;
+static int total_wants_key;
+
+static void on_thread_event(rb_event_flag_t event_id, const rb_internal_thread_event_data_t *event_data, void *data) {
+  VALUE thread = event_data->thread;
+  if (event_id == RUBY_INTERNAL_THREAD_EVENT_STARTED) {
+    rb_ary_push((VALUE) data, thread);
+  } else if (event_id == RUBY_INTERNAL_THREAD_EVENT_READY) {
+    rb_internal_thread_specific_set(thread, wants_gvl_at_key, (void *) get_monotonic_time_ns());
+  } else if (event_id == RUBY_INTERNAL_THREAD_EVENT_RESUMED) {
+    uint64_t wants_gvl_at = (uint64_t) rb_internal_thread_specific_get(thread, wants_gvl_at_key);
+    if (wants_gvl_at == 0) return;
+    uint64_t total_wants = (uint64_t) rb_internal_thread_specific_get(thread, total_wants_key);
+    rb_internal_thread_specific_set(
+      thread, total_wants_key, (void *) (total_wants + (get_monotonic_time_ns() - wants_gvl_at)));
+  }
+}
+
+VALUE track_wants_gvl(RB_UNUSED_VAR(VALUE _)) {
+  VALUE seen_threads = rb_ary_new();
+  rb_internal_thread_event_hook_t *hook =
+    rb_internal_thread_add_event_hook(
+      on_thread_event, RUBY_INTERNAL_THREAD_EVENT_STARTED | RUBY_INTERNAL_THREAD_EVENT_READY | RUBY_INTERNAL_THREAD_EVENT_RESUMED, (void *) seen_threads);
+  rb_yield(Qnil);
+  rb_internal_thread_remove_event_hook(hook);
+  VALUE result = rb_hash_new();
+  for (int i = 0; i < RARRAY_LEN(seen_threads); i++) {
+    VALUE thread = rb_ary_entry(seen_threads, i);
+    rb_hash_aset(result, thread, ULL2NUM((uint64_t) rb_internal_thread_specific_get(thread, total_wants_key)));
+  }
+  return result;
+}
+
+void init_track_wants_gvl(VALUE lowlevel_toolkit_module) {
+  wants_gvl_at_key = rb_internal_thread_specific_key_create();
+  total_wants_key = rb_internal_thread_specific_key_create();
+  rb_define_singleton_method(lowlevel_toolkit_module, "track_wants_gvl", track_wants_gvl, 0);
+}

data/ext/lowlevel_toolkit_native_extension/who_called_me.c

@@ -0,0 +1,17 @@
+#include <ruby/ruby.h>
+#include <ruby/debug.h>
+
+static VALUE callback(const rb_debug_inspector_t *dbg_context, void *data) {
+  bool return_self = (data != NULL);
+  return return_self ?
+    // Depth: 0 -> us; 1 -> caller; 2 -> caller of caller
+    rb_debug_inspector_frame_self_get(dbg_context, 2) : rb_debug_inspector_frame_binding_get(dbg_context, 2);
+}
+
+static VALUE who_called_me(RB_UNUSED_VAR(VALUE _)) { return rb_debug_inspector_open(callback, (void *) !NULL); }
+static VALUE who_called_me_binding(RB_UNUSED_VAR(VALUE _)) { return rb_debug_inspector_open(callback, NULL); }
+
+void init_who_called_me(VALUE lowlevel_toolkit_module) {
+  rb_define_singleton_method(lowlevel_toolkit_module, "who_called_me", who_called_me, 0);
+  rb_define_singleton_method(lowlevel_toolkit_module, "who_called_me_binding", who_called_me_binding, 0);
+}

data/lib/lowlevel-toolkit.rb

@@ -0,0 +1,33 @@
+# lowlevel-toolkit: Ruby gem for calling observability APIs
+# Copyright (c) 2025 Ivo Anjo <ivo@ivoanjo.me>
+#
+# This file is part of lowlevel-toolkit.
+#
+# MIT License
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+# frozen_string_literal: true
+
+require_relative "lowlevel_toolkit/version"
+
+require "lowlevel_toolkit_native_extension"
+
+module LowlevelToolkit
+end

data/lib/lowlevel_toolkit/version.rb

@@ -0,0 +1,30 @@
+# lowlevel-toolkit: Ruby gem for calling observability APIs
+# Copyright (c) 2025 Ivo Anjo <ivo@ivoanjo.me>
+#
+# This file is part of lowlevel-toolkit.
+#
+# MIT License
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+# frozen_string_literal: true
+
+module LowlevelToolkit
+  VERSION = "0.1.0"
+end

data/lowlevel-toolkit.gemspec

@@ -0,0 +1,51 @@
+# lowlevel-toolkit: Ruby gem for calling observability APIs
+# Copyright (c) 2025 Ivo Anjo <ivo@ivoanjo.me>
+#
+# This file is part of lowlevel-toolkit.
+#
+# MIT License
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+# frozen_string_literal: true
+
+require_relative "lib/lowlevel_toolkit/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "lowlevel-toolkit"
+  spec.version = LowlevelToolkit::VERSION
+  spec.authors = ["Ivo Anjo"]
+  spec.email = ["ivo@ivoanjo.me"]
+
+  spec.summary = "Ruby gem for calling observability APIs"
+  spec.homepage = "https://github.com/ivoanjo/lowlevel-toolkit"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.3.0"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features|examples)/|\.(?:git|travis|circleci)|appveyor)}) ||
+        [".editorconfig", ".ruby-version", ".standard.yml", "gems.rb", "Rakefile"].include?(f)
+    end
+  end
+  spec.require_paths = ["lib", "ext"]
+  spec.extensions = ["ext/lowlevel_toolkit_native_extension/extconf.rb"]
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: lowlevel-toolkit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ivo Anjo
+bindir: bin
+cert_chain: []
+date: 2025-04-08 00:00:00.000000000 Z
+dependencies: []
+email:
+- ivo@ivoanjo.me
+executables: []
+extensions:
+- ext/lowlevel_toolkit_native_extension/extconf.rb
+extra_rdoc_files: []
+files:
+- CODE_OF_CONDUCT.adoc
+- LICENSE
+- README.adoc
+- ext/lowlevel_toolkit_native_extension/extconf.rb
+- ext/lowlevel_toolkit_native_extension/last_allocation_at.c
+- ext/lowlevel_toolkit_native_extension/lowlevel_toolkit.c
+- ext/lowlevel_toolkit_native_extension/on_gc_finish.c
+- ext/lowlevel_toolkit_native_extension/print_gc_timing.c
+- ext/lowlevel_toolkit_native_extension/release_gvl_profiler.c
+- ext/lowlevel_toolkit_native_extension/track_objects_created.c
+- ext/lowlevel_toolkit_native_extension/track_wants_gvl.c
+- ext/lowlevel_toolkit_native_extension/who_called_me.c
+- lib/lowlevel-toolkit.rb
+- lib/lowlevel_toolkit/version.rb
+- lowlevel-toolkit.gemspec
+homepage: https://github.com/ivoanjo/lowlevel-toolkit
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+- ext
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Ruby gem for calling observability APIs
+test_files: []