Declarative KPI Definitions: Using YAML to Version-Control Your Business Logic

In today's data-driven landscape, Key Performance Indicators (KPIs) are the lifeblood of any successful organization. They are the numbers that tell you if you're winning or losing. Yet, how many of us are still managing these critical metrics in fragile spreadsheets, scattered documents, or siloed BI dashboards? Definitions change, formulas break, and the "single source of truth" becomes a myth.

There's a better way. By adopting a "Metrics as Code" philosophy, you can bring the same rigor, collaboration, and automation to your business logic that elite engineering teams apply to their software.

This post will explore how to use simple, declarative YAML files to define your KPIs, version-control them with Git, and automate them completely. Let's turn your business logic into a robust, measurable service.

The Chaos of Traditional KPI Management

Before diving into the solution, let's acknowledge the common pain points that plague traditional performance tracking:

• The "Spreadsheet of Doom": A single, complex Excel or Google Sheet holds all the critical formulas. It's difficult to track changes, impossible to version, and one accidental ctrl+v can bring your reporting to a halt.
• Inconsistent Definitions: Does "Monthly Active User" mean someone who logged in, or someone who performed a key action? The Sales team might have one definition, while Product has another. This ambiguity leads to confusion and mistrust in the data.
• Manual, Toil-Filled Reporting: Every week or month, someone spends hours pulling data from multiple sources, plugging it into a spreadsheet, and generating charts to paste into a slide deck. It's a time-consuming, error-prone process.
• Lack of Auditability: When a number suddenly looks wrong, how do you debug it? Who changed the calculation, and when? Without a version history, it's a forensic nightmare.

These problems all stem from treating business logic as a disposable artifact rather than what it is: a core, mission-critical piece of code.

The "Metrics as Code" Solution: Declarative KPIs with YAML

The "Metrics as Code" approach solves these problems by treating your KPI definitions as you would any other codebase. And the perfect language for this declarative definition is YAML.

What does declarative mean? It means you describe what you want to track, not how to calculate it step-by-step. You define the metric's name, its data source, its goal, and what to do when things go right or wrong. The underlying platform—like KPIs.do—handles the "how."

YAML is the ideal choice for this because it's:

1. Human-Readable: It's clean and easy for non-technical stakeholders (like product managers or marketing leads) to understand and even edit.
2. Version-Controllable: YAML files are plain text, making them a perfect fit for Git. You can now submit a pull request to introduce a new KPI or change a target.
3. Structured: It naturally maps to the structured data needed to define a complex metric with its various properties.

Example: Defining 'Customer Churn Rate' in YAML

Imagine you want to track customer churn. Instead of building a formula in a spreadsheet, you could create a file named customer-churn-rate.yml and store it in your team's Git repository.

# kpis/customer-churn-rate.yml

kpi:
  name: "customer-churn-rate"
  description: "The percentage of customers who canceled their subscription within a given month."
  owner: "team-growth"

# How to get the raw numbers
dataSource:
  type: "sql"
  connectionId: "prod-data-warehouse"
  query: |
    SELECT
      COUNT(DISTINCT CASE WHEN status = 'canceled' THEN user_id END) AS churned_users,
      COUNT(DISTINCT user_id) AS total_users_start_of_month
    FROM subscriptions
    WHERE month = CURRENT_MONTH();

# How to calculate the final KPI value
calculation:
  formula: "(churned_users / total_users_start_of_month) * 100"
  unit: "%"
  frequency: "daily" # Run this calculation every day

# Define what good and bad look like
thresholds:
  - level: "critical"
    condition: "value > 5.0"
    message: "Monthly churn has exceeded the critical threshold of 5%!"
  - level: "warning"
    condition: "value > 3.5"
    message: "Churn is trending high at {{value}}%."

# What to do when a threshold is crossed
actions:
  - on: "critical"
    type: "slack"
    channel: "#alerts-growth"
  - on: "warning"
    type: "pagerduty"
    serviceId: "growth-kpi-warnings"

Breaking Down the Definition

• Metadata (kpi): The name, description, and owner establish a clear, unambiguous identity for the metric. This is your single source of truth.
• Data Source (dataSource): This block declaratively points to where the data lives. Here, it’s a SQL query against a production data warehouse. Other sources could be APIs or data streams.
• Calculation (calculation): This defines the business logic. It takes the raw data from the dataSource and runs a formula. It also sets the frequency of the check.
• Thresholds & Actions (thresholds, actions): This is where automation comes alive. You're not just tracking a number; you're creating a responsive system. When the churn rate goes above 5%, a "critical" alert is automatically sent to the #alerts-growth Slack channel.

The Transformative Benefits of This Approach

When you manage your KPIs in version-controlled YAML files, you unlock a new level of operational excellence.

1. A Single Source of Truth: Your Git repository becomes the undeniable source of truth for all business logic. New team members can onboard faster, and cross-functional teams can align on a single, clear definition.
2. Collaboration via Pull Requests: Want to adjust the churn threshold from 5% to 4.5%? Open a pull request. Your team can review the change, discuss its impact, and approve it, creating a full audit trail.
3. Full Automation: Once a KPI definition is merged into the main branch, a platform like KPIs.do automatically deploys it. It runs the query, performs the calculation, and watches the thresholds on the defined schedule. Manual reporting becomes a thing of the past.
4. Performance as a Service: Your metrics are no longer just numbers on a dashboard; they are living, breathing services. You can interact with them via an API, just like any other microservice. For example, you can use the KPIs.do API to feed a metric's current status directly into a CI/CD pipeline to halt a risky deployment.

// Check a KPI's status before deploying
const churn = await kpis.get({ name: 'customer-churn-rate' });

if (churn.status === 'critical') {
  console.error('Deployment blocked: Customer Churn is critical!');
  process.exit(1);
}

How KPIs.do Brings Your YAML to Life

Defining KPIs in YAML is the blueprint. KPIs.do is the engine that builds, runs, and maintains the house.

Our agentic workflow platform is designed to be the execution layer for your "Metrics as Code" strategy.

• Connect: Securely connect to your data sources, from SQL databases to data warehouses like Snowflake.
• Define: Point KPIs.do at your Git repository. Our platform parses your YAML definitions.
• Automate: We handle the scheduling, execution, and calculation logic, turning your declarative files into automated performance tracking.
• Act: Our system evaluates thresholds and triggers actions, integrating seamlessly with Slack, PagerDuty, webhooks, and more.

By combining declarative YAML definitions with our powerful API, you create a complete, closed-loop system for continuous performance improvement.

Stop Reporting, Start Automating

It’s time to move beyond fragile spreadsheets and manual reporting. By treating your Key Performance Indicators as code, you bring clarity, accountability, and powerful automation to the core logic of your business.

Ready to bring version control to your business logic? Explore KPIs.do and transform your performance tracking from a manual chore into an automated, reliable service.