appoptics_apm 4.11.2 → 4.13.0

data/README.md

@@ -12,11 +12,11 @@ It requires an [AppOptics](https://www.appoptics.com/) account to view metrics.
 [it's free](https://my.appoptics.com/sign_up).
 
 [![Gem Version](https://badge.fury.io/rb/appoptics_apm.svg)](https://badge.fury.io/rb/appoptics_apm)
-[![Build Status](https://travis-ci.org/appoptics/appoptics-apm-ruby.png?branch=master)](https://travis-ci.org/appoptics/appoptics-apm-ruby)
-[![Maintainability](https://api.codeclimate.com/v1/badges/ac7f36241a23a3a82fc5/maintainability)](https://codeclimate.com/github/appoptics/appoptics-apm-ruby/maintainability)
 
-_Note: The repository is now at https://github.com/appoptics/appoptics-apm-ruby  Please update your github remotes with 
-`git remote set-url origin git@github.com:appoptics/appoptics-apm-ruby.git`._
+[![Run all Tests](https://github.com/appoptics/appoptics-apm-ruby/actions/workflows/run_tests.yml/badge.svg)](https://github.com/appoptics/appoptics-apm-ruby/actions/workflows/run_tests.yml)
+[![C++ Tests](https://github.com/appoptics/appoptics-apm-ruby/actions/workflows/run_cpluplus_tests.yml/badge.svg)](https://github.com/appoptics/appoptics-apm-ruby/actions/workflows/run_cpluplus_tests.yml)
+
+[comment]: <> ([![Maintainability]&#40;https://api.codeclimate.com/v1/badges/ac7f36241a23a3a82fc5/maintainability&#41;]&#40;https://codeclimate.com/github/appoptics/appoptics-apm-ruby/maintainability&#41;)
 
 # Documentation
 
@@ -234,7 +234,7 @@ Find more details in the [RubyDoc page](https://www.rubydoc.info/gems/appoptics_
 # Support
 
 If you run into a problem, find a bug, or would like to request an enhancement, feel free to contact our tech support 
-[support@appoptics.com](support@appoptics.com).  
+[technicalsupport@solarwinds.com](technicalsupport@solarwinds.com).  
 
 # Contributing
 
@@ -390,4 +390,4 @@ See the README in the test directory.
 
 Copyright (c) 2018 SolarWinds, LLC
 
-Released under the [Librato Open License](https://docs.appoptics.com/kb/apm_tracing/librato-open-license/)
+Released under the [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0)

data/appoptics_apm.gemspec

@@ -6,10 +6,10 @@ Gem::Specification.new do |s|
   s.version = AppOpticsAPM::Version::STRING
   s.date = Time.now.strftime('%Y-%m-%d')
 
-  s.license = "Librato Open License, Version 1.0, https://bit.ly/2Kmm0mN"
+  s.license = "Apache-2.0"
 
   s.authors = ["Maia Engeli", "Peter Giacomo Lombardo", "Spiros Eliopoulos"]
-  s.email = %q{support@appoptics.com}
+  s.email = %q{technicalsupport@solarwinds.com}
   s.homepage = %q{https://www.appoptics.com/}
   s.summary = %q{AppOptics APM performance instrumentation gem for Ruby}
   s.description = <<-EOF
@@ -26,12 +26,16 @@ Automatic tracing and metrics for Ruby applications. Get started at appoptics.co
   s.extra_rdoc_files = ['LICENSE']
   s.files = `git ls-files`.split("\n").reject { |f| f.match(%r{^(test|gemfiles)/}) }
   s.files += ['ext/oboe_metal/src/oboe.h',
-              'ext/oboe_metal/src/oboe.hpp',
+              'ext/oboe_metal/src/oboe_api.cpp',
+              'ext/oboe_metal/src/oboe_api.hpp',
               'ext/oboe_metal/src/oboe_debug.h',
-              'ext/oboe_metal/src/oboe_wrap.cxx',
+              'ext/oboe_metal/src/oboe_swig_wrap.cc',
               'ext/oboe_metal/src/bson/bson.h',
               'ext/oboe_metal/src/bson/platform_hacks.h',
-              'ext/oboe_metal/src/VERSION']
+              'ext/oboe_metal/src/VERSION',
+              'ext/oboe_metal/lib/liboboe-1.0-alpine-x86_64.so.0.0.0.sha256',
+              'ext/oboe_metal/lib/liboboe-1.0-x86_64.so.0.0.0.sha256'
+             ]
   s.files -= ['build_gem.sh',
               'build_gem_upload_to_packagecloud.sh',
               'Rakefile']
@@ -42,17 +46,20 @@ Automatic tracing and metrics for Ruby applications. Get started at appoptics.co
 
   s.extensions = ['ext/oboe_metal/extconf.rb'] unless defined?(JRUBY_VERSION)
 
-  s.add_runtime_dependency('json', '~> 2.3')
+  # this still gives a warning, would have to be pinned to a minor version
+  # but that is not necessary and may restrict other gems
+  s.add_runtime_dependency('json', '~> 2.0')
   s.add_runtime_dependency('no_proxy_fix', '~> 0.1.2', '>= 0.1.2')
 
   # Development dependencies used in gem development & testing
   # s.add_development_dependency('rake', '>= 0.9.0')
   # s.add_development_dependency('simplecov', '>= 0.16.0') if ENV["SIMPLECOV_COVERAGE"]
   # s.add_development_dependency('simplecov-console', '>= 0.4.0') if ENV["SIMPLECOV_COVERAGE"]
-  # s.add_development_dependency('irb', '>= 1.0.0') if RUBY_VERSION >= '2.6.0'
+  # s.add_development_dependency('irb', '>= 1.0.0', '< 1.2.2') if RUBY_VERSION >= '2.6.0'
   #
   # unless defined?(JRUBY_VERSION)
-  #   s.add_development_dependency('byebug', '>= 8.0.0')
+  #   s.add_development_dependency('byebug', '>= 11.0.0')
+  #   s.add_development_dependency('minitest')
   #   s.add_development_dependency('minitest-hooks', '>= 1.5.0')
   #   s.add_development_dependency('minitest-focus', '>=1.1.2')
   #   s.add_development_dependency('benchmark-ips', '>= 2.7.2')

data/examples/prepend.rb

@@ -0,0 +1,13 @@
+require 'appoptics_apm'
+
+module Measurements
+  def request(*args, &block)
+    req = args.first
+    AppOpticsAPM::SDK.summary_metric("request_size", req.to_hash.to_s.size)
+    resp = super
+    AppOpticsAPM::SDK.summary_metric("response_size", resp.to_hash.to_s.size)
+    return resp
+  end
+end
+
+Net::HTTP.send(:prepend, :Measurements)

data/examples/sdk_examples.rb

@@ -140,3 +140,19 @@ AppOpticsAPM::SDK.start_trace('log_trace_id') do
   trace = AppOpticsAPM::SDK.current_trace
   AppOpticsAPM.logger.warn "Some log message #{trace.for_log}"
 end
+
+###############################################################
+# START A TRACE AND PROFILE
+###############################################################
+#
+# AppOpticsAPM::Profiling.run
+# This method adds profiling for the code executed in the block
+
+AppOpticsAPM::SDK.start_trace("#{name}_profiling") do
+  AppOpticsAPM::Profiling.run do
+    10.times do
+      [9, 6, 12, 2, 7, 1, 9, 3, 4, 14, 5, 8].sort
+      sleep 0.2
+    end
+  end
+end

data/ext/oboe_metal/README.md

@@ -5,7 +5,7 @@ inspired by: https://dev.to/wataash/how-to-create-and-debug-ruby-gem-with-c-nati
 
 ## install ruby with sources
 
-rbenv is your friend ;) 😄 -k means keep sources
+rbenv is your friend ;) -k means keep sources
 
 ```
 rbenv install -k 2.6.3
@@ -66,4 +66,4 @@ Some inspiring examples here:
 
 https://jvns.ca/blog/2016/06/12/a-weird-system-call-process-vm-readv/
 
-https://medium.com/@zanker/finding-a-ruby-bug-with-gdb-56d6b321bc86
+https://medium.com/@zanker/finding-a-ruby-bug-with-gdb-56d6b321bc86

data/ext/oboe_metal/extconf.rb

@@ -8,20 +8,29 @@ require 'rbconfig'
 require 'open-uri'
 require 'no_proxy_fix'
 
+CONFIG['warnflags'] = CONFIG['warnflags'].gsub(/-Wdeclaration-after-statement/, '')
+                        .gsub(/-Wimplicit-function-declaration/, '')
+                        .gsub(/-Wimplicit-int/, '')
+                        .gsub(/-Wno-tautological-compare/, '')
+                        .gsub(/-Wno-self-assign/, '')
+                        .gsub(/-Wno-parentheses-equality/, '')
+                        .gsub(/-Wno-constant-logical-operand/, '')
+                        .gsub(/-Wno-cast-function-type/, '')
+init_mkmf(CONFIG)
+
 ext_dir = File.expand_path(File.dirname(__FILE__))
 
 # Check if we're running in JRuby
 jruby = defined?(JRUBY_VERSION) ? true : false
-
 # Set the mkmf lib paths so we have no issues linking to
 # the AppOpticsAPM libs.
 ao_lib_dir = File.join(ext_dir, 'lib')
 ao_include = File.join(ext_dir, 'src')
 
 # Download the appropriate liboboe from S3(via rake for testing) or files.appoptics.com (production)
-version = File.read(File.join(ao_include, 'VERSION')).chomp
+version = File.read(File.join(ao_include, 'VERSION')).strip
 if ENV['APPOPTICS_FROM_S3'].to_s.downcase == 'true'
-  ao_path = File.join('https://s3-us-west-2.amazonaws.com/rc-files-t2/c-lib/', version)
+  ao_path = File.join('https://rc-files-t2.s3-us-west-2.amazonaws.com/c-lib/', version)
   puts 'Fetching c-lib from S3'
 else
   ao_path = File.join('https://files.appoptics.com/c-lib', version)
@@ -29,7 +38,8 @@ end
 
 ao_arch = 'x86_64'
 if File.exist?('/etc/alpine-release')
-  version = open('/etc/alpine-release').read.chomp
+  version = File.read('/etc/alpine-release').strip
+
   ao_arch =
     if Gem::Version.new(version) < Gem::Version.new('3.9')
       'alpine-libressl-x86_64'
@@ -40,31 +50,31 @@ end
 
 ao_clib = "liboboe-1.0-#{ao_arch}.so.0.0.0"
 ao_item = File.join(ao_path, ao_clib)
-ao_checksum_item = "#{ao_item}.sha256"
+ao_checksum_file = File.join(ao_lib_dir, "#{ao_clib}.sha256")
 clib = File.join(ao_lib_dir, ao_clib)
 
 retries = 3
 success = false
 while retries > 0
   begin
-    # download
-    # TODO warning: calling URI.open via Kernel#open is deprecated, call URI.open directly or use URI#open
-    # ____ URI.open is not supported in 2.4.5, let's use open until we can deprecate 2.4.5
-    download = open(ao_item, 'rb')
+    download = RUBY_VERSION < '2.5.0' ? open(ao_item, 'rb') : URI.open(ao_item, 'rb')
     IO.copy_stream(download, clib)
 
-    checksum = open(ao_checksum_item, 'r').read.chomp
     clib_checksum = Digest::SHA256.file(clib).hexdigest
+    download.close
+    checksum =  File.read(ao_checksum_file).strip
 
-    # verify_checksum
+    # unfortunately these messages only show if the install command is run
+    # with the `--verbose` flag
     if clib_checksum != checksum
       $stderr.puts '== ERROR ================================================================='
-      $stderr.puts 'Checksum Verification failed for the c-extension of the appoptics_apm gem.'
-      $stderr.puts 'appoptics_apm will not instrument the code. No tracing will occur.'
-      $stderr.puts 'Contact support@appoptics.com if the problem persists.'
+      $stderr.puts 'Checksum Verification failed for the c-extension of the appoptics_apm gem'
+      $stderr.puts 'Installation cannot continue'
+      $stderr.puts "\nChecksum packaged with gem:   #{checksum}"
+      $stderr.puts "Checksum calculated from lib: #{clib_checksum}"
+      $stderr.puts 'Contact technicalsupport@solarwinds.com if the problem persists'
       $stderr.puts '=========================================================================='
-      create_makefile('oboe_noop', 'noop')
-      retries = 0
+      exit 1
     else
       success = true
       retries = 0
@@ -76,8 +86,8 @@ while retries > 0
       $stderr.puts '== ERROR =========================================================='
       $stderr.puts 'Download of the c-extension for the appoptics_apm gem failed.'
       $stderr.puts 'appoptics_apm will not instrument the code. No tracing will occur.'
-      $stderr.puts 'Contact support@appoptics.com if the problem persists.'
-      $stderr.puts "error:\n#{e.message}"
+      $stderr.puts 'Contact technicalsupport@solarwinds.com if the problem persists.'
+      $stderr.puts "error: #{ao_item}\n#{e.message}"
       $stderr.puts '==================================================================='
       create_makefile('oboe_noop', 'noop')
     end
@@ -107,11 +117,24 @@ if success
     $libs = append_library($libs, 'stdc++')
 
     $CFLAGS << " #{ENV['CFLAGS']}"
-    $CPPFLAGS << " #{ENV['CPPFLAGS']}"
+    # $CPPFLAGS << " #{ENV['CPPFLAGS']} -std=c++11"
+    # TODO for debugging: -pg -gdwarf-2, remove for production
+    # -pg does not work on alpine https://www.openwall.com/lists/musl/2014/11/05/2
+    $CPPFLAGS << " #{ENV['CPPFLAGS']} -std=c++11  -gdwarf-2 -I$$ORIGIN/../ext/oboe_metal/include -I$$ORIGIN/../ext/oboe_metal/src"
+    # $CPPFLAGS << " #{ENV['CPPFLAGS']} -std=c++11 -I$$ORIGIN/../ext/oboe_metal/include"
     $LIBS << " #{ENV['LIBS']}"
-    $LDFLAGS << " #{ENV['LDFLAGS']} '-Wl,-rpath=$$ORIGIN/../ext/oboe_metal/lib'"
 
-    create_makefile('oboe_metal', 'src')
+    # use "z,defs" to see what happens during linking
+    # $LDFLAGS << " #{ENV['LDFLAGS']} '-Wl,-rpath=$$ORIGIN/../ext/oboe_metal/lib,-z,defs'  -lrt"
+    $LDFLAGS << " #{ENV['LDFLAGS']} '-Wl,-rpath=$$ORIGIN/../ext/oboe_metal/lib' -lrt"
+    $CXXFLAGS += " -std=c++11 "
+
+    # ____ include debug info, comment out when not debugging
+    # ____ -pg -> profiling info for gprof
+    CONFIG["debugflags"] = "-ggdb3 "
+    CONFIG["optflags"] = "-O0"
+
+    create_makefile('libappoptics_apm', 'src')
 
   else
     $stderr.puts   '== ERROR ========================================================='
@@ -121,7 +144,7 @@ if success
     else
       $stderr.puts 'Could not find a matching c-library. No tracing will occur.'
     end
-    $stderr.puts   'Contact support@appoptics.com if the problem persists.'
+    $stderr.puts   'Contact technicalsupport@solarwinds.com if the problem persists.'
     $stderr.puts   '=================================================================='
     create_makefile('oboe_noop', 'noop')
   end

data/ext/oboe_metal/lib/liboboe-1.0-alpine-x86_64.so.0.0.0.sha256

@@ -0,0 +1 @@
+af7d764a88cec323940fc6040947f2dcf8041c389744bdfc46b7f2fe0a465dab

data/ext/oboe_metal/lib/liboboe-1.0-x86_64.so.0.0.0.sha256

@@ -0,0 +1 @@
+092e232d0e1aa1826b77c98d96f7bb2db39058c9bec3e2c0387cc6fb51b5b83c

data/ext/oboe_metal/src/README.md

@@ -0,0 +1,6 @@
+
+oboe_api.hpp and oboe_api.cpp are copied here from the oboe repo during install
+
+it is best to edit these file in the oboe repo and use the OBOE_WIP=true env
+var to include the development version while they aren't deploy to s3.
+

data/ext/oboe_metal/src/VERSION

@@ -1 +1,2 @@
-10.0.0
+10.2.0
+

data/ext/oboe_metal/src/frames.cc

@@ -0,0 +1,246 @@
+// Copyright (c) 2021 SolarWinds, LLC.
+// All rights reserved.
+
+#include "frames.h"
+
+using namespace std;
+
+unordered_map<VALUE, FrameData> cached_frames;
+
+// in theory the mutex is not needed, because Ruby does not context switch
+// while executing a foreign function, but will this always hold true?
+mutex cached_frames_mutex;
+
+void Frames::reserve_cached_frames() {
+    lock_guard<mutex> guard(cached_frames_mutex);
+    // unordered_maps grow automatically, but it starts at 1 and then
+    // doubles when it is full, so lets avoid the warmup
+    cached_frames.reserve(500);  // it will round to a prime number: 503
+}
+
+void Frames::clear_cached_frames() {
+    lock_guard<mutex> guard(cached_frames_mutex);
+        // unordered_maps grow automatically, but it starts at 1 and then
+        // doubles when it is full, so lets avoid the warmup
+    cached_frames.clear();
+}
+
+// this is a private function
+int Frames::cache_frame(VALUE frame) {
+    VALUE val;
+    FrameData data;
+
+    // only cache it if it does not exist
+    if (cached_frames.count(frame) == 0) {
+        val = rb_profile_frame_label(frame);  // returns method or block
+        if (RB_TYPE_P(val, T_STRING))
+            data.method = RSTRING_PTR(val);
+
+        if (data.method.rfind("block ", 0) == 0) {
+            // we don't need more info if it is a block
+            // we ignore block level info because they make things messy
+            lock_guard<mutex> guard(cached_frames_mutex);
+            cached_frames.insert({frame, data});
+            return 0;
+        }
+
+        val = rb_profile_frame_classpath(frame);  // returns class or nil
+        if (RB_TYPE_P(val, T_STRING)) data.klass = RSTRING_PTR(val);
+
+        val = rb_profile_frame_absolute_path(frame);  // returns file, use rb_profile_frame_path() if nil
+        if (!RB_TYPE_P(val, T_STRING)) val = rb_profile_frame_path(frame);
+        if (RB_TYPE_P(val, T_STRING)) data.file = RSTRING_PTR(val);
+
+        // Ruby 3 reports <cfunc>, but the linenumbers are bogus
+        // the default line number is 0
+        if (!data.file.compare("<cfunc>") == 0) {
+            val = rb_profile_frame_first_lineno(frame);  // returns line number
+            if (RB_TYPE_P(val, T_FIXNUM)) {
+                data.lineno = NUM2INT(val);
+            }
+        }
+        lock_guard<mutex> guard(cached_frames_mutex);
+        cached_frames.insert({frame, data});
+    }
+    return 0;
+}
+
+// all frames in frames_buffer must be in cached_frames
+// before calling this function
+// we are saving the check for better performance
+int Frames::collect_frame_data(VALUE *frames_buffer, int num, vector<FrameData> &frame_data) {
+    if (num == 1) {
+        if (frames_buffer[0] == PR_IN_GC) {
+            FrameData data;
+            data.method = "GARBAGE COLLECTION";
+            frame_data.push_back(data);
+            return 0;
+        } else if (frames_buffer[0] == PR_OTHER_THREAD) {
+            FrameData data;
+            data.method = "OTHER THREADS";
+            frame_data.push_back(data);
+            return 0;
+        }
+    }
+
+    for (int i = 0; i < num; i++) {
+        VALUE frame = frames_buffer[i];
+        frame_data.push_back(cached_frames[frame]);
+    }
+    return 0;
+}
+
+/////
+// For the sake of efficiency this function filters uninteresting frames and
+// does the caching of frames at the same time
+//
+// in-place removal of
+// - frames with line number == 0
+// - all but last of repeated frames
+// - "block" frames (they are confusing) <- revisit
+// and cache uncached frames
+int Frames::remove_garbage(VALUE *frames_buffer, int num) {
+    if (num == 1 && (frames_buffer[0] == PR_OTHER_THREAD || frames_buffer[0] == PR_IN_GC))
+        return 1;
+
+    // TODO decide what to do with <cfunc> frames in Ruby 3
+
+    // 1) ignore top frames where the line number is 0
+    // does that mean there is no line number???
+    bool found = true;
+
+    while (found && num > 0) {
+        if (cached_frames.count(frames_buffer[num - 1]) == 1) {
+            found = (cached_frames[frames_buffer[num - 1]].lineno == 0);
+            if (found) num--;
+        } else {
+            VALUE val = rb_profile_frame_first_lineno(frames_buffer[num - 1]);
+            found = (!RB_TYPE_P(val, T_FIXNUM) || !NUM2INT(val));
+            if (found) {
+                lock_guard<mutex> guard(cached_frames_mutex);
+                cached_frames[frames_buffer[num - 1]].lineno = 0;
+                num--;
+            }
+        }
+    }
+
+    // 2) remove all repeated frames, keep the last one
+    int count = 0;
+    int k = 0;
+    found = false;
+    while (count < num - k) {
+        // is this frame repeated ahead?
+        // if so we will replace it with the next one in line
+        for (int j = count + k + 1; j < num; j++) {
+            if (frames_buffer[count] == frames_buffer[j]) {
+                found = true;
+                break;
+            }
+        }
+
+        if (found) {
+            // if we found this frame again later in the snapshot
+            // we are going to override this one
+            // but not if this is going beyond the boundary
+            k++;
+            if (count + k < num - 1) frames_buffer[count] = frames_buffer[count + k];
+        } else {
+            count++;
+            frames_buffer[count] = frames_buffer[count + k];
+        }
+        found = false;
+    }
+
+    // 3) remove "block" frames, they are reported inconsistently and mess up
+    //    the profile in the dashboard
+    // 4)  while we are at it we also cache all the frames
+    // these 2 are combined so we don't have to run this loop twice
+    num = count;
+    count = 0, k = 0;
+    string method;
+
+    while (count < num - k) {
+        frames_buffer[count] = frames_buffer[count + k];
+        cache_frame(frames_buffer[count]);
+        method = cached_frames[frames_buffer[count]].method;
+
+        // TODO revisit need to remove block frames, they only appear when the Ruby
+        // ____ script is not started with a method and has blocks outside of the
+        // ____ methods called and sometimes inside of rack
+        if (method.rfind("block ", 0) == 0) {
+            k++;
+        } else {
+            count++;
+        }
+    }
+    return count;
+}
+
+// returns the number of the matching frames
+int Frames::num_matching(VALUE *frames_buffer, int num,
+                         VALUE *prev_frames_buffer, int prev_num) {
+    int i;
+    int min = std::min(num, prev_num);
+
+    for (i = 0; i < min; i++) {
+        // we have to start from the "top"
+        if (frames_buffer[num - 1 - i] != prev_frames_buffer[prev_num - 1 - i]) {
+            return i;
+        }
+    }
+    return i;
+}
+
+/////////////////////// DEBUGGING HELPER FUNCTIONS /////////////////////////////
+// helper function to print frame from ruby pointers to frame
+void Frames::print_raw_frame_info(VALUE frame) {
+    if (frame == PR_IN_GC || frame == PR_OTHER_THREAD) {
+        return;
+    }
+
+    VALUE val;
+    int lineno;
+    string file, klass, method;
+
+    val = rb_profile_frame_first_lineno(frame);  // returns line number
+    if (RB_TYPE_P(val, T_FIXNUM)) lineno = NUM2INT(val);
+
+    val = rb_profile_frame_classpath(frame);  // returns class or nil
+    if (RB_TYPE_P(val, T_STRING)) klass = RSTRING_PTR(val);
+
+    val = rb_profile_frame_absolute_path(frame);  // returns file, use rb_profile_frame_path() if nil
+    if (!RB_TYPE_P(val, T_STRING)) val = rb_profile_frame_path(frame);
+    if (RB_TYPE_P(val, T_STRING)) file = RSTRING_PTR(val);
+
+    val = rb_profile_frame_label(frame);  // returns method or block
+    if (RB_TYPE_P(val, T_STRING)) method = RSTRING_PTR(val);
+
+    cout << "    " << frame << "   "
+         << "L: " << lineno << " "
+         << "F: " << file << " "
+         << "C: " << klass << " "
+         << "M: " << method << endl;
+}
+
+void Frames::print_all_raw_frames(VALUE *frames_buffer, int num) {
+    for (int i = 0; i < num; i++) {
+        print_raw_frame_info(frames_buffer[i]);
+    }
+}
+
+// helper function to print frame info
+void Frames::print_frame_info(VALUE frame) {
+    if (cached_frames.find(frame) != cached_frames.end())
+        std::cout << cached_frames[frame].lineno << " "
+                  << cached_frames[frame].file << " "
+                  << cached_frames[frame].klass << " "
+                  << cached_frames[frame].method << std::endl;
+}
+
+// helper function for printing the cached frames
+void Frames::print_cached_frames() {
+    std::cout << "cached_frames contains:" << endl;
+    for (auto it = cached_frames.cbegin(); it != cached_frames.cend(); ++it)
+        std::cout << "           " << it->first << " - " << it->second.method << ":" << it->second.lineno << endl;  // cannot modify *it
+    std::cout << std::endl;
+}