Skip to main content

Logging Standards

This document establishes the logging standards and best practices for the CROW platform. Consistent, structured logging is critical for debugging, monitoring, security auditing, and compliance tracking.

Philosophy​

Our logging approach prioritizes:

  • Structured data: All logs use structured formats (JSON) for easy parsing and analysis
  • Meaningful context: Include relevant contextual information without over-logging
  • Security: Never log sensitive data (passwords, tokens, PII)
  • Performance: Logging should not significantly impact application performance

Log Formatting​

We follow industry best practices for log formatting and structure. The platform streams structured logs to Axiom for centralized analysis and long-term retention.

Reference Guide​

For comprehensive guidance on log formatting, we follow the standards outlined in:

BetterStack Logging Guide: Log Formatting

This guide covers:

  • Structured logging fundamentals
  • JSON log formatting
  • Log levels and their appropriate use
  • Contextual information best practices
  • Performance considerations

Implementation​

Log Levels​

Use appropriate log levels for different types of events:

  • ERROR: System errors and exceptions that require attention
  • WARN: Warning conditions that should be reviewed but don't prevent operation
  • INFO: General informational messages about system operation
  • DEBUG: Detailed information for debugging purposes (use sparingly in production)

Structured Format​

All logs must use structured JSON format with consistent field names:

{
  "timestamp": "2024-02-15T10:52:33.392Z",
  "level": "INFO",
  "service": "api-gateway",
  "message": "Request processed successfully",
  "requestId": "abc-123-def",
  "userId": "user-456",
  "duration": 125,
  "statusCode": 200
}

Context Requirements​

Include relevant context in all logs:

  • Request ID: Trace requests across services
  • User ID: (when applicable) Associate actions with users for audit trails
  • Service name: Identify the source service
  • Duration: For performance monitoring
  • Error details: Full error messages and stack traces for failures

Security​

Never log sensitive information:

  • Passwords or authentication credentials
  • API keys or tokens
  • Credit card numbers or payment information
  • Personal identification numbers (SSN, passport, etc.)
  • Full email addresses in non-audit logs (use hashed or truncated versions)

Monitoring and Analysis​

All structured logs stream to Axiom for:

  • Real-time debugging and tracing
  • Audit trail compliance
  • Performance analysis and bottleneck identification
  • Long-term retention and historical analysis