nilometer 0.0.0-stage → 0.1.0

package/dist/viewer/queries.js

@@ -0,0 +1,128 @@
+/**
+ * @file Loading the report's rows from the metric views (docs/development.md P7.1).
+ *
+ * Observations and projections are read by separate functions from separate view lists, and come
+ * back as separate objects, so no rendering code can place a projection among observations
+ * (README principle 2). `tests/unit/viewer/queries.test.ts` checks that {@link OBSERVED_VIEWS}
+ * holds only `obs_` views and {@link PROJECTED_VIEWS} only `proj_` views. The SQL here only selects
+ * whole views: every computation stays in the views themselves.
+ */
+import { listAliases } from "../core/plans/repository-aliases.js";
+/** The views {@link loadObserved} reads. Only `obs_` views belong here. */
+export const OBSERVED_VIEWS = [
+    "obs_limit_hits",
+    "obs_mid_task_interruptions",
+    "obs_lockout_time",
+    "obs_lockout_intervals",
+    "obs_interruptions_by_plan",
+    "obs_sessions_not_resumed",
+    "obs_window_headroom",
+    "obs_window_peak",
+    "obs_weekly_crossings",
+    "obs_usage_by_model",
+    "obs_usage_by_repo",
+];
+/**
+ * Metric views the report no longer shows, kept so `nilometer explain` can still list their
+ * events. Unattributed usage was zero in every one of Phase 8's 49 windows, since each fresh
+ * reading follows a request in its own session (D-044); D-079 took it off the screen, and the
+ * view stays to show that it is always zero.
+ */
+export const EXPLAIN_ONLY_VIEWS = ["obs_unattributed_usage"];
+/** The views {@link loadProjected} reads. Only `proj_` views belong here. */
+export const PROJECTED_VIEWS = ["proj_burn_rate", "proj_api_list_price"];
+/**
+ * Reads every row of one observed view.
+ * @param db - Open, migrated database.
+ * @param view - A name from {@link OBSERVED_VIEWS}.
+ * @param order - ORDER BY clause.
+ * @returns The rows.
+ */
+function observed(db, view, order = "1") {
+    return db.prepare(`SELECT * FROM ${view} ORDER BY ${order}`).all();
+}
+/**
+ * Reads every row of one projected view.
+ * @param db - Open, migrated database.
+ * @param view - A name from {@link PROJECTED_VIEWS}.
+ * @param order - ORDER BY clause.
+ * @returns The rows.
+ */
+function projected(db, view, order) {
+    return db.prepare(`SELECT * FROM ${view} ORDER BY ${order}`).all();
+}
+/**
+ * Loads every observed metric.
+ * @param db - Open, migrated database.
+ * @param reportedAt - The report's time: a window is open only until its reset, as of it (D-083).
+ *   Omitted, open is as of the last status line reading, as the views define it.
+ * @returns The observed report.
+ */
+export function loadObserved(db, reportedAt) {
+    // The report's own time, in Unix seconds, for "open" (D-083); null keeps the view's rule.
+    const at = reportedAt === undefined ? null : reportedAt.getTime() / 1000;
+    return {
+        limitHits: observed(db, "obs_limit_hits")[0],
+        midTask: observed(db, "obs_mid_task_interruptions")[0],
+        lockout: observed(db, "obs_lockout_time")[0],
+        lockoutIntervals: observed(db, "obs_lockout_intervals", "interval_number"),
+        // Before the first plan, then plans in order, then hits with no time (D-075).
+        interruptionsByPlan: observed(db, "obs_interruptions_by_plan", "CASE period_kind WHEN 'none' THEN 0 WHEN 'plan' THEN 1 ELSE 2 END, from_month"),
+        notResumed: observed(db, "obs_sessions_not_resumed")[0],
+        // Headroom and peak describe the same window instances, so they're joined in SQL to sit side by side.
+        windows: db
+            .prepare(`SELECT h.*, p.peak_used_percentage,
+           -- Open only until its reset, as of the report's time (D-083).
+           (h.window_open = 1 AND (:at IS NULL OR unixepoch(h.reset_at_utc, 'subsec') > :at))
+             AS open_at_report
+         FROM obs_window_headroom h
+         JOIN obs_window_peak p ON p.window = h.window AND p.reset_at_utc = h.reset_at_utc
+         ORDER BY open_at_report DESC, h.reset_at_utc DESC, h.window`)
+            .all({ at }),
+        // Newest window first, as the windows table lists them; within one, the lower level first.
+        weeklyCrossings: observed(db, "obs_weekly_crossings", "reset_at_utc DESC, threshold"),
+        byModel: observed(db, "obs_usage_by_model", "output_tokens DESC, model"),
+        byRepo: observed(db, "obs_usage_by_repo", "output_tokens DESC, repository"),
+        repositoryAliases: listAliases(db),
+    };
+}
+/**
+ * Loads every projection.
+ * @param db - Open, migrated database.
+ * @param reportedAt - The report's time, as for {@link loadObserved}: burn rate projects windows open at it.
+ * @returns The projected report.
+ */
+export function loadProjected(db, reportedAt) {
+    // The report's own time, as loadObserved takes it (D-083).
+    const at = reportedAt === undefined ? null : reportedAt.getTime() / 1000;
+    return {
+        // A projection for a window that has already reset would project into the past (D-083).
+        burnRate: db
+            .prepare(`SELECT *,
+           (window_open = 1 AND (:at IS NULL OR unixepoch(reset_at_utc, 'subsec') > :at))
+             AS open_at_report
+         FROM proj_burn_rate
+         ORDER BY open_at_report DESC, reset_at_utc DESC, window`)
+            .all({ at }),
+        apiListPrice: projected(db, "proj_api_list_price", "month"),
+        // Grouped by reading date so each count stays beside its own date. The month view's
+        // verified_on is the latest date in the month, which isn't the date its count refers to once
+        // price rows were read on different days.
+        rateReadings: db
+            .prepare(`SELECT verified_on, COUNT(*) AS priced_before_verified_requests
+         FROM request_costs
+         WHERE timestamp_utc IS NOT NULL AND unpriced_reason IS NULL AND day_utc < verified_on
+         GROUP BY verified_on
+         ORDER BY verified_on`)
+            .all(),
+    };
+}
+/**
+ * Reads when the last ingest finished.
+ * @param db - Open, migrated database.
+ * @returns ISO-8601 UTC, or null before any completed ingest.
+ */
+export function lastIngestAt(db) {
+    return db.prepare("SELECT MAX(finished_at) AS at FROM ingest_runs").get().at;
+}
+//# sourceMappingURL=queries.js.map