Initial commit

src/PowderCoating.Web/LOGGING-GUIDE.md

@@ -0,0 +1,167 @@
+# Logging Guide for PowderCoating Application
+
+## Log File Locations
+
+When you deploy the application to your testing server, logs will be written to:
+
+### On Windows Server
+```
+C:\inetpub\wwwroot\YourAppFolder\logs\
+```
+or wherever your application is deployed to.
+
+### Log Files Created
+
+1. **powdercoating-YYYYMMDD.txt** - All application logs (Info, Warning, Error)
+   - Contains general application activity
+   - Includes request logs with user information
+   - New file created daily
+   - Keeps last 30 days
+
+2. **errors-YYYYMMDD.txt** - Error logs only
+   - Contains ONLY errors and critical issues
+   - **Check this file first when troubleshooting**
+   - New file created daily
+   - Keeps last 90 days
+
+## What Gets Logged
+
+### Automatic Error Logging
+- **Unhandled Exceptions**: All unhandled errors are automatically logged with:
+  - Exception details and stack trace
+  - URL path where error occurred
+  - Username (or "Anonymous")
+  - Request trace ID
+  - Timestamp
+
+- **HTTP Requests**: All requests are logged with:
+  - HTTP method and path
+  - Response status code
+  - Duration
+  - User information
+  - IP address
+  - User agent
+
+### Log Entry Format
+```
+2026-02-11 10:30:45.123 -05:00 [ERR] [PowderCoating.Web.Controllers.JobsController] Error creating job
+System.InvalidOperationException: Job validation failed
+   at PowderCoating.Web.Controllers.JobsController.Create(...)
+```
+
+## Finding Logs on Your Testing Server
+
+### Step 1: Locate the Application Directory
+1. Connect to your testing server via RDP
+2. Navigate to where the application is deployed
+3. Look for a `logs` folder in the application root
+
+### Step 2: Check for Permissions
+The application needs write permissions to the logs folder. If no logs are created:
+1. Right-click the `logs` folder → Properties → Security
+2. Ensure the IIS application pool identity has "Modify" permissions
+3. Typically this is `IIS AppPool\YourAppPoolName`
+
+### Step 3: View Current Errors
+Open the most recent `errors-YYYYMMDD.txt` file to see all errors from today.
+
+## Troubleshooting: Logs Not Appearing
+
+### If logs folder doesn't exist:
+1. The application may not have started successfully
+2. Check Windows Event Viewer → Application logs for startup errors
+3. Check IIS logs in `C:\inetpub\logs\LogFiles\`
+
+### If logs folder exists but empty:
+1. Check folder permissions (application pool needs Write access)
+2. Check if application is actually running
+3. Restart the application pool in IIS Manager
+
+### If only seeing old logs:
+1. Application may have crashed - check Windows Event Viewer
+2. Application pool may have stopped - check IIS Manager
+3. Restart the application pool to generate fresh startup logs
+
+## Log Levels by Environment
+
+### Development
+- Logs everything at Information level and above
+- Full console output with colors
+- Detailed EF Core query logs
+
+### Production/Testing (Your Server)
+- Logs Information level and above
+- Warnings for Microsoft/System components
+- Separate error log for quick troubleshooting
+- Request logging enabled for audit trail
+
+## Reading the Logs
+
+### Finding Specific Errors
+Use PowerShell to search logs:
+```powershell
+# Find all errors today
+Get-Content "logs\errors-$(Get-Date -Format yyyyMMdd).txt"
+
+# Search for specific error
+Select-String -Path "logs\*.txt" -Pattern "InvalidOperationException"
+
+# Get last 50 error lines
+Get-Content "logs\errors-*.txt" | Select-Object -Last 50
+```
+
+### Common Log Patterns
+
+**Database Connection Error:**
+```
+[ERR] An error occurred using the connection to database 'PowderCoatingDb'
+```
+
+**Authentication Error:**
+```
+[ERR] [Microsoft.AspNetCore.Authentication] Authentication failed
+```
+
+**Unhandled Exception:**
+```
+[ERR] [PowderCoating.Web.Controllers.*] Unhandled exception occurred
+```
+
+## Additional Monitoring
+
+### Windows Event Viewer
+For startup/crash errors that may not appear in application logs:
+1. Open Event Viewer
+2. Windows Logs → Application
+3. Filter by Source: "ASP.NET Core"
+
+### IIS Logs
+For HTTP-level issues:
+- Location: `C:\inetpub\logs\LogFiles\W3SVC*\`
+- Shows HTTP status codes, response times
+- Useful for 500 errors, timeouts
+
+## Log Retention
+
+- **General Logs**: Last 30 days automatically retained
+- **Error Logs**: Last 90 days automatically retained
+- Older logs are automatically deleted to save disk space
+- Archive important logs if you need long-term retention
+
+## Performance Impact
+
+The current logging configuration:
+- **Minimal impact** on application performance
+- Logs are written asynchronously
+- File writes are flushed every 1 second
+- `shared: true` allows multiple processes to write to same log file
+
+## Next Steps: Production Logging Improvements
+
+For production deployment, consider:
+1. **Azure Application Insights** - Cloud-based monitoring and alerting
+2. **Seq** - Structured log server with web UI
+3. **ELK Stack** - Elasticsearch, Logstash, Kibana
+4. **Centralized logging** - Aggregate logs from multiple servers
+
+Contact your DevOps team to set up one of these for production.