atatus-profiling-agent

Continuous profiling agent for Node.js applications — part of the Atatus observability platform.

Collects CPU (wall-time), heap (space), and timeline/event profiles from running Node.js processes and uploads them to the Atatus profiling backend in pprof format.

Table of Contents

• Requirements
• Installation
• Quick Start
• Configuration Reference
  • Code Options
  • Environment Variables
• Profiler Types
• Exporters
• Logging
• OOM Monitoring
• Source Map Support
• Graceful Shutdown
• Architecture Overview
• Development
• License

Requirements

| Requirement | Version | |-------------|---------| | Node.js | ≥ 16.x | | OS | Linux, macOS (Windows: limited support) | | Atatus API Key | Required for upload |

Installation

npm install atatus-profiling-agent

Quick Start

Require the profiler before any other module in your application entry point, then call start():

const profiler = require('atatus-profiling-agent/profiler');

profiler.start({
  service: 'my-node-app',     // Required: name of your service
  version: '1.0.0',           // Optional: service version
  env: 'production',          // Optional: deployment environment
  apiKey: 'YOUR_API_KEY',     // Required: your Atatus API key
  profiling: {
    enabled: true
  }
});

// Rest of your app below...
const express = require('express');

Or pass the API key via environment variable:

ATATUS_API_KEY=YOUR_API_KEY node app.js

Configuration Reference

Code Options

Pass these as properties to profiler.start(config):

| Option | Type | Default | Description | |--------|------|---------|-------------| | service | string | "node" | Service name shown in the Atatus UI | | version | string | — | Service version | | env | string | — | Deployment environment (production, staging, etc.) | | apiKey | string | ATATUS_API_KEY env var | Required. Your 36-character Atatus API key | | url | string | https://profiling-rx.atatus.com | Profiling ingestion endpoint | | hostname | string | localhost | Agent host (when using agent exporter) | | port | number | 8126 | Agent port (when using agent exporter) | | tags | object\|string | — | Custom tags, e.g. { team: 'backend' } or "team:backend,region:us" | | logger | object | ConsoleLogger | Custom logger (see Logging) | | interval | number | 65000 | Profile upload interval in milliseconds (min ~60s) | | uploadTimeout | number | 60000 | Upload timeout in milliseconds | | sourceMap | boolean | true | Enable source map resolution for minified stacks | | debugSourceMaps | boolean | false | Log source map resolution details | | profilers | string[] | ["wall","space"] | Profilers to enable (see Profiler Types) | | exporters | string[]\|Exporter[] | ["agent"] | Where to send profiles (see Exporters) | | repositoryUrl | string | — | Git repo URL for source code integration | | commitSHA | string | — | Git commit SHA for source code integration | | timelineEnabled | boolean | true (non-Windows) | Enable timeline view in the Atatus UI | | codeHotspotsEnabled | boolean | true (non-Windows) | Link profiles to traces (code hotspots) | | endpointCollection | boolean | true (non-Windows) | Enable endpoint-level profiling aggregation | | cpuProfilingEnabled | boolean | true (non-Windows) | Enable CPU profiling | | samplingInterval | number | ~10.1ms (99 Hz) | Wall profiler sampling interval in milliseconds | | heapSamplingInterval | number | — | Heap profiler sampling interval in bytes | | uploadCompression | string | "gzip" | Compression: "on", "off", "gzip", "zstd", or with level e.g. "gzip-6" | | pprofPrefix | string | "" | File path prefix when using the file exporter | | oomMonitoring | boolean | true (non-Windows) | Capture heap snapshot on OOM | | oomHeapLimitExtensionSize | number | 0 | Bytes to extend heap before triggering OOM export | | oomMaxHeapExtensionCount | number | 0 | Max heap extensions before forcing OOM export | | oomExportStrategies | string[] | ["process"] | OOM strategies: "process", "worker", "interrupt" |

Environment Variables

| Environment Variable | Equivalent Option | |----------------------|-------------------| | ATATUS_API_KEY | apiKey | | ATATUS_SERVICE | service | | ATATUS_VERSION | version | | ATATUS_ENV | env | | ATATUS_TAGS | tags (comma-separated key:value pairs) | | ATATUS_PROFILING_URL | url | | ATATUS_AGENT_HOST | hostname | | ATATUS_TRACE_AGENT_PORT | port | | ATATUS_PROFILING_PROFILERS | profilers (e.g. wall,space) | | ATATUS_PROFILING_WALLTIME_ENABLED | Enable/disable wall profiler | | ATATUS_PROFILING_HEAP_ENABLED | Enable/disable heap profiler | | ATATUS_PROFILING_CPU_ENABLED | cpuProfilingEnabled | | ATATUS_PROFILING_UPLOAD_PERIOD | interval (in seconds) | | ATATUS_PROFILING_UPLOAD_TIMEOUT | uploadTimeout (in ms) | | ATATUS_PROFILING_SOURCE_MAP | sourceMap | | ATATUS_PROFILING_DEBUG_SOURCE_MAPS | debugSourceMaps | | ATATUS_PROFILING_TIMELINE_ENABLED | timelineEnabled | | ATATUS_PROFILING_CODEHOTSPOTS_ENABLED | codeHotspotsEnabled | | ATATUS_PROFILING_ENDPOINT_COLLECTION_ENABLED | endpointCollection | | ATATUS_PROFILING_DEBUG_UPLOAD_COMPRESSION | uploadCompression | | ATATUS_PROFILING_HEAP_SAMPLING_INTERVAL | heapSamplingInterval | | ATATUS_PROFILING_PPROF_PREFIX | pprofPrefix | | ATATUS_PROFILING_EXPERIMENTAL_OOM_MONITORING_ENABLED | oomMonitoring | | ATATUS_PROFILING_EXPERIMENTAL_OOM_HEAP_LIMIT_EXTENSION_SIZE | oomHeapLimitExtensionSize | | ATATUS_PROFILING_EXPERIMENTAL_OOM_MAX_HEAP_EXTENSION_COUNT | oomMaxHeapExtensionCount | | ATATUS_PROFILING_EXPERIMENTAL_OOM_EXPORT_STRATEGIES | oomExportStrategies |

Profiler Types

| Name | Alias | Description | |------|-------|-------------| | wall | cpu | Wall-time profiler — samples call stack at ~99 Hz to show CPU time | | space | — | Heap profiler — samples allocations to show memory usage by call site | | events | — | Events profiler — auto-added when timeline is enabled; captures async activity |

Default: wall,space

# Enable only wall profiler
ATATUS_PROFILING_PROFILERS=wall node app.js

# Disable heap profiler
ATATUS_PROFILING_HEAP_ENABLED=false node app.js

Exporters

| Exporter | Description | |----------|-------------| | "agent" | (default) Uploads profiles to https://profiling-rx.atatus.com | | "file" | Writes raw pprof files to disk (path set by pprofPrefix) |

// Send to API and also save to disk
profiler.start({
  service: 'my-app',
  apiKey: 'YOUR_API_KEY',
  exporters: ['agent', 'file'],
  pprofPrefix: '/tmp/profiles/my-app'
});

Logging

The profiler accepts any logger implementing these four methods:

{ debug, info, warn, error }

Integrate with Pino / Winston / Bunyan

const pino = require('pino');
const logger = pino();

profiler.start({
  service: 'my-app',
  apiKey: 'YOUR_API_KEY',
  logger: {
    debug: (msg) => logger.debug(msg),
    info:  (msg) => logger.info(msg),
    warn:  (msg) => logger.warn(msg),
    error: (msg, ...args) => logger.error(msg, ...args),
  }
});

Silence all logging

profiler.start({
  service: 'my-app',
  apiKey: 'YOUR_API_KEY',
  logger: { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} }
});

OOM Monitoring

Captures a heap snapshot automatically when the process is about to run out of memory.

Note: Not supported on Windows.

profiler.start({
  service: 'my-app',
  apiKey: 'YOUR_API_KEY',
  oomMonitoring: true,
  oomHeapLimitExtensionSize: 50 * 1024 * 1024, // extend heap by 50MB before snapshot
  oomMaxHeapExtensionCount: 1,
  oomExportStrategies: ['process'],
});

Export strategies:

| Strategy | Description | |----------|-------------| | process | Export in the current process (default) | | worker | Export in a spawned worker thread | | interrupt | Use async interrupt to trigger export |

Source Map Support

When sourceMap: true (default), minified/transpiled stack frames are resolved back to original source locations — useful for TypeScript projects.

profiler.start({
  service: 'my-ts-app',
  apiKey: 'YOUR_API_KEY',
  sourceMap: true,
  debugSourceMaps: true, // log resolution details
});

Graceful Shutdown

The agent hooks into process.beforeExit to flush profiles automatically. For explicit control:

process.on('SIGTERM', () => {
  profiler.stop();
  process.exit(0);
});

Architecture Overview

atatus-profiling-agent/
├── profiler.js            # Public API: start() / stop()
├── profiling/
│   ├── index.js           # Profiler lifecycle manager
│   ├── config.js          # Config parsing (options + env vars)
│   ├── profiler.js        # Core scheduler & upload loop
│   ├── profilers/
│   │   ├── wall.js        # Wall-time (CPU) profiler
│   │   ├── space.js       # Heap profiler
│   │   └── events.js      # Timeline events profiler
│   ├── exporters/
│   │   ├── agent.js       # HTTP upload to Atatus API
│   │   └── file.js        # Write pprof files to disk
│   └── loggers/
│       └── console.js     # Default console logger
├── pprof/                 # Native pprof bindings (@atatus/pprof)
├── libdatadog/            # Native Rust bindings (@atatus/libatatus)
├── plugins/               # Instrumentation shims
└── log/                   # Internal logging utilities

Development

# Install dependencies
npm install

# Run tests
node test.js

Runtime dependencies

| Package | Purpose | |---------|---------| | @atatus/pprof | Native pprof sampling (wall + heap) | | @atatus/libatatus | Native Rust library bindings | | atatus-nodejs | Core Atatus Node.js agent | | delay | Async delay utility (used by pprof) | | p-limit | Concurrency limiter (used by pprof) | | pprof-format | pprof protobuf serialization | | source-map | Source map resolution for stack frames | | dc-polyfill | diagnostics_channel polyfill | | koalas | Null-coalescing helper | | retry | Upload retry logic | | node-gyp-build | Native addon loader |

License

ISC © Atatus — https://www.atatus.com