AppMap Scanner
Code scanning, linting, assertions and alerts.
Provides consistent ways to filter (include and exclude) the AppMap events and property values.
Rule configuration
Event filters
Two standard event filters are provided that can be used with every rule: include
and exclude
.
These filters are applied to an event, and make a determination about whether or not that event
should be checked by the rule.
An event filter can be applied in one of two ways:
scope
the entire scope - for example, http_server_request
, command
.event
an individual event within a scope. When enumerateScope
is true for a rule, the event
filters are applied automatically by the scanner framework. When enumerateScope
is false, the
rule code must apply the filter itself.
The event filter consists of a property name and a test. The framework fetches the property value
from the event, and then applies the test. The test can be one of three types:
equal
- value string matches the filter condition exactly.include
- value string includes the filter condition.match
- value string matches the filter condition regexp.
Here's an example of a rule configured with a custom include
event filter. The event filter
prevents the rule from being applied to SQL queries that include the fragment
FROM "pg_class" INNER JOIN "pg_attribute"
(because these queries are fetching ORM metadata, not
application code).
- id: tooManyJoins
exclude:
- event:
property: query
test:
include: FROM "pg_class" INNER JOIN "pg_attribute"
Pattern filters
A second type of filter is pattern filter. Pattern filters are provided by rules that need, or
benefit from, specific configuration.
Like Event filters, a pattern filter uses equal
, include
, or match
. The data to which the
pattern filter is applied depends on the particulars of the rule. For example, this pattern filter
finds slow function calls within a specific package:
- id: slowFunctionCall
properties:
functions:
- match: ^app/models
timeAllowed: 0.25
Schema validation
The configuration YAML is validated against the rule schema before the scan is run. Any errors in
the configuration are reported, and must be fixed before the scan can continue. Consult the
documentation for each rule to see it's pattern filters and other configurable properties.
Development
We use yarn
for package management. Run yarn
to install dependencies and yarn build
to emit
JavaScript. To run without first emitting JavaScript to the filesystem, use yarn start
.
Installation
Install like any other Node.js package, using yarn
or npm
:
yarn add --dev @appland/scanner
Then, you may find it convenient to add some scripts to your package.json
:
"scripts": {
"scan": "npx @appland/scanner scan --appmap-dir tmp/appmap",
"scan-ci": "npx @appland/scanner ci --appmap-dir tmp/appmap",
},
Note tmp/appmap
is the standard AppMap location for some AppMap agents, but not all. Consult
your agent documentation and settings to configure the --appmap-dir
.
Scan locally
yarn run scan
Findings will be printed to the console, and saved to appland-findings.json
.
CI integration
When using Appmap Scanner in CI you can post findings summary as a commit status and/or a PR comment
(currently only GitHub is supported). In order to allow access to your repo you need to create a
personal token with following privileges and add it as a
GH_TOKEN
env variable to your CI:
repo
for posting PR commentsrepo:status
for posting commit statuses
yarn run scan-ci
Development
Using a local branch of @appland/models
Use yarn link
to create a symlink to a local version of @appland/models
. Make sure the models
package is built according to the instructions in its own README.
$ yarn link ../appmap-js/packages/models