2026-10-22-measurement-schema

field,kind,priority,definition_or_formula,grain,data_source,accountable_owner,cadence,decision_enabled,caveat,evidence_ids
use_case_id,dimension,Required,Stable workflow identifier; no personal data,Task and charge,Service registry / application,Engineering,Before first run,Join financial and execution records to a bounded service,Do not use changing display names as keys,G04;G09
business_owner,dimension,Required,Named accountable role/person for acceptance and value,Use case,Service registry,Product/business,At onboarding and ownership change,Who can scale or stop this use case?,Do not put personal names into high-cardinality metric labels,G02
service_owner,dimension,Required,Named team/on-call accountable for runtime and cost incident actions,Use case,Service registry,Engineering,At onboarding and ownership change,Who can investigate or cancel expensive runs?,An alert without an actionable owner is incomplete,G02
cost_center,dimension,Required for finance,Finance-approved allocation group,Charge/use case,ERP / service registry,Finance/FinOps,Daily mapping; monthly reconciliation,Budget and ownership view,Keep effective dates when organisations change,G04
environment,dimension,Required,Experiment / development / production,Run/charge,Application / cloud metadata,Engineering,At execution,Separate experiments from production cost,Do not infer production value from experimental token volume,G04
task_id,dimension,Required,Stable business task identifier retained across retries,Task,Application,Engineering,At task creation,Deduplicate accepted work and include all attempts,Use a pseudonymous ID; no raw document content needed,Analysis
run_id,dimension,Required,Unique execution attempt; link to task_id,Run,Orchestrator,Engineering,At each attempt,Compare attempts and repeat work,One task can have many runs; not many business successes,G12;Analysis
trace_span_parent_ids,dimension,Recommended,Trace/span IDs and parent link to model/tool/agent children,Execution span,Tracing,Engineering,At execution,Explain fan-out and end-to-end behavior,Deduplicate parent totals and child costs; sampled traces do not equal a ledger,G11;G12
variant_version,dimension,Required for experiments,Prompt / workflow / model configuration and evaluation rubric versions,Run,Deployment / experiment metadata,Engineering + Product,At execution,Attribute a change to a defined intervention,Freeze versions and workload cohort during comparison,Analysis
workload_stratum,dimension,Required for valid comparison,Relevant complexity/language/document/risk group,Task,Business/application metadata,Product,At task creation,Compare like work and inspect subgroup quality,Avoid comparisons where variant changes the task mix,Analysis
period_start_end_utc,dimension,Required,Inclusive start / exclusive end timestamps plus business reporting timezone,Charge/run/outcome,Provider / application / financial system,FinOps + Engineering,At ingestion,Align cost and outcome periods,Acceptance can arrive after execution; use cohort and maturity rules,G05;Analysis
provider_model_service_sku,dimension,Required,Provider; exact billed model/version; service; SKU; region when relevant,Billable item,Provider response + bill,Engineering + FinOps,At execution and invoice,Explain rate and model mix,Requested model and response/billed model may differ,G09;G11
meter_quantities_native,measure,Required for variable services,Provider-native billable meter quantity and unit per SKU,Billable item,Provider usage API / billing export,Engineering + FinOps,At response; reconcile daily,Find consumption drivers and calculate estimates,Retain uncached/cache-read/cache-write/output/tool categories as provider reports them; document overlaps,G06;G09;G11
input_output_token_totals,measure,Recommended diagnostic,Provider-reported total input and total output tokens,Model call,Provider usage response,Engineering,At response,Detect long context/output growth,Cache/reasoning/modality counts can be subsets; never add them again to totals,G11
provider_request_id,dimension,Recommended,Provider unique request ID plus idempotency/deduplication key,Model/tool call,Provider response / application,Engineering,At response,Resolve duplicate telemetry and reconcile disputed usage,An application retry may produce a new billable request,G11;Analysis
runtime_cost_estimate,measure,Required for runtime visibility,Sum of non-overlapping billable meter quantities times applicable estimated rates,Run,Usage response + versioned rate table,Engineering,After each response/tool operation,Anomaly and remaining-envelope estimate,Provisional; allow for delayed fees; not a final invoice or exact hard-cap guarantee,G09;G10
rate_table_version,dimension,Required for estimated costs,Rate source date; currency; unit; discount/service-tier assumptions,Estimated charge,Contract and provider price data,FinOps,On rate/contract change,Reproduce runtime estimates,List prices can differ from contracted prices; preserve original pricing units,G05;G06
billing_currency_fx_policy,dimension,Required,Original currency; base currency; FX source/date/policy,Charge,Invoice / finance FX table,Finance,At ingestion and reporting,Combine currencies consistently,Retain original amounts; do not treat FX changes as engineering savings,G05;Analysis
billed_cost,measure,Required financial,Provider Billed Cost under selected export/accounting policy,Charge,Invoice / native or FOCUS export,Finance/FinOps,Daily estimate; final at invoice,Invoice/cash reconciliation,Do not add Billed and Effective Cost as if they are separate spend,G05;G15
effective_cost,measure,Required for accrual unit economics when available,Provider/normalised Effective Cost including discounts and allocated recognised covering purchases,Charge,FOCUS / provider export,Finance/FinOps,Daily; close monthly,Comparable accrued use-case economics,Not the same as cash paid now; document credit/tax/support scope,G05
shared_run_cost_allocated,measure,Required if used in denominator,Share of platform/hosting/support operating cost under versioned policy,Use case/period,Finance + platform ledger,FinOps + Platform,Monthly or pilot period,Show fully loaded service run economics,Keep central-funded and unallocated costs visible; avoid false marginal-cost claims,G04
allocation_policy_version,dimension,Required,Direct/proxy/fixed/centrally funded method with effective dates,Shared-cost pool,Finance policy register,Finance/FinOps,On policy change,Explain differences in unit costs,Hold constant for matched comparisons or restate baseline,G04
review_rework_minutes,measure,Required if material,Observed human effort on review/corrections/escalations including unsuccessful tasks,Task,Review workflow/time sample,Product/operations,At review; aggregate weekly,Reveal quality costs outside the model bill,Observed effort is capacity effect; payroll reduction needs separate evidence,Analysis
labour_cost_rate,dimension,Required if monetising effort,Finance-approved relevant labour costing rate and method,Role/cohort,Finance,Finance,At pilot start,Convert review/rework time into consistent cost,Separate avoidable cash from absorbed labour cost; exclude double-counted implementation time,Analysis
acceptance_status,measure,Required,Accepted / rejected / pending / unknown against a fixed rubric,Task,Business workflow / human adjudication,Product/business,At decision and agreed reopening horizon,Business denominator and quality gate,A successful API response does not establish business acceptance,G03;Analysis
acceptance_rubric_version,dimension,Required,Written quality criteria; authority; delayed failure/reopen window,Task cohort,Product / quality management,Product/business,Before evaluation,Ensure equal acceptance definitions,Do not redefine success after seeing variant results,Analysis
accepted_outcomes,KPI,Leadership core,Count distinct task_id with accepted status inside the agreed matured cohort,Use case/cohort,Outcome table,Product/business,Weekly,What accepted work was delivered?,Count once across attempts; show unknown/pending separately,G03;Analysis
cost_per_accepted_outcome,KPI,Leadership core,Comparable run costs + attributable review/rework + allocated run costs divided by accepted_outcomes,Use case/matured cohort,Joined financial + execution + business records,FinOps + Product,Weekly with monthly reconciliation,Are we producing useful work more efficiently?,Undefined when accepted_outcomes=0; show numerator and denominator; build cost separate,G03;G05;Analysis
acceptance_rate_by_stratum,KPI,Leadership core,Accepted tasks / all evaluated tasks with explicit treatment of pending and unknown,Use case/stratum/cohort,Outcome table,Product/quality,Weekly,Does a cost intervention preserve acceptable work?,Report adjudicated and unknown counts; uncertainty; do not quietly exclude failures,Analysis
p95_end_to_end_latency,KPI,Leadership core when interactive,95th percentile task completion elapsed time including retries and agreed review scope,Use case/stratum,Task timestamps,Engineering/service owner,Daily/weekly,Does efficiency meet service needs?,Use same start/end definition; include timeouts as a separately reported rate,G11;Analysis
p95_run_cost,KPI,Recommended,95th percentile complete run cost estimate; inspect max and task totals too,Use case/run cohort,Runtime meters,Engineering,Daily/weekly,Identify expensive exceptions and runaway tail,A per-run percentile can hide many cheap retries per task; also inspect total task cost,G10;Analysis
retry_fanout_metrics,KPI,Diagnostic,Attempts per distinct task; child calls/jobs per run; repeated tool failure count,Use case/stratum,Orchestrator/traces,Engineering,Near runtime; daily aggregate,What amplified consumption?,Do not infer waste solely from retries; some improve accepted outcomes,G11;G12;Analysis
monthly_forecast_range,KPI,Leadership core,Demand range times measured workload-mix unit cost plus fixed/committed costs,Use case/period,Business demand plan + usage + commitments,Product + Finance,Weekly during pilot; monthly thereafter,How much envelope is needed and why?,Scenario estimate; reflect adoption and tail uncertainty; avoid false precision,G02;Analysis
ownership_spend_coverage,KPI,Data quality,Effective cost mapped to valid owner and use case / scoped effective cost,Spend perimeter/period,Ledger + ownership map,FinOps,Weekly,Can decisions reach an accountable owner?,Coverage denominator must include unknown spend; centrally funded shared costs are not unowned,G04;Analysis
reconciliation_gap,KPI,Data quality,Same-scope same-period internal estimates minus provider reported cost; report signed and absolute gap,Provider/use case/period,Internal ledger + provider bill,FinOps,Daily provisional; monthly final,Is the joined view complete enough to trust?,Threshold must account for reporting lag; currencies; credits; timing and fixed charges,G09;Analysis
net_avoidable_benefit_horizon,KPI,Investment core,Avoidable cost reduction + validated added benefit - implementation/migration/evaluation - added operations - risk allowance over explicit H,Intervention,Decision record + finance validation,Sponsor + Finance,At prioritisation and review,Is this optimisation worth implementing?,Keep scenario ranges; no double counting; already incurred build cost is sunk for forward choice,G14;Analysis
realised_cash_reduction,KPI,Benefit accounting,Verified reduction in cash/contract outflow net of replacement and transition costs,Intervention/period,Paid invoices/contracts + baseline,Finance,After billing/renewal confirmation,What reached the budget/cash position?,Lower use inside a prepaid commitment is not automatically cash saved,G05;Analysis
cost_avoidance,KPI,Benefit accounting,Credible forecasted matched-workload baseline minus actual/forecast intervention cost,Intervention/period,Frozen counterfactual + ledger,Finance,At review,What future spend was avoided?,Label counterfactual assumptions; never add again to the same realised reduction,Analysis
released_capacity_hours,KPI,Benefit accounting,Observed reduction in review/operation effort at matched accepted throughput,Intervention/cohort,Time sample / operations data,Product/operations,Weekly then validated,What capacity can be redeployed?,Not automatically payroll reduction or revenue; document actual redeployment,Analysis
control_envelope_and_action,dimension,Required for agents,Task budget; steps; retries; timeout; concurrency; tool allowances; queue/fallback/cancel policy,Service/agent config,Runtime policy,Engineering/service owner,Before autonomy; on policy change,Will spend stop or degrade predictably?,Test in-flight and concurrent overshoot; include external tool costs and critical-service exception,G07;G08;G10;Analysis
decision_record_status,dimension,Required,Scale / optimise / redesign / hold-for-evidence / pause / stop; owner and next review date,Use case/intervention,Decision log,Sponsor,At each funding review,What action follows from evidence?,A dashboard update alone is not a decision,G02;G14;Analysis