Custom Metrics

Custom metrics let you publish reusable calculations (SQL/DSAL) that any dashboard, alert, or workflow action can reference without duplicating logic. Definitions live alongside the rest of your .kiket/analytics assets and are synced via the configuration loader.

File Locations

Location	Source
.kiket/analytics/metrics/*.yml	Project repositories connected via Workflow Repositories
.kiket/metrics/*.yml	Legacy root support (converted on sync)
Marketplace bundles	extensions/<name>/.kiket/analytics/metrics/*.yml

Loader precedence matches other analytics assets: extensions & templates can ship defaults, but project repositories win when IDs overlap.

Schema

Each metric file can declare one or more entries:

Key	Type	Required	Notes
id	string	✅	Unique slug (e.g. cycle_time, capacity_load)
model_version	string	✅	Currently 1.0
name	string	✅	Human label surfaced in UI/CLI
description	string	➖	Markdown description used in tooltips
source	string	✅	Underlying query (dsal:<id> or sql:<statement>). DSAL references must point to a query defined in .kiket/analytics/queries.
format	string	➖	number, percentage, currency, duration
unit	string	➖	Free-form label (e.g. points, hours)
tags	array	➖	Used for catalog filtering (e.g. flow, sla)
parameters	array	➖	Mirrors query parameter definitions—declare name, type, required, and optional default.
access	object	➖	Scope controls (roles, projects, environments) so sensitive metrics stay private.

Example:

metrics:
  - id: flow.cycle_time
    model_version: "1.0"
    name: Average Cycle Time
    description: Tracks median days between `in_progress` and `done`.
    source: dsal:flow_cycle_time
    format: duration
    unit: days
    tags: [flow, sla]
    parameters:
      - name: project_id
        type: integer
        required: true

Surfacing Metrics

• Dashboards & Alerts – Widgets reference metric: <id> inside their config; the runtime injects the backing query automatically so designers only set parameter bindings.
• Command Palette – Metrics tagged with palette automatically appear in the analytics palette action for quick checks.
• API/CLI – /api/v1/projects/:id/metrics lists catalog entries. kiket analytics metrics list <project> renders the same metadata and supports --tag / --format filters.

Permissions

access.roles accepts organization/project role keys (e.g. admin, manager). When omitted, metrics inherit the dashboard’s ACL. Use access.projects for cross-project templates so only opted-in teams see sensitive KPIs.

Validation

• Run kiket analytics lint or trigger a workflow sync; metrics with missing queries or duplicate IDs are skipped and surfaced in the diagnostics feed.
• The loader stores successful entries under project.settings["metrics"], which the admin UI and CLI read to display catalogs.

Best Practices

• Prefer DSAL queries when possible so the loader can validate structure and parameters.
• Keep names/action labels short (≤40 characters); longer descriptions belong in description.
• Tag metrics consistently (flow, sla, capacity, finance) so catalogs remain searchable.
• Version control metrics alongside dashboards to keep dependencies obvious in code review.