name: logging
description: Logging standards and sensitive data handling. Use when writing logging
code or reviewing logs.

Logging Rules

1. Log Level Usage

Level Definitions

Level Selection Criteria

ERROR: Service disruption or data loss possible
WARN: Normal operation but monitoring needed
INFO: Business flow tracking
DEBUG: Root cause analysis when issues occur
TRACE: Performance analysis or deep debugging

2. Log Message Format

Basic Structure

[timestamp] [level] [traceId] [class:method] - message {context}

Example

2024-01-15T10:30:45.123Z INFO [abc123] [UserService:login] - User login successful {"userId": "user-001", "ip": "192.168.1.1"}
2024-01-15T10:31:00.456Z ERROR [abc123] [PaymentService:process] - Payment failed {"orderId": "order-123", "errorCode": "INSUFFICIENT_BALANCE"}

Required Fields

3. Sensitive Data Handling

Never Include in Logs

• Passwords
• API keys, secret keys
• Access tokens, refresh tokens
• Credit card numbers, CVV
• National ID, passport numbers
• Bank account numbers
• Biometric data
• Precise location data

Masking Rules

Masking Implementation Example

// Email masking
function maskEmail(email: string): string {
  const [localPart, domain] = email.split('@');
  const masked = localPart.slice(0, 2) + '***';
  return `${masked}@${domain}`;
}

// Phone masking
function maskPhone(phone: string): string {
  return phone.replace(/(\d{3})-(\d{4})-(\d{4})/, '$1-****-$3');
}

// Credit card masking
function maskCardNumber(cardNumber: string): string {
  const lastFour = cardNumber.slice(-4);
  return `****-****-****-${lastFour}`;
}

4. Structured Logging

JSON Log Format

{
  "timestamp": "2024-01-15T10:30:45.123Z",
  "level": "INFO",
  "traceId": "abc123",
  "service": "user-service",
  "class": "UserService",
  "method": "login",
  "message": "User login successful",
  "context": {
    "userId": "user-001",
    "loginMethod": "password",
    "durationMs": 150
  }
}

Context Information Inclusion

5. Logging Anti-Patterns

Patterns to Avoid

// Bad: Exposing sensitive info
logger.info(`User login: ${email}, password: ${password}`);

// Good: Exclude sensitive info
logger.info(`User login successful`, { userId: user.id });

// Bad: Error log without stack trace
logger.error(`Payment failed: ${error.message}`);

// Good: Include stack trace
logger.error(`Payment failed`, { error: error.stack, orderId });

// Bad: Excessive DEBUG logs
logger.debug(`Processing item 1`);
logger.debug(`Processing item 2`);
// ... thousands of logs

// Good: Log in meaningful batches
logger.debug(`Processing batch`, { itemCount: items.length });

// Bad: Wrong log level usage
logger.error(`User not found: ${userId}`);  // Business exception, not ERROR

// Good: Appropriate level
logger.info(`User not found`, { userId });  // Or WARN

6. Performance Considerations

• Disable DEBUG/TRACE in production by default
• Log in batches for large data processing
• Always mask sensitive info regardless of log level
• Use structured logs (JSON) for efficient searching

Log Volume Guidelines