Functional Specification
========================

Overview
--------

``gop`` is a console tool for database monitoring. It periodically runs
configured queries against one or more sources, stores results as NDJSON,
and can print live summaries or query stored logs.

Goals
-----

- Collect metrics from JDBC sources (single or multi-source).
- Persist results to local log files for later inspection.
- Provide a local HTTP API for log queries (no direct DB access).
- Offer a CLI for listing and watching logs.

Non-goals
---------

- No distributed storage or clustering.
- No remote API access (API binds to localhost).
- No built-in authentication/authorization.

Operating modes
---------------

Server
^^^^^^

- Collects metrics and writes log files.
- Starts local HTTP API (if enabled).
- No continuous console output (startup info only).

Run
^^^

- Console-only, sar-style output.
- Does not write log files.
- Uses a fixed interval (``timeInterval`` or ``-interval``).

Watch
^^^^^

- Reads stored logs and prints formatted output.
- Supports filtering by time range, measure name, or tag.
- ``-follow`` streams new log lines (tail -f style).

List (ls)
^^^^^^^^^

- Lists configs/sources/years/months/log files under the log root.

Configuration model
-------------------

- ``setting``
  - ``jdbcSource``: JDBC connection information.
  - ``source``: source id (single-source mode).
  - ``timeInterval``: polling interval (ms).
  - ``consolePrint``: print to console (run mode).
  - ``pageSize``: header repeat interval.
  - ``retention``: log retention policy.
  - ``printCSV``: CSV output flag.
  - ``fileLog``: log path and rotation settings.
  - ``api``: local API settings.
- ``measure[]``
  - Query definitions, tags, and alert rules.
- ``sources[]`` (multi-source mode)
  - Per-source ``jdbcSource`` + ``measure``.

Log storage
-----------

Path pattern:

::

   <logPath>/<configName>/YYYY/MM/<source>/log_YYYYMMDD.json

Where:

- ``configName`` = config filename without extension.
- ``source`` = ``source`` id from config.

Log format
^^^^^^^^^^

- NDJSON (one JSON object per line).
- Each line contains:
  - ``time`` (``yyyy-MM-dd HH:mm:ss.SSS``)
  - ``source``
  - ``rc`` array (measure, value, tag, alert)

Config snapshot
^^^^^^^^^^^^^^^

- On server start, a copy of the config is saved to:
  ``<logPath>/<configName>/config.json``.
- If the same name exists but content differs, the existing folder is backed
  up with ``_old_YYYYMMDDHHmmss`` suffix.

Rotation
^^^^^^^^

- Log files are rotated when ``maxBytes`` is exceeded.
- A compressed ``.gz`` backup is kept up to ``maxBackups``.

Alerts
------

- If a measure triggers an alert, the configured script runs.
- Alert output is appended to:
  ``<logPath>/<configName>/YYYY/MM/<source>/alert_YYYYMM.json``.

CLI behavior
------------

ls
^^

::

   gop ls
   gop ls <config>
   gop ls <config>/<source>
   gop ls <config>/<source>/YYYY
   gop ls <config>/<source>/YYYY/MM

watch
^^^^^

::

   gop watch -config <config> -source <sourceId>
   gop watch -config <config>            # all sources
   gop watch -config <config> -source <sourceId> tail -follow

Notes:

- ``-source`` is optional. If omitted, all sources in the config are printed.
- If ``-config`` is omitted and multiple configs exist, ``watch`` lists them.
- ``-follow`` requires ``-source``.
- ``-time`` and ``-follow`` are mutually exclusive.

API
---

- Local-only (``127.0.0.1``).
- Reads log files only; no DB queries.

Endpoints:

- ``GET /health``
- ``POST /status``
- ``POST /watch``

Limitations
-----------

- ``-follow`` follows the current log file only. If a new day starts,
  restart watch to follow the new file.
- ``watch`` output depends on existing log files; no DB backfill.