Performance Profiling

Profiling helps identify performance bottlenecks in the Meteor build tool and application. This guide covers built-in profilers and profiling techniques from the Meteor source code.

Built-in Profiler (METEOR_PROFILE)

Meteor includes a built-in profiler activated with the METEOR_PROFILE environment variable.

Basic Usage

The value is interpreted as a threshold in milliseconds:

METEOR_PROFILE=1 meteor run

This reports all calls taking more than 1ms.

Adjusting Threshold

Higher thresholds show only slower operations:

METEOR_PROFILE=100 meteor run  # Only calls > 100ms
METEOR_PROFILE=200 meteor run  # Only calls > 200ms

Understanding Output

You’ll see reports like:

| (#1) Profiling: ProjectContext prepareProjectForBuild
| ProjectContext prepareProjectForBuild..........9,207 ms (1)
|    _initializeCatalog.............................24 ms (1)
|       files.readFile                               7 ms (2)
|       runJavaScript package.js                     2 ms (1)
|       files.rm_recursive                           4 ms (4)
|       other _initializeCatalog                    11 ms
|    _resolveConstraints.........................6,702 ms (1)
|       bundler.readJsImage.........................42 ms (1)
...
| (#1) Total: 9,544 ms (ProjectContext prepareProjectForBuild)

Reading the Report

Top-down listing - Hierarchical call structure
Dotted lines - Entries with child entries
Time - Total cumulative time of all calls
Number in parentheses - Call count
Other entries - Time not accounted for by instrumented children

Key Metrics

Important sections to watch:

ProjectContext prepareProjectForBuild - Overall preparation time
_initializeCatalog - Package catalog loading
_resolveConstraints - Package version resolution
bundler.readJsImage - Loading compiled packages
ImportScanner#_readFile - File scanning and reading

Inspector Profiling (METEOR_INSPECT)

Meteor includes advanced profiling using Node.js’s inspector module, generating .cpuprofile files.

Basic Usage

Specify which functions to profile:

METEOR_INSPECT=bundler.bundle meteor build ./output-build

Profile Multiple Functions

METEOR_INSPECT=bundler.bundle,compiler.compile meteor run

Available Functions

Complete list for METEOR_INSPECT:

bundler.bundle
compiler.compile
Babel.compile
_readProjectMetadata
initializeCatalog
_downloadMissingPackages
_saveChangeMetadata
_realpath
package-client

Configuration Options

Context identifier:

METEOR_INSPECT_CONTEXT=my_build

Output directory:

METEOR_INSPECT_OUTPUT=/path/to/profiles

Default: ./profiling Sampling interval:

METEOR_INSPECT_INTERVAL=500

Lower values = more detail, more memory usage. Maximum profile size:

METEOR_INSPECT_MAX_SIZE=1000

Default: 2000 MB. Prevents out-of-memory errors.

Complete Example

METEOR_INSPECT=bundler.bundle,compiler.compile \
METEOR_INSPECT_CONTEXT=production_build \
METEOR_INSPECT_OUTPUT=./profiles \
METEOR_INSPECT_INTERVAL=500 \
METEOR_INSPECT_MAX_SIZE=1000 \
meteor build --directory ./output

Viewing Profile Results

Chrome DevTools

Open Chrome DevTools (F12)
Go to “Performance” or “Profiler” tab
Click “Load Profile”
Select the .cpuprofile file

Discoveryjs cpupro

Open-source interactive CPU profile viewer: Online:

Visit https://discoveryjs.github.io/cpupro/
Drag and drop your .cpuprofile file
Explore the interactive visualization

Locally:

npm install -g cpupro
cpupro <profile-file>.cpuprofile

Advantages over Chrome DevTools:

Better handling of large profiles
More flexible filtering
Advanced search capabilities
Multiple visualization modes
Ability to compare profiles

Memory Optimization

Increasing Memory Limit

Inspector profiling consumes more memory:

NODE_OPTIONS="--max-old-space-size=4096" \
METEOR_INSPECT=bundler.bundle meteor build ./output

Memory Considerations

Inspector profiling uses more memory than standard profiler
Large profiles (>2GB) automatically truncated
Consider METEOR_INSPECT_MAX_SIZE to limit memory usage
Use standard profiler for quick analysis

When to Use Each Profiler

Use METEOR_PROFILE when:

Quick performance check needed
General analysis of build times
Identifying obvious bottlenecks
Low memory environment
CI/CD performance monitoring

Use METEOR_INSPECT when:

Deep analysis required
Complex performance issues
Specific bottleneck investigation
Visual analysis needed
Comparing multiple builds

Instrumenting Code

Add profiling annotations to your own code:

Wrap Functions

var doIt = Profile("doIt", function (...) {
  // function body
});

Wrap Methods

MyClass.prototype.doIt = Profile(
  "MyClass doIt",
  MyClass.prototype.doIt
);

Timed Blocks

function doIt() {
  var result = Profile.time("doIt", () => {
    // timed code
  });
  return result;
}

Conditional Profiling

For packages loaded into the tool:

if (typeof Profile !== 'undefined') {
  Profile.time("operation", () => {
    // code
  });
} else {
  // code without profiling
}

Performance Considerations

Unreported Work

Not covered by standard reports:

App start-up time
File watcher creation after rebuild

Caching Impact

Multiple cache layers affect timing:

Built packages and plugins
Compiler plugin results (including old file versions)
Linker output
Server program (for client-only changes)
Constraint solver results

Rebuild Timings:

Initial build: Slowest (cold cache)
First rebuild: Faster (warm cache)
Second rebuild: Even faster (fully warm)

Release vs Checkout

Performance differences: Release Mode:

Faster startup
Pre-built core packages
Efficient constraint solving

Checkout Mode:

Recompiles core packages
Large number of watched files
Extra delay after rebuild
Useful for tool development

Hardware and OS Impact

Disk Speed:

SSDs much faster than HDDs
Impacts cache read/write times

Operating System:

Mac/Linux: Fast file operations, symlinks, atomic renames
Windows: Slower file operations, no symlinks, rename = copy
Virus scanners can block/delay operations

Profiling Specific Areas

CSS Minification

CSS processing can take 500ms to several seconds:

METEOR_PROFILE=100 meteor run --production

Watch for:

CSS parsing time
CSS generation time
Source map generation

Constraint Solving

METEOR_PROFILE=50 meteor run

Watch for:

_resolveConstraints time
Package database queries
Logic solver invocations

File Watching

METEOR_PROFILE=10 meteor run

Watch for:

File watcher creation
File scanning operations
WatchSet merging

Import Scanning

METEOR_INSPECT=compiler.compile meteor run

Watch for:

ImportScanner#_readFile
File reading operations
SHA1 hashing

Comparing Performance

Before/After Optimization

Baseline profile:

METEOR_PROFILE=100 meteor run > before.log 2>&1

Apply optimization

New profile:

METEOR_PROFILE=100 meteor run > after.log 2>&1

Compare times for specific operations

Using meteor profile

Compare build performance:

meteor profile

This provides detailed timing for:

Prepare project
Build app
Individual build steps

Debugging with node-inspector

For interactive debugging:

TOOL_NODE_FLAGS="--inspect" meteor run

Or break on first line:

TOOL_NODE_FLAGS="--inspect-brk" meteor run

Custom port:

TOOL_NODE_FLAGS="--inspect=6060" meteor run

Debugging Test Apps

SELF_TEST_TOOL_NODE_FLAGS="--inspect-brk=5859" meteor self-test

Use different port to avoid collision with main tool.

Common Performance Issues

Large “other” Time

If you see:

| ImportScanner#_readFile...............1,338 ms (329)
|    files.readFile                       100 ms (329)
|    sha1                                   3 ms (329)
|    other ImportScanner#_readFile      1,235 ms

Large “other” indicates missing instrumentation. Add more Profile calls to narrow down.

Source Map Generation

Noticeable time spent building source maps:

Consider more efficient use of source-map library
Look at Webpack’s optimizations

Linker Cache Writes

Large files taking seconds to write:

Watch files.writeFileAtomically calls
May appear outside top level (async)
Consider cleaning up old cache files

Package Server Updates

Slow “Updating package catalog…”:

Can take 5+ seconds
Sometimes much longer
Consider local package mirror

Best Practices

Use appropriate profiler - METEOR_PROFILE for quick checks, METEOR_INSPECT for deep dives
Set reasonable thresholds - Start with 100ms, adjust as needed
Profile production builds - Different performance characteristics
Clear caches first - For accurate cold-start measurements
Profile multiple runs - Account for variability
Watch for GC - Times can be inflated by garbage collection
Consider hardware - SSD vs HDD, OS differences
Instrument custom code - Add Profile calls to your plugins
Compare apples to apples - Same cache state, same environment
Document findings - Share results with team

Interpreting Results

Good Performance Indicators

Most time in actual work (compile, bundle)
Minimal “other” time
Efficient cache usage
Fast constraint solving

Red Flags

Large “other” sections
Repeated work (cache misses)
Slow file operations
Long constraint solving
Excessive file scanning

Build System

Deployment

Performance

Contributing

Documentation Index

​Performance Profiling

​Built-in Profiler (METEOR_PROFILE)

​Basic Usage

​Adjusting Threshold

​Understanding Output

​Reading the Report

​Key Metrics

​Inspector Profiling (METEOR_INSPECT)

​Basic Usage

​Profile Multiple Functions

​Available Functions

​Configuration Options

​Complete Example

​Viewing Profile Results

​Chrome DevTools

​Discoveryjs cpupro

​Memory Optimization

​Increasing Memory Limit

​Memory Considerations

​When to Use Each Profiler

​Use METEOR_PROFILE when:

​Use METEOR_INSPECT when:

​Instrumenting Code

​Wrap Functions

​Wrap Methods

​Timed Blocks

​Conditional Profiling

​Performance Considerations

​Unreported Work

​Caching Impact

​Release vs Checkout

​Hardware and OS Impact

​Profiling Specific Areas

​CSS Minification

​Constraint Solving

​File Watching

​Import Scanning

​Comparing Performance

​Before/After Optimization

​Using meteor profile

​Debugging with node-inspector

​Debugging Test Apps

​Common Performance Issues

​Large “other” Time

​Source Map Generation

​Linker Cache Writes

​Package Server Updates

​Best Practices

​Interpreting Results

​Good Performance Indicators

​Red Flags

​Related Topics

Build docs developers (and LLMs) love

Performance Profiling

Built-in Profiler (METEOR_PROFILE)

Basic Usage

Adjusting Threshold

Understanding Output

Reading the Report

Key Metrics

Inspector Profiling (METEOR_INSPECT)

Basic Usage

Profile Multiple Functions

Available Functions

Configuration Options

Complete Example

Viewing Profile Results

Chrome DevTools

Discoveryjs cpupro

Memory Optimization

Increasing Memory Limit

Memory Considerations

When to Use Each Profiler

Use METEOR_PROFILE when:

Use METEOR_INSPECT when:

Instrumenting Code

Wrap Functions

Wrap Methods

Timed Blocks

Conditional Profiling

Performance Considerations

Unreported Work

Caching Impact

Release vs Checkout

Hardware and OS Impact

Profiling Specific Areas

CSS Minification

Constraint Solving

File Watching

Import Scanning

Comparing Performance

Before/After Optimization

Using meteor profile

Debugging with node-inspector

Debugging Test Apps

Common Performance Issues

Large “other” Time

Source Map Generation

Linker Cache Writes

Package Server Updates

Best Practices

Interpreting Results

Good Performance Indicators

Red Flags

Related Topics