How to Build a Dimension

A Dimension is a category you define that assigns every cost to a value (called an element). You choose both the Dimension and its elements. For example, you can create an Environment Dimension with elements like Production, Staging, and Development, or a Team Dimension with elements like Platform, Data Engineering, and Mobile. You define the categories that matter to your business.

This page walks through the process of building a Dimension, from choosing what to organize through publishing and iterating. For an introduction to what Dimensions are and your options for creating them, see Overview of Cost Organization with Dimensions.

Overview

1. Choose what to organize
2. Write rules to assign costs
3. Publish and iterate
4. Split shared costs
5. Organize at scale with namespaces

Step 1: Choose what to organize

Most organizations start with a few Dimensions that categorize costs by the attributes that matter most to their stakeholders:

Step 2: Write rules to assign costs

Every Dimension is powered by rules. A rule assigns costs to an element by checking a source against a condition.

• A source is a data attribute from your cost data: an account name, a resource tag, a service, a region, a Kubernetes namespace, or any other metadata CloudZero has ingested. You can also reference other Dimensions you have already created as a source using the User:Defined:<DimensionID> syntax (where the Dimension ID is the key you set when creating the Dimension, for example User:Defined:Environment), so you can build on existing logic rather than repeating it. For the full list of available sources, see the CostFormation Reference.
• A condition is a comparison applied to the source value: equals, contains, begins with, matches a regex, and others. If the condition is true, the cost is assigned to that rule's element.

For example, in an Environment Dimension you have a Group rule that looks for any spend with an Environment tag that contains prd. The Dimension flattens values like prd, prd-us, and prd-eu into a single Production element.

CloudZero evaluates rules from top to bottom, assigning each cost to the first rule it matches, so order matters. Using the same example, if you add a second Group rule for a Non-Production element that looks for tags containing non-prd and place that rule below the Production rule, the Production rule's contains prd matches non-prd first. Placing the Non-Production rule above the Production rule ensures each value lands in the right element.

Costs that do not match any rule appear under an element called Not In Dimension. You can set a default value to assign unmatched costs to a specific element instead, either a new one (like Other) or one already defined in the Dimension.

Rule types

• Group rules let you name elements explicitly and define the conditions that match costs to them. Use these when you want business-friendly names like Production or Finance Team.
• GroupBy rules create elements automatically from source values. Use these when elements should reflect your data dynamically, like one element per account or per service.
• Metadata rules match substrings within source values and create elements from the matched content. Use these when resource names or tags contain embedded identifiers you want to extract.

Most Dimensions combine Group and GroupBy: Group rules at the top to normalize and name the elements you care about, with a GroupBy rule below to catch everything else. To create your first Dimension, see Create a Grouping Dimension. For detailed rule configuration, see Allocate through YAML with CostFormation or the CostFormation Reference.

Step 3: Publish and iterate

Dimension changes are retroactive, applied across your full cost history, and begin processing within a few minutes. You do not need to define everything upfront. A common approach:

1. Start with a GroupBy rule on a tag or source to see what values exist in your data.
2. Publish and open the Dimension in the Explorer. Sort by total cost to see which elements matter most.
3. Starting with the most expensive, add Group rules above the GroupBy to normalize anything that needs it. For example, if you see custservice, cs, and Customer Service as separate elements, create a Group rule named Customer Service that matches all three values. The GroupBy below catches any remaining values automatically.
4. Repeat until the high-cost elements are clean.

This works in both Dimension Studio and CostFormation YAML. For ready-to-use YAML patterns, see CostFormation Templates.

Step 4: Split shared costs

Some costs cannot be categorized from metadata alone. A shared database serves multiple teams, but the bill shows a single line item with no attribute that tells you how much each team consumed.

For these costs, CloudZero provides allocation methods that split a single cost across multiple elements:

• Even splits costs equally.
• Proportional splits costs based on each element's share of other known spend.
• Telemetry splits costs based on usage data you send to CloudZero, like API call counts or storage consumption per customer.

See Splitting Shared Costs for details on each method, or go directly to Create an Allocation Dimension to set one up.

Step 5: Organize at scale with namespaces

As your Dimension definitions grow, namespaces let you separate them by team or project with independent version history and access control. To control who can view or edit definitions within a namespace, see Namespace Access Control.