Prometheus Observability

Enterprise exposes a Prometheus-compatible metrics endpoint for production monitoring. The endpoint serves metrics in the standard Prometheus exposition format, ready for scraping by Prometheus, Grafana Agent, or any compatible collector.

Metrics endpoint

Example: Text

GET /api/metrics

The endpoint is accessible without authentication so that monitoring infrastructure can scrape it without storing credentials.

Example: Bash

curl -s http://localhost:6363/api/metrics

Example response

Example: Text

# HELP terminusdb_info Server information
# TYPE terminusdb_info gauge
terminusdb_info{version="11.2.0",git_hash="abc1234",edition="enterprise"} 1
# HELP terminusdb_uptime_seconds Server uptime in seconds
# TYPE terminusdb_uptime_seconds gauge
terminusdb_uptime_seconds 3842.7
# HELP terminusdb_global_stack_usage_bytes Global stack usage in bytes
# TYPE terminusdb_global_stack_usage_bytes gauge
terminusdb_global_stack_usage_bytes 524288
# HELP terminusdb_table_space_bytes Table space usage in bytes
# TYPE terminusdb_table_space_bytes gauge
terminusdb_table_space_bytes 1048576
# HELP terminusdb_active_requests Number of currently active HTTP requests
# TYPE terminusdb_active_requests gauge
terminusdb_active_requests 0
# HELP terminusdb_layer_cache_total Total layers ever loaded into cache
# TYPE terminusdb_layer_cache_total gauge
terminusdb_layer_cache_total 42
# HELP terminusdb_layer_cache_live Currently live (pinned or unpinned) layers
# TYPE terminusdb_layer_cache_live gauge
terminusdb_layer_cache_live 38
# HELP terminusdb_layer_cache_dead Evicted but not yet freed layers
# TYPE terminusdb_layer_cache_dead gauge
terminusdb_layer_cache_dead 4
# HELP terminusdb_layer_cache_memory_bytes Memory usage by layer cache
# TYPE terminusdb_layer_cache_memory_bytes gauge
terminusdb_layer_cache_memory_bytes{state="total"} 8388608
terminusdb_layer_cache_memory_bytes{state="live"} 7340032
terminusdb_layer_cache_memory_bytes{state="dead"} 1048576
# HELP terminusdb_lru_cache_limit_bytes LRU cache size limit
# TYPE terminusdb_lru_cache_limit_bytes gauge
terminusdb_lru_cache_limit_bytes 1073741824
# HELP terminusdb_lru_cache_used_bytes LRU cache currently used bytes
# TYPE terminusdb_lru_cache_used_bytes gauge
terminusdb_lru_cache_used_bytes 8388608
# HELP terminusdb_lru_cache_pinned_count Number of pinned entries in LRU cache
# TYPE terminusdb_lru_cache_pinned_count gauge
terminusdb_lru_cache_pinned_count 5
# HELP terminusdb_lru_cache_pinned_bytes Bytes used by pinned LRU entries
# TYPE terminusdb_lru_cache_pinned_bytes gauge
terminusdb_lru_cache_pinned_bytes 2097152

Available metrics

Server information

Metric	Type	Description
`terminusdb_info`	gauge	Always 1. Labels carry `version`, `git_hash`, and `edition`
`terminusdb_uptime_seconds`	gauge	Seconds since server start
`terminusdb_active_requests`	gauge	Number of HTTP requests currently being processed

Memory and stack

Metric	Type	Description
`terminusdb_global_stack_usage_bytes`	gauge	SWI-Prolog global stack usage
`terminusdb_table_space_bytes`	gauge	SWI-Prolog tabling space usage

Layer cache

The layer cache stores graph layers in memory for fast access. These metrics help you understand cache pressure and tune the LRU eviction policy.

Metric	Type	Description
`terminusdb_layer_cache_total`	gauge	Total layers ever loaded
`terminusdb_layer_cache_live`	gauge	Currently active layers (pinned + unpinned)
`terminusdb_layer_cache_dead`	gauge	Evicted layers not yet freed
`terminusdb_layer_cache_memory_bytes`	gauge	Memory by state: `total`, `live`, `dead`

LRU cache

The LRU (Least Recently Used) cache manages eviction of graph layers when memory pressure increases.

Metric	Type	Description
`terminusdb_lru_cache_limit_bytes`	gauge	Configured maximum cache size
`terminusdb_lru_cache_used_bytes`	gauge	Current cache usage
`terminusdb_lru_cache_pinned_count`	gauge	Number of pinned (non-evictable) entries
`terminusdb_lru_cache_pinned_bytes`	gauge	Memory used by pinned entries

Prometheus scrape configuration

Add TerminusDB to your Prometheus scrape_configs:

Example: YAML

scrape_configs:
  - job_name: 'terminusdb'
    scrape_interval: 15s
    static_configs:
      - targets: ['localhost:6363']
    metrics_path: '/api/metrics'

Grafana dashboard tips

Useful panels for a TerminusDB Grafana dashboard:

Uptime — terminusdb_uptime_seconds
Cache hit ratio — derive from terminusdb_layer_cache_live vs terminusdb_layer_cache_total
Memory pressure — terminusdb_lru_cache_used_bytes / terminusdb_lru_cache_limit_bytes
Active requests — terminusdb_active_requests for concurrency monitoring
Cache eviction headroom — terminusdb_lru_cache_limit_bytes - terminusdb_lru_cache_used_bytes