appmap 0.43.0 → 0.47.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4007f0eb67a3a25088e8b3677de8d0388fd1bfec4b326c43a51c503f640325b5
-  data.tar.gz: 1b593251a7a072b7a1483e7af172b9157d6913208658fb324630bc52b0b4fe73
+  metadata.gz: f1f2b43daf0437ceb6073a64272148ca9168c4ac781c01e2e73c36259a3bcc7b
+  data.tar.gz: 2a7275d2be15d2bfcf0c2dfc898807212840506c3692232b2d049bc771a4a3b9
 SHA512:
-  metadata.gz: 6af64a17bf69655ae8bdc9b4b67b7e2c9bd1b87d07a23e266dcabd2a927311224a4b27a77355674559828a08ae1df2e7231e2a68a2734c0f620de8efc48ec6d4
-  data.tar.gz: 7725cb0c79d8be13fddf7a3b688113f4fd31941c4f08f64ee44d4fbb3f5255dd3a308b08ef578413938052ee3b9eeecedc3e58bc092b12e23bfa872eac119eb7
+  metadata.gz: 5000bdc938facaa5e181de6e3d6023c6a1b1a1e48a260545ae3245236bf271e22ab6462c16d1c73fb44b4e9bc4e6533f8be12428e2d7ff9e1c06f65ec1992bf7
+  data.tar.gz: 10db3cd34b1f9eb5f81070607d12b6a714b12735ac25828df4c6a3e50d0efa354ad9ff9206bc42cd2d7ccb61ffef83f663d41b3896928f0fd9bdd1e53ed4e543

data/.releaserc.yml

@@ -0,0 +1,11 @@
+plugins:
+  - '@semantic-release/commit-analyzer'
+  - '@semantic-release/release-notes-generator'
+  - '@semantic-release/changelog'
+  - 'semantic-release-rubygem'
+  - - '@semantic-release/git'
+    - assets:
+        - CHANGELOG.md
+        - appmap.gemspec
+        - lib/appmap/version.rb
+  - '@semantic-release/github'

data/.travis.yml

@@ -13,11 +13,42 @@ services:
 # necessary.
 before_script:
   - unset RAILS_ENV
-  
+
+cache:
+  bundler: true
+
+before_install:
+  # see https://blog.travis-ci.com/docker-rate-limits 
+  # and also https://www.docker.com/blog/what-you-need-to-know-about-upcoming-docker-hub-rate-limiting/
+  # if we do not use authorized account, 
+  # the pulls-per-IP quota is shared with other Travis users
+  - >
+    if [ ! -z "$DOCKERHUB_PASSWORD" ] && [ ! -z "$DOCKERHUB_USERNAME" ]; then
+      echo "$DOCKERHUB_PASSWORD" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin  ;
+    fi
+
+ 
+# GEM_ALTERNATIVE_NAME only needed for deployment 
 jobs:
   include:
   - stage: test
     script:
     - mkdir tmp
-    - bundle exec rake test
+    - GEM_ALTERNATIVE_NAME='' bundle exec rake test
+
     
+before_deploy:
+  - |
+    nvm install --lts \
+      && nvm use --lts \
+      && npm i -g \
+        semantic-release \
+        @semantic-release/git \
+        @semantic-release/changelog \
+        semantic-release-rubygem
+
+deploy:
+  - provider: script
+    script: ./release.sh
+    on:
+      branch: master

data/CHANGELOG.md

@@ -1,3 +1,47 @@
+# [0.47.0](https://github.com/applandinc/appmap-ruby/compare/v0.46.0...v0.47.0) (2021-05-13)
+
+
+### Features
+
+* Emit swagger-style normalized paths instead of Rails-style ones ([5a93cd7](https://github.com/applandinc/appmap-ruby/commit/5a93cd7096ca195146a84a6733c7d502dbcd0272))
+
+# [0.46.0](https://github.com/applandinc/appmap-ruby/compare/v0.45.1...v0.46.0) (2021-05-12)
+
+
+### Features
+
+* Record view template rendering events and template paths ([973b258](https://github.com/applandinc/appmap-ruby/commit/973b2581b6e2d4e15a1b93331e4e95a88678faae))
+
+## [0.45.1](https://github.com/applandinc/appmap-ruby/compare/v0.45.0...v0.45.1) (2021-05-04)
+
+
+### Bug Fixes
+
+* Optimize instrumentation and load time ([db4a8ce](https://github.com/applandinc/appmap-ruby/commit/db4a8ceed4103a52caafa46626c66f33fbfeac27))
+
+# [0.45.0](https://github.com/applandinc/appmap-ruby/compare/v0.44.0...v0.45.0) (2021-05-03)
+
+
+### Bug Fixes
+
+* Properly name status_code in HTTP server response ([556e87c](https://github.com/applandinc/appmap-ruby/commit/556e87c9a7bf214f6b8714add4f77448fd223d33))
+
+
+### Features
+
+* Record http_client_request and http_client_response ([1db32ae](https://github.com/applandinc/appmap-ruby/commit/1db32ae0d26a7f1400b6b814d25b13368f06c158))
+* Update AppMap format version to 1.5.0 ([061705e](https://github.com/applandinc/appmap-ruby/commit/061705e4619cb881e8edd022ef835183e399e127))
+* **build:** add deployment via `semantic-release` with automatic publication to rubygems ([9f183de](https://github.com/applandinc/appmap-ruby/commit/9f183de13f405900000c3da979c3a8a5b6e34a24))
+
+# v0.44.0
+
+* Support recording and labeling of indivudal functions via `functions:` section in *appmap.yml*.
+* Remove deprecated `exe/appmap`.
+* Add `test_status` and `exception` fields to AppMap metadata.
+* Write AppMap file atomically, by writing to a temp file first and then moving it into place.
+* Remove printing of `Inventory.json` file.
+* Remove source code from `classMap`.
+
 # v0.43.0
 
 * Record `name` and `class` of each entry in Hash-like parameters, messages, and return values.

data/README.md

@@ -9,10 +9,11 @@
   - [Minitest](#minitest)
   - [Cucumber](#cucumber)
   - [Remote recording](#remote-recording)
-  - [Server process recording](#server-process-recording)
 - [AppMap for VSCode](#appmap-for-vscode)
+- [AppMap Swagger](#appmap-swagger)
 - [Uploading AppMaps](#uploading-appmaps)
 - [Development](#development)
+  - [Internal architecture](#internal-architecture)
   - [Running tests](#running-tests)
   - [Using fixture apps](#using-fixture-apps)
     - [`test/fixtures`](#testfixtures)
@@ -109,6 +110,9 @@ name: my_project
 packages:
 - path: app/controllers
 - path: app/models
+  # Exclude sub-paths within the package path
+  exclude:
+  - concerns/accessor
 - path: app/jobs
 - path: app/helpers
 # Include the gems that you want to see in the dependency maps.
@@ -117,15 +121,22 @@ packages:
 - gem: devise
 - gem: aws-sdk
 - gem: will_paginate
+# Global exclusion of a class name
 exclude:
 - MyClass
 - MyClass#my_instance_method
 - MyClass.my_class_method
+functions:
+- packages: myapp
+  class: ControllerHelper
+  function: logged_in_user
+  labels: [ authentication ]
 ```
 
 * **name** Provides the project name (required)
 * **packages** A list of source code directories which should be recorded.
 * **exclude** A list of classes and/or methods to definitively exclude from recording.
+* **functions** A list of specific functions, scoped by package and class, to record.
 
 **packages**
 
@@ -144,6 +155,11 @@ Each entry in the `packages` list is a YAML object which has the following keys:
 
 Optional list of fully qualified class and method names. Separate class and method names with period (`.`) for class methods and hash (`#`) for instance methods.
 
+**functions**
+
+Optional list of `class, function` pairs. The `package` name is used to place the function within the class map, and does not have to match
+the folder or gem name. The primary use of `functions` is to apply specific labels to functions whose source code is not accessible (e.g., it's in a Gem).
+For functions which are part of the application code, use `@label` or `@labels` in code comments to apply labels.
 
 # Labels
 
@@ -309,29 +325,40 @@ if defined?(AppMap)
 end
 ```
 
-2. Download and unpack the [AppLand browser extension](https://github.com/applandinc/appland-browser-extension). Install into Chrome using `chrome://extensions/`. Turn on "Developer Mode" and then load the extension using the "Load unpacked" button.
+2. (optional) Download and unpack the [AppLand browser extension](https://github.com/applandinc/appland-browser-extension). Install into Chrome using `chrome://extensions/`. Turn on "Developer Mode" and then load the extension using the "Load unpacked" button.
 
-3. Start your Rails application server. For example:
+3. Start your Rails application server, with `APPMAP_RECORD=true`. For example:
 
 ```sh-session
-$ bundle exec rails server
+$ APPMAP_RECORD=true bundle exec rails server
 ```
 
-4. Open the AppLand browser extension and push `Start`.
+4. Start the recording
 
-5. Use your app. For example, perform a login flow, or run through a manual UI test.
+Option 1: Open the AppLand browser extension and push `Start`.
+Option 2: `curl -XPOST localhost:3000/_appmap/record` (be sure and get the port number right)
 
-6. Open the AppLand browser extension and push `Stop`. The recording will be transferred to the AppLand website and opened in your browser.
+5. Use your app. For example, perform a login flow, or run through a manual UI test.
 
-## Server process recording
+6. Finish the recording.
 
-Run your Rails server with `APPMAP_RECORD=true`. When the server exits, an *appmap.json* file will be written to the project directory. This is a great way to start the server, interact with your app as a user (or through it's API), and then view an AppMap of everything that happened.
+Option 1: Open the AppLand browser extension and push `Stop`. The recording will be transferred to the AppLand website and opened in your browser.
+Option 2: `curl -XDELETE localhost:3000/_appmap/record > recording.appmap.json` - Saves the recording as a local file.
 
-Be sure and set `WEB_CONCURRENCY=1`, if you are using a webserver that can run multiple processes. You only want there to be one process while you are recording, otherwise they will both try and write *appmap.json* and one of them will clobber the other.
 
 # AppMap for VSCode
 
-The [AppMap extension for VSCode](https://marketplace.visualstudio.com/items?itemName=appland.appmap) is a great way to onboard developers to new code, and troubleshoot hard-to-understand bugs with visuals.
+The [AppMap extension for VSCode](https://marketplace.visualstudio.com/items?itemName=appland.appmap) helps you navigate your code more efficiently with interactive, accurate software architecture diagrams right in your IDE. In less than two minutes you can go from installing the AppMap extension to exploring maps of your code's architecture. AppMap helps you:
+
+* Onboard to code architecture, with no extra work for the team
+* Conduct code and design reviews using live and accurate data
+* Troubleshoot hard-to-understand bugs using a "top-down" approach.
+
+Each interactive diagram links directly to the source code, and the information is easy to share.
+
+# AppMap Swagger
+
+[appmap_swagger](https://github.com/applandinc/appmap_swagger-ruby) is a tool to generate Swagger files from AppMap data. With `appmap_swagger`, you can add Swagger to your Ruby or Ruby on Rails project, with no need to write or modify code. Use the Swagger UI to interact with your web services API as you build it, and use diffs of Swagger to perform code review of web service changes.
 
 # Uploading AppMaps
 
@@ -342,6 +369,34 @@ For instructions on uploading, see the documentation of the [AppLand CLI](https:
 # Development
 [![Build Status](https://travis-ci.com/applandinc/appmap-ruby.svg?branch=master)](https://travis-ci.com/applandinc/appmap-ruby)
 
+## Internal architecture
+
+**Configuration**
+
+*appmap.yml* is loaded into an `AppMap::Config`. 
+
+**Hooking**
+
+Once configuration is loaded, `AppMap::Hook` is enabled. "Hooking" refers to the process of replacing a method
+with a "hooked" version of the method. The hooked method checks to see if tracing is enabled. If so, it wraps the original
+method with calls that record the parameters and return value.
+
+**Builtins**
+
+`Hook` begins by iterating over builtin classes and modules defined in the `Config`. Builtins include code
+like `openssl` and `net/http`. This code is not dependent on any external libraries being present, and 
+`appmap` cannot guarantee that it will be loaded before builtins. Therefore, it's necessary to require it and
+hook it by looking up the classes and modules as constants in the `Object` namespace.
+
+**User code and gems**
+
+After hooking builtins, `Hook` attaches a [TracePoint](https://ruby-doc.org/core-2.6/TracePoint.html) to `:begin` events.
+This TracePoint is notified each time a new class or module is being evaluated. When this happens, `Hook` uses the `Config`
+to determine whether any code within the evaluated file is configured for hooking. If so, a `TracePoint` is attached to
+`:end` events. Each `:end` event is fired when a class or module definition is completed. When this happens, the `Hook` enumerates
+the public methods of the class or module, hooking the ones that are targeted by the `Config`. Once the `:end` TracePoint leaves
+the scope of the `:begin`, the `:end` TracePoint is disabled.
+
 ## Running tests
 
 Before running tests, configure `local.appmap` to point to your local `appmap-ruby` directory.

data/README_CI.md

@@ -0,0 +1,29 @@
+# Configuration variables:
+
+* `GH_TOKEN`: used by `semantic-release` to push changes to Github and manage releases
+* `GEM_HOST_API_KEY`: rubygems API key
+* `GEM_ALTERNATIVE_NAME` (optional): used for testing of CI flows, 
+to avoid publication of test releases under official package name
+* `DOCKERHUB\_USERNAME`, `DOCKERHUB_PASSWORD`: optional dockerhub credentials, 
+to avoid throttling of dockerhub anonymous pulls
+
+Note: for security reasons, it's better to use dedicated (not personal) 
+Dockerhub account, 
+and also use [access tokens](https://docs.docker.com/docker-hub/access-tokens/) 
+instead of primary password
+
+# Release command
+
+`./release.sh` 
+
+Bash wrapper script is used merely as a launcher of `semantic-release` 
+with extra logic to explicitly determine git url from `TRAVIS_REPO_SLUG` \
+variable if its defined (otherwise git url is taken from `package.json`, 
+which breaks CI on forked repos).
+
+# CI flow
+
+1. Test happens using current version number specified in `lib/appmap/version.rb`, then `release.sh` launches `semantic-release` to do the rest
+2. The version number is increased (including modicication of `version.rb`)
+3. Gem is published under new version number
+4. Github release is created with the new version number

data/Rakefile

@@ -37,7 +37,8 @@ end
   
 def build_base_image(ruby_version)
   run_cmd "docker build" \
-         " --build-arg RUBY_VERSION=#{ruby_version} --build-arg GEM_VERSION=#{GEM_VERSION}" \
+         " --build-arg RUBY_VERSION=#{ruby_version}"    \
+         " --build-arg GEM_VERSION=#{GEM_VERSION}"      \
          " -t appmap:#{GEM_VERSION} -f Dockerfile.appmap ."
 end
   
@@ -46,7 +47,7 @@ def build_app_image(app, ruby_version)
     run_cmd( {"RUBY_VERSION" => ruby_version, "GEM_VERSION" => GEM_VERSION},
       " docker-compose build" \
       " --build-arg RUBY_VERSION=#{ruby_version}" \
-      " --build-arg GEM_VERSION=#{GEM_VERSION}")
+      " --build-arg GEM_VERSION=#{GEM_VERSION}"  ) 
   end
 end
 
@@ -138,3 +139,4 @@ task spec: %i[spec:all]
 task test: %i[spec:all minitest]
 
 task default: :test
+

data/appmap.gemspec

@@ -4,8 +4,12 @@ lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'appmap/version'
 
+
+
 Gem::Specification.new do |spec|
-  spec.name          = 'appmap'
+  # ability to parameterize gem name is added intentionally, 
+  # to support the possibility of unofficial releases, e.g. during CI tests
+  spec.name          = (ENV['GEM_ALTERNATIVE_NAME'].to_s.empty? ? 'appmap' : ENV["GEM_ALTERNATIVE_NAME"] )
   spec.version       = AppMap::VERSION
   spec.authors       = ['Kevin Gilpin']
   spec.email         = ['kgilpin@gmail.com']
@@ -20,8 +24,6 @@ Gem::Specification.new do |spec|
 ")
   spec.extensions << "ext/appmap/extconf.rb"
 
-  spec.bindir        = 'exe'
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
   spec.add_dependency 'activesupport'

data/lib/appmap.rb

@@ -43,6 +43,7 @@ module AppMap
     # Call this function before the program code is loaded by the Ruby VM, otherwise
     # the load events won't be seen and the hooks won't activate.
     def initialize(config_file_path = 'appmap.yml')
+      raise "AppMap configuration file #{config_file_path} does not exist" unless ::File.exists?(config_file_path)
       warn "Configuring AppMap from path #{config_file_path}"
       Config.load_from_file(config_file_path).tap do |configuration|
         self.configuration = configuration
@@ -50,11 +51,6 @@ module AppMap
       end
     end
 
-    # Whether to include source and comments in all class maps.
-    def include_source?
-      ENV['APPMAP_SOURCE'] == 'true'
-    end
-
     # Used to start tracing, stop tracing, and record events.
     def tracing
       @tracing ||= Trace::Tracing.new
@@ -88,8 +84,8 @@ module AppMap
     end
 
     # Builds a class map from a config and a list of Ruby methods.
-    def class_map(methods, options = {})
-      ClassMap.build_from_methods(methods, options)
+    def class_map(methods)
+      ClassMap.build_from_methods(methods)
     end
 
     # Returns default metadata detected from the Ruby system and from the

data/lib/appmap/class_map.rb

@@ -71,27 +71,24 @@ module AppMap
     end
 
     class << self
-      def build_from_methods(methods, options = {})
+      def build_from_methods(methods)
         root = Types::Root.new
         methods.each do |method|
-          add_function root, method, options
+          add_function root, method
         end
         root.children.map(&:to_h)
       end
 
       protected
 
-      def add_function(root, method, include_source: true)
-        package = method.package
-        static = method.static
-
+      def add_function(root, method)
         object_infos = [
           {
-            name: package.name,
+            name: method.package,
             type: 'package'
           }
         ]
-        object_infos += method.defined_class.split('::').map do |name|
+        object_infos += method.class_name.split('::').map do |name|
           {
             name: name,
             type: 'class'
@@ -100,7 +97,7 @@ module AppMap
         function_info = {
           name: method.name,
           type: 'function',
-          static: static
+          static: method.static
         }
         location = method.source_location
 
@@ -108,23 +105,15 @@ module AppMap
           if location
             location_file, lineno = location
             location_file = location_file[Dir.pwd.length + 1..-1] if location_file.index(Dir.pwd) == 0
-            [ location_file, lineno ].join(':')
+            [ location_file, lineno ].compact.join(':')
           else
-            [ method.defined_class, static ? '.' : '#', method.name ].join
+            [ method.class_name, method.static ? '.' : '#', method.name ].join
           end
 
-        source, comment = begin
-          [ method.source, method.comment ]
-        rescue MethodSource::SourceNotFoundError
-          [ nil, nil, ]
-        end
-
-        if include_source
-          function_info[:source] = source unless source.blank?
-          function_info[:comment] = comment unless comment.blank?
-        end
+        comment = method.comment
+        function_info[:comment] = comment unless comment.blank?
 
-        function_info[:labels] = parse_labels(comment) + (package.labels || [])
+        function_info[:labels] = parse_labels(comment) + (method.labels || [])
         object_infos << function_info
 
         parent = root

data/lib/appmap/command/record.rb

@@ -27,7 +27,7 @@ module AppMap
           event_thread.join
           yield AppMap::APPMAP_FORMAT_VERSION,
                 AppMap.detect_metadata,
-                AppMap.class_map(tracer.event_methods, include_source: AppMap.include_source?),
+                AppMap.class_map(tracer.event_methods),
                 events
         end