# 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

```json
{
  "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`