Documentation

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:

LevelUse
emergencySystem is unusable.
alertImmediate action is required.
criticalCritical failure.
errorFailed operation or service error.
warningSuspicious or degraded behavior.
noticeImportant normal operational events.
infoRoutine operational detail.
debugDevelopment-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, or info when 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:

CounterMeaning
totalall counted requests
readsread operations
writeswrite operations
getGET requests
postPOST requests
patchPATCH requests
putPUT requests
delDELETE requests
optOPTIONS 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.