# Profiler

Atmos includes built-in performance profiling capabilities using Go's pprof profiler. This allows you to analyze CPU usage, memory allocations, goroutines, and other performance metrics when running Atmos commands.

## Configuration

The profiler is configured in the `profiler` section:

**File:** `atmos.yaml`

```yaml
profiler:
  # Enable or disable the pprof profiling server
  enabled: false
  # Host to bind the profiling server to (default: localhost)
  host: "localhost"
  # Port to run the profiling server on (default: 6060)
  port: 6060
```

- **`profiler.enabled`**

  Enable or disable the pprof profiling server. When enabled, Atmos will start an HTTP server that serves pprof endpoints for performance analysis. Can also be set using the `--profiler-enabled` command-line flag.
- **`profiler.host`**

  The host address to bind the profiling server to. Defaults to `localhost` for security. Can also be set using the `--profiler-host` command-line flag.
- **`profiler.port`**

  The port number for the profiling server. Defaults to `6060` (the standard pprof port). Can also be set using the `--profiler-port` command-line flag.

## Using the Profiler

When the profiler is enabled, Atmos will start a pprof server and display the URL when any command is run:

```shell
pprof profiler available at: http://localhost:6060/debug/pprof/
Executing 'terraform plan' command...
```

## Available Endpoints

The profiler provides several endpoints for different types of analysis:

| Endpoint | Description |
|----------|-------------|
| `http://localhost:6060/debug/pprof/profile` | 30-second CPU profile |
| `http://localhost:6060/debug/pprof/heap` | Memory heap profile |
| `http://localhost:6060/debug/pprof/goroutine` | Stack traces of all current goroutines |
| `http://localhost:6060/debug/pprof/` | Interactive web interface |

## Analyzing Performance Data

You can use Go's pprof tool to analyze the profiling data:

```shell
# Capture and analyze CPU profile
go tool pprof http://localhost:6060/debug/pprof/profile

# Capture and analyze memory profile
go tool pprof http://localhost:6060/debug/pprof/heap

# Generate a web-based visualization
go tool pprof -http=:8080 http://localhost:6060/debug/pprof/profile
```

## Security Considerations

:::warning Security Notice
The profiler exposes detailed runtime information about your Atmos process. Only enable it when needed for debugging or performance analysis, and ensure the host/port are not accessible from untrusted networks.
:::

By default, the profiler binds to `localhost` only, which prevents external access. If you need to access the profiler from another machine, make sure to use appropriate network security measures.

## Environment Variables

- **`ATMOS_PROFILER_ENABLED`**
  Enable or disable the pprof HTTP profiling server.
- **`ATMOS_PROFILER_HOST`**
  Host address for the profiling server.
- **`ATMOS_PROFILER_PORT`**
  Port for the profiling server.
- **`ATMOS_PROFILE_FILE`**
  Write profiling data to the specified file.
- **`ATMOS_PROFILE_TYPE`**
  Type of profile to collect: 
  `cpu`
  , 
  `heap`
  , 
  `allocs`
  , 
  `goroutine`
  , 
  `block`
  , 
  `mutex`
  , 
  `threadcreate`
  , 
  `trace`
  .

## See Also

- [CLI Configuration](/cli/configuration) — Overview of CLI configuration
- [Environment Variables](/cli/environment-variables) — All configuration environment variables