Unit Economics Cloud | The Garnet Wiki

Orientation

Unit Economics Cloud is the discipline of deriving cost‑per‑unit metrics from raw cloud billing data and allocating those costs to the specific dimensions that drive your business or technical operations—whether that’s per‑customer, per‑transaction, per‑job, per‑service, or per‑team. It matters when you need to price internal services, allocate infrastructure costs to business units, evaluate the marginal cost of a new feature, or make go/no‑go decisions based on measurable unit cost rather than aggregate spend. Unlike broad cost optimization, anomaly detection, or commitment strategies, unit economics asks not just “how much are we spending?” but “how much does each unit of what we do cost us, and how does that compare to what we charge or value it at?”

Extracting Raw Cost and Usage Data

The first step is pulling the granular line‑item export that contains both consumed quantity and monetary cost for every resource or event. Most cloud providers expose this through a billing API that returns JSON or CSV records keyed by timestamp, resource ID, usage type, and unblended cost. Because the endpoint shape varies by platform, the safest approach is to treat the export as a stream of records with a known schema and fetch it with a standard tool that exists on every operational host.

The following curl command retrieves a month of cost‑and‑usage data from a generic billing endpoint, asking for daily granularity and the two fields needed for unit‑economics calculations: the resource identifier and the unblended cost. The -G flag forces GET mode, --data-urlencode supplies the time window, and the Authorization header carries the reader’s bearer token (the actual issuance mechanism is platform‑specific and is not described here).

curl -G \
  --data-urlencode "start=$(date -d '1 month ago' +%Y-%m-%d)" \
  --data-urlencode "end=$(date +%Y-%m-%d)" \
  -H "Authorization: Bearer $BILLING_API_TOKEN" \
  https://billing.example.org/v1/cost-exports | jq -r '
    .results[]
    | select(.line_item_type == "Usage")
    | {resource_id, unblended_cost, usage_type, timestamp}
  '

The jq filter keeps only usage‑type records (excluding subscriptions, refunds, and credit notes) and extracts the four fields that will feed the downstream aggregation. If your export uses CSV, replace the jq pipeline with csvcut -c resource_id,unblended_cost,usage_type,timestamp from the csvkit suite, or pipe the raw text into psql via \copy.

The output is a tab‑delimited stream suitable for insertion into a relational store or for further jq/awk filtering. A typical record looks like:

res-0a1b2c3d	12.45	API_CALL	2024-03-15T08:23:00Z

No specific cost value is embedded; the mechanism is purely “fetch, filter, forward.”

Aggregating by Logical Dimension

Once the raw records are in hand, the next task is to group them by the dimension that defines a “unit” for your organization. The choice of dimension—resource ID, tag value, service name, or a custom business identifier—directly determines what “per‑unit” means. A common pattern is to aggregate by resource ID and usage type, then compute the ratio of total cost to event count.

The following psql statement creates a table that will hold the per‑unit result and populates it in a single step. It assumes the curl/jq pipeline has been saved to a temporary file cost_raw.json and loaded into a staging table cost_export with columns that match the jq output keys.

CREATE TABLE IF NOT EXISTS unit_economics (
  period DATE NOT NULL,
  resource_id TEXT NOT NULL,
  usage_type TEXT NOT NULL,
  unit_count BIGINT NOT NULL,
  cost_aggregate NUMERIC(12,2) NOT NULL,
  cost_per_unit NUMERIC(12,2) GENERATED ALWAYS AS (cost_aggregate / NULLIF(unit_count,0)) STORED
);

TRUNCATE unit_economics;

INSERT INTO unit_economics (period, resource_id, usage_type, unit_count, cost_aggregate)
SELECT 
  DATE(timestamp) AS period,
  resource_id,
  usage_type,
  COUNT(*) AS unit_count,
  SUM(CAST(unblended_cost AS NUMERIC)) AS cost_aggregate
FROM cost_export
GROUP BY DATE(timestamp), resource_id, usage_type;

The generated column cost_per_unit computes the average cost per event for that resource‑and‑type combination. If your definition of “unit” is not “per event” but “per transaction,” “per GB transferred,” or “per container‑hour,” replace COUNT(*) with the appropriate aggregation—SUM(bytes) for volume‑based units, COUNT(*) FILTER (WHERE event_type = 'request') for request‑based units, etc. The SQL pattern remains the same: a GROUP BY over the chosen dimension, a SUM of cost, and a divisor that reflects the unit count.

A sharp edge that appears at this stage is dimension mismatch. If some resources lack the cost‑allocation tag you’re grouping by, the export may drop those records entirely or assign them to a default “unallocated” bucket. The resulting unit_economics rows will have fewer entries than the underlying cost data, and the cost_per_unit values will be artificially low for the tagged set and high for the untagged remainder. Always inspect the COUNT(*) versus the total rows in cost_export after the first load.

Binding Unit Cost to Business Context

Raw per‑unit numbers are of limited use until they are mapped to the business context that stakeholders understand: which customer, which team, which product line, which environment. This is typically done with a join against a reference table that maps the technical identifier (resource ID, project ID, container name) to a business dimension.

Assume you have a dimension_map table in the same finops database:

CREATE TABLE IF NOT EXISTS dimension_map (
  technical_id TEXT PRIMARY KEY,
  business_unit TEXT NOT NULL,
  team_owner TEXT NOT NULL,
  product_line TEXT NOT NULL
);

The following \copy command exports the current unit_economics view enriched with business metadata, producing a CSV that can be handed to finance or product management:

psql -d finops -c \
  "\COPY (
    SELECT 
      ue.period,
      ue.resource_id,
      ue.usage_type,
      ue.unit_count,
      ue.cost_aggregate,
      ue.cost_per_unit,
      dm.business_unit,
      dm.team_owner,
      dm.product_line
    FROM unit_economics ue
    JOIN dimension_map dm ON ue.resource_id = dm.technical_id
  ) TO '/tmp/unit-economics-export.csv' WITH CSV HEADER;"

The resulting file contains one row per resource‑per‑type‑per‑period, with columns that finance teams can ingest into their chargeback models, budgeting spreadsheets, or internal pricing engines.

A quietly failing pattern occurs when dimension_map is not kept in sync with the actual resource inventory. If a team spins up a new cluster or renames a service without updating the map, those rows will be lost from the export (the JOIN produces no output for unmatched technical_id values). The per‑unit totals will appear to drop, and the business units will report “missing cost” without an obvious cause. The remedy is a nightly diff between the set of resource IDs seen in the cost export and the keys present in dimension_map, flagging any that lack a mapping for manual follow‑up.

Automating the Calculation Loop

Unit economics is not a one‑off query; it must refresh as billing data evolves and as the resource inventory changes. A cron‑driven shell script can fetch the latest export, reload the staging table, reroll the aggregation, and refresh the business‑context view. The following script illustrates a minimal, dependency‑light loop that uses only curl, jq, and psql—all standard tools found on any Linux‑based ops host.

#!/usr/bin/env bash
set -euo pipefail


START=$(date -d '1 day ago' +%Y-%m-%d)
END=$(date +%Y-%m-%d)

curl -G \
  --data-urlencode "start=$START" \
  --data-urlencode "end=$END" \
  -H "Authorization: Bearer $BILLING_API_TOKEN" \
  https://billing.example.org/v1/cost-exports \
  | jq -r '
      .results[]
      | select(.line_item_type == "Usage")
      | {resource_id, unblended_cost, usage_type, timestamp}
    ' > /tmp/cost_raw.json

# 2. Load raw records into the staging table (assumes COPY format matching jq output)
psql -d finops -c "TRUNCATE cost_export;"
psql -d finops -c "\COPY cost_export FROM '/tmp/cost_raw.json' WITH (FORMAT json)"

# 3. Re‑aggregate per‑unit metrics
psql -d finops -c "TRUNCATE unit_economics;"
psql -d finops -c "
  INSERT INTO unit_economics (period, resource_id, usage_type, unit_count, cost_aggregate)
  SELECT 
    DATE(timestamp) AS period,
    resource_id,
    usage_type,
    COUNT(*) AS unit_count,
    SUM(CAST(unblended_cost AS NUMERIC)) AS cost_aggregate
  FROM cost_export
  GROUP BY DATE(timestamp), resource_id, usage_type;
"

# 4. Refresh the business‑context view (requires dimension_map to be current)
psql -d finops -c "\COPY (
  SELECT ue.period, ue.resource_id, ue.usage_type, ue.unit_count, ue.cost_aggregate, ue.cost_per_unit,
         dm.business_unit, dm.team_owner, dm.product_line
  FROM unit_economics ue
  JOIN dimension_map dm ON ue.resource_id = dm.technical_id
) TO '/var/lib/finops/unit-economics-latest.csv' WITH CSV HEADER;"

Make the script executable (chmod +x /usr/local/bin/finops-unit-economics.sh) and install it as a daily cron entry (0 3 * * * /usr/local/bin/finops-unit-economics.sh). The script writes no state beyond the database and the CSV, so re‑runs are idempotent and can be safely re‑executed if a step fails midway.

Failure modes in automation typically stem from three sources: the billing API returning a different JSON shape (e.g., a new line_item_type added without updating the jq filter), the dimension_map missing keys for newly provisioned resources, or the PostgreSQL server being temporarily unavailable during the COPY phase. Each of these will cause the script to exit with a non‑zero status (thanks to set -euo pipefail), alerting the operator via the cron mailer or a configured monitoring webhook. The operator’s first response is usually to inspect the jq output against the latest export schema, update the mapping table, and re‑run the script.

Sharp Edges and Failure Modes

Understanding the boundary conditions of unit‑economics calculations prevents costly surprises in production.

Silently dropped costs. When a resource lacks all cost‑allocation tags, the billing export may either omit the record entirely or route it to a platform‑specific “unallocated” bucket. If your aggregation groups by tag value, those omitted records vanish from unit_economics, and the per‑unit cost for the tagged subset appears lower than the true organizational average. The mismatch is invisible unless you compare SELECT COUNT(*) FROM cost_export against SELECT COUNT(*) FROM unit_economics after a full load.

Tag‑vs‑service confusion. Many teams group by service_name from the cost export, then later discover that the same service name maps to different resource IDs across accounts, or that a single resource ID spans multiple services. The resulting cost_per_unit aggregates heterogeneous workloads, diluting the metric’s relevance. A reliable pattern is to include the resource_id in the GROUP BY clause alongside any tag or service dimension, ensuring each group represents a uniquely identifiable consumption unit.

Time‑window lag. Billing data is typically published with a 24‑ to 48‑hour delay. If your cron job fetches “yesterday’s” export at 03:00 UTC and your workloads are active around the clock, the most recent 24 hours of usage will be missing, causing unit_count to be understated and cost_per_unit to be overstated for that period. Mark the period column with a note that values for the most recent day are provisional, and design downstream dashboards to filter out the latest‑day bucket unless your organization has a real‑time cost‑streaming pipeline.

Showback vs. chargeback semantics. Unit economics calculations often assume chargeback semantics—i.e., the cost is actually billed back to the consuming team. If your organization practices showback (display‑only, no financial flow), the numbers are informational only. Presenting them as “cost allocated” without a clear disclaimer can lead to budgeting errors when finance teams later attempt to reconcile the numbers against actual invoices. Always prefix exported reports with a label such as “Showback‑derived unit cost—actual chargeback may differ.”

Schema evolution. Cloud providers occasionally add new line_item_type values (e.g., "SavingsPlan" or "ReservedInstance") or change the naming of existing fields. A jq filter that hard‑codes .line_item_type == "Usage" will silently drop new record types, reducing unit_count without any error signal. Guard against this by validating the set of line_item_type values present in the export after each fetch, and by using a more permissive filter such as .line_item_type | test("^Usage|^Savings|^Reserved") if your cost model includes those dimensions.

What you learn after it breaks. In practice, the first production‑wide unit‑economics dashboard almost always reveals a tag‑completeness gap: a newly formed engineering team’s resources are invisible because their environment tag was never standardized. The dashboard shows a sudden dip in per‑unit cost for the “mature” teams and a corresponding spike for the “unallocated” bucket. The operator’s immediate action is to add the missing tags retroactively, re‑run the aggregation, and update the dimension_map ingestion pipeline to enforce tag validation at resource‑creation time. The lesson is that unit economics is only as reliable as the tagging discipline that feeds it; invest in policy‑as‑code guards (e.g., OPA or Terraform validation rules) before scaling the metric across the organization.

This page was rewritten on 17 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.