CloudWatch logs
Log groups
| Environment | Log group | Description |
|---|---|---|
| Staging | /ecs/staging/address-api | All staging logs |
| Production | /ecs/prod/address-api | All production logs |
Log streams
Each ECS task creates two log streams:| Stream prefix | Description |
|---|---|
ecs-init/ | Database migration logs |
ecs/ | Application logs |
Viewing logs in AWS Console
- Go to CloudWatch → Log groups
- Select
/ecs/{env}/address-api - Click on a log stream
- Use the search bar to filter logs
Useful filters
Filter by log level:Viewing logs with AWS CLI
Tail logs in real-time
Search logs
Get logs for specific time range
Log format
The Address API uses structured JSON logging with zerolog:Log levels
| Level | Description | When to use |
|---|---|---|
debug | Detailed information | Development only |
info | General information | Normal operations |
warn | Warning messages | Potential issues |
error | Error messages | Failures that need attention |
fatal | Fatal errors | Server crashes |
Common log patterns
Successful geocoding request
Failed geocoding request
Database connection error
Migration logs
CloudWatch Insights queries
Top error messages
Request latency percentiles
Requests by endpoint
Error rate over time
Better Stack monitoring
Better Stack provides external monitoring and alerting.Metrics tracked
| Metric | Description | Alert threshold |
|---|---|---|
| API calls | Total requests per minute | - |
| Status codes | Distribution of HTTP status codes | 5xx > 5% |
| Response time | Average response time | > 1000ms |
| Uptime | Service availability | < 99.9% |
Accessing Better Stack
- Go to Better Stack dashboard
- Select the Address API project
- View metrics and alerts
Alert channels
Alerts are sent to:- Slack: #engineering-alerts channel
- Email: engineering@commenda.io
- PagerDuty: On-call engineer (production only)
ECS Exec for live debugging
ECS Exec allows you to run commands inside running containers.Enable ECS Exec
ECS Exec is already enabled for the Address API service.Connect to a running task
- List running tasks:
- Connect to a task:
- Run commands:
Performance monitoring
RDS Performance Insights
- Go to RDS → Databases
- Select
{env}-address-api-postgres - Click Performance Insights tab
- Top SQL queries
- Database load
- Wait events
- Connection count
ECS Service metrics
- Go to ECS → Clusters →
{env}-ecs-cluster - Select address-api service
- Click Metrics tab
- CPU utilization
- Memory utilization
- Network in/out
- Task count
Debugging checklist
When investigating an issue:- Check CloudWatch logs for errors
- Review CloudWatch alarms
- Check ECS service health
- Verify RDS is running
- Check Better Stack metrics
- Review recent deployments
- Test endpoints manually
- Check security group rules
- Verify secrets are correct
- Review Performance Insights