# Atatus JS Profiler Setup Guide

This guide describes how to install, configure, and run the Atatus JS profiler in a Node.js project.

## 1. Quick Start (Minimum Configuration)

To run the profiler in your project, require or import the profiler agent before any other modules, and call `start()` with your configuration options.

### Code Initialization
```javascript
const profiler = require('profiling-js-agent/profiler');

profiler.start({
  service: 'my-node-app',
  version: '1.0.0',
  env: 'production',
  apiKey: 'YOUR_ATATUS_API_KEY_HERE', // REQUIRED: Your Atatus API key
  profiling: {
    enabled: true
  }
});

// Require the rest of your app below...
const express = require('express');
const app = express();
// ...
```

### Environment Variables
Alternatively, you can provide the API key (and other options) via environment variables when running your Node application:

```bash
ATATUS_API_KEY=YOUR_ATATUS_API_KEY_HERE node app.js
```

---

## 2. API Key Requirement

The `apiKey` configuration is **mandatory** for the profiler to successfully upload profiles to the Atatus backend. It must be a valid 36-character Atatus API key. 

If it is not provided in the `start()` configuration block, it will fall back to reading the `ATATUS_API_KEY` environment variable. If neither are found, requests to the profile ingestion API will fail and will be logged as HTTP errors.

---

## 3. Configuring Logging

The profiler includes built-in logging which can be highly customized. 

### Enabling and Disabling Logging
By default, the internal logger will only output on application crashes or critical startup errors. You can enable debug-level logging or mute it entirely by passing a custom logger object to the `logger` configuration key.

**To Enable Debug Logging:**
Pass a custom logger that directs `.debug()` calls to standard output. 
```javascript
const log = console;

profiler.start({
  service: 'my-node-app',
  apiKey: 'YOUR_ATATUS_API_KEY_HERE',
  logger: {
    debug: (msg, ...args) => log.debug ? log.debug(msg, ...args) : console.debug(msg, ...args),
    info: (msg, ...args) => log.info ? log.info(msg, ...args) : console.info(msg, ...args),
    warn: (msg, ...args) => log.warn ? log.warn(msg, ...args) : console.warn(msg, ...args),
    error: (msg, ...args) => log.error ? log.error(msg, ...args) : console.error(msg, ...args),
  }
});
```

**To Disable All Logging:**
Pass an empty or "blackhole" logger implementation where the functions do nothing.

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

### Supported Log Levels
The logger implementation requires four function keys: `debug`, `info`, `warn`, and `error`. We recommend integrating the profiler logging directly into your app's existing Winston, Pino, or Bunyan instances for better aggregation.