92 lines
4.1 KiB
Markdown
92 lines
4.1 KiB
Markdown
# production-analytics
|
|
|
|
`production-analytics` is a small Python service that derives production
|
|
analytics from ENLYZE data for Grafana. ENLYZE remains the authority for raw
|
|
process data; this project persists only derived metrics, events, relevant
|
|
production-order context, and calculation state.
|
|
|
|
## Status
|
|
|
|
This repository includes a read-only ENLYZE API exploration CLI. It contains
|
|
no verified ENLYZE operation wrappers, database migrations, or HTTP endpoints.
|
|
|
|
## Intended flow
|
|
|
|
```text
|
|
ENLYZE (raw data) -> retrieval boundary -> calculations -> TimescaleDB -> Grafana
|
|
\-> calculation provenance/state
|
|
```
|
|
|
|
Production orders are the primary attribution context for results. Every
|
|
persisted result will ultimately be traceable to its machine, order/article
|
|
context, source time range, and calculation implementation version.
|
|
|
|
## Development
|
|
|
|
Requires Python 3.11 or newer. Install the project and development tools:
|
|
|
|
```bash
|
|
python3 -m pip install -e '.[dev]'
|
|
pytest
|
|
ruff check .
|
|
```
|
|
|
|
Copy `.env.example` to `.env` for public/local configuration documentation.
|
|
Put real ENLYZE credentials only in `secrets/enlyze.env`, which is ignored.
|
|
The CLI reads that file by default without executing it; it accepts only simple
|
|
`KEY=VALUE` lines (quoted values are supported). Environment variables may be
|
|
used instead when appropriate. Never pass keys as command-line arguments.
|
|
|
|
The generic request command only performs `GET` requests and requires the
|
|
operator to provide an API path that is known to be safe and authorized:
|
|
|
|
```bash
|
|
production-analytics enlyze raw /verified/path --pretty
|
|
production-analytics enlyze raw /verified/path --save-fixture response.json
|
|
```
|
|
|
|
Public ENLYZE documentation verifies Bearer-token authentication. Put
|
|
`ENLYZE_API_KEY='...'` in the local secret file; the exploration client sends
|
|
it as an `Authorization: Bearer …` header and never prints that header/value.
|
|
|
|
The second command saves a sanitized, reviewable fixture under
|
|
`fixtures/enlyze/` by default. Raw captures belong in the ignored
|
|
`data/raw/enlyze/` directory and must not be committed.
|
|
|
|
The OpenAPI server URL is `https://app.enlyze.com/api/`; its operation paths
|
|
begin with `/v2/`. Set `ENLYZE_BASE_URL` to that server URL, not to an
|
|
operation path. The documented read-only time-series operation is exposed for
|
|
exploration as `production-analytics enlyze timeseries`.
|
|
|
|
The current Compose file has no application service, so it deliberately does
|
|
not pass ENLYZE credentials to TimescaleDB. A future application service should
|
|
use `env_file: ./secrets/enlyze.env` rather than copying secrets into Compose.
|
|
|
|
## Peak-cycle detection
|
|
|
|
`PeakCycleDetector` is a pure calculation-domain component for roll length,
|
|
roll weight, and comparable sawtooth/batch signals. It retains the current
|
|
maximum and emits it only after the value is below
|
|
`drop_ratio * current_peak` continuously for `hold_seconds`. Configuration is
|
|
`min_peak`, `drop_ratio` (strictly between 0 and 1), non-negative
|
|
`hold_seconds`, and positive `max_sample_gap_seconds`. The hold uses elapsed
|
|
timestamps, never a sample count; an interval longer than the configured
|
|
maximum sample gap restarts a reset candidate,
|
|
so a timestamp gap alone is not evidence that a signal remained below threshold.
|
|
`max_sample_gap_seconds` is required rather than defaulted, so the source's
|
|
continuity assumption is explicit for each detector configuration.
|
|
Reset values can be negative and need not be zero. Equal timestamps are
|
|
accepted in arrival order but add no elapsed hold time; backwards timestamps
|
|
are rejected.
|
|
|
|
The first real-world validation case is K7 roll length (m), variable
|
|
`bf81c547-dccf-4709-aee2-0f78366d1dfc`. When the ignored local capture is
|
|
present, run `python scripts/validate_k7_roll_length.py` to inspect detected
|
|
peaks without adding the raw capture to tests or version control.
|
|
|
|
`docker compose up -d timescaledb` is an optional local database design for a
|
|
future persistence milestone. It is not required for the bootstrap tests.
|
|
|
|
See [PROJECT_KNOWLEDGE.md](PROJECT_KNOWLEDGE.md) for durable project context
|
|
and [docs/roadmap.md](docs/roadmap.md) for the implementation sequence.
|