Logging and Metrics
Cleave records operational behavior around transactional requests. Operational logs and metrics have separate configuration sections and can use different destinations.
Logging destinations
Cleave can log to the console or to syslog:
[logging]
type = "console"
level = "notice"
For syslog:
[logging]
type = "syslog"
transport = "udp"
endpoint = "127.0.0.1:514"
Supported transports are:
udp;tcp;tls;unix.
Logging levels
Cleave logging uses syslog-style severity names:
| Level | Use |
|---|---|
emergency | System is unusable. |
alert | Immediate action is required. |
critical | Critical failure. |
error | Failed operation or service error. |
warning | Suspicious or degraded behavior. |
notice | Important normal operational events. |
info | Routine operational detail. |
debug | Development-level detail. |
Use debug only during development or controlled troubleshooting. Debug logs can include
critical and sensitive implementation details.
Use info carefully in production. Info-level logs can include user-specific or
request-specific sensitive information, depending on the request path and enabled logging.
Recommended starting points:
- development:
debug; - production:
notice, orinfowhen additional operational detail is required and the log destination is properly protected.
Metrics loop
Enable reporting under [metrics], independently of operational log severity:
[metrics]
enabled = true
type = "syslog"
transport = "udp"
endpoint = "logstash:5515"
interval = 10
send_sparse = false
request_latency = true
The receiver must be running and reachable. interval is seconds and must be
positive. send_sparse = false skips intervals with no requests; true emits
empty intervals too. request_latency enables response-time measurements.
The counters describe each reporting interval, rather than cumulative totals.
Operational logging can remain at notice while metrics are enabled separately.
See Deployment for receiver
setup and the Metrics example.
Emitted counters
The current metrics line includes:
| Counter | Meaning |
|---|---|
total | all counted requests |
reads | read operations |
writes | write operations |
get | GET requests |
post | POST requests |
patch | PATCH requests |
put | PUT requests |
del | DELETE requests |
opt | OPTIONS requests |
Example shape:
metrics total: 1200, reads: 1100, writes: 100, get: 1100, post: 40, patch: 35, put: 10, del: 15, opt: 0
These counters are intentionally operational rather than analytical. They help operators see whether a Cleave service is read-heavy, write-heavy, mixed, or idle.
Tuning from metrics
Use the method mix and read/write counters to tune:
- reader pool sizing;
- writer pool sizing;
- repository read replica use;
- page limits;
- request body and URI limits;
- logging verbosity;
- cache use for collection GET paths.
Metrics should be interpreted alongside repository-level signals such as connection pool pressure, query latency, lock waits, index usage, and replica lag.