157 lines
7.1 KiB
Markdown
157 lines
7.1 KiB
Markdown
# Weatherreporter Operations
|
|
|
|
This guide covers normal operation, managed workspace state, inspection,
|
|
recovery, and operational caveats. See the [CLI reference](cli.md) for complete
|
|
command syntax and the [configuration reference](config.md) for fields,
|
|
defaults, and notification templates. For symptom-based diagnosis, see
|
|
[Troubleshooting](troubleshooting.md).
|
|
|
|
## Normal Operation
|
|
|
|
After configuring a Weather API endpoint, generate one report:
|
|
|
|
```sh
|
|
weatherreporter generate today --out ./today.md
|
|
```
|
|
|
|
A generation collects weather data, resolves the report period, builds and
|
|
persists the module snapshot and prompt data package, runs Scriptorium
|
|
preflight, then produces the managed Markdown report. Daily, Today, Tomorrow,
|
|
and Hourly reports additionally persist generated-text artifacts, validate the
|
|
structured generated text, and render Markdown from the validated text and
|
|
deterministic values.
|
|
|
|
The managed report and its final metadata are saved before single-report
|
|
Distributor notification is attempted. `--out` writes an extra operator copy;
|
|
it never changes the managed report or upload source. A successful generate
|
|
command prints its summary to stdout unless `--quiet` is used.
|
|
|
|
Run a scheduled batch with the same configured collection:
|
|
|
|
```sh
|
|
weatherreporter run morning --out-dir ./reports
|
|
```
|
|
|
|
Each batch collects once before it plans reports. Morning runs Today, Tomorrow,
|
|
and every eligible dated Daily Report; evening runs Tomorrow and the same
|
|
eligible Daily Reports. Eligible Daily dates begin after tomorrow and require
|
|
complete hourly coverage for their entire local civil day. A batch continues
|
|
after an individual report fails and returns an aggregate failure when any
|
|
report or batch notification fails.
|
|
|
|
`--out-dir` writes extra copies such as `today.md`, `tomorrow.md`, and
|
|
`daily-YYYY-MM-DD.md`. These copies are never upload sources. Batch report
|
|
copies and notification behavior are summarized in the CLI result; use the
|
|
[CLI reference](cli.md) for its exact JSON and stderr contract.
|
|
|
|
## Managed Workspace
|
|
|
|
The default workspace root is `workspace`. Artifact paths use the report
|
|
definition's artifact group, the valid-period start date in the effective
|
|
timezone, and the RunID:
|
|
|
|
```text
|
|
workspace/
|
|
reports/<artifact_group>/<YYYY-MM-DD>/report.<run_id>.md
|
|
|
|
snapshots/<artifact_group>/<YYYY-MM-DD>/modules.<run_id>.json
|
|
snapshots/<artifact_group>/<YYYY-MM-DD>/metadata.<run_id>.json
|
|
snapshots/<artifact_group>/<YYYY-MM-DD>/generated_text_raw.<run_id>.json
|
|
snapshots/<artifact_group>/<YYYY-MM-DD>/generated_text_result.<run_id>.json
|
|
snapshots/<artifact_group>/<YYYY-MM-DD>/generated_text.<run_id>.json
|
|
snapshots/<artifact_group>/<YYYY-MM-DD>/render_context.<run_id>.json
|
|
|
|
data-packages/<artifact_group>/<YYYY-MM-DD>/data_package.<run_id>.yaml
|
|
preflight/<artifact_group>/<YYYY-MM-DD>/render.<run_id>.json
|
|
|
|
notifications/<artifact_group>/<YYYY-MM-DD>/distributor.<run_id>.json
|
|
notifications/batches/<batch>/<YYYY-MM-DD>/distributor.<batch_run_id>.json
|
|
```
|
|
|
|
The generated-text and render-context artifacts are written only by Daily,
|
|
Today, Tomorrow, and Hourly reports. A report's metadata links the module
|
|
snapshot, data package, preflight artifact, managed report, and any available
|
|
generated-text or single-report notification artifact. Batch notification
|
|
artifacts are separate batch-level records under `notifications/batches`.
|
|
|
|
RunIDs begin with the UTC generation timestamp and report ID. A Daily RunID
|
|
also contains its local valid date so multiple Daily reports in one batch have
|
|
different managed paths. Batch notification RunIDs contain the UTC batch start
|
|
timestamp and batch name.
|
|
|
|
## Distributor Notification
|
|
|
|
When `notify.distributor.enabled` is enabled, a successful `generate`
|
|
uploads only the managed Markdown report after final metadata has been saved.
|
|
The extra copy from `--out` is never uploaded. A notification attempt writes
|
|
a redacted debug artifact at
|
|
`notifications/<artifact_group>/<YYYY-MM-DD>/distributor.<run_id>.json`; its
|
|
path is then recorded in report metadata.
|
|
|
|
Batches suppress per-report notification. When both Distributor and its batch
|
|
notification are enabled, Weatherreporter submits one multi-report upload after
|
|
every planned report succeeds. If any report fails, it records a top-level
|
|
`skipped` notification with reason `one or more reports failed` and does not
|
|
call Distributor. If batch notification is disabled, a batch does not fall back
|
|
to individual uploads.
|
|
|
|
A batch notification attempt writes
|
|
`notifications/batches/<batch>/<YYYY-MM-DD>/distributor.<batch_run_id>.json`.
|
|
A notification failure makes the batch fail but does not change successful
|
|
individual report items into failed items. The debug artifacts contain rendered
|
|
identifiers, managed source and bundle paths, upload and status results, and
|
|
redacted errors; they do not contain tokens.
|
|
|
|
## Inspecting Stored Runs
|
|
|
|
Inspection is read-only: it neither collects weather data nor invokes
|
|
Scriptorium or Distributor. Start by finding a RunID:
|
|
|
|
```sh
|
|
weatherreporter inspect reports --limit 10
|
|
weatherreporter inspect metadata RUN_ID
|
|
```
|
|
|
|
| Command | Reads |
|
|
| --- | --- |
|
|
| `inspect reports` | Metadata files under the workspace snapshots tree. |
|
|
| `inspect metadata RUN_ID` | Metadata located by RunID. |
|
|
| `inspect modules RUN_ID` | The module snapshot path recorded in metadata. |
|
|
| `inspect data-package RUN_ID` | The data-package path recorded in metadata. |
|
|
| `inspect prior RUN_ID` | The run metadata, then compatible earlier metadata for its comparison policy. |
|
|
| `inspect sources RUN_ID` | Source provenance and warnings in the run metadata. |
|
|
|
|
A missing snapshots directory produces no listed reports. An unknown or empty
|
|
RunID is an error; use `inspect reports` to obtain a valid value.
|
|
|
|
## Recovery
|
|
|
|
Keep the workspace when a run fails: artifacts reached before the failure
|
|
remain available where they can be safely persisted.
|
|
|
|
- A preflight failure can leave the preflight artifact and metadata.
|
|
- A report-generation failure can leave the managed report, module snapshot,
|
|
data package, and metadata.
|
|
- A generated-text failure can leave raw text, the structured run result, or a
|
|
validated generated-text and render-context artifact, depending on where it
|
|
stopped.
|
|
- A single-report notification failure preserves the report and final metadata,
|
|
including its notification artifact when it was written.
|
|
- A batch notification failure preserves each report's artifacts and adds the
|
|
top-level batch notification artifact.
|
|
|
|
Use the RunID from the action summary with the inspection commands above. For
|
|
a batch failure, inspect the summary first, then inspect the affected report
|
|
RunIDs or the batch notification path. Do not remove the whole workspace as a
|
|
first response; retain it until the failure is understood.
|
|
|
|
## Operational Caveats
|
|
|
|
- Workspace files, generated reports, and Scriptorium stderr can contain
|
|
sensitive operational context. Set appropriate filesystem permissions and do
|
|
not publish them unintentionally.
|
|
- Weatherreporter uses one configured Weather API endpoint and local workspace
|
|
state.
|
|
- It does not provide automatic resume, cleanup, archival, remote state, daemon
|
|
operation, or automatic storm monitoring.
|