Watch files¶

plotsrv can expose files on disk in the same browser UI as Python objects.

This is useful when a process already writes useful files, such as:

• logs
• CSV files
• JSON, YAML, INI, TOML files
• markdown reports
• HTML reports
• generated images

Watch a log file¶

To simply "watch" a log file, you can use the plotsrv watch command:

plotsrv watch ./logs/job.log

Open:

http://127.0.0.1:8000

The file appears in the plotsrv UI and updates when the file changes.

For log-like files, plotsrv is usually most useful in tail mode, showing the newest content from the end of the file.

plotsrv watch ./logs/job.log --tail

Watch files while running plotsrv as a server¶

For scripts, jobs, and pipelines, watched files can be declared when starting the server. In this example, the plotsrv UI will include 2 on-disk files in the plotsrv UI dropdown menu:

plotsrv run . --host 127.0.0.1 --port 8000 \
  --watch logs/uvicorn.log --watch-label "job log" --watch-section "files" --watch-tail \
  --watch reports/daily_report.html --watch-label "daily" --watch-section "reports"

This starts the plotsrv UI and adds the watched file as a view.

Watch a CSV file¶

CSV files are rendered as tables.

plotsrv watch ./outputs/results.csv

The table renderer provides search, filters, pagination, and column controls.

CSV watching is useful when a process writes result tables to disk, but changing the Python code to call publish_view() is not convenient.

Watch a JSON file¶

JSON files are rendered with the JSON renderer.

plotsrv watch ./outputs/status.json

For example:

{
  "job": "daily-import",
  "status": "ok",
  "rows_processed": 123,
  "warnings": 2
}

This appears as an expandable JSON view in the browser.

Choose head or tail mode¶

Head mode reads from the start of the file.

plotsrv watch ./outputs/results.csv --head

Tail mode reads from the end of the file.

plotsrv watch ./logs/job.log --tail

Limit large files¶

Large watched files can be limited in megabytes with --max-mb.

plotsrv watch ./logs/job.log --max-mb 25

To read the full file:

plotsrv watch ./logs/job.log --max-mb off

--max-bytes is still available as a legacy/advanced option when byte-level precision is needed:

plotsrv watch ./logs/job.log --max-bytes 5000000

For large logs, keeping a read limit is usually better. It keeps the UI responsive and avoids reading too much from disk.

The equivalent config key is:

limits:
  watched_files:
    max_mb: 500

Watched CSV files also use table preparation limits:

limits:
  truncate_after:
    table_rows: 100000
    table_columns: 200

File types¶

plotsrv infers common file types from the extension.

Watch files or publish from Python?¶

Watching files is best when the useful output already exists on disk.

Publishing from Python is better when the useful object already exists in memory.

For example, this is usually better than writing a temporary CSV just for plotsrv:

ps.publish_view(
    df,
    label="results",
    section="demo",
    host="127.0.0.1",
    port=8000,
)

But if a process already writes results.csv, watching that file is a simple way to expose it.

Freshness and storage defaults for watched files¶

Watched files are source-aware.

Global freshness settings do not mark watched-file views stale by default. A watched file might be static for a long time and still be valid.

To apply freshness to a watched file, opt that specific view in:

freshness-settings:
  enabled: true
  views:
    "files:job log":
      enabled: true
      expected_every: 5m
      warn_after: 10m
      overdue_after: 30m

Storage is source-aware too. Historical snapshots for watched files are disabled by default unless storage-settings.watch_enabled or a per-view watch_enabled override is enabled.

storage-settings:
  enabled: true
  watch_enabled: false

Next step¶

Continue to Configuration basics.