Skip to main content

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:

atmos.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:

atmos terraform plan vpc -s plat-ue2-dev --profiler-enabled

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:

EndpointDescription
http://localhost:6060/debug/pprof/profile30-second CPU profile
http://localhost:6060/debug/pprof/heapMemory heap profile
http://localhost:6060/debug/pprof/goroutineStack 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:

Analyzing CPU profile

# 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​

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​