appmap-ruby is a Ruby Gem for recording
AppMaps of your code.
“AppMap” is a data format which records code structure (modules, classes, and methods), code execution events
(function calls and returns), and code metadata (repo name, repo URL, commit
SHA, labels, etc). It’s more granular than a performance profile, but it’s less
granular than a full debug trace. It’s designed to be optimal for understanding the design intent and structure of code and key data flows.
There are several ways to record AppMaps of your Ruby program using the appmap gem:
APPMAP=true. An AppMap will be generated for each spec.AppMap.record block, which returns JSON containing the code execution trace.Once you have made a recording, there are two ways to view automatically generated diagrams of the AppMaps.
The first option is to load the diagrams directly in your IDE, using the AppMap extension for VSCode or the AppMap plugin for RubyMine.
The second option is to upload them to the AppMap Cloud using the CLI for AppMap Cloud.
Support for new versions is added frequently, please check back regularly for updates.
Add gem 'appmap' to 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
Install with bundle install, as usual.
When you run your program, the appmap gem reads configuration settings from appmap.yml. Here’s an extensive example file for a Rails project:
# 'name' should generally be the same as the code repo name.
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.
# These are just examples.
- gem: activerecord
- 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 ]
packages
Each entry in the packages list is a YAML object which has the following keys:
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 list.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.
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.
The AppMap data format provides for class and function labels, which can be used to enhance the AppMap visualizations, and to programatically analyze the data.
You can apply function labels using source code comments in your Ruby code. To apply a labels to a function, add a @label or @labels line to the comment which immediately precedes a function.
For example, if you add this comment to your source code:
class ApiKey
# @labels provider.authentication security
def authenticate(key)
# logic to verify the key here...
end
end
Then the AppMap metadata section for this function will include:
{
"name": "authenticate",
"type": "function",
"labels": [ "provider.authentication", "security" ]
}
Run the tests with the environment variable APPMAP=true:
$ APPMAP=true bundle exec rspec
Each RSpec test will output an AppMap file into the directory tmp/appmap/rspec. For example:
$ find tmp/appmap/rspec
Hello_says_hello_when_prompted.appmap.json
Run your tests as you normally would with the environment variable APPMAP=true. For example:
$ APPMAP=true bundle exec rake test
or
$ APPMAP=true bundle exec ruby -Ilib -Itest test/*_test.rb
Each Minitest test will output an AppMap file into the directory tmp/appmap/minitest. For example:
$ find tmp/appmap/minitest
Hello_says_hello_when_prompted.appmap.json
To record Cucumber tests, follow these additional steps:
1) Require appmap/cucumber in support/env.rb:
require 'appmap/cucumber'
Be sure to require it before config/environment is required.
2) Create an Around hook in support/hooks.rb to record the scenario:
if AppMap::Cucumber.enabled?
Around('not @appmap-disable') do |scenario, block|
appmap = AppMap.record do
block.call
end
AppMap::Cucumber.write_scenario(scenario, appmap)
end
end
3) Run the tests with the environment variable APPMAP=true:
$ APPMAP=true bundle exec cucumber
Each Cucumber test will output an AppMap file into the directory tmp/appmap/cucumber. For example:
$ find tmp/appmap/cucumber
Hello_Says_hello_when_prompted.appmap.json
To manually record ad-hoc AppMaps of your Ruby app, use AppMap remote recording.
(optional) Download and unpack the AppMap browser extension. Install into Chrome using chrome://extensions/. Turn on “Developer Mode” and then load the extension using the “Load unpacked” button.
Start your Rails application server, with APPMAP=true. For example:
$ APPMAP=true bundle exec rails server
Continue with the remote recording for code editors instructions.
https://github.com/applandinc/appmap-ruby