Monitoring

ArcadeDB provides built-in metrics collection and integration with Prometheus and Grafana for production monitoring.

Enabling Metrics

Metrics are enabled by default. Verify with:

SELECT FROM ( SELECT expand(settings) FROM schema:database ) WHERE key = 'arcadedb.serverMetrics'

Or set in arcadedb-server.properties:

arcadedb.serverMetrics=true
arcadedb.serverMetrics.logging=true

Prometheus Integration

The Prometheus metrics plugin auto-registers when the metrics module is on the classpath (included in the standard distributions) and metrics are enabled (arcadedb.serverMetrics=true, the default). It exposes a scrape endpoint at http://localhost:2480/prometheus.

Authentication on the scrape endpoint is on by default; set arcadedb.serverMetrics.prometheus.requireAuthentication=false to allow unauthenticated scraping.

This setting accepts only true or false. Anything else (yes, 1, on, or a misspelling) is refused with a warning at startup and the endpoint stays authenticated, so a typo cannot expose it by accident. See Settings.

Configure Prometheus to scrape ArcadeDB:

# prometheus.yml
scrape_configs:
  - job_name: 'arcadedb'
    scrape_interval: 15s
    metrics_path: /prometheus
    static_configs:
      - targets: ['localhost:2480']
    basic_auth:
      username: root
      password: arcadedb

Available Metrics

ArcadeDB exposes metrics for:

Database operations — Query count, command count, read/write throughput
Cache — Page cache hits, misses, evictions
Disk — Read/write operations, compaction activity
Transactions — Active transactions, commits, rollbacks
Network — HTTP request count, response times
JVM — Heap usage, GC pauses, thread count
Backup — Point-in-time window activity (see below)
Time series reads — How much data each query actually had to read (see below)

Disk space

diskFreeSpace, diskTotalSpace and diskFreeSpacePerc (on GET /api/v1/server and on the Databases Disk card in Studio) describe the filesystem holding the configured database directory (arcadedb.server.databaseDirectory), which on a container is normally a mounted volume rather than the filesystem the server process was started in. The diskDirectory field names the measured directory, so it is always clear which filesystem the figures refer to.

Free space is what the server process can actually write, so any quota or reserved space is already subtracted.

Backup point-in-time windows

A full backup, an HA database verify and an HA snapshot ship read a point-in-time image of the database. By default that image is served from a copy-on-write shadow, so writers keep running at full speed while it is read. When the shadow cannot be used the operation still completes, but by freezing the data files instead - which throttles every writer until it finishes.

That fallback is invisible from the outside: the backup succeeds either way. These counters are what make it alertable:

Metric Meaning

Metric	Meaning
`arcadedb_engine_snapshot_windows_overflowed_total`	The shadow reached `arcadedb.pageSnapshotMaxSize`. Raise it, or give the spill volume more room.
`arcadedb_engine_snapshot_windows_failed_total`	A page pre-image could not be read or written. Look at the disk.
`arcadedb_engine_snapshot_barrier_failed_total`	The window could not be opened at all. Split by cause below.
`arcadedb_engine_snapshot_barrier_failed_suspend_total`	Transient and expected under sustained load.
`arcadedb_engine_snapshot_barrier_failed_flush_total`	A pending write never landed. Points at the disk.

arcadedb_engine_snapshot_windows_overflowed_total

The shadow reached arcadedb.pageSnapshotMaxSize. Raise it, or give the spill volume more room.

arcadedb_engine_snapshot_windows_failed_total

A page pre-image could not be read or written. Look at the disk.

arcadedb_engine_snapshot_barrier_failed_total

The window could not be opened at all. Split by cause below.

arcadedb_engine_snapshot_barrier_failed_suspend_total

Transient and expected under sustained load.

arcadedb_engine_snapshot_barrier_failed_flush_total

A pending write never landed. Points at the disk.

Any of these rising means backups have quietly gone back to throttling writers. See arcadedb.pageSnapshotMaxSize, arcadedb.pageSnapshotMaxRAM and arcadedb.pageSnapshotSpillPath in Settings.

Time series reads

A time series query does not read everything in its range. Older data is stored in compacted blocks, each carrying a summary of what it holds, so a query can skip a block entirely or answer from its summary without decompressing it. These counters say how often that is working for your data, and are tagged by db, type and surface (the endpoint that made the read).

Metric Meaning

Metric	Meaning
`arcadedb_timeseries_read_blocks_total`	Compacted blocks, split by `outcome`: `skipped` (not read at all), `fast-path` (answered from the block summary) and `slow-path` (decompressed in full).
`arcadedb_timeseries_read_pages_total`	Pages of recent, not-yet-compacted data, split by `outcome`: `scanned` or `skipped`.
`arcadedb_timeseries_read_rows_total`	Rows actually materialised, i.e. the ones that survived every filter.
`arcadedb_timeseries_read_overflow_buckets_total`	Aggregation buckets that fell outside the pre-sized window. Results are correct either way, but a rising value means the range estimate is coming up short.
`arcadedb_timeseries_read_phase_seconds`	Time spent per `phase`: `io`, `decompress-timestamps`, `decompress-values`, `accumulate`.

arcadedb_timeseries_read_blocks_total

Compacted blocks, split by outcome: skipped (not read at all), fast-path (answered from the block summary) and slow-path (decompressed in full).

arcadedb_timeseries_read_pages_total

Pages of recent, not-yet-compacted data, split by outcome: scanned or skipped.

arcadedb_timeseries_read_rows_total

Rows actually materialised, i.e. the ones that survived every filter.

arcadedb_timeseries_read_overflow_buckets_total

Aggregation buckets that fell outside the pre-sized window. Results are correct either way, but a rising value means the range estimate is coming up short.

arcadedb_timeseries_read_phase_seconds

Time spent per phase: io, decompress-timestamps, decompress-values, accumulate.

The ratio worth watching is slow-path against skipped and fast-path. A high slow-path share means queries are decompressing blocks they could have skipped - usually because the query filters on something the block summaries cannot narrow, or because the blocks predate the summary they would need.

These counters are collected only while metrics are enabled; with metrics off the read path is unchanged and nothing is measured.

Periodic Metric Dumps

For environments without Prometheus, enable periodic metric logging:

arcadedb.dumpMetricsEvery=60

This dumps metrics to the server log every 60 seconds.

Grafana Dashboard Setup

Install Grafana and add a Prometheus datasource pointing to your Prometheus instance
Import or create dashboards using ArcadeDB metrics
For time series data visualization, use ArcadeDB’s native Grafana integration endpoints with the Infinity datasource plugin

Health Checks

Use the server info endpoint for health monitoring:

curl http://localhost:2480/api/v1/server

For time series health:

curl http://localhost:2480/api/v1/ts/mydb/grafana/health

Server health warnings

Since v26.10.1 the server runs a health monitor that samples, every ten seconds, three things a running server can degrade on:

free disk space on the filesystem holding the databases — the same filesystem the diskFreeSpace figures above describe, and the warning that precedes a database that can no longer write;
available heap;
JVM pause times.

When one of them degrades, a WARNING event is written to the server event log, visible in Studio and through GET /api/v1/server/events. Each kind of warning is rate limited so a server that stays degraded reports it periodically rather than on every sample: once a day for low disk, once every 30 minutes for heap and JVM pauses.

Set arcadedb.server.healthCheck.enabled=false to turn the monitor off.

The monitor is enabled by default. On an in-place upgrade a server already close to those thresholds starts producing event-log warnings it did not produce before.