Enrichment modules: AWS and Azure service coverage¶

SPRUCE generates its estimates by chaining EnrichmentModules. An EnrichmentModule is the unit of extension in SPRUCE. Each module reads columns from the CUR input row and/or from values set by earlier modules, then writes its results into a shared map. The pipeline materialises one output row per CUR row at the end, avoiding per-module row copies.

The enrichment modules are listed and configured in a configuration file, one per cloud provider and report format. If no configuration is specified, SPRUCE uses the bundled default for the active provider (e.g. default-config-aws.json for a native AWS CUR, or default-config-aws-focus.json / default-config-azure-focus.json for an AWS or Azure FOCUS report). See Configure the modules for instructions on how to modify the enrichment modules, and Write a module to add your own. The list of columns generated by the modules can be found in the SpruceColumn class.

The pipeline at a glance¶

The modules run in sequence and fall into five stages. Later stages consume the columns written by earlier ones, which is why the order in the configuration file matters.

flowchart LR
    A[Billing row] --> B("<b>Metadata</b><br>RegionExtraction")
    B --> C("<b>Energy &amp; embodied</b><br>Storage, Networking,<br>Serverless, Accelerators,<br>Boavizta, EcoLogits")
    C --> D("<b>Factors</b><br>PWUE,<br>AverageCarbonIntensity")
    D --> E("<b>Impacts</b><br>OperationalEmissions,<br>Water")
    E --> F("<b>Normalisation</b><br>FOCUSColumns<br>(native formats only)")
    F --> G[Enriched row]

Stage 1 — Metadata extraction¶

RegionExtraction¶

Extracts the region information from the provider-specific input columns and stores it in a standard location, where all the following modules can find it. The FOCUS variant is provider-neutral: it reads the standard RegionId column.

Stage 2 — Energy and embodied estimates¶

The modules in this stage estimate the energy used by a row of usage and, for Storage, Boavizta and EcoLogits, the related embodied emissions. Each module handles a different kind of usage (storage, networking, compute, …), so they complement each other rather than overlap.

Storage¶

Estimates the energy used for storage by applying a flat coefficient per GB, following the approach of the Cloud Carbon Footprint project, and the embodied emissions of the drives holding the data, amortised over their service life. Service-specific replication factors are applied to both, since the same bytes occupy that many times more physical drives. On Azure, managed disks are estimated from their provisioned capacity.

Energy configuration (in Wh per TB-hour):

Embodied emissions configuration:

The two media are modelled on different bases. A hard drive costs roughly the same to manufacture whatever its capacity, since the platters, motor, actuator, casing and PCB are near-fixed for a 3.5" unit and areal density does the work, so its embodied emissions are a constant per drive divided by an assumed capacity. An SSD's die area scales with capacity, so its figure is a rate per GB. With the defaults that works out at 0.40 kg CO2eq per TB-year for HDD and 11 kg for SSD.

Note that hdd_capacity_gb describes the physical drive rather than a provisioned volume, so it is not the same thing as an Azure Managed Disk size or an EBS volume size.

Data sources for the embodied figures:

The first four rows converge on roughly 30 kg per drive across a 40x range of capacities, which is itself the evidence for treating HDD embodied carbon as capacity independent. The Tannu & Nair rate cannot be applied per GB to current hardware: it encodes the drive sizes of a pre-2023 corpus and overstates per-byte embodied carbon by about an order of magnitude. See issue #102 for the full derivation.

Networking¶

Estimates the energy used for networking in and out of data centres. The module distinguishes between three transfer types with separate coefficients, taken from the Boavizta Cloud Emissions Working Group.

In a CUR, the transfer type is read from the transfer_type product attribute of the AWSDataTransfer lines. A FOCUS report carries neither, so the category is derived from the SkuMeter suffixes instead (DataTransfer-Regional-Bytes and DataTransfer-xAZ-*-Bytes → intra, AWS-*-Bytes and CloudFront-*-Bytes → inter, DataTransfer-In/Out-Bytes → external), which map one-to-one to the CUR transfer types.

Configuration — the network_coefficients_kwh_gb map (in kWh/GB):

Serverless¶

Estimates the energy for the memory and vCPU usage of serverless services like Fargate, EMR Serverless or DocumentDB Elastic, which bill compute in vCPU-hours and GB-hours rather than by instance type. The default coefficients are taken from the Tailpipe methodology.

DocumentDB Elastic clusters bill their compute as ElasticCPUUsage in vCPU-hours; the storage and backup lines of the same clusters are covered by Storage instead. AWS does not document the underlying hardware, so the x86 coefficient is applied.

Configuration:

Accelerators¶

Estimates the energy used by accelerators (GPUs), following the approach of the Cloud Carbon Footprint project: the power draw is interpolated between the minimum and maximum wattage of the accelerator at an assumed utilisation rate.

Instance types which expose only a fraction of a physical GPU (e.g. g6f.large, which gets an eighth of an NVIDIA L4) are supported: their share of the GPU is a decimal number and the power draw is scaled accordingly.

Configuration:

Compute — Boavizta¶

Estimates the final energy used for computation (e.g. EC2, OpenSearch, RDS, Amazon MQ, ElastiCache on AWS; virtual machines on Azure), as well as the related embodied emissions and abiotic resource depletion, using the BoaviztAPI.

In a CUR, the instance type is read from product_instance_type; a FOCUS report does not carry it, so it is parsed from the SkuMeter column instead (e.g. EUW2-BoxUsage:t3.xlarge).

Several managed services report their instance shape behind a service-specific prefix, which is removed before the lookup: db. for RDS, mq. for Amazon MQ, cache. for ElastiCache, and the .search suffix for OpenSearch. The two formats do not always agree on this, so both are normalised: product_instance_type already reads m5.large for an Amazon MQ broker, while the matching SkuMeter still reads mq.m5.large.

Amazon MQ is also the one service here that does not bill per instance. A clustered deployment is charged one cluster-hour whatever its size, so a three-node RabbitMQ cluster running for an hour appears as a single unit of USE1-RabbitMQ-3-InstanceUsage:mq.m5.large. The node count is read back from the usage type and applied to both the energy and the embodied impacts; usage types carrying no such marker are treated as a single instance, and Multi-AZ as two.

Each provider has two variants:

• BoaviztAPI queries a running instance of the API (docker run -p 5000:5000 ghcr.io/boavizta/boaviztapi:latest). The address can be set with the address configuration key (default http://localhost:5000).
• BoaviztAPIstatic reads the same information from a static file generated from the API and bundled with SPRUCE. No API instance is needed, which makes it simpler to use — this is the variant enabled in the default configurations.

LLM inference — EcoLogits¶

Estimates the energy consumption and embodied emissions of LLM inference on AWS Bedrock and Azure AI Foundry (initially the Azure OpenAI models), based on static per-model coefficients derived from the EcoLogits project. Like BoaviztAPIstatic, a static data file bundled in the JAR is loaded at initialisation time; the modules then match billing rows to per-model coefficients.

BedrockEcoLogits parses the line_item_usage_type field (format: {REGION}-{ModelKey}-{input|output}-tokens[-batch]) to extract both the model key and the token type, then normalises the token count from pricing_unit (handling real-world values such as 1K tokens or 1M tokens). Only output-token rows are scored — the EcoLogits methodology attributes ~all generation cost to the autoregressive output phase, so input-token rows are skipped.

AzureFoundryTokenEcoLogits does the same for token meters billed under the Azure OpenAI (or newer Foundry Models) category: the model label and token direction are extracted from MeterName (e.g. GPT 5 outpt Glbl 1M Tokens) and the token count is read from Quantity (ConsumedQuantity in FOCUS reports). Both hold the number of tokens consumed: the 1K/1M unit in UnitOfMeasure only describes the pricing block and does not scale the quantity — Microsoft's FOCUS conversion defines ConsumedQuantity = Quantity and ContractedCost = UnitPrice × Quantity / x_PricingBlockSize. Provisioned throughput (PTU), hourly hosting and fine-tuning meters are not token-based and are not covered. The other Foundry model families (Mistral, Cohere, Llama, ...) bill through the same kind of token meters and only need mapping.csv entries verified against real exports — the module initially ships with Azure OpenAI mappings.

Stage 3 — Efficiency and intensity factors¶

The modules in this stage do not estimate energy themselves; they attach the per-region factors that the impact modules in the next stage multiply the energy estimates by.

PWUE¶

Loads both Power Usage Effectiveness (PUE) and Water Usage Effectiveness (WUE) factors from a CSV resource file bundled per provider: aws-pue-wue.csv carries the 2022–2025 figures published by AWS, and azure-pue-wue.csv is sourced from Microsoft's data centre sustainability pages.

These factors are published per year and move noticeably from one year to the next, so they are keyed by region and year rather than applied as a blanket value. The year is that of the line item's usage date, read from whichever of ChargePeriodStart, line_item_usage_start_date, Date or BILLING_PERIOD the report carries.

The lookup logic follows this priority:

1. Exact region match (e.g. us-east-1)
2. Regex pattern match (e.g. eu-.+), i.e. the geography-level average
3. The provider-wide GLOBAL average, where the CSV has one
4. Default configured value (fallback to 1.15 for PUE, null for WUE)

Within a tier the entry for the usage year is used; when that year is not covered — a region AWS started reporting on recently, a WUE only published from 2024 onwards, or a row with no usable date — the closest year available for that region is used instead.

Configuration:

AverageCarbonIntensity¶

Adds average carbon intensity factors derived from Ember's electricity data, distributed under the Creative Commons Attribution Licence (CC-BY-4.0). Values are keyed directly by cloud provider and region (e.g. aws:us-east-1). For regions in countries with sub-national data (currently the US and India), the carbon intensity is taken from the Ember value for the state hosting the data centre; otherwise the country-level Ember value is used.

The data is loaded from ember/ember_co2_intensity.csv, which is generated from cloud_regions.json — see the scripts under scripts/ and the dedicated README for how to refresh it.

Stage 4 — Impacts¶

The modules in this stage combine the energy estimates from stage 2 with the factors from stage 3 to produce the final impact columns.

OperationalEmissions¶

Computes operational emissions from the energy usage, carbon intensity and PUE estimated by the preceding modules:

operational_emissions_co2eq_g =
    operational_energy_kwh × carbon_intensity × power_usage_effectiveness
    × powerSupplyEfficiency × powerTransmissionLosses

It accounts for two additional overheads:

• Power Supply Efficiency: the power lost between the data centre mains electricity and the server (default 1.04).
• Power Transmission Losses: the power lost between the power station and the data centre mains electricity (default 1.08).

Configuration:

Water¶

Estimates the water consumption associated with cloud usage, producing three columns:

• water_cooling_l — the volume of water (in litres) used for data centre cooling. Computed as operational_energy_kwh × power_usage_effectiveness × WUE, where WUE is the ratio of litres of water consumed for cooling per kWh of IT energy, loaded per region by the PWUE module.

• water_electricity_production_l — the volume of water (in litres) consumed during electricity generation to power the data centre. Computed as operational_energy_kwh × power_usage_effectiveness × WCF, where WCF (Water Consumption Factor) represents the litres of water consumed per kWh of electricity generated. The WCF values per electricity grid zone are sourced from the WRI methodology for calculating water use embedded in purchased electricity.

• water_consumption_stress_area_l — the total water consumption (water_cooling_l + water_electricity_production_l) attributed to regions under high or extremely high water stress. This field is only populated when the electricity grid zone for the region has a baseline water stress category of 3 (High) or 4 (Extremely High) in the WRI Aqueduct 4.0 dataset; it is absent otherwise. The Aqueduct data is licensed through Creative Commons and has been extracted and mapped to cloud provider region codes.

Stage 5 — Output normalisation¶

FOCUSColumns¶

Bridges provider-native billing columns to provider-neutral FOCUS (FinOps Open Cost & Usage Specification) columns, so the reporting scripts and dashboard can consume enriched data with the same column names whatever the input format. Only the columns the reporting scripts and dashboard rely on are covered — this is not a full native-to-FOCUS conversion, and values are copied as-is (e.g. ChargeCategory carries the raw line_item_line_item_type / ChargeType vocabulary). Runs last in the pipeline, after region has been set by RegionExtraction.

These modules are only needed for the native formats: a FOCUS report already carries these columns on input, so the FOCUS pipelines do not include them.

For AWS CURs:

For Azure cost details exports (columns that already carry a FOCUS-compatible name in the input, such as BillingCurrency and Tags, pass through unchanged — except that Tags, which EA exports truncate to a JSON fragment without the enclosing braces, is wrapped back into a valid JSON object when the report is loaded):

Supporting data¶

Cloud region metadata¶

SPRUCE ships with cloud_regions.json, a single JSON file listing the AWS, GCP, and Azure cloud regions together with their location (country, metro area, latitude/longitude), service status, and number of availability zones. It is the canonical source for the region-to-location mapping used by the modules and resource files (e.g. AverageCarbonIntensity).

The file is produced in two steps by scripts under scripts/, see scripts/README.md for the full usage details.