Add ability to filter logs via CLI option or environment variable

[lukastaegert]

This PR contains:

• bugfix
• feature
• refactor
• documentation
• other

Are tests included?

• yes (bugfixes and features will not be merged without tests)
• no

Breaking Changes?

• yes (breaking changes will not be merged unless absolutely necessary)
• no

List any relevant issue numbers:

Description

This PR adds the ability to easily filter logs based on a new command line option —-filterLogs <filter> and environment variable ROLLUP_FILTER_LOGS. The motivation is to allow for easy drilling down into logs for debugging purposes like only showing logs from certain plugins or logs with matching messages.

Filtering is done based on log properties. From the documentation:

--filterLogs <filter>

Only display certain log messages based on custom filters. In its most basic form, a filter is a key:value pair where the key is a property of the log object and the value is an allowed value. For instance

rollup -c --filterLogs code:EVAL

will only display log messages where log.code === 'EVAL'. You can specify multiple filters by separating them with a comma or using the option multiple times:

rollup -c --filterLogs "code:FOO,message:This is the message" --filterLogs code:BAR

This will display all logs where the code is either "FOO" or "BAR" or where the message is "This is the message".

For situations where you cannot easily add additional command line parameters, you can also use the ROLLUP_FILTER_LOGS environment variable. The value of this variable will be handled the same way as if you specified --filterLogs on the command line and supports a comma-separated list of filters.

There is also some advanced syntax available for more complex filters.

• ! will negate a filter:

  rollup -c --filterLogs "!code:CIRCULAR_DEPENDENCY"

  will display all logs except circular dependency warnings.

• * matches any sub-string when used in a filter value:

  rollup -c --filterLogs "code:*_ERROR,message:*error*"

  will only display logs where either the code ends with _ERROR or the message contains the string error.

• & intersects several filters:

  rollup -c --filterLogs "code:CIRCULAR_DEPENDENCY&ids:*/main.js*"

  will only display logs where both the code is "CIRCULAR_DEPENDENCY" and the ids contain /main.js. This makes use of another feature:

• if the value is an object, it will be converted to a string via JSON.stringify before applying the filter. Other non-string values will be directly cast to string.

• nested properties are supported as well:

  rollup -c --filterLogs "foo.bar:value"

  will only display logs where the property log.foo.bar has the value "value".

Currently, this is implemented as a CLI-only feature while the actual log filter function is exported by Rollup as a helper function similar to loadConfigFile to be reused by tools like Vite. That way, it can be used even in dev mode when Rollup is not running. Also from the documentation:

Applying advanced log filters

While the command line interface provides a powerful way to filter logs via the --filterLogs flag, this functionality is not directly available when using the JavaScript API. However, Rollup exposes a helper getLogFilter to generate filters using the same syntax as the CLI. This is useful when specifying a custom onLog handler and for third party systems that want to provide a similar filtering experience as Rollup CLI. This function accepts an array of strings. Note that it does not split up comma-separated lists of filters like the CLI does.

// rollup.config.mjs
import { getLogFilter } from 'rollup/getLogFilter';

const logFilter = getLogFilter(['code:FOO', 'code:BAR']);

export default {
	input: 'main.js',
	output: { format: 'es' },
	onLog(level, log, handler) {
		if (logFilter(log)) {
			handler(level, log);
		}
	}
};

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
rollup	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 26, 2023 8:15pm

[github-actions]

Thank you for your contribution! ❤️

You can try out this pull request locally by installing Rollup via

npm install rollup/rollup#filter-logs

or load it into the REPL:
https://rollup-2d79iuafk-rollup-js.vercel.app/repl/?pr=5035

[codecov]

Codecov Report

Merging #5035 (54e1bbd) into master (83d21a4) will increase coverage by 0.00%.
The diff coverage is 100.00%.

❗ Current head 54e1bbd differs from pull request most recent head 49028ad. Consider uploading reports for the commit 49028ad to get more accurate results

@@           Coverage Diff           @@
##           master    #5035   +/-   ##
=======================================
  Coverage   98.96%   98.96%           
=======================================
  Files         225      226    +1     
  Lines        8302     8347   +45     
  Branches     2280     2289    +9     
=======================================
+ Hits         8216     8261   +45     
  Misses         31       31           
  Partials       55       55           

Impacted Files	Coverage Δ
src/utils/options/mergeOptions.ts	100.00% <ø> (ø)
cli/run/batchWarnings.ts	100.00% <100.00%> (ø)
cli/run/loadConfigFile.ts	96.77% <100.00%> (+0.05%)	⬆️
cli/run/loadConfigFromCommand.ts	100.00% <100.00%> (ø)
src/utils/getLogFilter.ts	100.00% <100.00%> (ø)

... and 1 file with indirect coverage changes

[lukastaegert]

This is now ready from my side

[rollup-bot]

This PR has been released as part of rollup@3.26.0. You can test it via npm install rollup.

[ivodolenc]

Hi @lukastaegert, sorry to tag you here, but I can't find any info for a related topic in the official docs, so I'm hoping you can help me with that.

As in the example above, is it possible to ignore multiple logs using getLogsFilter()?

A quick example:

// I would like to ignore multiple codes from the array and print all other logs,
// but at the moment this prints all logs without filtering
getLogFilter(['!code:PLUGIN_1', '!code:PLUGIN_2', '!code:PLUGIN_3'])

It works fine in this case:

// this works fine and prints all logs except `PLUGIN_WARNING`
const logFilter = getLogFilter(['!code:PLUGIN_WARNING'])

As far as I understand, a sign ! ignores the specified log and prints all others to the console.

Since we are adding more of them they will cancel each other out and eventually all the logs will be printed, at least that's how I understood it, maybe I'm wrong?

How can we filter multiple codes simultaneously to print all logs except the specified ones from the array?

// at the moment this prints all logs without filtering
const logFilter = getLogFilter([
  '!code:PLUGIN_WARNING',
  '!pluginCode:SPECIAL_CODE',
  // ...
])

const builder = await rollup({
  input: './src/index.ts',
  onLog(level, log, handler) {
    if (logFilter(log)) {
      handler(level, log)
    }
  },
})