Skip to content
Documentation
Operations
Telemetry

Telemetry

New: V5.4.0

What is measured

Cavaliba counts what happens inside it and keeps the numbers per time period (minute, hour, day, week, month, quarter, year). Each indicator has a key (auth.login, http.duration), sometimes split by a low-cardinality id (the view, the schema, the endpoint).

Key Shows
auth.login, auth.login.failure logins and login failures, id = authentication mode
users.active distinct users per day, week and month
view.request, ajax.request page hits, id = page
http.duration response time in ms, id = page
http.exception pages that ended in an error
api.request API calls, id = endpoint
task.duration background task duration, id = task
log.event log events, id = level
cache.get, cache.session cache hits and misses
data.write, data.write.action object writes, id = schema; and create / update / delete
data.objects, data.objects.total number of objects, id = schema
data.rows size of the main tables, id = table

No field value is ever recorded. User names are only counted, never stored: for users.active they are replaced by a one-way hash.

Telemetry page

Sidebar Telemetry. Requires p_telemetry_read.

  • Explore: pick a key, a function (sum, p95, last, breakdown, …), a period and a range (now-1d, now, 2026-11-01). You get a barchart, a table, and - when the key has ids - one row per id, heaviest first.
  • Dashboards: Security, Users, Operations, Performance, Data. Each refreshes on its own.
  • Last raw events: the most recent individual events, for a quick check that something is being recorded.

Examples:

  • Slowest pages today: key http.duration, function p95, period hour, range now-1d.
  • Busiest schemas this week: key data.write, period day, range now-7d.
  • Cache efficiency: key cache.get - compare hit_local / hit_shared with miss.

Reading the numbers

  • The period in progress is not counted yet: a value card shows the last finished minute, hour or day. Active users are the exception and update live.
  • Object quantities are sampled once an hour, so they are a snapshot, not a continuous level.
  • Percentiles (p90, p95, p99) are exact per minute and hour; from the day up they are an approximation.
  • Only the heaviest ids of a key are kept, the others are added up as _other.

Retention

Configuration page, home application:

  • TELEMETRY_ENABLED: yes / no (nothing is recorded when no)
  • TELEMETRY_RAW_KEEP_MINUTES: how long individual events are kept (default 60)
  • TELEMETRY_KEEP_DAYS_MINUTE / _HOUR / _DAY / _WEEK / _MONTH / _QUARTER / _YEAR: days kept per period, 0 = forever (default: 7 days for minutes, 365 for hours, forever above)
  • TELEMETRY_MAX_KEYS: maximum number of distinct keys

Aggregation and cleanup run on their own, every minute; quantities are sampled once an hour. Nothing to configure.

API

With an API key holding p_telemetry_read:

curl -H "X-Cavaliba-Key: $KEY" https://<server>/api/telemetry/
curl -H "X-Cavaliba-Key: $KEY" https://<server>/api/telemetry/auth.login/
curl -H "X-Cavaliba-Key: $KEY" "https://<server>/api/telemetry/auth.login/day/sum/?start=now-7d&end=now"

An application can also send its own events (p_telemetry_write):

curl -X POST -H "X-Cavaliba-Key: $KEY" -H "Content-Type: application/json" \
     -d '{"key": "myapp.job", "type": "timer", "id": "nightly", "value": 1250}' \
     https://<server>/api/telemetry/

On an installation upgraded from an earlier version, add - app: telemetry to SIDEBAR_CONTENT to get the sidebar entry, and grant p_telemetry_read to a role.

Logging