cirron 0.2.2

data/lib/cirron.rb

@@ -0,0 +1,2 @@
+require_relative 'tracer'
+require_relative 'collector'

data/lib/cirronlib.cpp

@@ -0,0 +1,321 @@
+#include <stdio.h>
+#include <string.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+#include <errno.h>
+#include <sys/ioctl.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+#if defined(__linux__)
+#include <linux/perf_event.h>
+#elif defined(__APPLE__)
+#include "apple_arm_events.h"
+#endif
+
+struct counter
+{
+    uint64_t time_enabled_ns;
+    uint64_t instruction_count;
+    uint64_t branch_misses;
+    uint64_t page_faults;
+};
+
+extern "C"
+{
+    int start();
+    int end(int fd, struct counter *out);
+}
+
+#if defined(__linux__)
+struct read_format
+{
+    uint64_t nr;
+    uint64_t time_enabled;
+    uint64_t time_running;
+    struct
+    {
+        uint64_t value;
+    } values[];
+};
+
+struct perf_event_config
+{
+    uint64_t type;
+    uint64_t config;
+};
+
+struct perf_event_config events[] = {
+    {PERF_TYPE_HARDWARE, PERF_COUNT_HW_INSTRUCTIONS},
+    {PERF_TYPE_HARDWARE, PERF_COUNT_HW_BRANCH_MISSES},
+    {PERF_TYPE_SOFTWARE, PERF_COUNT_SW_PAGE_FAULTS},
+    // {PERF_TYPE_SOFTWARE, PERF_COUNT_SW_CONTEXT_SWITCHES}, For whatever reason, these two always show 0
+    // {PERF_TYPE_SOFTWARE, PERF_COUNT_SW_CPU_MIGRATIONS},
+};
+
+const int NUM_EVENTS = sizeof(events) / sizeof(events[0]);
+#elif defined(__APPLE__)
+u64 counters_0[KPC_MAX_COUNTERS] = {0};
+usize counter_map[KPC_MAX_COUNTERS] = {0};
+#endif
+
+int start()
+{
+#if defined(__linux__)
+    // Construct base perf_event_attr struct
+    struct perf_event_attr attr;
+    memset(&attr, 0, sizeof(attr));
+    attr.size = sizeof(attr);
+    attr.disabled = 1;
+    attr.exclude_kernel = 1;
+    attr.exclude_hv = 1;
+    attr.sample_period = 0;
+    attr.read_format = PERF_FORMAT_GROUP | PERF_FORMAT_TOTAL_TIME_ENABLED | PERF_FORMAT_TOTAL_TIME_RUNNING;
+
+    int group = -1;
+    int leader_fd;
+
+    // Enable every event in perf_event_config
+    for (int i = 0; i < NUM_EVENTS; i++)
+    {
+        attr.type = events[i].type;
+        attr.config = events[i].config;
+
+        int fd = syscall(SYS_perf_event_open, &attr, 0, -1, group, 0);
+        if (fd == -1)
+        {
+            fprintf(stderr, "Failed to open event %lu: %s.\n", events[i].config, strerror(errno));
+            return -1;
+        }
+
+        if (i == 0)
+        {
+            group = fd;
+            leader_fd = fd;
+        }
+    }
+
+    // Enable the event group
+    if (ioctl(leader_fd, PERF_EVENT_IOC_ENABLE, PERF_IOC_FLAG_GROUP) == -1)
+    {
+        fprintf(stderr, "Failed to enable perf events: %s.\n", strerror(errno));
+        // Consider cleaning up previously opened file descriptors here
+        return -1;
+    }
+
+    return leader_fd;
+#elif defined(__APPLE__)
+    // load dylib
+    if (!lib_init())
+    {
+        printf("Error: %s\n", lib_err_msg);
+        return 1;
+    }
+
+    // check permission
+    int force_ctrs = 0;
+    if (kpc_force_all_ctrs_get(&force_ctrs))
+    {
+        printf("Permission denied, xnu/kpc requires root privileges.\n");
+        return 1;
+    }
+
+    // load pmc db
+    int ret = 0;
+    kpep_db *db = NULL;
+    if ((ret = kpep_db_create("a9", &db)))
+    {
+        printf("Error: cannot load pmc database: %d.\n", ret);
+        return 1;
+    }
+
+    // create a config
+    kpep_config *cfg = NULL;
+    if ((ret = kpep_config_create(db, &cfg)))
+    {
+        printf("Failed to create kpep config: %d (%s).\n",
+               ret, kpep_config_error_desc(ret));
+        return 1;
+    }
+    if ((ret = kpep_config_force_counters(cfg)))
+    {
+        printf("Failed to force counters: %d (%s).\n",
+               ret, kpep_config_error_desc(ret));
+        return 1;
+    }
+
+    // get events
+    const usize ev_count = sizeof(profile_events) / sizeof(profile_events[0]);
+    kpep_event *ev_arr[ev_count] = {0};
+    for (usize i = 0; i < ev_count; i++)
+    {
+        const event_alias *alias = profile_events + i;
+        ev_arr[i] = get_event(db, alias);
+        if (!ev_arr[i])
+        {
+            printf("Cannot find event: %s.\n", alias->alias);
+            return 1;
+        }
+    }
+
+    // add event to config
+    for (usize i = 0; i < ev_count; i++)
+    {
+        kpep_event *ev = ev_arr[i];
+        if ((ret = kpep_config_add_event(cfg, &ev, 0, NULL)))
+        {
+            printf("Failed to add event: %d (%s).\n",
+                   ret, kpep_config_error_desc(ret));
+            return 1;
+        }
+    }
+
+    // prepare buffer and config
+    u32 classes = 0;
+    usize reg_count = 0;
+    kpc_config_t regs[KPC_MAX_COUNTERS] = {0};
+    if ((ret = kpep_config_kpc_classes(cfg, &classes)))
+    {
+        printf("Failed get kpc classes: %d (%s).\n",
+               ret, kpep_config_error_desc(ret));
+        return 1;
+    }
+    if ((ret = kpep_config_kpc_count(cfg, &reg_count)))
+    {
+        printf("Failed get kpc count: %d (%s).\n",
+               ret, kpep_config_error_desc(ret));
+        return 1;
+    }
+    if ((ret = kpep_config_kpc_map(cfg, counter_map, sizeof(counter_map))))
+    {
+        printf("Failed get kpc map: %d (%s).\n",
+               ret, kpep_config_error_desc(ret));
+        return 1;
+    }
+    if ((ret = kpep_config_kpc(cfg, regs, sizeof(regs))))
+    {
+        printf("Failed get kpc registers: %d (%s).\n",
+               ret, kpep_config_error_desc(ret));
+        return 1;
+    }
+
+    // set config to kernel
+    if ((ret = kpc_force_all_ctrs_set(1)))
+    {
+        printf("Failed force all ctrs: %d.\n", ret);
+        return 1;
+    }
+    if ((classes & KPC_CLASS_CONFIGURABLE_MASK) && reg_count)
+    {
+        if ((ret = kpc_set_config(classes, regs)))
+        {
+            printf("Failed set kpc config: %d.\n", ret);
+            return 1;
+        }
+    }
+
+    // start counting
+    if ((ret = kpc_set_counting(classes)))
+    {
+        printf("Failed set counting: %d.\n", ret);
+        return 1;
+    }
+    if ((ret = kpc_set_thread_counting(classes)))
+    {
+        printf("Failed set thread counting: %d.\n", ret);
+        return 1;
+    }
+
+    // get counters before
+    if ((ret = kpc_get_thread_counters(0, KPC_MAX_COUNTERS, counters_0)))
+    {
+        printf("Failed get thread counters before: %d.\n", ret);
+        return 1;
+    }
+
+    return 0;
+#else
+    printf("This systems seems to be neither Linux, nor ARM OSX, so I don't know how to proceeed.\nIf this is a mistake, please open an issue on the GitHub repository.\n");
+    return -1;
+#endif
+}
+
+int end(int fd, struct counter *out)
+{
+#if defined(__linux__)
+    if (out == NULL)
+    {
+        fprintf(stderr, "Error: 'out' pointer is NULL in end().\n");
+        return -1;
+    }
+
+    // Disable the event group
+    if (ioctl(fd, PERF_EVENT_IOC_DISABLE, PERF_IOC_FLAG_GROUP) == -1)
+    {
+        fprintf(stderr, "Error disabling perf event (fd: %d): %s\n", fd, strerror(errno));
+        return -1;
+    }
+
+    // Allocate buffer for reading results
+    int size = sizeof(struct read_format) + (sizeof(uint64_t) * NUM_EVENTS);
+    struct read_format *buffer = (struct read_format *)malloc(size);
+    if (!buffer)
+    {
+        fprintf(stderr, "Failed to allocate memory for read buffer.\n");
+        return -1;
+    }
+
+    // Read results
+    int ret_val = read(fd, buffer, size);
+    if (ret_val == -1)
+    {
+        fprintf(stderr, "Error reading perf event results: %s\n", strerror(errno));
+        free(buffer);
+        return -1;
+    }
+    else if (ret_val != size)
+    {
+        fprintf(stderr, "Error reading perf event results: read %d bytes, expected %d\n", ret_val, size);
+        free(buffer);
+        return -1;
+    }
+
+    // Assign time_enabled_ns
+    out->time_enabled_ns = buffer->time_enabled;
+
+    // Directly assign values to struct fields treating them as an array 8)
+    uint64_t *counter_ptr = (uint64_t *)out;
+    counter_ptr++; // Now points to instruction_count, the first counter field
+
+    for (int i = 0; i < NUM_EVENTS; i++)
+    {
+        counter_ptr[i] = buffer->values[i].value;
+    }
+
+    close(fd);
+    free(buffer);
+    return 0;
+#elif defined(__APPLE__)
+    // get counters after
+    int ret = 0;
+    u64 counters_1[KPC_MAX_COUNTERS] = {0};
+    if ((ret = kpc_get_thread_counters(0, KPC_MAX_COUNTERS, counters_1)))
+    {
+        printf("Failed get thread counters after: %d.\n", ret);
+        return 1;
+    }
+
+    kpc_set_counting(0);
+    kpc_set_thread_counting(0);
+    kpc_force_all_ctrs_set(0);
+
+    out->time_enabled_ns = 0;
+    out->instruction_count = counters_1[counter_map[1]] - counters_0[counter_map[1]];
+    out->page_faults = 0;
+    out->branch_misses = counters_1[counter_map[3]] - counters_0[counter_map[3]];
+    return 0;
+#else
+    printf("This systems seems to be neither Linux, nor OSX, so I don't know how to proceeed.\nIf this is a mistake, please open an issue on the GitHub repository.\n");
+    return -1;
+#endif
+}

data/lib/collector.rb

@@ -0,0 +1,70 @@
+require 'ffi'
+
+module CirronInterOp
+  extend FFI::Library
+
+  lib_path = File.join(__dir__, 'cirronlib.so')
+  source_path = File.join(__dir__, 'cirronlib.cpp')
+
+  unless File.exist?(lib_path)
+    exit_status = system("c++ -std=c++17 -O3 -shared -fPIC -o #{lib_path} #{source_path}")
+    if exit_status.nil? || !exit_status
+      raise "Failed to compile cirronlib.cpp, make sure you have 'c++' installed."
+    end
+  end
+
+  ffi_lib lib_path
+  attach_function :start, [], :int
+  attach_function :end, [:int, :pointer], :int
+end
+
+class Counter < FFI::Struct
+  layout :time_enabled_ns, :uint64,
+         :instruction_count, :uint64,
+         :branch_misses, :uint64,
+         :page_faults, :uint64
+
+  def self.create_accessors
+    layout.members.each do |field|
+      define_method(field) { self[field] }
+      define_method("#{field}=") { |value| self[field] = value }
+    end
+  end
+
+  create_accessors
+
+  def to_s
+    inspect
+  end
+
+  def inspect
+    fields = self.class.layout.members.map do |field|
+      "#{field}: #{self[field]}"
+    end
+    "Counter(#{fields.join(', ')})"
+  end
+end
+
+module Cirron
+  def self.start
+    ret_val = CirronInterOp.start
+    if ret_val == -1
+      raise "Failed to start collector"
+    end
+    ret_val
+  end
+
+  def self.end(fd, counter)
+    CirronInterOp.end(fd, counter)
+  end
+
+  def self.collector(&blk)
+    counter = Counter.new
+    ret_val = self.start
+
+    yield
+
+    self.end(ret_val, counter)
+    counter
+  end
+end

data/lib/tracer.rb

@@ -0,0 +1,162 @@
+require 'tempfile'
+require 'json'
+
+class Syscall
+  attr_reader :name, :args, :retval, :duration, :timestamp, :pid
+
+  def initialize(name:, args:, retval:, duration:, timestamp:, pid:)
+    @name = name
+    @args = args
+    @retval = retval
+    @duration = duration
+    @timestamp = timestamp
+    @pid = pid
+  end
+
+  def to_s
+    "#{name}(#{args}) = #{retval} <#{duration}s>"
+  end
+end
+
+class TraceSignal
+  attr_reader :name, :details, :timestamp, :pid
+
+  def initialize(name:, details:, timestamp:, pid:)
+    @name = name
+    @details = details
+    @timestamp = timestamp
+    @pid = pid
+  end
+
+  def to_s
+    "#{name} {#{details}}"
+  end
+end
+
+def parse_strace(file)
+  syscall_pattern = /^(\d+) +(\d+\.\d+) (\w+)\((.*?)\) += +(.*?) <(.*?)>$/
+  signal_pattern = /^(\d+) +(\d+\.\d+) --- (\w+) {(.*)} ---$/
+  unfinished_pattern = /^(\d+) +(\d+\.\d+) (\w+)\((.*?) +<unfinished \.\.\.>$/
+  resumed_pattern = /^(\d+) +(\d+\.\d+) <\.\.\. (\w+) resumed>(.*?)?\) += +(.*?) <(.*?)>$/
+
+  result = []
+  unfinished_syscalls = {}
+
+  file.each_line do |line|
+    case line
+    when syscall_pattern
+      pid, timestamp, syscall, args, retval, duration = $~.captures
+      result << Syscall.new(name: syscall, args: args, retval: retval, duration: duration, timestamp: timestamp, pid: pid)
+    when signal_pattern
+      pid, timestamp, signal, details = $~.captures
+      result << TraceSignal.new(name: signal, details: details, timestamp: timestamp, pid: pid)
+    when unfinished_pattern
+      pid, timestamp, syscall, args = $~.captures
+      key = [pid, syscall]
+      unfinished_syscalls[key] ||= []
+      unfinished_syscalls[key] << [timestamp, args]
+    when resumed_pattern
+      pid, timestamp, syscall, args2, retval, duration = $~.captures
+      key = [pid, syscall]
+      if unfinished_syscalls[key]&.any?
+        start_timestamp, args = unfinished_syscalls[key].pop
+        result << Syscall.new(name: syscall, args: "#{args}#{args2}", retval: retval, duration: duration, timestamp: start_timestamp, pid: pid)
+      else
+        puts "Resumed syscall without a start: #{line}"
+      end
+    else
+      puts "Attempted to parse unrecognized strace line: #{line}"
+    end
+  end
+
+  result
+end
+
+def filter_trace(trace, marker_path)
+  start_index = trace.index { |event| event.args.include?(marker_path) }
+  end_index = trace.rindex { |event| event.args.include?(marker_path) }
+
+  if start_index && end_index
+    trace[start_index + 1...end_index]
+  else
+    puts "Failed to find start and end markers for the trace, returning the full trace."
+    trace
+  end
+end
+
+module Cirron
+  def self.tracer(timeout = 10, &block)
+    trace_file = Tempfile.new('cirron')
+    trace_file.close
+    parent_pid = Process.pid
+    cmd = "strace --quiet=attach,exit -f -T -ttt -o #{trace_file.path} -p #{parent_pid}"
+    
+    strace_proc = spawn(cmd, :out => "/dev/null", :err => "/dev/null")
+    
+    # Wait for the trace file to be created
+    deadline = Time.now + timeout
+    begin
+      until File.exist?(trace_file.path)
+        if Time.now > deadline
+          raise Timeout::Error, "Failed to start strace within #{timeout}s."
+        end
+      end
+      # :(
+      sleep 0.1
+
+      # We use this dummy fstat to recognize when we start executing the block
+      File.stat(trace_file.path + ".dummy") rescue nil
+
+      yield if block_given?
+
+      # Same here, to recognize when we're done executing the block
+      File.stat(trace_file.path + ".dummy") rescue nil
+    ensure
+      Process.kill('INT', strace_proc) rescue nil
+      Process.wait(strace_proc) rescue nil
+    end
+
+    # Parse the trace file into a list of events
+    trace = File.open(trace_file.path, 'r') do |file|
+      parse_strace(trace)
+    end
+
+    trace = filter_trace(trace, trace_file.path + ".dummy")
+
+    trace_file.unlink
+
+    trace
+  end
+
+  def to_tef(parsed_events)
+    events = parsed_events.map do |event|
+      case event
+      when Syscall
+        start_ts = event.timestamp.to_f * 1_000_000
+        duration_us = event.duration.to_f * 1_000_000
+        {
+          name: event.name,
+          ph: "X",
+          ts: start_ts,
+          dur: duration_us,
+          pid: event.pid.to_i,
+          tid: event.pid.to_i,
+          args: { args: event.args, retval: event.retval }
+        }
+      when TraceSignal
+        ts = event.timestamp.to_f * 1_000_000
+        {
+          name: "Signal: #{event.name}",
+          ph: "i",
+          s: "g",
+          ts: ts,
+          pid: event.pid.to_i,
+          tid: event.pid.to_i,
+          args: { details: event.details }
+        }
+      end
+    end
+
+    JSON.pretty_generate(events)
+  end
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: cirron
+version: !ruby/object:Gem::Version
+  version: 0.2.2
+platform: ruby
+authors:
+- Matt Stuchlik
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-07-06 00:00:00.000000000 Z
+dependencies: []
+description: |
+  ==
+  # Cirron
+
+  Cirron measures a piece of Ruby code and report back several performance counters: CPU instruction count, branch misses, page faults and time spent measuring. It uses the Linux perf events interface or @ibireme's [KPC demo](https://gist.github.com/ibireme/173517c208c7dc333ba962c1f0d67d12) on OSX.
+
+  It can also trace syscalls using `strace`, Linux only!
+
+  ## Prerequisites
+
+  - Linux with perf events support / Apple ARM OSX
+  - C++
+  - Ruby 3.x
+
+  ## Usage
+
+  ### Performance Counters
+  ```
+  from cirron import Collector
+
+  # Start collecting performance metrics
+  with Collector() as collector:
+      # Your code here
+      # ...
+
+  # Retrieve the metrics
+  print(collector.counters)
+  ```
+
+  ### Syscalls
+  ```
+  from cirron import Tracer, to_tef
+
+  with Tracer() as tracer:
+      # Your code here
+      # ...
+
+  # Stop collecting and retrieve the trace
+  print(tracer.trace)
+
+  # Save the trace for ingesting to Perfetto
+  open("/tmp/trace", "w").write(to_tef(trace))
+  ```
+email:
+- matej.stuchlik@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- cirron.gemspec
+- lib/apple_arm_events.h
+- lib/cirron.rb
+- lib/cirronlib.cpp
+- lib/collector.rb
+- lib/tracer.rb
+homepage: https://github.com/s7nfo/Cirron
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/s7nfo/Cirron
+  source_code_uri: https://github.com/s7nfo/Cirron
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.10
+signing_key:
+specification_version: 4
+summary: Cirron measures how many CPU instructions and system calls a piece of Ruby
+  code executes.
+test_files: []