Skip to main content

Runtime Trace Filtering

This article explains how Dbux determines which files and lines of code to trace.

When Dbux is enabled, it automatically records execution of all files that are not in node_modules1. This can be configured. However, it is a balancing act to determine the optimal set of files to trace. Often times it is easiest to tell Dbux to just trace everything, but tracing everything can slow things down significantly.

tip

If you know that some packages do not contribute to your dynamic analysis, do not whitelist them or explicitly blacklist them. This can improve performance, especially if they contain many lines of code or many trace❔ event records.

Whitelists and Blacklists

Dbux currently offers several configuration options to tell Dbux which files to trace:

  • packageWhitelist (pw)
  • packageBlacklist (pb)
  • fileWhitelist (fw)
  • fileBlacklist (fb)

Some notes:

  • Each one of these settings supports comma-separated lists of file or package names or regexes.
  • All paths are normalized to use /, so don't use backslashes on Windows.
  • Implementation of the filter is in @dbux/common-node/src/filters/moduleFilter.js.
  • -> packageName is determined via parsePackageName
    • NOTE: packageName supports namespaces.
    • Examples of packageName detection for different module paths:
      • my/app/node_modules/a -> a
      • my/app/node_modules/a/b/c.js -> a
      • my/app/node_modules/a/b/node_modules/c/d -> c
      • my/app/node_modules/@a/b/c.js -> @a/b
      • etc.

Run Button + @dbux/cli

When using the Run Button and/or @dbux/cli, you can configure this via the --pw, --pb, --fw and --fb flags.

  • Example: npx dbux run --pw=.* --pb=lodash ./test.js
    • -> Traces all libraries, but lodash.

Babel Config

When manually integrating Dbux into your build pipeline, you generally want to make use of the moduleFilter API (@dbux/babel-plugin/src/external) in your config file and manually adjust your global Babel include or ignore settings to make sure that you are tracing and recording the files that you want.

NOTE: The moduleFilter functions return function (not string or RegExp).

const shouldInclude = require('@dbux/common-node/dist/filters/makeInclude').default;

// ...

const moduleFilterOptions = {
  packageWhitelist: 'interestingPackage1,@interesting/package2',
  // packageBlacklist: '',
  fileBlacklist: '.*bad_file1\.js,.*/unwanted_dir1/.*'
};

module.exports = {
  include: [
    shouldInclude(moduleFilterOptions)
  ]
};

/* dbux disable /

You can disable tracing of individual traces and/or expressions by adding a comment containing a line of dbux disable, (e.g. /** dbux disable */) in front of it.

E.g., in the following sample code, a long-running (but unimportant) loop will not get instrumented, thus largely improving performance:

f();
/* dbux disable */
for (const i = 0; i < 1e6; ++i) {
  // ...
}
g();
  1. Support for PnP and other module systems are future-work.↩