Metrics Registry

Define, manage, and share consistent metric definitions across your organization using the Lucaro Metrics Registry.

Why Use a Metrics Registry?

The Metrics Registry solves the "multiple sources of truth" problem that plagues many organizations:

Without a Registry

Different teams calculate revenue differently
Dashboard metrics don't match reports
No one knows which definition is correct
Hours spent reconciling numbers

With a Registry

Single source of truth for all metrics
Consistent calculations everywhere
Clear ownership and documentation
Version history and audit trail

Defining Metrics

Metrics are defined in YAML format with the following structure:

# metrics.yaml
metrics:
  - name: monthly_revenue
    label: "Monthly Revenue"
    description: "Total revenue for the calendar month"
    expression: "SUM(amount)"
    grain: order_id
    format: currency
    tags:
      - finance
      - kpi
    dimensions:
      - region
      - product_category

  - name: active_users
    label: "Active Users"
    description: "Users with at least one session in the period"
    expression: "COUNT(DISTINCT user_id)"
    grain: session_id
    format: count
    tags:
      - product
      - engagement

  - name: conversion_rate
    label: "Conversion Rate"
    description: "Percentage of visitors who completed a purchase"
    expression: "COUNT(DISTINCT CASE WHEN purchased THEN user_id END) * 100.0 / COUNT(DISTINCT user_id)"
    grain: user_id
    format: percentage
    tags:
      - marketing
      - funnel

Metric Properties

Property	Required	Description
name	Yes	Unique identifier (snake_case)
label	Yes	Human-readable display name
description	Yes	Detailed description of what the metric measures
expression	Yes	SQL aggregation expression
grain	No	The level of aggregation (e.g., order_id, user_id)
format	No	Display format: currency, percentage, count, duration
tags	No	Tags for categorization and search
dimensions	No	Allowed dimensions for slicing the metric

Dimensions

Dimensions allow metrics to be sliced and filtered. Define them separately:

dimensions:
  - name: region
    label: "Region"
    type: string
    table: orders
    column: region

  - name: product_category
    label: "Product Category"
    type: string
    table: products
    column: category

  - name: order_date
    label: "Order Date"
    type: date
    table: orders
    column: created_at

Uploading Your Registry

Upload your metrics registry via the UI or API:

Via API

curl -X POST "https://api.lucaro.dev/v2/projects/{projectId}/metrics/registry" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/yaml" \
  --data-binary @metrics.yaml

Via UI

Navigate to your project and select Metrics Registry
Click Upload Registry or drag and drop your YAML file
Review the validation results and fix any errors
Click Save to publish the registry

Using Metrics in Dashboards

Once defined, metrics appear in the dashboard builder:

Select metrics from the Metrics panel when adding visualizations
Choose allowed dimensions for grouping and filtering
The SQL is generated automatically based on your definitions
Format hints ensure consistent number formatting

Validation

Lucaro validates your metrics registry before saving:

curl -X POST "https://api.lucaro.dev/v2/projects/{projectId}/metrics/registry/validate" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/yaml" \
  --data-binary @metrics.yaml

# Response
{
  "valid": true,
  "metrics_count": 15,
  "dimensions_count": 8,
  "warnings": [
    "Metric 'legacy_revenue' has no tags defined"
  ]
}