From 1ae97cd85aec95f6270f853b28e48774cefc6bf6 Mon Sep 17 00:00:00 2001
From: DanConwayDev <DanConwayDev@protonmail.com>
Date: Mon, 26 Jan 2026 16:17:55 +0000
Subject: feat: add NGIT_LOG_LEVEL configuration option

Add proper log level configuration following standard approach:
- CLI flag: --log-level <level>
- Environment variable: NGIT_LOG_LEVEL
- Default: info
- Supports simple levels (error, warn, info, debug, trace)
- Supports filter expressions (e.g., ngit_grasp=debug,actix_web=info)

Configuration is now consistent across all four sources:
1. src/config.rs - Config struct with log_level field
2. docs/reference/configuration.md - Full documentation
3. nix/module.nix - NixOS module with logLevel option
4. .env.example - Example configuration file

This replaces the previous RUST_LOG approach with proper integration
into the ngit-grasp configuration system, enabling trace logging from
CLI, environment variables, or NixOS configuration.
---
 docs/reference/configuration.md | 37 +++++++++++++++++++++++++------------
 1 file changed, 25 insertions(+), 12 deletions(-)

(limited to 'docs/reference')

diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index b24b498..b09b20f 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -1041,10 +1041,10 @@ Per-connection limits (built-in to relay-builder, not configurable):
 
 ### Logging Configuration
 
-#### `RUST_LOG`
+#### `NGIT_LOG_LEVEL`
 
-**Description:** Logging level and filters (standard Rust environment variable)  
-**Type:** String (log level or filter)  
+**Description:** Logging level and filters for application logging  
+**Type:** String (log level or filter expression)  
 **Default:** `info`  
 **Required:** No
 
@@ -1052,17 +1052,17 @@ Per-connection limits (built-in to relay-builder, not configurable):
 
 ```bash
 # Simple levels
-RUST_LOG=error    # Errors only
-RUST_LOG=warn     # Warnings and errors
-RUST_LOG=info     # Info, warnings, errors
-RUST_LOG=debug    # Debug and above
-RUST_LOG=trace    # Everything
+NGIT_LOG_LEVEL=error    # Errors only
+NGIT_LOG_LEVEL=warn     # Warnings and errors
+NGIT_LOG_LEVEL=info     # Info, warnings, errors (default)
+NGIT_LOG_LEVEL=debug    # Debug and above
+NGIT_LOG_LEVEL=trace    # Everything (very verbose)
 
-# Module-specific
-RUST_LOG=ngit_grasp=debug,actix_web=info
+# Module-specific filtering
+NGIT_LOG_LEVEL=ngit_grasp=debug,actix_web=info
 
 # Complex filters
-RUST_LOG=debug,hyper=info,tokio=warn
+NGIT_LOG_LEVEL=debug,hyper=info,tokio=warn
 ```
 
 **Log levels (most to least verbose):**
@@ -1073,12 +1073,25 @@ RUST_LOG=debug,hyper=info,tokio=warn
 4. `warn` - Warnings about potential issues
 5. `error` - Errors only
 
+**CLI flag:**
+
+```bash
+ngit-grasp --log-level trace
+```
+
 **Production recommendation:**
 
 ```bash
-RUST_LOG=info,ngit_grasp=debug
+NGIT_LOG_LEVEL=info
 ```
 
+**Notes:**
+
+- Uses Rust's `tracing` crate filter syntax
+- Supports module-level filtering (e.g., `ngit_grasp=debug,hyper=info`)
+- `trace` level can significantly impact performance
+- For production, `info` or `warn` is recommended
+
 ---
 
 ### Security Configuration (Planned)
-- 
cgit v1.2.3