explorer-monorepo/docs/specs/observability/logging.md

Logging Architecture Specification

Overview

Centralized logging architecture for the explorer platform.

Log Aggregation Strategy

Solution: ELK Stack (Elasticsearch, Logstash, Kibana) or Loki + Grafana

Flow:

1. Services emit logs
2. Log collectors aggregate logs
3. Logs stored in central store
4. Dashboards and queries via UI

Log Levels and Categorization

Log Levels

• DEBUG: Detailed debugging information
• INFO: General informational messages
• WARN: Warning messages
• ERROR: Error messages
• FATAL: Critical errors

Categories

Application Logs: Business logic, API requests Access Logs: HTTP requests, authentication System Logs: Infrastructure, system events Audit Logs: Security events, compliance

Structured Logging Format

Log Format

{
  "timestamp": "2024-01-01T00:00:00Z",
  "level": "INFO",
  "service": "explorer-api",
  "message": "Request processed",
  "request_id": "uuid",
  "user_id": "uuid",
  "chain_id": 138,
  "method": "GET",
  "path": "/api/v1/blocks",
  "status_code": 200,
  "duration_ms": 45,
  "metadata": {}
}

Log Retention Policies

Development: 7 days Staging: 30 days Production: 90 days (hot), 1 year (cold archive)

PII Sanitization in Logs

Strategy: Remove PII before logging Fields to Sanitize:

• Email addresses
• Personal names
• Addresses
• API keys (partial masking)

Implementation: Log sanitization middleware

References

• Metrics & Monitoring: See metrics-monitoring.md