ADR-081: Centralized Logging Architecture
Status: Accepted Date: 2026-01-17 Decision Makers: Hal Casteel, AZ1.AI CODITECT Team Technical Area: Observability, Monitoring Impact Level: High Version: 1.0.0
Context
CODITECT's distributed architecture spans multiple components (MCP servers, agents, skills, hooks) running locally with eventual cloud synchronization. Current logging is inconsistent:
- Some components log to stdout/stderr
- Some use Python's logging module
- No centralized collection
- No cloud aggregation
- No multi-tenant isolation
- No cross-session traceability
This creates blind spots when debugging issues across:
- Individual user sessions
- Team collaboration
- Tenant-wide patterns
- System administration
Decision
Implement a tiered centralized logging architecture that flows from local → cloud with persona-based access controls.
Architecture Overview
┌─────────────────────────────────────────────────────────────────────────────┐
│ LOCAL (Machine) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ MCP Server 1 │ │ MCP Server 2 │ │ Agents │ │ Hooks │ │
│ │ semantic- │ │ call-graph │ │ │ │ │ │
│ │ search │ │ │ │ │ │ │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │ │
│ └─────────────────┬┴─────────────────┴─────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ ~/.coditect/logs/ │ ← Centralized local logs │
│ │ │ │
│ │ mcp-semantic.log │ │
│ │ mcp-call-graph.log │ │
│ │ mcp-impact.log │ │
│ │ agents.log │ │
│ │ hooks.log │ │
│ │ unified.log │ ← Aggregated view │
│ └───────────┬───────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ Log Sync Agent │ ← Background daemon │
│ │ (coditect-log-sync) │ │
│ └───────────┬───────────┘ │
│ │ │
└───────────────────────────┼──────────────────────────────────────────────────┘
│
│ HTTPS (batched, compressed)
│
┌───────────────────────────┼──────────────────────────────────────────────────┐
│ ▼ CLOUD (api.coditect.ai) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────┐ │
│ │ Log Ingestion API │ │
│ │ /api/v1/logs/ │ │
│ └───────────┬───────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ Multi-Tenant │ │
│ │ Log Storage │ │
│ │ (django-multitenant)│ │
│ └───────────┬───────────┘ │
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ User │ │ Team │ │ Tenant │ │
│ │ Dashboard │ │ Dashboard │ │ Dashboard │ │
│ │ │ │ │ │ │ │
│ │ Own logs │ │ Team logs │ │ All tenant │ │
│ │ only │ │ aggregate │ │ logs │ │
│ └────────────┘ └────────────┘ └────────────┘ │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ System Admin Dashboard │ │
│ │ │ │
│ │ Cross-tenant analytics │ │
│ │ Platform health metrics │ │
│ │ Usage patterns │ │
│ └─────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Log Levels and Categories
| Level | Usage | Retention |
|---|---|---|
ERROR | Failures requiring attention | 90 days |
WARNING | Potential issues | 30 days |
INFO | Normal operations | 14 days |
DEBUG | Detailed troubleshooting | 7 days (local only) |
| Category | Examples |
|---|---|
mcp.* | MCP server operations |
agent.* | Agent executions |
hook.* | Hook triggers |
sync.* | Cloud sync operations |
auth.* | Authentication events |
context.* | Context management |
Log Format
{
"timestamp": "2026-01-17T14:23:45.123Z",
"level": "INFO",
"category": "mcp.semantic-search",
"message": "Tool call: hybrid_search",
"context": {
"machine_id": "abc123",
"session_id": "session-456",
"user_id": "user-789",
"tenant_id": "tenant-012",
"task_id": "H.5.5.3"
},
"data": {
"tool": "hybrid_search",
"args": {"query": "authentication", "limit": 10},
"duration_ms": 45
}
}
Persona Access Matrix
| Persona | Scope | Actions |
|---|---|---|
| Individual | Own logs only | View, search, export |
| Team Lead | Team member logs | View, search, aggregate, alerts |
| Tenant Admin | All tenant logs | Full access, retention config |
| System Admin | Cross-tenant | Platform analytics, debugging |
Local Configuration
File: ~/.coditect/config/logging.json
{
"version": "1.0.0",
"local": {
"log_dir": "~/.coditect/logs",
"max_file_size_mb": 50,
"max_files": 10,
"min_level": "INFO",
"format": "json"
},
"cloud_sync": {
"enabled": true,
"batch_size": 100,
"batch_interval_seconds": 60,
"retry_max": 3,
"offline_queue_max_mb": 100
},
"categories": {
"mcp.*": {"level": "INFO", "cloud_sync": true},
"agent.*": {"level": "INFO", "cloud_sync": true},
"hook.*": {"level": "WARNING", "cloud_sync": true},
"debug.*": {"level": "DEBUG", "cloud_sync": false}
}
}
Implementation Phases
| Phase | Scope | Timeline |
|---|---|---|
| Phase 1 | Local centralized logging | Complete |
| Phase 2 | Unified log format + rotation | H.6 |
| Phase 3 | Cloud sync agent | H.7 |
| Phase 4 | Multi-tenant dashboards | H.8 |
Consequences
Positive
- Debugging: Single location for all local logs
- Traceability: Task ID links logs to work items
- Team Visibility: Aggregated view for collaboration
- Compliance: Audit trail with retention policies
- Proactive Monitoring: Cloud-side alerting
Negative
- Storage: Local logs consume disk space (mitigated by rotation)
- Complexity: Additional sync daemon
- Privacy: Logs may contain sensitive data (mitigated by filtering)
Neutral
- Requires background daemon for cloud sync
- JSON format increases log size vs text (but enables querying)
Alternatives Considered
1. Cloud-Only Logging
Rejected: No offline capability, latency for local debugging
2. Centralized Cloud Service (DataDog, etc.)
Rejected: Cost, vendor lock-in, less control over multi-tenant isolation
3. Local-Only Logging
Rejected: No team/tenant aggregation, no cross-machine visibility
Security Considerations
- PII Filtering: Strip sensitive data before cloud sync
- Encryption: TLS for transport, encrypted at rest
- Access Control: Tenant isolation via django-multitenant
- Retention: Configurable per tenant for compliance
Related
- ADR-053: Cloud Context Sync Architecture
- ADR-058: Machine-Specific Session Logs
- Task: H.5.5.3 (MCP server logging)
Author: AZ1.AI CODITECT Team Approved By: Hal Casteel Implementation Status: Phase 1 Complete