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
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
To use a non-default configuration, specify the path to the configuration file via the
$ 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.
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
Some rule options are defined as type
MatchPatternConfig is a flexible way to
match a string such as content type, code object name, etc.
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
- ignoreCase: boolean # When true, the match/include/equal test is case-insensitive
illegalPackageDependency rule is applied to the package
app/controllers (exactly). The caller package must
- rule: illegalPackageDependency properties: callerPackages: - equal: actionpack calleePackage: equal: app/controllers
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
missingAuthentication rule is not applied to any event whose
- rule: missingAuthentication exclude: - event: property: route test: include: /api/
When a scanner check matches an AppMap, it issues a finding. A finding includes detailed information about the match, indicating such information as:
ruleIdidentifier of the rule algorithm.
checkIdidentifier of the
check, which a configured instance of a
ruleTitlehuman-friendly title of the rule.
messagehuman-friendly message describing the finding.
appMapFilerelative path to the AppMap file containing the match.
eventJSON object of the primary event on which the match was found.
relatedEventsJSON of other events in the AppMap which are associated with the finding. They can be inspected in the AppMap to better understand the finding.
scopeJSON of the event which defines the AppMap subtree in which the finding was discovered.
hashof the finding which can be used to identify duplicate findings.
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 AppMaps. 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.