mirror of
https://github.com/hanzoai/ai.git
synced 2026-11-20 14:13:23 +00:00
hanzo-inc/cloud#800. A serving node (or the router in front of it) states the runtime that answered as X-Hanzo-Runtime-Digest and X-Hanzo-Cache-Connector, on the response head or in the trailer of a stream. ai reads both into the usage record and writes them on every gen_ai span (gen_ai.hanzo.runtime.digest, gen_ai.hanzo.kv_cache.connector) and every hanzo.cloud_usage row (runtime_digest, cache_connector). Neither is relayed to the caller. The new leaf package provenance is the one rule for what is recorded: - a digest is `<algo>:<hex>` for sha256/sha384/sha512/blake3, or the digest of an image reference pinned by one (`repo@sha256:...`, registry dropped); a tag, a path or anything malformed is "unknown"; - a connector is one name from a closed vocabulary (in-memory, cpu-offload, disk-offload, external:<lmcache|mooncake|nixl|p2p-nccl|redis|s3|valkey| kv-fabric>, external:other); vLLM connector class names map onto it, a URL keeps its scheme alone, so no host, path or credential reaches a trace; - a node that states nothing reads "unknown", on the span and the row alike, so both attributes are on every span and a filter for either is one lookup. The columns are added with DEFAULT 'unknown' (DDL and migration), so rows written before them, and the subset inserts (DO backfill, cloud's OpenRouter import), read "unknown" too. ServedUsage carries both for a host that serves a model in process (TraceServedUsage). Testing: go test ./provenance ./object ./controllers ./routers (new: TestTheServingRuntimeIsReadAndNeverRelayed, TestEverySpanAndRowNamesTheRuntime, plus the provenance package's digest/connector/idempotence tests). Risk: low. Two String columns with defaults on the usage table (ADD COLUMN IF NOT EXISTS); values are normalised before any write. Billing is untouched. How to revert: revert this commit; the columns can stay (they default to 'unknown' and nothing else reads them). Co-Authored-By: Claude Opus 5.5 <[email protected]>
883 lines
36 KiB
Go
883 lines
36 KiB
Go
// Copyright 2023-2026 Hanzo AI Inc. All Rights Reserved.
|
||
//
|
||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||
// you may not use this file except in compliance with the License.
|
||
// You may obtain a copy of the License at
|
||
//
|
||
// http://www.apache.org/licenses/LICENSE-2.0
|
||
//
|
||
// Unless required by applicable law or agreed to in writing, software
|
||
// distributed under the License is distributed on an "AS IS" BASIS,
|
||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
// See the License for the specific language governing permissions and
|
||
// limitations under the License.
|
||
|
||
// Read side of the hanzo.cloud_usage ledger.
|
||
//
|
||
// The write side (controllers/zap_native.go zapWriteUsage) appends one row per
|
||
// inference call to the datastore table hanzo.cloud_usage via the direct datastore
|
||
// client (object/datastore.go). This file is the symmetric READ side: it aggregates that
|
||
// ledger into the console2 "Overview" dashboard payload — totals + period
|
||
// deltas, an evenly-spaced time series, spend-by-model (top-N + "other"), and
|
||
// the recent-activity feed — for BOTH the tenant-scoped console surface and the
|
||
// all-orgs admin god-view. One query path, scoped by organization.
|
||
//
|
||
// Design: every shaping rule (window resolution, gap-filled series, top-N fold,
|
||
// delta math, value coercion) is a pure function. GetCloudUsageOverview is a
|
||
// thin "fetch six aggregates, then assemble" orchestration; buildCloudUsageOverview
|
||
// is the pure assembler the test drives with mock rows — no datastore needed.
|
||
|
||
package object
|
||
|
||
import (
|
||
"context"
|
||
"encoding/json"
|
||
"fmt"
|
||
"math"
|
||
"sort"
|
||
"strconv"
|
||
"strings"
|
||
"sync/atomic"
|
||
"time"
|
||
|
||
"github.com/hanzoai/types"
|
||
)
|
||
|
||
// cloudUsageTableDDL is the ONE definition of the hanzo.cloud_usage schema.
|
||
// Both the write path (EnsureCloudUsageTable, called by zapWriteUsage) and the
|
||
// read path use it — there is no second copy.
|
||
const cloudUsageTableDDL = `
|
||
CREATE TABLE IF NOT EXISTS hanzo.cloud_usage (
|
||
id String,
|
||
timestamp DateTime,
|
||
owner String,
|
||
user_id String,
|
||
organization String,
|
||
project String,
|
||
model String,
|
||
requested String,
|
||
provider String,
|
||
origin String,
|
||
agent String,
|
||
api_key_hash String,
|
||
session_id String,
|
||
trace_id String,
|
||
request_id String,
|
||
prompt_tokens UInt32,
|
||
completion_tokens UInt32,
|
||
total_tokens UInt32,
|
||
cache_read_tokens UInt32,
|
||
cache_write_tokens UInt32,
|
||
cost_cents UInt64,
|
||
currency String,
|
||
status String,
|
||
error_msg String,
|
||
is_premium UInt8,
|
||
is_stream UInt8,
|
||
client_ip String,
|
||
byo UInt8,
|
||
fee_cents Int64,
|
||
account String,
|
||
cost_nano Int64,
|
||
billed_nano Int64,
|
||
margin_nano Int64,
|
||
unpriced UInt8,
|
||
uncosted UInt8,
|
||
cache_saved_nano Int64,
|
||
reasoning String,
|
||
reasoning_tokens UInt32,
|
||
served String,
|
||
vendor String,
|
||
arms String,
|
||
loss_nano Int64,
|
||
runtime_digest String DEFAULT 'unknown',
|
||
cache_connector String DEFAULT 'unknown'
|
||
) ENGINE = ReplacingMergeTree()
|
||
ORDER BY (timestamp, organization, user_id, id)
|
||
TTL timestamp + INTERVAL 2 YEAR`
|
||
|
||
// cloudUsageReplacingMergeTreeMigration documents the ONE-TIME, operator-run
|
||
// migration that converts a pre-existing hanzo.cloud_usage (created as plain
|
||
// MergeTree, ORDER BY (timestamp, organization, user_id)) to the id-deduplicating
|
||
// ReplacingMergeTree above (same key + id appended). CREATE TABLE IF NOT EXISTS
|
||
// does NOT alter an existing table's engine or sort key, and ClickHouse cannot
|
||
// ALTER either in place, so this is applied by hand (devnet first) and NEVER
|
||
// auto-run on boot (the backfill is heavy and would race across pods). Write-safe
|
||
// sequence (no lost writes):
|
||
//
|
||
// CREATE TABLE hanzo.cloud_usage_ridedup (<identical columns>)
|
||
// ENGINE = ReplacingMergeTree()
|
||
// ORDER BY (timestamp, organization, user_id, id)
|
||
// TTL timestamp + INTERVAL 2 YEAR;
|
||
// -- swap the empty ReplacingMergeTree in FIRST so live writes land in it:
|
||
// EXCHANGE TABLES hanzo.cloud_usage AND hanzo.cloud_usage_ridedup;
|
||
// -- backfill old rows; existing ids are unique so nothing real collapses, and
|
||
// -- any id already re-written post-EXCHANGE dedups harmlessly:
|
||
// INSERT INTO hanzo.cloud_usage SELECT * FROM hanzo.cloud_usage_ridedup;
|
||
// DROP TABLE hanzo.cloud_usage_ridedup;
|
||
//
|
||
// GetCloudUsageOverview reads dedup by id at query time (GROUP BY id), so a
|
||
// duplicate is never double-counted in the window between EXCHANGE and the first
|
||
// background merge — independently of this engine change.
|
||
|
||
// cloudUsageColumnMigrations bring an ALREADY-EXISTING table up to the current
|
||
// schema: CREATE TABLE IF NOT EXISTS is a no-op on a table created before these
|
||
// columns were added, so each additive column also needs an idempotent
|
||
// ADD COLUMN IF NOT EXISTS. Applied after the CREATE in EnsureCloudUsageTable so
|
||
// both a fresh and a legacy table converge on the same shape. Keep in lockstep
|
||
// with the DDL above and the zapWriteUsage INSERT.
|
||
var cloudUsageColumnMigrations = []string{
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS byo UInt8`,
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS fee_cents Int64`,
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS account String`,
|
||
// Nano-USD margin ledger (money-of-record): cost_nano = provider COGS,
|
||
// billed_nano = org debit, margin_nano = billed_nano − cost_nano. cost_cents
|
||
// stays the derived spend column the console reads.
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS cost_nano Int64`,
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS billed_nano Int64`,
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS margin_nano Int64`,
|
||
// unpriced = 1 when the model had no configured price and billed at the default,
|
||
// so the honest "priced?" flag is queryable in the warehouse, not just the span.
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS unpriced UInt8`,
|
||
// uncosted = 1 when no COGS was known for the call, so cost_nano holds 0 because
|
||
// nobody told us rather than because the call was free. The two are opposite facts
|
||
// that the Int64 column alone spells the same way, and a SUM that cannot tell them
|
||
// apart reports a business with no costs.
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS uncosted UInt8`,
|
||
// project is the caller's org SUB-SCOPE (X-Project-Id); it lets the per-org
|
||
// metrics board narrow WITHIN an org by project. Additive: a pre-existing row
|
||
// carries '' (the org's default project == whole-org view).
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS project String`,
|
||
// origin is the HOST that answered (object.Provider.Origin), beside provider,
|
||
// which is our route label for the same call. A label cannot disagree with
|
||
// itself however far the thing it names drifts; two columns can, and that
|
||
// disagreement is the measurement.
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS origin String`,
|
||
// agent is the machine credential that placed the call when no person did.
|
||
// Rows with an agent and an empty user_id are spend nobody owns — the query
|
||
// that finds them is the point of the column.
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS agent String`,
|
||
// api_key_hash is the SHA-256 ref of the caller credential the gen_ai span
|
||
// already carries — never the key. On the ledger it answers "what did this
|
||
// key spend", which is what a revocation decision needs and could not ask.
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS api_key_hash String`,
|
||
// session_id is the conversation the call belongs to. The gen_ai span has
|
||
// carried it all along, but a span plane and a spend ledger answer different
|
||
// questions: "what happened" versus "what did it cost". Asking which
|
||
// conversation spent the money meant joining two stores on a column only one
|
||
// of them had. Here it is a GROUP BY.
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS session_id String`,
|
||
// trace_id is the gen_ai span's own id, so a row and the span describing the
|
||
// same call join on an id both observed rather than on two ids that merely
|
||
// describe the same request.
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS trace_id String`,
|
||
// requested is the model the caller ASKED for, written only when a different
|
||
// route answered — when a vendor's account was spent and it served the request
|
||
// from a route it charges nothing for. Empty on every ordinary row, so
|
||
// `WHERE requested != ''` IS the query for "which generations were downgraded,
|
||
// and what did the customer actually want". Beside `model` (what answered) it
|
||
// makes a fallback a fact in the ledger rather than an inference from two rows.
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS requested String`,
|
||
// cache_saved_nano is what the prompt cache took off this call's bill: its
|
||
// cache-read tokens at the model's input price less the same tokens at the
|
||
// cache-read price, in the billed price's own nano-USD. It is written from the
|
||
// price the debit used, so a later price change never rewrites what a past call
|
||
// saved. A row written before the column carries 0, which is "not measured".
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS cache_saved_nano Int64`,
|
||
// reasoning is how hard the caller asked the model to think — none, low, medium,
|
||
// high, max, or default for a request that asked nothing and got its model's own —
|
||
// and reasoning_tokens the part of the completion it spent doing so. A price that
|
||
// moves with routing moves with depth, so the rates job reads both.
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS reasoning String`,
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS reasoning_tokens UInt32`,
|
||
// served is the upstream model that answered and vendor the provider whose
|
||
// account ran it: the arm. A family's answer names both, and a row that kept
|
||
// neither could not say what a request was routed to or whose credit bought it.
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS served String`,
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS vendor String`,
|
||
// arms is every arm a request priced at cost ran, as JSON: each upstream, its
|
||
// provider, its rates at the time and the tokens it was paid for, and each arm
|
||
// that failed first with why. The Enso family's requests carry it.
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS arms String`,
|
||
// loss_nano is what a call cost us past what it billed, 0 for every call billed
|
||
// at or above its cost. Never silent: a loss is a row, and the rates job counts it.
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS loss_nano Int64`,
|
||
// runtime_digest is the immutable digest of the image or serving binary that
|
||
// answered, cache_connector the KV cache path it ran with (in-memory,
|
||
// cpu-offload, disk-offload, external:<name>): which bytes and which cache served
|
||
// a call, for an integrity or isolation audit (hanzo-inc/cloud#800). Never a tag,
|
||
// a host or a credential (github.com/hanzoai/ai/provenance). "unknown" when no
|
||
// node stated it, and on every row written before the columns: those rows did not
|
||
// record it, so unknown is what they know.
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS runtime_digest String DEFAULT 'unknown'`,
|
||
`ALTER TABLE hanzo.cloud_usage ADD COLUMN IF NOT EXISTS cache_connector String DEFAULT 'unknown'`,
|
||
}
|
||
|
||
// CloudUsageColumns is the write order for a usage row, and the ONLY place it is
|
||
// written down. CloudUsageInsert is derived from it, so the column list and the
|
||
// placeholder count cannot disagree — the shift-by-one that silently lands every
|
||
// value after a newly inserted column in its neighbour's field is not expressible.
|
||
//
|
||
// It lives beside the DDL because a schema and the statement that fills it are one
|
||
// fact. Split across two packages, they drifted: four columns were declared here,
|
||
// documented here, populated on the record, and written by nothing.
|
||
var CloudUsageColumns = []string{
|
||
"id", "timestamp", "owner", "user_id", "organization", "project",
|
||
"model", "requested", "provider", "origin", "agent", "api_key_hash", "session_id", "trace_id",
|
||
"request_id",
|
||
"prompt_tokens", "completion_tokens", "total_tokens",
|
||
"cache_read_tokens", "cache_write_tokens",
|
||
"cost_cents", "currency", "status", "error_msg",
|
||
"is_premium", "is_stream", "client_ip",
|
||
"byo", "fee_cents", "account",
|
||
"cost_nano", "billed_nano", "margin_nano", "unpriced", "uncosted",
|
||
"cache_saved_nano",
|
||
"reasoning", "reasoning_tokens", "served", "vendor", "arms", "loss_nano",
|
||
"runtime_digest", "cache_connector",
|
||
}
|
||
|
||
// CloudUsageInsert is the usage-row INSERT, derived from CloudUsageColumns.
|
||
var CloudUsageInsert = "INSERT INTO hanzo.cloud_usage (" +
|
||
strings.Join(CloudUsageColumns, ", ") + ") VALUES (" +
|
||
strings.TrimSuffix(strings.Repeat("?, ", len(CloudUsageColumns)), ", ") + ")"
|
||
|
||
var cloudUsageTableReady atomic.Bool
|
||
|
||
// EnsureCloudUsageTable creates hanzo.cloud_usage if it does not exist, then
|
||
// applies the additive column migrations so a pre-existing table gains the
|
||
// byo/fee_cents/account columns. It is idempotent and only latches success, so a
|
||
// transient datastore outage at boot does not permanently poison later attempts.
|
||
func EnsureCloudUsageTable(ctx context.Context) error {
|
||
if cloudUsageTableReady.Load() {
|
||
return nil
|
||
}
|
||
if err := DatastoreExec(ctx, cloudUsageTableDDL); err != nil {
|
||
return err
|
||
}
|
||
for _, stmt := range cloudUsageColumnMigrations {
|
||
if err := DatastoreExec(ctx, stmt); err != nil {
|
||
return err
|
||
}
|
||
}
|
||
cloudUsageTableReady.Store(true)
|
||
return nil
|
||
}
|
||
|
||
// ── Request ─────────────────────────────────────────────────────────────────
|
||
|
||
// CloudUsageParams is the resolved, already-authorized query for one Overview.
|
||
// The controller fills Org/AllOrgs from the session (a tenant is pinned to its
|
||
// own org; a super admin may target one org or omit for all orgs). Start/End/
|
||
// Interval come from types.ParseWindow. The only field that reaches SQL
|
||
// un-parameterized is Interval, whose type admits only "hour" or "day"; Org is
|
||
// always passed as a bound parameter.
|
||
type CloudUsageParams struct {
|
||
RangeLabel string // echoed back ("24h"|"7d"|"30d"|"custom")
|
||
Start time.Time
|
||
End time.Time
|
||
Interval types.Interval // time-series bucket width
|
||
Org string // organization slug; ignored when AllOrgs is true
|
||
AllOrgs bool // super-admin all-orgs view (no organization filter)
|
||
// User, when set, narrows the org's rows to one member's own ("org/name").
|
||
// A member who is not an admin of the org reads only their own usage; many
|
||
// people share a signup org, and its aggregate is not any one of theirs.
|
||
User string
|
||
// Admin selects which of the two lenses the ONE ledger row is read through.
|
||
// It is not a second permission check: the controller sets it from the SAME
|
||
// evaluation of the SAME predicate (util.IsSuperAdmin + own brand) that already
|
||
// decided Org/AllOrgs, so a reader's scope and a reader's columns can never
|
||
// disagree about who is asking.
|
||
//
|
||
// false — the CUSTOMER lens, and the zero value on purpose. `provider` is the
|
||
// SKU it has always been ("hanzo", "enso"); `origin` is neither selected nor
|
||
// assigned. A caller that asks for nothing gets the customer shape, so the
|
||
// upstream cannot be disclosed by forgetting to hide it — only by proving the
|
||
// predicate.
|
||
//
|
||
// true — the ADMIN lens: the same row additionally carries the host that
|
||
// actually answered.
|
||
Admin bool
|
||
TopModels int // spend-by-model: keep top N, fold the rest into "other"
|
||
ActivityType string // "all" | "inference" (others → honest-empty feed)
|
||
ActivityLimit int
|
||
ActivityOffset int
|
||
}
|
||
|
||
// ── Response ────────────────────────────────────────────────────────────────
|
||
|
||
type CloudUsageTotals struct {
|
||
Tokens int64 `json:"tokens"`
|
||
PromptTokens int64 `json:"promptTokens"`
|
||
CompletionTokens int64 `json:"completionTokens"`
|
||
Requests int64 `json:"requests"`
|
||
SpendCents int64 `json:"spendCents"`
|
||
Models int64 `json:"models"`
|
||
Providers int64 `json:"providers"`
|
||
}
|
||
|
||
// CloudUsageDelta is one card's "vs prior period" comparison. Pct is nil when
|
||
// the prior period had no basis (prior == 0), so the client shows "—"/"new"
|
||
// instead of a fabricated ratio.
|
||
type CloudUsageDelta struct {
|
||
Current int64 `json:"current"`
|
||
Prior int64 `json:"prior"`
|
||
Pct *float64 `json:"pct"`
|
||
}
|
||
|
||
type CloudUsageSeriesPoint struct {
|
||
T string `json:"t"` // RFC3339 bucket start (UTC)
|
||
Tokens int64 `json:"tokens"`
|
||
SpendCents int64 `json:"spendCents"`
|
||
Requests int64 `json:"requests"`
|
||
Models int64 `json:"models"`
|
||
}
|
||
|
||
type CloudUsageModelSpend struct {
|
||
Model string `json:"model"`
|
||
Provider string `json:"provider"`
|
||
SpendCents int64 `json:"spendCents"`
|
||
Tokens int64 `json:"tokens"`
|
||
Requests int64 `json:"requests"`
|
||
Pct float64 `json:"pct"` // share of total spend, 0..100
|
||
}
|
||
|
||
type CloudUsageModelOther struct {
|
||
SpendCents int64 `json:"spendCents"`
|
||
Tokens int64 `json:"tokens"`
|
||
Requests int64 `json:"requests"`
|
||
Pct float64 `json:"pct"`
|
||
ModelCount int `json:"modelCount"`
|
||
}
|
||
|
||
type CloudUsageByModel struct {
|
||
Items []CloudUsageModelSpend `json:"items"`
|
||
Other *CloudUsageModelOther `json:"other"`
|
||
TotalCents int64 `json:"totalCents"`
|
||
}
|
||
|
||
type CloudUsageActivityRow struct {
|
||
Time string `json:"time"` // RFC3339 (UTC)
|
||
Model string `json:"model"`
|
||
Provider string `json:"provider"`
|
||
Type string `json:"type"` // "inference" — the only event class in this ledger
|
||
Status string `json:"status"`
|
||
Tokens int64 `json:"tokens"`
|
||
PromptTokens int64 `json:"promptTokens"`
|
||
CompletionTokens int64 `json:"completionTokens"`
|
||
CostCents int64 `json:"costCents"`
|
||
Stream bool `json:"stream"`
|
||
Premium bool `json:"premium"`
|
||
RequestID string `json:"requestId"`
|
||
Org string `json:"org"`
|
||
User string `json:"user"`
|
||
|
||
// Upstream is the host that ANSWERED this call — the hostname of the serving
|
||
// provider's URL, observed at the moment of the call rather than copied from a
|
||
// route's configured name. Present only under the admin lens; omitempty, so a
|
||
// customer read does not carry the key at all.
|
||
//
|
||
// Provider and Upstream are two different facts about one call: what we sold
|
||
// and where it was served. Keeping them in one row is what lets them be asked
|
||
// whether they still agree — a reroute or a fallback moves the second while the
|
||
// first keeps reading correct. Two stores would answer that question twice.
|
||
Upstream string `json:"upstream,omitempty"`
|
||
}
|
||
|
||
type CloudUsageActivity struct {
|
||
Items []CloudUsageActivityRow `json:"items"`
|
||
Limit int `json:"limit"`
|
||
Offset int `json:"offset"`
|
||
Total int64 `json:"total"`
|
||
Type string `json:"type"`
|
||
}
|
||
|
||
type CloudUsageScope struct {
|
||
Org string `json:"org"` // "" when allOrgs
|
||
AllOrgs bool `json:"allOrgs"`
|
||
}
|
||
|
||
type CloudUsageOverview struct {
|
||
Range string `json:"range"`
|
||
Start string `json:"start"` // RFC3339 (UTC)
|
||
End string `json:"end"` // RFC3339 (UTC)
|
||
Interval string `json:"interval"`
|
||
Scope CloudUsageScope `json:"scope"`
|
||
Totals CloudUsageTotals `json:"totals"`
|
||
Deltas map[string]CloudUsageDelta `json:"deltas"` // keys: tokens, spendCents, requests, models
|
||
Series []CloudUsageSeriesPoint `json:"series"`
|
||
ByModel CloudUsageByModel `json:"byModel"`
|
||
Activity CloudUsageActivity `json:"activity"`
|
||
}
|
||
|
||
// ── Live orchestration ────────────────────────────────────────────────────────
|
||
|
||
// cloudUsageDedupedSource wraps the ledger in an id-deduplication subquery so a
|
||
// duplicate row (a ZAP frame replay or an app retry) is counted exactly once at
|
||
// query time, without waiting for the ReplacingMergeTree background merge. any()
|
||
// is exact because rows sharing an id are byte-identical (id = the per-completion
|
||
// request UUID).
|
||
//
|
||
// The predicate lives in its OWN inner scan, one level below the aggregation.
|
||
// It cannot share a SELECT with the any() aliases: each alias deliberately
|
||
// reuses its column's name, and ClickHouse resolves a WHERE identifier against
|
||
// the same query's SELECT aliases — so `WHERE timestamp >= ?` beside
|
||
// `any(timestamp) AS timestamp` reads the AGGREGATE and refuses with
|
||
// ILLEGAL_AGGREGATION (code 184). The scan is still a plain filter over the
|
||
// base table, so the (timestamp, organization) primary index prunes it as
|
||
// before.
|
||
// extra carries any ADDITIONAL any() aliases the caller needs up through the
|
||
// dedup, as a leading-comma fragment. The subquery names its columns explicitly,
|
||
// so a column the outer SELECT projects must be aliased here or the query does
|
||
// not run; only the activity read passes anything (the lensed upstream), and the
|
||
// aggregates pass "".
|
||
func cloudUsageDedupedSource(where, extra string) string {
|
||
return "(SELECT id, any(timestamp) AS timestamp, any(owner) AS owner, " +
|
||
"any(user_id) AS user_id, any(organization) AS organization, any(model) AS model, " +
|
||
"any(provider) AS provider, any(request_id) AS request_id, " +
|
||
"any(prompt_tokens) AS prompt_tokens, any(completion_tokens) AS completion_tokens, " +
|
||
"any(total_tokens) AS total_tokens, any(cost_cents) AS cost_cents, " +
|
||
"any(status) AS status, any(is_stream) AS is_stream, any(is_premium) AS is_premium" +
|
||
extra +
|
||
" FROM (SELECT * FROM hanzo.cloud_usage WHERE " + where + ") GROUP BY id)"
|
||
}
|
||
|
||
// cloudUsageTotalsSQL is the id-deduplicated totals aggregation over one window.
|
||
func cloudUsageTotalsSQL(where string) string {
|
||
return "SELECT count() AS requests, sum(total_tokens) AS tokens, " +
|
||
"sum(prompt_tokens) AS prompt_tokens, sum(completion_tokens) AS completion_tokens, " +
|
||
"sum(cost_cents) AS cost_cents, uniqExact(model) AS models, uniqExact(provider) AS providers " +
|
||
"FROM " + cloudUsageDedupedSource(where, "")
|
||
}
|
||
|
||
// GetCloudUsageOverview runs the aggregate queries against the datastore ledger
|
||
// and assembles the Overview. Errors are surfaced (not swallowed) so the client
|
||
// can show an honest "unavailable" state rather than fabricated zeros.
|
||
func GetCloudUsageOverview(ctx context.Context, p CloudUsageParams) (*CloudUsageOverview, error) {
|
||
if !DatastoreEnabled() {
|
||
return nil, fmt.Errorf("usage ledger unavailable: datastore peer not connected")
|
||
}
|
||
if err := EnsureCloudUsageTable(ctx); err != nil {
|
||
return nil, fmt.Errorf("usage ledger: %w", err)
|
||
}
|
||
|
||
where, args := p.whereClause(p.Start, p.End)
|
||
span := p.End.Sub(p.Start)
|
||
priorWhere, priorArgs := p.whereClause(p.Start.Add(-span), p.Start)
|
||
|
||
totalsRow, err := cloudUsageQueryOne(ctx, cloudUsageTotalsSQL(where), args)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("usage totals: %w", err)
|
||
}
|
||
priorRow, err := cloudUsageQueryOne(ctx, cloudUsageTotalsSQL(priorWhere), priorArgs)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("usage prior totals: %w", err)
|
||
}
|
||
|
||
// Interval admits only Hour or Day, so the bucket function this interpolates
|
||
// cannot be widened by a request.
|
||
bucketFn := "Hour"
|
||
if p.Interval == types.Day {
|
||
bucketFn = "Day"
|
||
}
|
||
seriesSQL := fmt.Sprintf("SELECT toStartOf%s(timestamp, 'UTC') AS bucket, sum(total_tokens) AS tokens, "+
|
||
"sum(cost_cents) AS cost_cents, count() AS requests, uniqExact(model) AS models "+
|
||
"FROM %s GROUP BY bucket ORDER BY bucket", bucketFn, cloudUsageDedupedSource(where, ""))
|
||
seriesRows, err := DatastoreQuery(ctx, seriesSQL, args...)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("usage series: %w", err)
|
||
}
|
||
|
||
modelSQL := "SELECT model, any(provider) AS provider, sum(cost_cents) AS cost_cents, " +
|
||
"sum(total_tokens) AS tokens, count() AS requests FROM " + cloudUsageDedupedSource(where, "") +
|
||
" GROUP BY model ORDER BY cost_cents DESC LIMIT 100"
|
||
modelRows, err := DatastoreQuery(ctx, modelSQL, args...)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("usage by-model: %w", err)
|
||
}
|
||
|
||
var activityRows []map[string]any
|
||
var activityTotal int64
|
||
if cloudUsageActivityQueryable(p.ActivityType) {
|
||
limit := p.ActivityLimit
|
||
if limit <= 0 {
|
||
limit = 20
|
||
}
|
||
if limit > 200 {
|
||
limit = 200
|
||
}
|
||
offset := max(p.ActivityOffset, 0)
|
||
inner, outer := cloudUsageUpstreamColumns(p)
|
||
activitySQL := fmt.Sprintf("SELECT timestamp, model, provider, status, total_tokens, prompt_tokens, "+
|
||
"completion_tokens, cost_cents, is_stream, is_premium, request_id, user_id, organization%s "+
|
||
"FROM %s ORDER BY timestamp DESC LIMIT %d OFFSET %d",
|
||
outer, cloudUsageDedupedSource(where, inner), limit, offset)
|
||
if activityRows, err = DatastoreQuery(ctx, activitySQL, args...); err != nil {
|
||
return nil, fmt.Errorf("usage activity: %w", err)
|
||
}
|
||
countRow, err := cloudUsageQueryOne(ctx, "SELECT count(DISTINCT id) AS requests FROM hanzo.cloud_usage WHERE "+where, args)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("usage activity count: %w", err)
|
||
}
|
||
activityTotal = cuInt64(countRow["requests"])
|
||
}
|
||
|
||
return buildCloudUsageOverview(p, totalsRow, priorRow, seriesRows, modelRows, activityRows, activityTotal), nil
|
||
}
|
||
|
||
// whereClause builds the time + organization predicate. Times are formatted as
|
||
// datastore DateTime literals (UTC); the org slug is always a bound parameter
|
||
// (never interpolated) so a super admin's ?org= can't inject SQL.
|
||
func (p CloudUsageParams) whereClause(start, end time.Time) (string, []any) {
|
||
clause := "timestamp >= ? AND timestamp < ?"
|
||
args := []any{cloudUsageTS(start), cloudUsageTS(end)}
|
||
if !p.AllOrgs {
|
||
clause += " AND organization = ?"
|
||
args = append(args, p.Org)
|
||
}
|
||
if p.User != "" {
|
||
clause += " AND user_id = ?"
|
||
args = append(args, p.User)
|
||
}
|
||
return clause, args
|
||
}
|
||
|
||
func cloudUsageTS(t time.Time) string { return t.UTC().Format("2006-01-02 15:04:05") }
|
||
|
||
func cloudUsageQueryOne(ctx context.Context, sql string, args []any) (map[string]any, error) {
|
||
rows, err := DatastoreQuery(ctx, sql, args...)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
if len(rows) == 0 {
|
||
return map[string]any{}, nil
|
||
}
|
||
return rows[0], nil
|
||
}
|
||
|
||
// cloudUsageActivityQueryable reports whether an activity-tab filter maps to rows
|
||
// in THIS ledger. The cloud_usage table holds only inference events, so the
|
||
// deployments/jobs/payments tabs are honestly empty here (they are sourced from
|
||
// other surfaces) rather than faked.
|
||
func cloudUsageActivityQueryable(t string) bool {
|
||
switch strings.ToLower(strings.TrimSpace(t)) {
|
||
case "", "all", "inference":
|
||
return true
|
||
default:
|
||
return false
|
||
}
|
||
}
|
||
|
||
// ── Pure assembler (unit-tested) ──────────────────────────────────────────────
|
||
|
||
// buildCloudUsageOverview assembles the Overview from already-fetched raw rows.
|
||
// It is pure (no I/O), so the test drives it with mock datastore rows.
|
||
func buildCloudUsageOverview(
|
||
p CloudUsageParams,
|
||
totalsRow, priorRow map[string]any,
|
||
seriesRows, modelRows, activityRows []map[string]any,
|
||
activityTotal int64,
|
||
) *CloudUsageOverview {
|
||
totals := cloudUsageTotalsFromRow(totalsRow)
|
||
prior := cloudUsageTotalsFromRow(priorRow)
|
||
|
||
scope := CloudUsageScope{Org: p.Org, AllOrgs: p.AllOrgs}
|
||
if p.AllOrgs {
|
||
scope.Org = ""
|
||
}
|
||
|
||
items, other := foldCloudUsageModels(modelRows, p.TopModels, totals.SpendCents)
|
||
|
||
return &CloudUsageOverview{
|
||
Range: p.RangeLabel,
|
||
Start: p.Start.UTC().Format(time.RFC3339),
|
||
End: p.End.UTC().Format(time.RFC3339),
|
||
Interval: string(p.Interval),
|
||
Scope: scope,
|
||
Totals: totals,
|
||
Deltas: map[string]CloudUsageDelta{
|
||
"tokens": cloudUsageDelta(totals.Tokens, prior.Tokens),
|
||
"spendCents": cloudUsageDelta(totals.SpendCents, prior.SpendCents),
|
||
"requests": cloudUsageDelta(totals.Requests, prior.Requests),
|
||
"models": cloudUsageDelta(totals.Models, prior.Models),
|
||
},
|
||
Series: buildCloudUsageSeries(p.Start, p.End, p.Interval, seriesRows),
|
||
ByModel: CloudUsageByModel{Items: items, Other: other, TotalCents: totals.SpendCents},
|
||
Activity: buildCloudUsageActivity(p, activityRows, activityTotal),
|
||
}
|
||
}
|
||
|
||
func cloudUsageTotalsFromRow(r map[string]any) CloudUsageTotals {
|
||
return CloudUsageTotals{
|
||
Tokens: cuInt64(r["tokens"]),
|
||
PromptTokens: cuInt64(r["prompt_tokens"]),
|
||
CompletionTokens: cuInt64(r["completion_tokens"]),
|
||
Requests: cuInt64(r["requests"]),
|
||
SpendCents: cuInt64(r["cost_cents"]),
|
||
Models: cuInt64(r["models"]),
|
||
Providers: cuInt64(r["providers"]),
|
||
}
|
||
}
|
||
|
||
// cloudUsageDelta computes a card's prior-period comparison. Pct is left nil when
|
||
// prior == 0 (no basis), so the client never renders a fake "+∞%".
|
||
func cloudUsageDelta(current, prior int64) CloudUsageDelta {
|
||
d := CloudUsageDelta{Current: current, Prior: prior}
|
||
if prior > 0 {
|
||
p := round1((float64(current) - float64(prior)) / float64(prior) * 100)
|
||
d.Pct = &p
|
||
}
|
||
return d
|
||
}
|
||
|
||
// buildCloudUsageSeries turns sparse datastore buckets into an evenly-spaced,
|
||
// gap-filled series so the client charts a continuous line. Bucket alignment
|
||
// matches toStartOf{Hour,Day}(…, 'UTC'): Go's Truncate over the chosen step
|
||
// lands on the same UTC boundaries.
|
||
func buildCloudUsageSeries(start, end time.Time, interval types.Interval, rows []map[string]any) []CloudUsageSeriesPoint {
|
||
step := interval.Step()
|
||
|
||
type agg struct{ tokens, spend, requests, models int64 }
|
||
idx := make(map[int64]agg, len(rows))
|
||
for _, r := range rows {
|
||
bt := cuTime(r["bucket"]).Truncate(step)
|
||
idx[bt.Unix()] = agg{
|
||
tokens: cuInt64(r["tokens"]),
|
||
spend: cuInt64(r["cost_cents"]),
|
||
requests: cuInt64(r["requests"]),
|
||
models: cuInt64(r["models"]),
|
||
}
|
||
}
|
||
|
||
out := make([]CloudUsageSeriesPoint, 0, 64)
|
||
for t := start.UTC().Truncate(step); t.Before(end); t = t.Add(step) {
|
||
a := idx[t.Unix()]
|
||
out = append(out, CloudUsageSeriesPoint{
|
||
T: t.UTC().Format(time.RFC3339),
|
||
Tokens: a.tokens,
|
||
SpendCents: a.spend,
|
||
Requests: a.requests,
|
||
Models: a.models,
|
||
})
|
||
}
|
||
return out
|
||
}
|
||
|
||
// foldCloudUsageModels keeps the top-N models by spend and folds the rest into a
|
||
// single "other" bucket, computing each share of total spend. Pure.
|
||
func foldCloudUsageModels(rows []map[string]any, topN int, totalCents int64) ([]CloudUsageModelSpend, *CloudUsageModelOther) {
|
||
if topN <= 0 {
|
||
topN = 6
|
||
}
|
||
|
||
type m struct {
|
||
model, provider string
|
||
spend, tokens, requests int64
|
||
}
|
||
all := make([]m, 0, len(rows))
|
||
for _, r := range rows {
|
||
all = append(all, m{
|
||
model: cuString(r["model"]),
|
||
provider: cuString(r["provider"]),
|
||
spend: cuInt64(r["cost_cents"]),
|
||
tokens: cuInt64(r["tokens"]),
|
||
requests: cuInt64(r["requests"]),
|
||
})
|
||
}
|
||
sort.SliceStable(all, func(i, j int) bool { return all[i].spend > all[j].spend })
|
||
|
||
items := make([]CloudUsageModelSpend, 0, topN)
|
||
var other CloudUsageModelOther
|
||
for i, x := range all {
|
||
if i < topN {
|
||
items = append(items, CloudUsageModelSpend{
|
||
Model: x.model,
|
||
Provider: x.provider,
|
||
SpendCents: x.spend,
|
||
Tokens: x.tokens,
|
||
Requests: x.requests,
|
||
Pct: pctOf(x.spend, totalCents),
|
||
})
|
||
} else {
|
||
other.SpendCents += x.spend
|
||
other.Tokens += x.tokens
|
||
other.Requests += x.requests
|
||
other.ModelCount++
|
||
}
|
||
}
|
||
if other.ModelCount > 0 {
|
||
other.Pct = pctOf(other.SpendCents, totalCents)
|
||
return items, &other
|
||
}
|
||
return items, nil
|
||
}
|
||
|
||
// cloudUsageUpstreamColumns is the FIRST of the two places the lens applies: under
|
||
// the customer lens `origin` is never selected, so the host is not in the process
|
||
// that serves the response and cannot be disclosed by any later mistake in
|
||
// shaping it.
|
||
//
|
||
// It returns BOTH fragments the activity query needs, because they are one
|
||
// decision: `inner` carries origin up through the id-dedup subquery, and `outer`
|
||
// projects it. The subquery lists its columns explicitly, so an outer column
|
||
// without its inner alias is not a leak — it is a query that does not run
|
||
// (UNKNOWN_IDENTIFIER). Returning them together is what makes that pairing
|
||
// unforgettable; two functions could be called one at a time.
|
||
//
|
||
// Both are constant fragments chosen by a bool — no caller input reaches the SQL.
|
||
func cloudUsageUpstreamColumns(p CloudUsageParams) (inner, outer string) {
|
||
if !p.Admin {
|
||
return "", ""
|
||
}
|
||
return ", any(origin) AS origin", ", origin"
|
||
}
|
||
|
||
// cloudUsageUpstream is the SECOND place the lens applies, and the ONLY writer of
|
||
// CloudUsageActivityRow.Upstream. Assignment goes through this function so the
|
||
// question "may this reader see the host?" has exactly one answer in exactly one
|
||
// place, and the customer lens returns "" even if the column were somehow present.
|
||
//
|
||
// Two layers rather than one because they fail differently: the first keeps the
|
||
// value out of memory, the second keeps it out of the payload. Either alone is
|
||
// correct; together, being wrong takes two mistakes instead of one.
|
||
func cloudUsageUpstream(p CloudUsageParams, r map[string]any) string {
|
||
if !p.Admin {
|
||
return ""
|
||
}
|
||
return cuString(r["origin"])
|
||
}
|
||
|
||
func buildCloudUsageActivity(p CloudUsageParams, rows []map[string]any, total int64) CloudUsageActivity {
|
||
items := make([]CloudUsageActivityRow, 0, len(rows))
|
||
for _, r := range rows {
|
||
items = append(items, CloudUsageActivityRow{
|
||
Upstream: cloudUsageUpstream(p, r),
|
||
Time: cuTime(r["timestamp"]).Format(time.RFC3339),
|
||
Model: cuString(r["model"]),
|
||
Provider: cuString(r["provider"]),
|
||
Type: "inference",
|
||
Status: cuString(r["status"]),
|
||
Tokens: cuInt64(r["total_tokens"]),
|
||
PromptTokens: cuInt64(r["prompt_tokens"]),
|
||
CompletionTokens: cuInt64(r["completion_tokens"]),
|
||
CostCents: cuInt64(r["cost_cents"]),
|
||
Stream: cuBool(r["is_stream"]),
|
||
Premium: cuBool(r["is_premium"]),
|
||
RequestID: cuString(r["request_id"]),
|
||
Org: cuString(r["organization"]),
|
||
User: cuString(r["user_id"]),
|
||
})
|
||
}
|
||
at := strings.ToLower(strings.TrimSpace(p.ActivityType))
|
||
if at == "" {
|
||
at = "all"
|
||
}
|
||
return CloudUsageActivity{Items: items, Limit: p.ActivityLimit, Offset: p.ActivityOffset, Total: total, Type: at}
|
||
}
|
||
|
||
// ── Value coercion ────────────────────────────────────────────────────────────
|
||
//
|
||
// datastore rows arrive from the direct datastore-go client as native-typed maps
|
||
// (uint64/string/time.Time/float64), but coercion stays defensive: a value may
|
||
// still surface as float64, json.Number, or (for big UInt64) a string, and DateTime
|
||
// as "2006-01-02 15:04:05". These helpers coerce robustly so a driver encoding
|
||
// change can't crash a read.
|
||
|
||
func cuInt64(v any) int64 {
|
||
switch n := v.(type) {
|
||
case nil:
|
||
return 0
|
||
case int:
|
||
return int64(n)
|
||
case int64:
|
||
return n
|
||
case int32:
|
||
return int64(n)
|
||
case int16:
|
||
return int64(n)
|
||
case int8:
|
||
return int64(n)
|
||
case uint:
|
||
return int64(n)
|
||
case uint64:
|
||
return int64(n)
|
||
case uint32:
|
||
return int64(n)
|
||
case uint16:
|
||
return int64(n)
|
||
case uint8:
|
||
return int64(n)
|
||
case float64:
|
||
return int64(n)
|
||
case float32:
|
||
return int64(n)
|
||
case json.Number:
|
||
i, _ := n.Int64()
|
||
return i
|
||
case string:
|
||
if i, err := strconv.ParseInt(strings.TrimSpace(n), 10, 64); err == nil {
|
||
return i
|
||
}
|
||
if f, err := strconv.ParseFloat(strings.TrimSpace(n), 64); err == nil {
|
||
return int64(f)
|
||
}
|
||
return 0
|
||
default:
|
||
return 0
|
||
}
|
||
}
|
||
|
||
func cuString(v any) string {
|
||
switch s := v.(type) {
|
||
case nil:
|
||
return ""
|
||
case string:
|
||
return s
|
||
case fmt.Stringer:
|
||
return s.String()
|
||
default:
|
||
return fmt.Sprintf("%v", s)
|
||
}
|
||
}
|
||
|
||
func cuBool(v any) bool {
|
||
switch b := v.(type) {
|
||
case nil:
|
||
return false
|
||
case bool:
|
||
return b
|
||
case string:
|
||
return b == "1" || strings.EqualFold(b, "true")
|
||
default:
|
||
return cuInt64(v) != 0
|
||
}
|
||
}
|
||
|
||
func cuTime(v any) time.Time {
|
||
// The direct datastore driver decodes DateTime columns to time.Time; take it
|
||
// as-is before falling back to the string/unix layouts (a JSON transport path).
|
||
if t, ok := v.(time.Time); ok {
|
||
return t.UTC()
|
||
}
|
||
s := strings.TrimSpace(cuString(v))
|
||
if s != "" {
|
||
for _, layout := range []string{"2006-01-02 15:04:05", time.RFC3339, "2006-01-02"} {
|
||
if t, err := time.Parse(layout, s); err == nil {
|
||
return t.UTC()
|
||
}
|
||
}
|
||
}
|
||
if n := cuInt64(v); n > 0 {
|
||
return time.Unix(n, 0).UTC()
|
||
}
|
||
return time.Time{}
|
||
}
|
||
|
||
func pctOf(part, total int64) float64 {
|
||
if total <= 0 {
|
||
return 0
|
||
}
|
||
return round1(float64(part) / float64(total) * 100)
|
||
}
|
||
|
||
func round1(f float64) float64 { return math.Round(f*10) / 10 }
|