Add trace log level using debug npm package for flexible verbosity control

AGENTS.md

@@ -159,9 +159,11 @@ The codebase follows a modular architecture with clear separation of concerns:
    - `SquidConfig`, `DockerComposeConfig`: Typed configuration objects
 
 5. **Logging** (`src/logger.ts`)
-   - Singleton logger with configurable log levels (debug, info, warn, error)
+   - Singleton logger with configurable log levels (trace, debug, info, warn, error)
+   - Uses the [`debug`](https://www.npmjs.com/package/debug) npm package for flexible namespace-based logging
    - Uses `chalk` for colored output
    - All logs go to stderr (console.error) to avoid interfering with command stdout
+   - Supports both `--log-level` flag and `DEBUG` environment variable for fine-grained control
 
 ### Container Architecture
 
@@ -385,7 +387,7 @@ sudo cat /tmp/squid-logs-<timestamp>/access.log
 
 - Tests use Jest (`npm test`)
 - Currently no test files exist (tsconfig excludes `**/*.test.ts`)
-- Integration testing: Run commands with `--log-level debug` and `--keep-containers` to inspect generated configs and container logs
+- Integration testing: Run commands with `--log-level debug` or `--log-level trace` and `--keep-containers` to inspect generated configs and container logs
 
 ## MCP Server Configuration for Copilot CLI
 

README.md

@@ -69,6 +69,71 @@ Common domain lists:
 --allow-domains github.com,arxiv.org,example.com
 ```
 
+## Verbosity and Logging
+
+Control the verbosity of awf output using the `--log-level` option. The logging system uses the [`debug`](https://www.npmjs.com/package/debug) npm package for flexible, namespace-based logging.
+
+### Using --log-level flag
+
+```bash
+# Available log levels: trace, debug, info, warn, error
+# Default: info
+
+# Trace level - most verbose, shows all internal operations
+sudo awf --log-level trace \
+  --allow-domains github.com \
+  'curl https://api.github.com'
+
+# Debug level - detailed information for troubleshooting
+sudo awf --log-level debug \
+  --allow-domains github.com \
+  'curl https://api.github.com'
+
+# Info level - standard output (default)
+sudo awf --log-level info \
+  --allow-domains github.com \
+  'curl https://api.github.com'
+
+# Warn level - only warnings and errors
+sudo awf --log-level warn \
+  --allow-domains github.com \
+  'curl https://api.github.com'
+
+# Error level - only errors
+sudo awf --log-level error \
+  --allow-domains github.com \
+  'curl https://api.github.com'
+```
+
+### Advanced: Using DEBUG environment variable
+
+For more fine-grained control, you can use the `DEBUG` environment variable to enable specific log namespaces:
+
+```bash
+# Enable all awf logs
+DEBUG=awf:* sudo -E awf --allow-domains github.com 'curl https://api.github.com'
+
+# Enable only debug and trace logs
+DEBUG=awf:debug,awf:trace sudo -E awf --allow-domains github.com 'curl https://api.github.com'
+
+# Enable only info, warn, and error logs
+DEBUG=awf:info,awf:warn,awf:error sudo -E awf --allow-domains github.com 'curl https://api.github.com'
+```
+
+**Available namespaces:**
+- `awf:trace` - Trace-level messages (most verbose)
+- `awf:debug` - Debug-level messages
+- `awf:info` - Informational messages
+- `awf:success` - Success messages
+- `awf:warn` - Warning messages
+- `awf:error` - Error messages
+
+**Log Level Hierarchy:**
+- `trace` - All messages (most verbose)
+- `debug` - Debug, info, warnings, and errors
+- `info` - Info, warnings, and errors (default)
+- `warn` - Warnings and errors only
+- `error` - Errors only (least verbose)
 
 ## Security Considerations
 

docs/architecture.md

@@ -60,9 +60,11 @@ The firewall uses a containerized architecture with Squid proxy for L7 (HTTP/HTT
 - `SquidConfig`, `DockerComposeConfig`: Typed configuration objects
 
 ### 5. Logging (`src/logger.ts`)
-- Singleton logger with configurable log levels (debug, info, warn, error)
+- Singleton logger with configurable log levels (trace, debug, info, warn, error)
+- Uses the [`debug`](https://www.npmjs.com/package/debug) npm package for flexible namespace-based logging
 - Uses `chalk` for colored output
 - All logs go to stderr (console.error) to avoid interfering with command stdout
+- Supports both `--log-level` flag and `DEBUG` environment variable for fine-grained control
 
 ## Container Architecture
 

docs/usage.md

@@ -8,7 +8,7 @@ sudo awf [options] <command>
 Options:
   --allow-domains <domains>  Comma-separated list of allowed domains (required)
                              Example: github.com,api.github.com,arxiv.org
-  --log-level <level>        Log level: debug, info, warn, error (default: info)
+  --log-level <level>        Log level: trace, debug, info, warn, error (default: info)
   --keep-containers          Keep containers running after command exits
   --work-dir <dir>           Working directory for temporary files
   -V, --version              Output the version number
@@ -224,11 +224,24 @@ sudo awf --allow-domains github.com "curl -f http://169.254.169.254"
 
 ### Enable Debug Logging
 
+The logging system uses the [`debug`](https://www.npmjs.com/package/debug) npm package for flexible namespace-based logging.
+
 ```bash
+# Using --log-level flag
 sudo awf \
   --allow-domains github.com \
   --log-level debug \
   'your-command'
+
+# Using DEBUG environment variable for fine-grained control
+DEBUG=awf:* sudo -E awf \
+  --allow-domains github.com \
+  'your-command'
+
+# Enable only specific namespaces
+DEBUG=awf:debug,awf:info sudo -E awf \
+  --allow-domains github.com \
+  'your-command'
 ```
 
 This will show:
@@ -238,6 +251,14 @@ This will show:
 - Network connectivity tests
 - Proxy traffic logs
 
+**Available namespaces:**
+- `awf:trace` - Most verbose
+- `awf:debug` - Debug information
+- `awf:info` - Informational messages
+- `awf:success` - Success messages
+- `awf:warn` - Warnings
+- `awf:error` - Errors
+
 ### Real-Time Log Streaming
 
 Container logs are streamed in real-time, allowing you to see output as commands execute:

package.json

@@ -35,20 +35,22 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "commander": "^12.0.0",
     "chalk": "^4.1.2",
+    "commander": "^12.0.0",
+    "debug": "^4.4.3",
     "execa": "^5.1.1",
     "js-yaml": "^4.1.0"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
-    "@types/js-yaml": "^4.0.5",
+    "@types/debug": "^4.1.12",
+    "@types/glob": "^8.1.0",
     "@types/jest": "^29.0.0",
+    "@types/js-yaml": "^4.0.5",
+    "@types/node": "^20.0.0",
     "@typescript-eslint/eslint-plugin": "^6.0.0",
     "@typescript-eslint/parser": "^6.0.0",
     "eslint": "^8.0.0",
     "glob": "^10.3.0",
-    "@types/glob": "^8.1.0",
     "jest": "^29.0.0",
     "ts-jest": "^29.0.0",
     "typescript": "^5.0.0"

src/cli.test.ts

@@ -210,7 +210,7 @@ describe('cli', () => {
           '--allow-domains <domains>',
           'Comma-separated list of allowed domains'
         )
-        .option('--log-level <level>', 'Log level: debug, info, warn, error', 'info')
+        .option('--log-level <level>', 'Log level: trace, debug, info, warn, error', 'info')
         .option('--keep-containers', 'Keep containers running after command exits', false)
         .argument('<command>', 'Copilot command to execute');
 

src/cli.ts

@@ -77,7 +77,7 @@ program
   )
   .option(
     '--log-level <level>',
-    'Log level: debug, info, warn, error',
+    'Log level: trace, debug, info, warn, error',
     'info'
   )
   .option(
@@ -120,7 +120,7 @@ program
   .action(async (copilotCommand: string, options) => {
     // Parse and validate options
     const logLevel = options.logLevel as LogLevel;
-    if (!['debug', 'info', 'warn', 'error'].includes(logLevel)) {
+    if (!['trace', 'debug', 'info', 'warn', 'error'].includes(logLevel)) {
       console.error(`Invalid log level: ${logLevel}`);
       process.exit(1);
     }