appmap 0.40.0 → 0.41.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b0943dadde84e67780d724918fa26377b869791eaab6edfb714e5081ecb5c80
-  data.tar.gz: c492323d80541a913b800924d04a7c24a6c8682263ba3ec4deabfa8d7ade3908
+  metadata.gz: d747c0e65dc1efb45769ae9118a7b97015b0378d79e20eec855e74c20b622af2
+  data.tar.gz: dcc3b91f32246aaefd02fbcf47672bfdf13acf6cadb715fbc5ff0040dbcfbf72
 SHA512:
-  metadata.gz: 2a27e5b9bc3dafbba8aafd7035732b6ffcb813d57bb216d0e544af30260c0e26f23a920d1b2d6d35882046e74a57f8b492b12b9869de5d820ff6a4e09cafd716
-  data.tar.gz: f1bdc22fda7a6fdf0a37fc1d5bd419947e0fffa16511873dbe8a1549f30bf862566fe74fa4c9952c4338f5263414c99f3d598daec0a599b467e52ebac374b4f7
+  metadata.gz: 5f82a6a0cf8075537b0835e783779c827c5afed81e83e242bc97cbfd5b6ef0320fe352235436f57009a63db321223b9f7f82e8bcdced558d9b935a2ce4e4cbf3
+  data.tar.gz: aaa4676d24b6bb1bcbd34fb7f0e3a0244d005c36dd89782b774b342b7e30e1c9637795d0d492522b2a5e525de413e3adb9da54bd5ace2699373ffdfadf3a8157

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+# v0.41.0
+
+* Adjust some label names to match `provider.*`, `format.*`.
+* Add global `exclude` list to *appmap.yml* which can be used to definitively exclude specific classes and methods.
+
 # v0.40.0
 
 * Parse source code comments into function labels.

data/README.md

@@ -53,15 +53,23 @@ Support for new versions is added frequently, please check back regularly for up
 <a href="https://www.loom.com/share/78ab32a312ff4b85aa8827a37f1cb655"> <p>Quick and easy setup of the AppMap gem for Rails - Watch Video</p> <img style="max-width:300px;" src="https://cdn.loom.com/sessions/thumbnails/78ab32a312ff4b85aa8827a37f1cb655-with-play.gif"> </a>
 
 
-Add `gem 'appmap'` to your Gemfile just as you would any other dependency. We recommend that the Gem be added to the `:development, :test` section.
+Add `gem 'appmap'` to **beginning** of your Gemfile. We recommend that you add the `appmap` gem to the `:development, :test` group. Your Gemfile should look something like this:
 
 ```
+source 'https://rubygems.org'
+git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
+# Optional rubRuby version
+# ruby '2.7.2'
+
 group :development, :test do
   gem 'appmap'
 end
 ```
 
-Then install with `bundle`.
+Install with `bundle install`, as usual.
+
+It's important to add the `appmap` gem before any other gems that you may want to instrument. There is more about this in the section on adding gems to the *appmap.yml*.
 
 **Railtie**
 
@@ -79,7 +87,8 @@ When you run your program, the `appmap` gem reads configuration settings from `a
 file for a typical Rails project:
 
 ```yaml
-name: MyProject
+# 'name' should generally be the same as the code repo name.
+name: my_project
 packages:
 - path: app/controllers
 - path: app/models
@@ -91,10 +100,15 @@ packages:
 - gem: devise
 - gem: aws-sdk
 - gem: will_paginate
+exclude:
+- MyClass
+- MyClass#my_instance_method
+- MyClass.my_class_method
 ```
 
 * **name** Provides the project name (required)
-* **packages** A list of source code directories which should be instrumented.
+* **packages** A list of source code directories which should be recorded.
+* **exclude** A list of classes and/or methods to definitively exclude from recording.
 
 **packages**
 
@@ -102,13 +116,18 @@ Each entry in the `packages` list is a YAML object which has the following keys:
 
 * **path** The path to the source code directory. The path may be relative to the current working directory, or it may
   be an absolute path.
-* **gem** As an alternative to specifying the path, specify the name of a dependency gem. When using `gem`, don't specify `path`.
+* **gem** As an alternative to specifying the path, specify the name of a dependency gem. When using `gem`, don't specify `path`. In your `Gemfile`, the `appmap` gem **must** be listed **before** any gem that you specify in your *appmap.yml*.
 * **exclude** A list of files and directories which will be ignored. By default, all modules, classes and public
-  functions are inspected.
+  functions are inspected. See also: global `exclude` list.
 * **shallow** When set to `true`, only the first function call entry into a package will be recorded. Subsequent function calls within 
   the same package are not recorded unless code execution leaves the package and re-enters it. Default: `true` when using `gem`,
   `false` when using `path`.
 
+**exclude**
+
+Optional list of fully qualified class and method names. Separate class and method names with period (`.`) for class methods and hash (`#`) for instance methods.
+
+
 # Labels
 
 The [AppMap data format](https://github.com/applandinc/appmap) provides for class and function `labels`, which can be used to enhance the AppMap visualizations, and to programatically analyze the data.

data/lib/appmap/config.rb

@@ -57,32 +57,32 @@ module AppMap
     # Methods that should always be hooked, with their containing
     # package and labels that should be applied to them.
     HOOKED_METHODS = {
-      'ActiveSupport::SecurityUtils' => Hook.new(:secure_compare, Package.build_from_path('active_support', package_name: 'active_support', labels: %w[security crypto])),
-      'ActionView::Renderer' => Hook.new(:render, Package.build_from_path('action_view', package_name: 'action_view', labels: %w[view]))
+      'ActiveSupport::SecurityUtils' => Hook.new(:secure_compare, Package.build_from_path('active_support', package_name: 'active_support', labels: %w[provider.secure_compare])),
+      'ActionView::Renderer' => Hook.new(:render, Package.build_from_path('action_view', package_name: 'action_view', labels: %w[mvc.view]))
     }.freeze
 
     BUILTIN_METHODS = {
       'OpenSSL::PKey::PKey' => Hook.new(:sign, OPENSSL_PACKAGES),
-      'Digest::Instance' => Hook.new(:digest, OPENSSL_PACKAGES),
       'OpenSSL::X509::Request' => Hook.new(%i[sign verify], OPENSSL_PACKAGES),
       'OpenSSL::PKCS5' => Hook.new(%i[pbkdf2_hmac_sha1 pbkdf2_hmac], OPENSSL_PACKAGES),
       'OpenSSL::Cipher' => Hook.new(%i[encrypt decrypt final], OPENSSL_PACKAGES),
       'OpenSSL::X509::Certificate' => Hook.new(:sign, OPENSSL_PACKAGES),
-      'Net::HTTP' => Hook.new(:request, Package.build_from_path('net/http', package_name: 'net/http', labels: %w[http io])),
-      'Net::SMTP' => Hook.new(:send, Package.build_from_path('net/smtp', package_name: 'net/smtp', labels: %w[smtp email io])),
-      'Net::POP3' => Hook.new(:mails, Package.build_from_path('net/pop3', package_name: 'net/pop', labels: %w[pop pop3 email io])),
-      'Net::IMAP' => Hook.new(:send_command, Package.build_from_path('net/imap', package_name: 'net/imap', labels: %w[imap email io])),
-      'Marshal' => Hook.new(%i[dump load], Package.build_from_path('marshal', labels: %w[serialization marshal])),
-      'Psych' => Hook.new(%i[dump dump_stream load load_stream parse parse_stream], Package.build_from_path('yaml', package_name: 'psych', labels: %w[serialization yaml])),
-      'JSON::Ext::Parser' => Hook.new(:parse, Package.build_from_path('json', package_name: 'json', labels: %w[serialization json])),
-      'JSON::Ext::Generator::State' => Hook.new(:generate, Package.build_from_path('json', package_name: 'json', labels: %w[serialization json])),
+      'Net::HTTP' => Hook.new(:request, Package.build_from_path('net/http', package_name: 'net/http', labels: %w[protocol.http io])),
+      'Net::SMTP' => Hook.new(:send, Package.build_from_path('net/smtp', package_name: 'net/smtp', labels: %w[protocol.smtp protocol.email io])),
+      'Net::POP3' => Hook.new(:mails, Package.build_from_path('net/pop3', package_name: 'net/pop', labels: %w[protocol.pop protocol.email io])),
+      'Net::IMAP' => Hook.new(:send_command, Package.build_from_path('net/imap', package_name: 'net/imap', labels: %w[protocol.imap protocol.email io])),
+      'Marshal' => Hook.new(%i[dump load], Package.build_from_path('marshal', labels: %w[format.marshal provider.serialization marshal])),
+      'Psych' => Hook.new(%i[dump dump_stream load load_stream parse parse_stream], Package.build_from_path('yaml', package_name: 'psych', labels: %w[format.yaml provider.serialization])),
+      'JSON::Ext::Parser' => Hook.new(:parse, Package.build_from_path('json', package_name: 'json', labels: %w[format.json provider.serialization])),
+      'JSON::Ext::Generator::State' => Hook.new(:generate, Package.build_from_path('json', package_name: 'json', labels: %w[format.json provider.serialization])),
     }.freeze
 
-    attr_reader :name, :packages
+    attr_reader :name, :packages, :exclude
 
-    def initialize(name, packages = [])
+    def initialize(name, packages = [], exclude = [])
       @name = name
       @packages = packages
+      @exclude = exclude
     end
 
     class << self
@@ -108,22 +108,30 @@ module AppMap
             [ Package.build_from_path(path, exclude: package['exclude'] || [], shallow: package['shallow']) ]
           end
         end.flatten
-        Config.new config_data['name'], packages
+        Config.new config_data['name'], packages, config_data['exclude'] || []
       end
     end
 
     def to_h
       {
         name: name,
-        packages: packages.map(&:to_h)
+        packages: packages.map(&:to_h),
+        exclude: exclude
       }
     end
 
+    # package_for_method finds the Package, if any, which configures the hook
+    # for a method.
     def package_for_method(method)
+      package_hooked_by_class(method) || package_hooked_by_source_location(method)
+    end
+
+    def package_hooked_by_class(method)
       defined_class, _, method_name = ::AppMap::Hook.qualify_method_name(method)
-      package = find_package(defined_class, method_name)
-      return package if package
+      return find_package(defined_class, method_name)
+    end
 
+    def package_hooked_by_source_location(method)
       location = method.source_location
       location_file, = location
       return unless location_file
@@ -135,14 +143,22 @@ module AppMap
       end
     end
 
-    def included_by_location?(method)
-      !!package_for_method(method)
+    def never_hook?(method)
+      defined_class, separator, method_name = ::AppMap::Hook.qualify_method_name(method)
+      return true if exclude.member?(defined_class) || exclude.member?([ defined_class, separator, method_name ].join)
     end
 
+    # always_hook? indicates a method that should always be hooked.
     def always_hook?(defined_class, method_name)
       !!find_package(defined_class, method_name)
     end
 
+    # included_by_location? indicates a method whose source location matches a method definition that has been
+    # configured for inclusion.
+    def included_by_location?(method)
+      !!package_for_method(method)
+    end
+
     def find_package(defined_class, method_name)
       hook = find_hook(defined_class)
       return nil unless hook

data/lib/appmap/hook.rb

@@ -63,6 +63,8 @@ module AppMap
             # Skip methods that have no instruction sequence, as they are obviously trivial.
             next unless disasm
 
+            next if config.never_hook?(method)
+
             next unless \
               config.always_hook?(hook_cls, method.name) ||
               config.included_by_location?(method)
@@ -84,6 +86,8 @@ module AppMap
       tp.enable(&block)
     end
 
+    # hook_builtins builds hooks for code that is built in to the Ruby standard library.
+    # No TracePoint events are emitted for builtins, so a separate hooking mechanism is needed. 
     def hook_builtins
       return unless self.class.lock_builtins
 
@@ -97,6 +101,7 @@ module AppMap
         require hook.package.package_name if hook.package.package_name
         Array(hook.method_names).each do |method_name|
           method_name = method_name.to_sym
+
           cls = class_from_string.(class_name)
           method = \
             begin
@@ -105,6 +110,8 @@ module AppMap
               cls.method(method_name) rescue nil
             end
 
+          next if config.never_hook?(method)
+
           if method
             Hook::Method.new(hook.package, cls, method).activate
           else

data/lib/appmap/version.rb

@@ -3,7 +3,7 @@
 module AppMap
   URL = 'https://github.com/applandinc/appmap-ruby'
 
-  VERSION = '0.40.0'
+  VERSION = '0.41.0'
 
   APPMAP_FORMAT_VERSION = '1.4'
 end

data/spec/abstract_controller_base_spec.rb

@@ -8,7 +8,7 @@ describe 'AbstractControllerBase' do
         FileUtils.rm_rf tmpdir
         FileUtils.mkdir_p tmpdir
         cmd = <<~CMD.gsub "\n", ' '
-          docker-compose run --rm -e APPMAP=true
+          docker-compose run --rm -e RAILS_ENV=test -e APPMAP=true
           -v #{File.absolute_path tmpdir}:/app/tmp app ./bin/rspec #{spec_name}
         CMD
         run_cmd cmd, chdir: fixture_dir
@@ -137,7 +137,7 @@ describe 'AbstractControllerBase' do
                   'name' => 'Renderer',
                   'children' => include(hash_including(
                     'name' => 'render',
-                    'labels' => ['view']
+                    'labels' => ['mvc.view']
                   ))
                 ))
               ))

data/spec/config_spec.rb

@@ -7,6 +7,7 @@ require 'appmap/config'
 describe AppMap::Config, docker: false do
   it 'loads from a Hash' do
     config_data = {
+      exclude: [],
       name: 'test',
       packages: [
         {

data/spec/fixtures/hook/exclude.rb

@@ -0,0 +1,15 @@
+class ExcludeTest
+  def instance_method
+    'instance_method'
+  end
+
+  class << self
+    def singleton_method
+      'singleton_method'
+    end
+  end
+
+  def self.cls_method
+    'class_method'
+  end
+end

data/spec/fixtures/rails5_users_app/appmap.yml

@@ -1,4 +1,7 @@
 name: rails5_users_app
 packages:
-  - path: app
+  - path: app/models
+    labels: [ mvc.model ]
+  - path: app/controllers
+    labels: [ mvc.controller ]
   - gem: sequel

data/spec/fixtures/rails6_users_app/appmap.yml

@@ -1,5 +1,8 @@
 name: rails6_users_app
 packages:
-  - path: app
+  - path: app/models
+    labels: [ mvc.model ]
+  - path: app/controllers
+    labels: [ mvc.controller ]
   - gem: sequel
 

data/spec/hook_spec.rb

@@ -61,6 +61,16 @@ describe 'AppMap class Hooking', docker: false do
     AppMap.configuration = nil
   end
 
+  it 'excludes named classes and methods' do
+    load 'spec/fixtures/hook/exclude.rb'
+    package = AppMap::Config::Package.build_from_path('spec/fixtures/hook/exclude.rb')
+    config = AppMap::Config.new('hook_spec', [ package ], %w[ExcludeTest])
+    AppMap.configuration = config
+
+    expect(config.never_hook?(ExcludeTest.new.method(:instance_method))).to be_truthy
+    expect(config.never_hook?(ExcludeTest.method(:cls_method))).to be_truthy
+  end
+
   it 'parses labels from comments' do
     _, tracer = invoke_test_file 'spec/fixtures/hook/labels.rb' do
       ClassWithLabel.new.fn_with_label
@@ -827,7 +837,7 @@ describe 'AppMap class Hooking', docker: false do
       entry = cm[1][:children][0][:children][0][:children][0]
       # Sanity check, make sure we got the right one
       expect(entry[:name]).to eq('secure_compare')
-      expect(entry[:labels]).to eq(%w[security crypto])
+      expect(entry[:labels]).to eq(%w[provider.secure_compare])
     end
   end
 

data/spec/record_sql_rails_pg_spec.rb

@@ -5,7 +5,7 @@ describe 'SQL events' do
     around(:each) do |example|
       FileUtils.rm_rf tmpdir
       FileUtils.mkdir_p tmpdir
-      cmd = "docker-compose run --rm -e ORM_MODULE=#{orm_module} -e APPMAP=true -v #{File.absolute_path tmpdir}:/app/tmp app ./bin/rspec spec/controllers/users_controller_api_spec.rb:#{test_line_number}"
+      cmd = "docker-compose run --rm -e ORM_MODULE=#{orm_module} -e RAILS_ENV=test -e APPMAP=true -v #{File.absolute_path tmpdir}:/app/tmp app ./bin/rspec spec/controllers/users_controller_api_spec.rb:#{test_line_number}"
       run_cmd cmd, chdir: fixture_dir
 
       example.run

data/spec/rspec_feature_metadata_spec.rb

@@ -7,7 +7,7 @@ describe 'RSpec feature and feature group metadata' do
     around(:each) do |example|
       FileUtils.rm_rf tmpdir
       FileUtils.mkdir_p tmpdir
-      cmd = "docker-compose run --rm -e APPMAP=true -v #{File.absolute_path(tmpdir).shellescape}:/app/tmp app ./bin/rspec spec/models/user_spec.rb"
+      cmd = "docker-compose run --rm -e RAILS_ENV=test -e APPMAP=true -v #{File.absolute_path(tmpdir).shellescape}:/app/tmp app ./bin/rspec spec/models/user_spec.rb"
       run_cmd cmd, chdir: fixture_dir
 
       example.run

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: appmap
 version: !ruby/object:Gem::Version
-  version: 0.40.0
+  version: 0.41.0
 platform: ruby
 authors:
 - Kevin Gilpin
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-01-29 00:00:00.000000000 Z
+date: 2021-02-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -386,6 +386,7 @@ files:
 - spec/fixtures/hook/compare.rb
 - spec/fixtures/hook/constructor.rb
 - spec/fixtures/hook/exception_method.rb
+- spec/fixtures/hook/exclude.rb
 - spec/fixtures/hook/instance_method.rb
 - spec/fixtures/hook/labels.rb
 - spec/fixtures/hook/singleton_method.rb