begriffs open source - ai-review/blob - critic/logging-practices.md

   1 # Source Code Logging Implementation Critic Framework
   2
   3 This framework guides the Critic role when evaluating logging implementations within source code files. This critic focuses on effective logging practices, appropriate log levels, meaningful context, structured data, and operational value that ensure logging provides actionable insights for debugging, monitoring, and incident investigation.
   4
   5 ## Source Code Logging Evaluation Areas
   6
   7 ### 1. Log Placement and Timing
   8 **What to Look For:**
   9 - Logging at appropriate points in code execution flow
  10 - Logging before and after critical operations
  11 - Logging of entry/exit points for important functions
  12 - Logging of state changes and decision points
  13 - Logging of error conditions and exceptional cases
  14
  15 **Common Problems:**
  16 - Missing logs at critical decision points or state changes
  17 - Logging too early or too late in execution flow
  18 - Inconsistent logging patterns across similar operations
  19 - Missing logs for error conditions and edge cases
  20 - Over-logging of trivial operations
  21
  22 **Evaluation Questions:**
  23 - Are logs placed at appropriate points in the execution flow?
  24 - Are critical operations and state changes properly logged?
  25 - Are error conditions and exceptional cases logged?
  26 - Is there consistent logging across similar operations?
  27 - Are entry/exit points logged for important functions?
  28
  29 ### 2. Log Level Appropriateness
  30 **What to Look For:**
  31 - Appropriate use of ERROR, WARN, INFO, DEBUG log levels
  32 - ERROR level for actual errors that need immediate attention
  33 - WARN level for concerning but non-fatal issues
  34 - INFO level for important business events and state changes
  35 - DEBUG level for detailed troubleshooting information
  36
  37 **Common Problems:**
  38 - Using ERROR level for non-error conditions
  39 - Using INFO level for debug information
  40 - Missing ERROR logs for actual error conditions
  41 - Inconsistent log level usage across similar operations
  42 - Overuse of DEBUG level in production code
  43
  44 **Evaluation Questions:**
  45 - Are log levels used appropriately for the severity of events?
  46 - Are actual errors logged at ERROR level?
  47 - Is DEBUG level used only for troubleshooting information?
  48 - Is there consistent log level usage across similar operations?
  49 - Are WARN logs used for concerning but non-fatal issues?
  50
  51 ### 3. Context and Information Quality
  52 **What to Look For:**
  53 - Sufficient context for effective debugging and analysis
  54 - Relevant identifiers (user ID, request ID, session ID, etc.)
  55 - Meaningful error messages with actionable information
  56 - State information that helps understand the context
  57 - Correlation data for distributed operations
  58
  59 **Common Problems:**
  60 - Generic error messages without specific context
  61 - Missing identifiers needed for correlation
  62 - Insufficient state information for debugging
  63 - Vague or unhelpful log messages
  64 - Missing correlation data for distributed operations
  65
  66 **Evaluation Questions:**
  67 - Do log messages include sufficient context for debugging?
  68 - Are relevant identifiers included (user ID, request ID, etc.)?
  69 - Do error messages provide actionable information?
  70 - Is state information included when relevant?
  71 - Are correlation IDs included for distributed operations?
  72
  73 ### 4. Structured Data and Formatting
  74 **What to Look For:**
  75 - Consistent log message structure and format
  76 - Structured data fields for automated parsing
  77 - Proper escaping of special characters
  78 - Consistent field naming conventions
  79 - Machine-readable data formats
  80
  81 **Common Problems:**
  82 - Inconsistent log message formats
  83 - Unstructured text that's difficult to parse
  84 - Missing or inconsistent field names
  85 - Poor escaping of special characters
  86 - Non-machine-readable data formats
  87
  88 **Evaluation Questions:**
  89 - Are log messages structured consistently?
  90 - Is data formatted for automated parsing?
  91 - Are field names consistent and meaningful?
  92 - Are special characters properly escaped?
  93 - Is the format machine-readable?
  94
  95 ### 5. Performance and Resource Impact
  96 **What to Look For:**
  97 - Efficient log message construction
  98 - Conditional logging for expensive operations
  99 - Proper use of log level filtering
 100 - Minimal impact on application performance
 101 - Appropriate use of structured logging
 102
 103 **Common Problems:**
 104 - Expensive operations in log message construction
 105 - Logging in tight loops without level checks
 106 - Inefficient string concatenation for log messages
 107 - Logging sensitive or large data structures
 108 - Performance impact from excessive logging
 109
 110 **Evaluation Questions:**
 111 - Are log messages constructed efficiently?
 112 - Is conditional logging used for expensive operations?
 113 - Are log level checks used in performance-critical code?
 114 - Does logging have minimal impact on performance?
 115 - Is sensitive data properly handled in logs?
 116
 117 ## Source Code Logging Criticism Guidelines
 118
 119 ### Focus on Logging Effectiveness
 120 **Good Criticism:**
 121 - "Missing ERROR log after database connection failure makes debugging impossible"
 122 - "Generic 'operation failed' message provides no actionable information"
 123 - "Logging user password in DEBUG message creates security vulnerability"
 124 - "Missing correlation ID makes distributed transaction tracing impossible"
 125
 126 **Poor Criticism:**
 127 - "This logging isn't good enough"
 128 - "The log message could be better"
 129 - "This doesn't provide enough information"
 130
 131 ### Emphasize Context and Debugging Value
 132 **Good Criticism:**
 133 - "Log message 'error occurred' provides no context for debugging"
 134 - "Missing user ID in authentication log prevents user-specific investigation"
 135 - "No state information logged before critical operation failure"
 136 - "Missing request ID makes correlation across services impossible"
 137
 138 **Poor Criticism:**
 139 - "This context is insufficient"
 140 - "More information would be helpful"
 141 - "This logging lacks detail"
 142
 143 ### Consider Operational Impact
 144 **Good Criticism:**
 145 - "Logging entire user object in DEBUG creates performance and security issues"
 146 - "Missing log level check in tight loop causes 50% performance degradation"
 147 - "String concatenation in log message creates unnecessary object allocation"
 148 - "Logging sensitive data violates security requirements"
 149
 150 **Poor Criticism:**
 151 - "This might cause performance issues"
 152 - "Security could be a concern"
 153 - "This logging is inefficient"
 154
 155 ## Source Code Logging Evaluation Questions
 156
 157 ### For Any Logging Implementation
 158 1. **Are logs placed at appropriate points in the execution flow?**
 159 2. **Are log levels used appropriately for the severity of events?**
 160 3. **Do log messages include sufficient context for debugging?**
 161 4. **Are log messages structured consistently?**
 162 5. **Are log messages constructed efficiently?**
 163 6. **Are critical operations and state changes properly logged?**
 164 7. **Are error conditions and exceptional cases logged?**
 165 8. **Are relevant identifiers included (user ID, request ID, etc.)?**
 166 9. **Is conditional logging used for expensive operations?**
 167 10. **Are correlation IDs included for distributed operations?**
 168
 169 ### For Error Handling
 170 1. **Are actual errors logged at ERROR level?**
 171 2. **Do error messages provide actionable information?**
 172 3. **Is sufficient context included with error logs?**
 173 4. **Are error conditions logged before and after handling?**
 174 5. **Are stack traces or error details included when appropriate?**
 175
 176 ### For Business Logic
 177 1. **Are important business events logged at INFO level?**
 178 2. **Are state changes and decision points logged?**
 179 3. **Is user activity logged with appropriate identifiers?**
 180 4. **Are critical operations logged before and after execution?**
 181 5. **Is there consistent logging across similar business operations?**
 182
 183 ### For Performance-Critical Code
 184 1. **Are log level checks used before expensive operations?**
 185 2. **Is conditional logging used for debug information?**
 186 3. **Are log messages constructed efficiently?**
 187 4. **Is sensitive data properly handled in logs?**
 188 5. **Does logging have minimal impact on performance?**
 189
 190 ## Source Code Logging Principles Applied
 191
 192 ### "Log What Matters"
 193 - Log critical operations and state changes
 194 - Log error conditions with sufficient context
 195 - Log important business events and decisions
 196 - Don't log trivial or obvious operations
 197
 198 ### "Provide Context"
 199 - Include relevant identifiers and correlation data
 200 - Provide sufficient state information for debugging
 201 - Use meaningful error messages with actionable information
 202 - Include context that helps understand the situation
 203
 204 ### "Use Appropriate Levels"
 205 - ERROR for actual errors that need immediate attention
 206 - WARN for concerning but non-fatal issues
 207 - INFO for important business events and state changes
 208 - DEBUG for detailed troubleshooting information
 209
 210 ### "Structure for Analysis"
 211 - Use consistent log message formats
 212 - Include structured data for automated parsing
 213 - Use consistent field naming conventions
 214 - Provide machine-readable data formats
 215
 216 ### "Consider Performance"
 217 - Construct log messages efficiently
 218 - Use conditional logging for expensive operations
 219 - Check log levels before expensive operations
 220 - Avoid logging sensitive or large data structures
 221
 222 ### "Enable Debugging"
 223 - Log entry/exit points for important functions
 224 - Log before and after critical operations
 225 - Include correlation data for distributed operations
 226 - Provide sufficient detail for effective troubleshooting