AcademyProduct Documentation
Academy

Dimension & CostFormation Overview

Suggest Edits


Dimensions are a critical and technical topic in your CloudZero learning journey. Be sure to watch all the videos, review the material posted below the videos on Dimension Introduction, Group, GroupBy, and Common Patterns in this module thoroughly. To solidify your understanding, we highly recommend completing the exercises in the Group and GroupBy sections. These exercises will help reinforce the concepts covered.


Prerequisites

Before starting the Dimension learning path, ensure you meet the following requirements:

  1. Familiarity with Conditional Logic:
    You should understand conditional logic, which might come from experience with:
    1. Spreadsheet formulas and logic
    2. Programming languages
    3. Querying databases
    4. General data analysis
  2. CloudZero Organizer Role:
    Only users with the organizer role in CloudZero can authenticate and edit Dimensions.
  3. Development Environment Setup:
    You have installed Visual Studio Code (VSCode) and the CloudZero extension from the marketplace by following instructions here

Introduction

CloudZero Dimensions are a powerful tool for analyzing and understanding the costs of running cloud software in ways that directly align with your business objectives. They provide a flexible framework for categorizing cloud infrastructure using key characteristics, such as accounts, services, or tags, enabling you to create meaningful cost groupings tailored to your organization’s needs.

Think of Dimensions as a meta-tagging layer that consolidates and organizes the diverse metadata associated with your cloud resources. By leveraging this meta-tagging system, you can extract deeper insights into cost drivers, allocate expenses to the appropriate teams or projects, and make more informed decisions about optimizing cloud spend.

Dimensions go beyond basic tagging by allowing you to define custom categorizations that reflect your business structure or goals. Whether you need to understand the cost of specific products, track expenses by department, or analyze usage across environments (e.g., development, staging, production), Dimensions provide the framework to do so efficiently and accurately.

Understanding how spend across dozens, hundreds, or thousands of accounts and dozens of services aggregates to represent your business contexts is a fundamental prerequisite to operating a smart SaaS business built in the Cloud. Getting to a good set of Dimensions will serve as a common language across the business and will enable many high-value outcomes:

  • “Shift Left” - Empowering engineering teams with cost intelligence notifications and a mechanism to quickly understand their resource's spend. The Dimensions you configure in CloudZero will serve as a way to define subsets of infrastructure that anomalies and notifications can be run against.
  • Unit Cost - Unit cost is a generic term that can refer to a lot of different desired outcomes: cost per customer, cost per product, cost per 1,000 messages, cost per event, etc. The Dimensions you configure in CloudZero will serve as a way to associate your business' demand drivers to a business context.
  • Reporting - Most finance teams/organizations have logic they use to understand their AWS spend. This can range from simple to complex. Configuring Dimensions within CloudZero is how you’ll simplify you’re reporting processes and gain a shared understanding of cloud cost across the organization.

Dimension & CostFormation Overview

Terminology

  • Dimension - CloudZero context that implements business logic
  • Element - Each value within a Dimension. This is what is created by the logic of the Dimension.

Example
Customer ← Dimension

  • CloudZero ← Element
  • Acme ← Element
  • PiedPiper ← Element

CostFormation Syntax

CostFormation is a proprietary CloudZero language built on top of YAML. There are 2 different styles of syntax you’ll find in our documentation: short form and long form. Short form is more concise, but only allows you to do the most basic mapping. In many cases you’ll want to do more complicated things so this documentation will focus on long form notation.

The YAML syntax is always the same for CloudZero dimension definitions and it’s important to understand the structure and spacing:

  DimensionID:
    Name: Dimension Name
    Rules:
      - Type: Group
        Name: CloudZero Resources
        Conditions:
          - Source: Tag:Name
            Transforms:
              - Type: Lower
            Contains: cloudzero
  • Line 1 - This is the DimensionID. It needs to be unique across all dimensions and is the way you’ll reference this dimension in another dimension configuration if necessary.
  • Line 2 - This is the friendly Name for the dimension. This is what will be listed in the Explorer UI
  • Line 4 - This is the start of the various rules / logic you want to configure for the dimension. Each Type: Group represents a new “block” of logic to create one “element”. Always remember that YAML files are processed sequentially, from the top down.
    • NOTE - There are a number of different types of rules each with their own syntax. Group is the most basic and probably most widely used type. Each rule type will be described in the CostFormation Rules section below.
  • Line 5 - This is the friendly Name for the dimension element you’re about to configure logic for. This name differs from the name on line 2 in that line 2 specifies the friendly name for the whole dimension, while this name is the friendly name for this particular element within the dimension.
  • Line 7 - These are the Source(s) that the logic will match against. There can be one or more of these. If there are multiple sources listed, the logic will be evaluated against each source and the results will be OR’d together. See here for a full list of the possible sources.
  • Line 8 - Transforms are a way to affect the source values before they’re evaluated against your matching criteria (see line 12). Since some of the metadata sources (see line 7) are based on user input, the values can’t be controlled (casing, spacing, etc). This needs to be considered when building your dimension element logic. See here for a full list of the possible transforms.
  • Line 10 - Specifies the operator and the logic for the condition. See here for a full list of the possible conditional operators. I’d actually recommend you NOT look at that section yet though because it will likely confuse you until you’ve gone through a number of examples.

📘

Each billing line item will be evaluated against the logic in your CostFormation YAML, starting from the top and processing sequentially to the bottom. The first block where the logic evaluates to TRUE, that billing line item will get the corresponding element name. A Dimension is then an aggregation of all the billing line items that have been assigned the various element names based on the CostFormation logic in the YAML.

CostFormation Logic
CostFormation is the language CloudZero developed to help describe the logic you want to define the elements of a dimension. The full documentation can be found here. You should think of this logic like a SQL CASE statement or an IF/THEN/ELSE statement. Every line item in the cost-and-usage data is processed against the CostFormation for a dimension (sequentially). Once a line item matches a conditional statement, it’s associated to whatever element the condition describes. Any given line item can only be associated to a single Dimension element.

Lineitem_Type:
    Name: Lineitem Type
    DefaultValue: Other
    Rules:
      - Type: Group
        Name: Support
        Conditions:
          - Source: Service
            Equals: OCBPremiumSupport
      - Type: Group
        Name: EdpRefund
        Conditions:
          - And:
            - Source: LineItemType
              Equals: Refund
            - Source: Description
              Equals: Enterprise Program Discount
      - Type: Group
        Name: Credit
        Conditions:
          - And:
            - Source: LineItemType
              Equals: Refund
            - Source: Description
              Transforms:
                - Type: Lower
              Contains: credit

The above does not represent CostFormation training, it merely serves as an example of logic equivalency. So what logic does the CostFormation above implement?

IF Source:Service = “OCBPremiumSupport” THEN “Support”
ELSEIF (Source:LineItemType = “Refund” AND Source:Description = “Enterprise Program Discount”) THEN “EdpRefund”
ELSEIF (Source:LineItemType = “Refund” AND Lower(Source:Description) = “credit” THEN “Credit”
ELSE “Other”
END

The above represents a basic example of a dimension remapping. There are numerous use cases for this alone, but the real power comes all the types of rules and sources and how you can use them all in combination.

CostFormation Sources
As people begin to create Dimensions, one of the first questions they have is, “What are all the different sources I can use to create Dimensions?” The basic answer is, any of the Dimensions you can use in the Explorer filters / group by:


Review the full list of Dimension sources here.

Here are the few Sources that are tricky and cause confusion:

Source: Service - The values in this source are actually the service codes, not the service values you see in the UI. You can either find the service code by filtering to a service and looking in the URL or you can use the CZ:Defined:ServiceDisplay source which aligns with the display values you see in the UI.

Source: CZ:Defined:ResourceSummaryID - The values in this source are actually the resource CZRNs, not the resource summary values you see in the UI. You almost always want to source CZ:Defined:ResourceSummaryDisplay when trying to match against resources. The values in CZ:Defined:ResourceSummaryDisplay will align with the values you see in the UI.

Source: Resource - The values in this source are actually the resource CZRNs, not the resource values you see in the UI. If you must use Resource as a source, you almost always want to source CZ:Defined:ResourceDisplay which aligns with the resource values you see in the UI.

If you need to match against resources, you should always try to use Resource Summary (CZ:Defined:ResourceSummaryDisplay) as a source instead of Resource (CZ:Defined:ResourceDisplay). As soon as you use Resource as a source, you run the risk of causing performance challenges in the Explorer. The main difference between Resource Summary and Resource is that Resource Summary does not have instance IDs. In our experience, in 95+% of Dimension use cases you do not need to match against instance IDs.

Updated 30 days ago

What’s Next