Storage and history¶

plotsrv keeps live views in memory by default.

That is simple and fast, but it means live views disappear when the server stops.

Storage adds persistence so plotsrv can:

• keep historical snapshots for browsing
• restore the latest view after restart
• limit how much history is kept

For most workflows, latest restore is just part of enabling storage.

Enable storage¶

Storage is opt-in. Simply:

storage-settings:
  enabled: true

Or with more control:

storage-settings:
  enabled: true
  root_dir: .plotsrv/store
  default_keep_last: 5
  default_min_store_interval: 1h
  max_snapshot_size_mb: 20

storage-settings.enabled is the main switch.

When storage is enabled, plotsrv can keep historical snapshots, depending on the retention settings. It can also persist the latest live view and restore it when the server starts again.

What storage does¶

Storage has two effects:

Snapshots appear in the history controls.

The latest restored view appears as the current live view.

Snapshots¶

Snapshots keep previous versions of views.

They are used for history browsing in the UI.

storage-settings:
  enabled: true
  default_keep_last: 5
  default_min_store_interval: 1h
  max_snapshot_size_mb: 20

A common starting point is to keep a small number of recent snapshots:

storage-settings:
  enabled: true
  default_keep_last: 5

For noisy or frequently updated views, add a minimum storage interval:

storage-settings:
  enabled: true
  default_keep_last: 5
  default_min_store_interval: 1h

Latest restore¶

When storage is enabled, plotsrv can restore the latest live content after restart.

This is useful for outputs that update occasionally, such as:

• daily imports
• scheduled reports
• validation jobs
• long-running monitors
• generated result tables
• status objects from batch processes

Restored content is marked in the UI, so it is clear that the view came from storage and is waiting for the next live update.

Freshness indicators, when enabled, still use the original update time rather than the restore time.

Turning off latest restore¶

Latest restore can be turned off if a server should always start with an empty live UI.

storage-settings:
  enabled: true
  latest:
    restore_on_startup: false

It can also be limited using restore_scope.

storage-settings:
  enabled: true
  latest:
    restore_scope: discovered

Common values are:

discovered is a good default for project-specific server runs because it avoids restoring unrelated old views.

Stream-session history¶

When a JSONL stream is used with storage enabled, plotsrv stores bounded session metadata, derived summary windows, and noteworthy/continuity observations beneath the dedicated streams/ storage namespace. Once a producer run is superseded, its successfully stored session appears in the stream view's Run selector without requiring a server restart. Retained runs are restored there after later restarts as well. A stored run is marked as historical and is never presented as a live producer.

If the server restarts while a producer is still observing its source, the producer reconnects using a new transport session. Its logical view and client identity stay the same, and its pending batch is retried in the new session. The observer continues from its acknowledged source position; it does not replay the whole log. If an acknowledgement was lost just before the restart, that batch may appear in both the old stored session and the new one. Retries within the same server session remain deduplicated. StreamHandle.session_id reflects the current transport session after reconnection.

Raw source rows remain opt-in. They can be retained only with a finite raw block policy; the history view shows those explicitly retained segments, not a source-log replay.

storage-settings:
  enabled: true
  streams:
    keep_last_sessions: 4
    summary_retention: 32
    noteworthy_keep_last: 32
    # This is a hard ceiling for every retained session and optional raw block
    # for one logical stream view. It overrides the softer count policies.
    max_bytes_per_view_mb: 16
    raw_retention:
      max_blocks: 8
      max_bytes_mb: 4
      max_age_s: 24h

Use raw_retention: null (the default) to keep compact history only. A persistence gap remains visible on the restored historical session; storage is observational history, not an audit guarantee. If a hard byte ceiling can retain only the small persistence-gap marker, the session still appears as an incomplete stored session with its compact details unavailable rather than disappearing or being shown as complete.

To override one logical stream without changing snapshot settings for that view, put a nested stream mapping under storage-settings.views:

storage-settings:
  enabled: true
  views:
    "logs:worker stream":
      stream:
        keep_last_sessions: 2
        max_bytes_per_view_mb: 4

Storage retention¶

Storage retention controls how much historical material is kept.

For example:

storage-settings:
  enabled: true
  default_keep_last: 5
  default_min_store_interval: 1h
  max_snapshot_size_mb: 20

This means:

• keep up to 5 snapshots per view
• do not store snapshots more often than once per hour
• skip snapshots larger than 20 MB

Use conservative values at first. Storage is meant to be useful, not to become an unmanaged data store.

Per-view storage settings¶

Global storage settings apply to all views by default.

For projects with several views, per-view settings can be generated with:

plotsrv config populate storage .

This scans for:

• @ps.view(...) decorators
• simple publish_view(...) calls

and adds storage entries for discovered views.

For example:

import plotsrv as ps

@ps.view(label="daily import", section="pipelines")
def daily_import_status():
    return {"status": "ok"}

The discovered view identity is:

pipelines:daily import

Per-view storage settings are useful when different views need different retention behaviour.

For example:

• keep more snapshots for important result tables
• keep fewer snapshots for large plots
• set a minimum snapshot interval for frequently updated views
• reduce storage for noisy or low-value outputs

Populate storage config¶

To populate storage entries:

plotsrv config populate storage .

To scan a specific file:

plotsrv config populate storage demo_pipeline.py

To scan a source directory:

plotsrv config populate storage ./src

To merge generated entries into an existing config:

plotsrv config populate storage . --mode merge

To replace generated storage entries:

plotsrv config populate storage . --mode replace

To skip confirmation prompts:

plotsrv config populate storage . --yes

A common pattern is:

plotsrv config create
plotsrv config populate storage . --yes

Then edit generated entries where specific views need different retention behaviour.

Storage CLI commands¶

plotsrv includes CLI commands for inspecting and clearing stored data.

Show storage statistics:

plotsrv store stats

List stored views, snapshots, and stream history:

plotsrv store list

List one view:

plotsrv store list --view "pipelines:daily import"

Clear one view:

plotsrv store clear --view "pipelines:daily import"

Clear all stored material:

plotsrv store clear --all

Storage directory¶

By default, storage is written under:

.plotsrv/store

This is controlled by:

storage-settings:
  root_dir: .plotsrv/store

For local project use, .plotsrv/ is usually a good candidate for .gitignore.

.plotsrv/

Next steps¶

• CLI reference
• Freshness
• Configuration basics