---
name: database-observability
description: "Instrument database queries, connection pools, and detect N+1 queries"
triggers:
  - "instrument database"
  - "trace queries"
  - "database metrics"
  - "connection pool monitoring"
  - "slow query detection"
priority: 2
---

# Database Observability

Database is often the bottleneck. Track queries, pools, and patterns.

## Query Span Attributes

| Attribute | Example | Required |
|-----------|---------|----------|
| `db.system` | postgresql, mysql | Yes |
| `db.operation` | SELECT, INSERT | Yes |
| `db.name` | orders_db | Yes |
| `db.sql.table` | users | Recommended |
| `db.statement` | SELECT * FROM users WHERE id = ? | **Parameterized only!** |

## Connection Pool Metrics (USE)

| Metric | Type | Description |
|--------|------|-------------|
| `db.connections.active` | Gauge | In use |
| `db.connections.idle` | Gauge | Available |
| `db.connections.max` | Gauge | Pool limit |
| `db.connections.wait_count` | Counter | Had to wait |
| `db.connections.wait_duration` | Histogram | Wait time |

## Issues to Detect

| Issue | Detection | Fix |
|-------|-----------|-----|
| **N+1 queries** | >10 identical queries per request | Use eager loading |
| **Slow queries** | Duration > p95 threshold | Add indexes, optimize |
| **Pool exhaustion** | wait_count increasing | Increase pool, fix leaks |

## Query Wrapper Pattern

```
Before: Start span (db.system, db.operation, db.sql.table), start timer
After:  Record duration, set db.rows_affected, record errors, end span
```

## Pool Monitor Pattern

```
Every 10s: Record active, idle, wait_count, wait_duration from pool stats
```

## Anti-Patterns

- **Full SQL with values** → PII risk, use parameterized only
- **No pool metrics** → Can't detect saturation
- **Missing slow query alerts** → Problems go unnoticed

## References

- `references/methodology/use-methodology.md`
- `references/platforms/{platform}/database.md`