logging.yaml

# Logging Code Review Guidelines
# Comprehensive rules for log levels, structured logging, sensitive data, performance, and observability

description: "Code review guidelines for logging covering log levels, structured logging, security, performance, and observability"
globs:
  - "**/*.ts"
  - "**/*.js"
  - "**/*.py"
  - "**/*.java"
  - "**/*.go"
  - "**/*.rb"
  - "**/*.cs"
  - "**/*.rs"
  - "**/*log*"
  - "**/*logger*"

rules:
  # ============================================================================
  # LOG LEVELS RULES
  # ============================================================================

  - name: use-error-level-appropriately
    description: >
      Use ERROR for failures that need immediate attention: unhandled exceptions,
      failed critical operations, data corruption. Errors should be actionable
      and alert-worthy. Don't use ERROR for expected conditions.
    severity: high

  - name: use-warn-level-appropriately
    description: >
      Use WARN for potential issues that don't require immediate action: deprecated
      feature usage, approaching limits, recoverable errors. Warns indicate
      issues to investigate, not emergencies.
    severity: medium

  - name: use-info-level-appropriately
    description: >
      Use INFO for significant events in normal operation: request handling,
      configuration loaded, service started. INFO logs should tell the story
      of system operation without excessive noise.
    severity: medium

  - name: use-debug-level-appropriately
    description: >
      Use DEBUG for detailed diagnostic information: variable values, execution
      paths, timing. DEBUG should be disabled in production by default. Ensure
      DEBUG logs don't impact performance when disabled.
    severity: low

  - name: avoid-excessive-logging
    description: >
      Don't log every function entry/exit or routine operations. Excessive
      logging creates noise, consumes storage, and impacts performance. Log
      meaningful events at appropriate levels.
    severity: medium

  # ============================================================================
  # STRUCTURED LOGGING RULES
  # ============================================================================

  - name: use-json-format
    description: >
      Use JSON format for logs to enable parsing and analysis. Structured logs
      support querying, alerting, and dashboards. Configure logging framework
      for JSON output. Include consistent field names.
    severity: medium

  - name: use-consistent-fields
    description: >
      Use consistent field names across all logs: timestamp, level, message,
      service, request_id, user_id, etc. Consistency enables cross-service
      querying. Define and document standard fields.
    severity: medium

  - name: enable-searchability
    description: >
      Structure logs for searchability. Include relevant identifiers, statuses,
      and categories. Avoid embedding IDs in message strings; use separate
      fields. Think about how logs will be queried.
    severity: medium

  - name: include-context-fields
    description: >
      Include contextual fields: request_id, user_id, session_id, operation_name,
      service_name. Context enables filtering and correlation. Propagate context
      through async operations.
    severity: high

  - name: standardize-timestamps
    description: >
      Use ISO 8601 format with timezone (preferably UTC) for timestamps. Consistent
      timestamps enable time-based queries and correlation across services.
      Configure framework for standard format.
    severity: medium

  # ============================================================================
  # SENSITIVE DATA RULES
  # ============================================================================

  - name: redact-pii
    description: >
      Never log Personally Identifiable Information (PII) in plain text: names,
      emails, addresses, phone numbers, SSN. Use redaction or hashing for audit
      trails. Compliance (GDPR, CCPA) requires PII protection.
    severity: critical

  - name: mask-secrets
    description: >
      Never log passwords, API keys, tokens, or credentials. Mask or omit
      entirely. Secrets in logs are security vulnerabilities. Audit logs
      regularly for secret exposure.
    severity: critical

  - name: comply-with-gdpr
    description: >
      Ensure logging practices comply with GDPR: data minimization, purpose
      limitation, retention limits. Document what is logged and why. Support
      data subject access requests. Consider log data in privacy impact assessments.
    severity: high

  - name: implement-log-sanitization
    description: >
      Implement automatic log sanitization for sensitive patterns: credit cards,
      SSNs, passwords. Use sanitization libraries or custom filters. Test
      sanitization effectiveness regularly.
    severity: high

  # ============================================================================
  # PERFORMANCE RULES
  # ============================================================================

  - name: use-async-logging
    description: >
      Use asynchronous logging to prevent blocking application threads. Sync
      logging can cause latency spikes under load. Configure async appenders
      with appropriate buffer sizes.
    severity: medium

  - name: implement-log-sampling
    description: >
      Implement sampling for high-volume logs in production. Log every Nth
      occurrence or random percentage. Sampling preserves signal while reducing
      volume. Ensure errors are never sampled out.
    severity: medium

  - name: configure-log-rotation
    description: >
      Configure log rotation by size or time to prevent disk exhaustion. Archive
      or delete old logs per retention policy. Monitor disk usage. Rotation
      prevents catastrophic disk full scenarios.
    severity: high

  - name: avoid-expensive-operations
    description: >
      Don't perform expensive operations (serialization, external calls) in
      log statements. Use lazy evaluation for expensive log arguments. Check
      log level before expensive operations.
    severity: medium

  # ============================================================================
  # OBSERVABILITY RULES
  # ============================================================================

  - name: include-correlation-ids
    description: >
      Include correlation/trace IDs in all logs. Correlation IDs enable tracing
      requests across services and time. Generate at entry point, propagate
      through all operations. Essential for distributed debugging.
    severity: high

  - name: integrate-distributed-tracing
    description: >
      Integrate logs with distributed tracing (OpenTelemetry, Jaeger, Zipkin).
      Include trace/span IDs in logs. Enable jumping from logs to traces.
      Tracing + logging provides complete observability.
    severity: medium

  - name: emit-metrics-from-logs
    description: >
      Extract metrics from log patterns: error rates, latencies, throughput.
      Use log aggregation tools for metrics extraction. Consider dedicated
      metrics for critical measurements.
    severity: medium

  - name: enable-log-aggregation
    description: >
      Ship logs to central aggregation (ELK, Splunk, CloudWatch). Centralized
      logs enable cross-service analysis and alerting. Configure appropriate
      retention and access controls.
    severity: high

  - name: create-meaningful-alerts
    description: >
      Create alerts based on log patterns: error spikes, specific error codes,
      unusual patterns. Alerts should be actionable and not too noisy. Use
      aggregation windows to reduce alert fatigue.
    severity: medium