query_statsCounters and health

Three calls answer three different questions:

Question	Call	Scope
Is the server healthy?	pgrdf.stats()	Cumulative, every session and database on the server
Was my last query complete?	pgrdf.last_call_stats()	This session, the most recent sparql / construct / describe call
Which build is running?	pgrdf.version(), pgrdf.build_id(), extversion	This server and database

pgrdf.stats(): instance counters

SELECT jsonb_pretty(pgrdf.stats());

{
    "shmem_hits": 328,
    "shmem_ready": true,
    "shmem_slots": 16384,
    "shmem_misses": 593,
    "shmem_inserts": 540,
    "plan_cache_hits": 77,
    "shmem_evictions": 0,
    "plan_cache_misses": 106,
    "plan_cache_inserts": 106,
    "plan_cache_local_size": 0,
    "filter_clauses_dropped": 0,
    "path_depth_truncations": 0
}

Key	Meaning
shmem_ready	true when pgrdf is in shared_preload_libraries and the shared term cache is available. false means the preload is missing or the server wasn't restarted.
shmem_slots	Capacity of the shared term cache.
shmem_hits, shmem_misses	Term lookups made while loading data that the shared term cache could, or could not, answer.
shmem_inserts, shmem_evictions	Terms added to, and evicted from, the shared term cache.
plan_cache_hits, plan_cache_misses	SPARQL queries that reused a cached translation, or needed a new one, across all connections. See Plan cache.
plan_cache_inserts	Translations added to plan caches, across all connections.
plan_cache_local_size	Translations cached by the connection you are asking from.
filter_clauses_dropped, path_depth_truncations	Running totals of the two completeness signals that last_call_stats() reports per query.

How to read them:

• Apart from plan_cache_local_size, the counters are shared by every session and every database on the server, and they only grow. For rates, take the difference between two readings. shmem_reset() and plan_cache_clear() don't reset them.
• The values are JSON numbers, so they cast straight to numeric.

Hit ratios for a dashboard:

SELECT round((s->>'shmem_hits')::numeric
             / nullif((s->>'shmem_hits')::numeric + (s->>'shmem_misses')::numeric, 0), 3) AS term_cache_hit_ratio,
       round((s->>'plan_cache_hits')::numeric
             / nullif((s->>'plan_cache_hits')::numeric + (s->>'plan_cache_misses')::numeric, 0), 3) AS plan_cache_hit_ratio
  FROM pgrdf.stats() AS s;

A low term-cache ratio is normal while loading data with many new terms. Each new term is a miss the first time it is seen.

One row per counter, the shape most SQL-based metrics exporters expect:

SELECT key AS metric, value::numeric AS value
  FROM jsonb_each(pgrdf.stats())
 WHERE jsonb_typeof(value) = 'number'
 ORDER BY key;

         metric         | value
------------------------+-------
 filter_clauses_dropped |     0
 path_depth_truncations |     0
 plan_cache_hits        |   518
 plan_cache_inserts     |   301
 …

last_call_stats(): was my query complete?

Right after a sparql, construct or describe call, in the same session:

SELECT pgrdf.last_call_stats();
-- {"filter_clauses_dropped": 0, "path_depth_truncations": 0}

Both zero means the last call's answer was complete. The figures belong to your session, so other sessions can't change them. Don't use stats() for this question, because every other session moves those totals. The warning, the setting that turns truncation into an error, and a worked example are in Was the answer complete?.

Which build is running?

stats() carries no version information. Three values identify the build:

SELECT pgrdf.version(), pgrdf.build_id(),
       (SELECT extversion FROM pg_extension WHERE extname = 'pgrdf');

 version | build_id | extversion
---------+----------+------------
 0.6.34  | v0.6.34  | 0.6.34

On an official release all three agree: build_id() shows the release tag. extversion behind version() means the database still needs ALTER EXTENSION pgrdf UPDATE. More in What is this server running?. graph_manifest() records the same three values alongside a graph's digests, so an exported graph says which build produced it.

See also

• Cache control.
• Plan cache.
• Errors and diagnostics.