AppMap Analysis

When there is AppMap Data available in your project, AppMap Runtime Analysis can scan them to detect flaws in the code. These flaws are surfaced as findings and are displayed in your code editor as you work so that they can be addressed before they are propagated to test or production environments.

Enable AppMap Scanner

The AppMap dynamic runtime analysis of AppMap data is disabled by default. Follow the instructions below to enable the AppMap Scanner to analyze your AppMap data for software flaws.

In JetBrains

Open the JetBrains settings page and search for appmap scanner. Ensure the box is checked for the AppMap Scanner setting.

After applying this change, restart your JetBrains editor and in the AppMap plugin you will see the Runtime Analysis section with any findings within your AppMap data.

In VS Code

Open the VS Code settings page and search for appmap scanner. Ensure the box is checked for the AppMap Scanner setting.

After applying this change, reload your VS Code editor and in the AppMap plugin you will see the Runtime Analysis section with any findings within your AppMap data.

Findings are displayed In the Runtime Analysis sidebar pane sorted by impact category and type.

Clicking the ‘Overview’ link in the Runtime Analysis sidebar will open the ‘Runtime Analysis Summary’ window which contains a summary of findings for a particular project.

In this video
AppMap Analysis scans your AppMap Data to find software design flaws that impact performance, stability, security and maintainability. This runtime code analysis can find the problems that static code analyzers miss - and that cause 90% of today’s most serious production issues.

Links mentioned
AppMap Community Slack
Get AppMap for VSCode
Get AppMap for JetBrains

Investigate findings

Let’s look at a sample Ruby on rails application, where AppMap has already been installed and AppMap Data has been generated. From the test cases, you’ll see a new option for findings in the left-hand column or an option here for investigate findings.

You can see one of the issues we’ve found is that a log event contained secret data by clicking on the finding will be taken directly to the line of code where this event occurs by hovering over the pin.

Use labels to visually explore your code

You can open the AppMap and see exactly where the function wrote this secret to a log file. How does AppMap know that this was a secret? Unlike static analyzers and other tools that do pattern matching AppMap knows this function generates secrets because we have built in knowledge of common software libraries with pre-populated labels.

We know exactly where to look to avoid false positives. Developers can extend their labels, whether it’s a common library or not with simple code comments on their functions.

If you search for the secret label, you’ll see the location in the code where this event occurs by clicking on the function, you’ll be taken to the exact location of the AppMap, where the secret was generated. Additionally, you can open the code, combining a visual model alongside the code.

Configuring Analysis Checks

AppMap Analysis is configured in a YAML document. It’s primary job is to specify which scanner rules will check the code. Each check specifies a rule id, and may include additional properties that customized and tune the behavior of the rule.

AppMap Analysis ships with a default configuration file located in node_modules/@appland/scanner/built/sampleConfig/default.yml.

Without specifying the --config command line option, AppMap will attempt to load appmap-scanner.yml, the default configuration for analysis rules. If that file does not exist, AppMap will fail back to loading the configuration in the node_modules path.

To use a non-default configuration, specify the path to the configuration file via the -c or --config option:

$ npx @appland/scanner \
    --appmap-dir tmp/appmap \
    --config appmap-scanner.yml \
    ci

To use a custom configuration create a file named appmap-scanner.yml in the root of your project directory, you can copy the default.yml in the AppMap source code as a starting point. Refer to the Rules Reference for additional configuration options per scanner rule.

Example appmap-scanner.yml

checks:
  - rule: authzBeforeAuthn
  - rule: http500
  - rule: illegalPackageDependency
    properties:
      callerPackages:
        - equal: actionpack
      calleePackage:
        equal: app/controllers
  - rule: insecureCompare
  - rule: missingAuthentication
  - rule: missingContentType
  - rule: nPlusOneQuery
  - rule: secretInLog
  - rule: slowFunctionCall
    properties:
      timeAllowed: 0.2
      functions:
        - match: Controller#create$
  - rule: slowHttpServerRequest
    properties:
      timeAllowed: 0.5
  - rule: slowQuery
    properties:
      timeAllowed: 0.05
  - rule: tooManyJoins
  - rule: tooManyUpdates
  - rule: unbatchedMaterializedQuery
  - rule: updateInGetRequest

Match pattern config

Some rule options are defined as type MatchPatternConfig. MatchPatternConfig is a flexible way to match a string such as content type, code object name, etc.

Each MatchPatternConfig requires one of the following three YAML keys:

- match: RegExp   # String value must match this regexp
- include: string # String value must include this substring
- equal: string   # String value must equal this string

Optionally:

- ignoreCase: boolean # When true, the match/include/equal test is case-insensitive

Examples

The illegalPackageDependency rule is applied to the package app/controllers (exactly). The caller package must be actionpack (exactly).

  - rule: illegalPackageDependency
    properties:
      callerPackages:
        - equal: actionpack
      calleePackage:
        equal: app/controllers

The slowFunctionCall rule is applied to all functions that match one of two regular expressions (case sensitive).

  - rule: slowFunctionCall
    properties:
      functions:
        - match: ^app/models
        - match: ^app/jobs

The missingAuthentication rule is not applied to any event whose route includes /api/.

  - rule: missingAuthentication
    exclude:
      - event:
          property: route
          test:
            include: /api/

Findings Reference

When a scanner check matches an AppMap, it issues a finding. A finding includes detailed information about the match, indicating such information as:

  • A title and message.
  • AppMap in which the finding was found.
  • The primary and secondary events that are relevant to the finding.

Properties

  • ruleId identifier of the rule algorithm.
  • checkId identifier of the check, which a configured instance of a rule.
  • ruleTitle human-friendly title of the rule.
  • message human-friendly message describing the finding.
  • appMapFile relative path to the AppMap file containing the match.
  • event JSON object of the primary event on which the match was found.
  • relatedEvents JSON of other events in the AppMap which are associated with the finding. They can be inspected in the AppMap to better understand the finding.
  • scope JSON of the event which defines the AppMap subtree in which the finding was discovered.
  • hash of the finding which can be used to identify duplicate findings.

Finding hash

A hash of the finding is computed from the finding properties that are most important and characteristic. The hash is used implement a critical feature of AppMap Analysis - de-duplication. De-duplication serves two purposes:

1) A finding may occur many times within a set of AppMap Diagrams. As a user, you’re only interested in unique findings, therefore the hash can be used to de-duplicate the findings and present a minimal data set. 2) Findings can be managed and triaged in the AppMap Server UI. For example, a finding can be deferred to prevent that finding from holding up a build or pull request. If the finding occurs again in the future, the hash is used to recognize that the finding has already been found, triaged - therefore the finding is not reported as new, and does not block the build or need to be re-triaged.

Was this page helpful? thumb_up Yes thumb_down No
Thank you for your feedback!