Stats Data

While an analysis of the overall rule performance for an ESLint run can be carried out by setting the TIMING environment variable, it can sometimes be useful to acquire more granular timing data (lint time per file per rule) or collect other measures of interest. In particular, when developing new custom plugins and evaluating/benchmarking new languages or rule sets. For these use cases, you can optionally collect runtime statistics from ESLint.

Enable stats collection

To enable collection of statistics, you can either:

1. Use the --stats CLI option. This will pass the stats data into the formatter used to output results from ESLint. (Note: not all formatters output stats data.)
2. Set stats: true as an option on the ESLint constructor.

Enabling stats data adds a new stats key to each LintResult object containing data such as parse times, fix times, lint times per rule.

As such, it is not available via stdout but made easily ingestible via a formatter using the CLI or via the Node.js API to cater to your specific needs.

◆ Stats type

The Stats value is the timing information of each lint run. The stats property of the LintResult type contains it. It has the following properties:

• fixPasses (number)
  The number of times ESLint has applied at least one fix after linting.
• times ({ passes: TimePass[] })
  The times spent on (parsing, fixing, linting) a file, where the linting refers to the timing information for each rule.
  • TimePass ({ parse: ParseTime, rules?: Record<string, RuleTime>, fix: FixTime, total: number })
    An object containing the times spent on (parsing, fixing, linting)
    • ParseTime ({ total: number })
      The total time that is spent when parsing a file.
    • RuleTime ({ total: number }) The total time that is spent on a rule.
    • FixTime ({ total: number }) The total time that is spent on applying fixes to the code.

CLI usage

Let’s consider the following example:

/*eslint no-regex-spaces: "error", wrap-regex: "error"*/

function a() {
    return / foo/.test("bar");
}
1
2
3
4
5

Run ESLint with --stats and output to JSON via the built-in json formatter:

npx eslint file-to-fix.js --fix --stats -f json
1

This yields the following stats entry as part of the formatted lint results object:

{
    "times": {
        "passes": [
            {
                "parse": {
                    "total": 3.975959
                },
                "rules": {
                    "no-regex-spaces": {
                        "total": 0.160792
                    },
                    "wrap-regex": {
                        "total": 0.422626
                    }
                },
                "fix": {
                    "total": 0.080208
                },
                "total": 12.765959
            },
            {
                "parse": {
                    "total": 0.623542
                },
                "rules": {
                    "no-regex-spaces": {
                        "total": 0.043084
                    },
                    "wrap-regex": {
                        "total": 0.007959
                    }
                },
                "fix": {
                    "total": 0
                },
                "total": 1.148875
            }
        ]
    },
    "fixPasses": 1
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

Note, that for the simple example above, the sum of all rule times should be directly comparable to the first column of the TIMING output. Running the same command with TIMING=all, you can verify this:

$ TIMING=all npx eslint file-to-fix.js --fix --stats -f json
...
Rule            | Time (ms) | Relative
:---------------|----------:|--------:
wrap-regex      |     0.431 |    67.9%
no-regex-spaces |     0.204 |    32.1%
1
2
3
4
5
6

API Usage

You can achieve the same thing using the Node.js API by passingstats: true as an option to the ESLint constructor. For example:

const { ESLint } = require("eslint");

(async function main() {
    // 1. Create an instance.
    const eslint = new ESLint({ stats: true, fix: true });

    // 2. Lint files.
    const results = await eslint.lintFiles(["file-to-fix.js"]);

    // 3. Format the results.
    const formatter = await eslint.loadFormatter("json");
    const resultText = formatter.format(results);

    // 4. Output it.
    console.log(resultText);
})().catch((error) => {
    process.exitCode = 1;
    console.error(error);
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19