Logging

Terraback writes structured logs that help you understand what a scan is doing and diagnose failures. By default it logs to the console at the INFO level. You can raise the verbosity with command-line flags or environment variables, and you can redirect logs to a file.

Log Levels

Terraback uses standard Python log levels, from least to most verbose:

Level	When to use
ERROR	Only failures (authentication errors, API errors, fatal problems)
WARNING	Recoverable issues (throttling, skipped resources, retries)
INFO	Default. High-level progress: scanners started, resource counts, timings
DEBUG	Everything: per-resource detail, API calls, retry/backoff decisions

Command-Line Flags

Two global flags control verbosity. Place them before the command:

# Verbose output (more detail than the default INFO level)
terraback --verbose scan all aws -r us-east-1 -o ./output

# Short form
terraback -v scan all aws -r us-east-1 -o ./output

# Full debug logging (most detailed)
terraback --debug scan all aws -r us-east-1 -o ./output

• --verbose / -v raises the console log level for more progress detail.
• --debug enables DEBUG logging, including per-resource and API-call detail.

Use --debug when you are reporting a bug or trying to understand exactly which API call failed.

Environment Variables

You can also control logging with environment variables. These are useful in CI or when you want the same behavior across every command without repeating flags.

Variable	Description	Example
TERRABACK_LOG_LEVEL	Sets the log level (DEBUG, INFO, WARNING, ERROR)	DEBUG
TERRABACK_LOG_FILE	Writes logs to a file in addition to the console	/tmp/terraback.log

# Set the log level for the session
export TERRABACK_LOG_LEVEL=DEBUG

# Also write logs to a file
export TERRABACK_LOG_FILE=/tmp/terraback.log

# Run any command - it will log at DEBUG to both console and file
terraback scan all aws -r us-east-1 -o ./output

Set these variables before running any command to adjust log output. The --debug flag and TERRABACK_LOG_LEVEL=DEBUG have the same effect on verbosity.

Reading Logs

When a log file is configured, you can inspect it during or after a scan:

# View the full log
cat /tmp/terraback.log

# Follow the log live while a scan runs
tail -f /tmp/terraback.log

# Search for errors and warnings only
grep -E "ERROR|WARNING" /tmp/terraback.log

Logging When Reporting Issues

When you contact support or file an issue, the most useful information comes from a debug run captured to a file:

export TERRABACK_LOG_LEVEL=DEBUG
export TERRABACK_LOG_FILE=/tmp/terraback-debug.log

terraback scan all aws -r us-east-1 -o ./output

Attach /tmp/terraback-debug.log along with your Python version, operating system, cloud provider, and the exact command you ran. See the Troubleshooting Guide for more.