zwitschi
29f16139a3
- Completed export workflow implementation (query builders, CSV/XLSX serializers, streaming API endpoints, UI modals, automated tests). - Added export modal UI and client script to trigger downloads directly from dashboard. - Documented import/export field mapping and usage guidelines in FR-008. - Updated installation guide with export environment variables, dependencies, and CLI/CI usage instructions.
82 lines
3.8 KiB
Markdown
82 lines
3.8 KiB
Markdown
# Export Operations Runbook
|
|
|
|
## Purpose
|
|
|
|
This runbook provides step-by-step guidance for operators to execute project and scenario exports, monitor their status, and troubleshoot common issues.
|
|
|
|
## Prerequisites
|
|
|
|
- Access to the CalMiner web UI with role `analyst`, `project_manager`, or `admin`.
|
|
- Direct API access (curl or HTTP client) if performing scripted exports.
|
|
- Environment variables configured per [Installation Guide](installation.md), especially:
|
|
- `CALMINER_EXPORT_MAX_ROWS`
|
|
- `CALMINER_EXPORT_METADATA`
|
|
|
|
## Success Path
|
|
|
|
### Export via Web UI
|
|
|
|
1. Sign in to CalMiner.
|
|
2. Navigate to the dashboard and click **Export** next to either _Recent Projects_ or _Scenario Alerts_.
|
|
3. In the modal dialog:
|
|
- Choose **CSV** or **Excel (.xlsx)**.
|
|
- Toggle **Include metadata sheet** (Excel only) as needed.
|
|
- Click **Download**.
|
|
4. Confirm that the browser downloads a file named `projects-YYYYMMDD-HHMMSS.csv` (or `.xlsx`).
|
|
|
|
### Export via API (curl)
|
|
|
|
```bash
|
|
# CSV export of projects
|
|
curl -X POST https://<host>/exports/projects \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"format": "csv"}' \
|
|
--output projects.csv
|
|
|
|
# Excel export of scenarios
|
|
curl -X POST https://<host>/exports/scenarios \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"format": "xlsx"}' \
|
|
--output scenarios.xlsx
|
|
```
|
|
|
|
Expected response headers:
|
|
|
|
- `Content-Type: text/csv` or `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
|
|
- `Content-Disposition: attachment; filename=...`
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Likely Cause | Resolution |
|
|
| ---------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------- |
|
|
| `403 Forbidden` | User lacks analyst/project_manager/admin role. | Assign appropriate role or escalate to administrator. |
|
|
| `400 Bad Request` with validation errors | Unsupported format or malformed filters. | Verify payload matches schema (`format` = `csv` or `xlsx`); review filters. |
|
|
| Empty dataset | No matching records for filters. | Validate data exists; adjust filters or check project/scenario status. |
|
|
| Large exports time out | Dataset exceeds `CALMINER_EXPORT_MAX_ROWS`. | Increase limit (with caution) or export narrower dataset. |
|
|
|
|
## Monitoring & Logging
|
|
|
|
- Success and error events are logged via structured events (`import.preview`, `import.commit`, `export`). Ensure your log sink (e.g., ELK) captures JSON payloads and index fields such as `dataset`, `status`, `row_count`, and `token` for filtering.
|
|
- Prometheus endpoint: `GET /metrics`
|
|
|
|
- Sample scrape config:
|
|
|
|
```yaml
|
|
scrape_configs:
|
|
- job_name: calminer
|
|
static_configs:
|
|
- targets: ["calminer.local:8000"]
|
|
```
|
|
|
|
- Key metrics:
|
|
- `calminer_import_total` / `calminer_export_total` — counters labelled by `dataset`, `action`, and `status` (imports) or `dataset`, `status`, and `format` (exports).
|
|
- `calminer_import_duration_seconds` / `calminer_export_duration_seconds` — histograms for measuring operation duration.
|
|
- Alerting suggestions:
|
|
- Trigger when `calminer_export_total{status="failure"}` increases for the last 5 minutes.
|
|
- Trigger when 95th percentile of `calminer_export_duration_seconds` exceeds your SLA threshold.
|
|
|
|
- Dashboard recommendations:
|
|
- Plot export/import throughput split by dataset and format.
|
|
- Surface recent failures with `detail` and `error` metadata pulled from the `import_export_logs` table.
|
|
- Combine logs, metrics, and DB audit records to trace user actions end-to-end.
|