# 0007. Logging Strategy for v1.0.0

Date: 2024-11-20

## Status
Accepted

## Context
We need structured logging for debugging, security auditing, and operational monitoring. The choice is between JSON-structured logs (machine-parseable), Python's standard logging with structured fields, or simple string logging.

## Decision
Use Python's standard logging module with structured string formatting for v1.0.0:

Format pattern:
```
%(asctime)s [%(levelname)s] %(name)s: %(message)s
```

Structured information in message strings:
```python
logger.info("Domain verification requested", extra={
    "domain": domain,
    "email": email,
    "request_id": request_id
})
```

Log levels:
- **Development**: `DEBUG` (default when `GONDULF_DEBUG=true`)
- **Production**: `INFO` (default)

Configuration:
```
GONDULF_LOG_LEVEL=INFO
GONDULF_DEBUG=false
```

Output: stdout/stderr (let deployment environment handle log collection)

## Consequences
### Positive
- Standard Python logging - no additional dependencies
- Simple to implement and test
- Human-readable for local development
- Structured extras can be extracted if needed later
- Easy to redirect to files or syslog via deployment config

### Negative
- Not as machine-parseable as pure JSON logs
- May need to migrate to structured JSON logging in future versions
- Extra fields may not be captured by all log handlers

## Future Consideration
If operational monitoring requires it, we can migrate to JSON-structured logging in a minor version update without breaking changes.