buffer-cache-review

See what is occupying shared buffers and whether it is the right thing.

promptread-only tools

Synopsis

buffer-cache-review([connection])

Arguments

connection optional

connection to review; defaults to the configured default

What it asks the model to do

The text below is exactly what prompts/get returns for the example arguments. A client inserts it as the opening message of a conversation, and the model then calls the tools it names.

Review shared buffer usage on connection shop_prod.

0. Call checkPrivileges. Both buffer-cache tools need the monitoring role, and they are the whole of this review.
1. Call bufferCacheSummary first. It is cheap; bufferCacheContents aggregates every buffer and is not.
   Read the usage_counts histogram and usagecount_avg, not only the used and dirty totals. A cache that is full but sitting at low usage counts is being churned -- buffers are evicted before anything reads them twice -- and a cache that is full at high usage counts is simply working. Those two want opposite actions and buffers_used alone cannot tell them apart, which is the question step 5 has to answer.
2. Call hostCapacity and compare shared_buffers against the host's RAM, and effective_cache_size against what the OS can plausibly cache.
3. Call tableIOStats. A low hit ratio on a small, frequently read table is the actionable case; a low ratio on a large table scanned once a day is not a problem.
   Then call ioStats for the same period. evictions counts buffers thrown out to make room and reuses counts a ring buffer recycling its own, which is what a large sequential scan does deliberately so it cannot flush the cache. Distinguishing them is the difference between a cache under real pressure and one doing its job: rising evictions is the finding, rising reuses is a big scan behaving correctly.
4. Only if the summary suggests something is wrong, call bufferCacheContents to see which relations hold the buffers.
5. Report whether the cache is undersized, mis-sized relative to the host, or being churned by one workload, and say which reading supports the conclusion.

Example mocked arguments

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "prompts/get",
  "params": {
    "name": "buffer-cache-review",
    "arguments": {
      "connection": "shop_prod"
    }
  }
}