Metrics
Configuring Metrics
Complete reference for every section of the metric editor — from aggregation and time windows to notification templates, access control, and everything in between.
Editor layout
The metric editor is a side sheet with six accordion sections that correspond to the setup journey:
Metric name and status
Give your metric a clear, descriptive name — it appears in Slack alerts, the metrics list, and the notification template via {{ metric_name }}.
The status controls whether the metric is actively monitored. You can change it at any time:
| Status | Meaning |
|---|---|
| Draft | Default for new metrics. The metric is not monitored. Use this to configure before going live. |
| Live | Actively monitored on schedule. Alerts fire when thresholds are breached. |
| Paused | Monitoring suspended. Configuration is preserved. Resume when ready. |
| Invalid | The metric definition has a configuration error. Resolve the errors shown in the Summary section before re-enabling. |
Metric types
| Type | Description |
|---|---|
| Business | Form-based. Pick an aggregation function and column — no SQL required. Supports all built-in time window, filter, and segment options. |
| SQL | Write your own SQL. Full flexibility for joins, ratios, and custom logic. You test the query and map result columns to roles. |
Both types support the same schedule, threshold, segment, and notification configuration. The only difference is how the metric value is computed.
Metric builder
Business metrics — aggregation
Pick the aggregation function and the column it operates on. The column picker shows only columns marked as metric columns on the dataset, except for COUNT (any column) and COUNT DISTINCT (any column).
| Function | What it computes |
|---|---|
| COUNT | Number of rows matching the time window and filters |
| COUNT DISTINCT | Number of unique values of the selected column |
| AVG | Average value of the selected column across matching rows |
| SUM | Sum of the selected column across matching rows |
| MIN | Minimum value of the selected column |
| MAX | Maximum value of the selected column |
| MEDIAN | Median value of the selected column |
Formula mode lets you combine multiple aggregations into a single expression — for example, SUM(revenue) / COUNT(orders) for average order value. Enable it in the aggregation section.
Time window
A time window controls which rows Lighthouse reads on each run. Configure three fields:
| Field | Options | Example |
|---|---|---|
| Period column | Any column marked as a datetime column on the dataset | created_at |
| Relation | WITHIN (inclusive end), WITHIN_EXCLUDED (exclusive end), BEFORE | WITHIN |
| Unit | Minutes, Hours, Days, Weeks, Months, Years + a number | Last 1 hour |
Data lag
Data lag adds a deliberate delay before Lighthouse evaluates the metric. Use it when your pipeline has a known ingestion delay — for example, if events take 30 minutes to arrive in your warehouse after they occur.
When enabled, set the lag amount (unit: minutes or hours). On each run, Lighthouse shifts the time window back by the lag amount before querying, so you're always looking at a fully-arrived window.
Filters
Filters add WHERE conditions to the metric query. Only columns marked as filter columns on the dataset appear in the picker. Common patterns:
- —Restrict to a specific status:
status = 'completed' - —Limit to a region:
country IN ('US', 'GB', 'CA') - —Exclude test users:
is_internal != true
SQL metrics
- 1Write your SQL — The query must return at least one numeric column (the metric value). It can also return segment columns for breakdowns.
- 2Test the query — Click Test Query. Lighthouse runs the SQL against your warehouse and infers column names and types from the result.
- 3Map columns — Assign a role to each result column — metric value, segment dimension, or other. Mark one column as the primary metric value.
Schedule
The schedule controls how often Lighthouse runs the metric query. You can configure it using the visual Editor or write a raw Cron expression — toggle between the two at the top of the Schedule section.
Manual schedule types
| Type | Fields | Detail |
|---|---|---|
| Every X Minutes | Frequency (5–59), optional From minute / To minute | Runs every N minutes within each hour. Use From/To to restrict to a window within the hour. |
| Every X Hours | Frequency (1–23), Minute of hour (0–59), optional From hour / To hour | Runs every N hours. Minute of hour sets when within the hour it runs. Use From/To to restrict to business hours. |
| Daily | Hour (0–23) and Minute (0–59) | Runs once per day at the specified time in the metric's timezone. |
Use Cron mode for patterns not covered by the manual editor — for example, running only on weekdays at a specific time, or complex multi-interval schedules.
Days of week
Below the schedule type, a seven-day toggle (Sun – Sat) restricts which calendar days the schedule runs. All seven days are selected by default. Deselect days to skip weekends, for example.
Days are evaluated in the metric's timezone (see below). Cron mode encodes days directly in the cron expression.
Timezone
Every metric has its own timezone. Schedule times and day-of-week evaluation use this timezone. It defaults to your organization's timezone but can be changed per metric. Timezone is required — the metric cannot go live without one.
Round to nearest hour
Available on Business metrics only (not SQL) and only when the schedule type is Hours or Daily (not Minutes). When enabled, Lighthouse rounds metric values to the nearest calendar hour before evaluating thresholds. Useful for hourly KPIs where partial-hour results would create noise.
Upcoming runs preview
A debug card at the bottom of the Schedule section shows the next several scheduled run times in the metric's timezone. Use this to verify your schedule fires when you expect.
General
Description
Optional free-text description of what the metric measures and why it matters. The description is included in default Slack notification templates via {{ metric_description }}. It's not shown as a column in the metrics list, but it appears in the metric editor and in summary tooltips.
AI context
An optional field used by Lighthouse AI assistants — the Metric Assistant and the metric suggestions agent — to generate more relevant suggestions and configuration. Provide any context about this metric that isn't obvious from its definition: what business question it answers, which team owns it, or what counts as a normal vs abnormal value.
Tags
Tags (internally called kpis) are plain text labels for organizing and filtering your metrics. You can assign up to 10 tags per metric. Create new tags inline or pick from existing org-wide tag suggestions.
| Where tags appear | Detail |
|---|---|
| Metrics list — Tags column | Shown as badges. The list can be filtered by one or more tags via the Tags filter. |
| Metrics list — filter | Multi-select filter: shows metrics that have any of the selected tags. |
| API | Included as kpis[] on metric create, update, and search requests. |
| Slack alerts | Tags are not available as notification template variables and are not included in default alert messages. |
Severity
Assign a severity level to the metric. The severity appears in Slack alert messages and in the metrics list. It defaults to S2 for new metrics.
| Level | Typical use |
|---|---|
| S0 | Production incidents — payment failure, complete service outage |
| S1 | Severe business impact — major revenue drop, critical funnel failure |
| S2 | Significant change — the default. Unusual but not necessarily urgent. |
| S3 | Notable variance — worth knowing but not waking anyone up for |
| S4 | Low-priority trend monitoring |
| S5 | Informational — logged for context, no action expected |
Severity is a label only. Lighthouse does not route alerts to different channels or escalation paths based on severity — that logic lives in your Slack configuration.
Access control
Inside an Access Control accordion within General, you configure two independent dimensions: who can view the metric and who can edit it.
| Access level | Who has access |
|---|---|
| Everyone | All org members (default for new metrics) |
| Owner | Only the metric creator and the user assigned as metric owner. Org admins always have full access. |
| Selected people | Specific users you add to the viewer or editor lists |
Set both Who can view and Who can edit independently. For example, you can make a metric visible to everyone but editable only by selected users.
Owner
A single user picked from your org. Defaults to whoever created the metric. The owner is displayed as a column and avatar in the metrics list, and is filterable via the Owners filter.
Ownership is primarily operational: it determines who can edit or delete a metric when they don't have org-wide edit permissions. It does not automatically add the owner as a Slack or email recipient.
Creator
Read-only display in Access Control showing who created the metric. The creator is always locked into viewer and editor lists when access is set to Selected people — they cannot be removed.
Notification
Slack destination
Pick the Slack workspace from the App dropdown (only connected workspaces appear). Then set at least one destination:
| Field | Behavior |
|---|---|
| Send to channel | Posts alerts to a public or private Slack channel. Bot must be invited to private channels. |
| Send to user | Sends a Slack DM to a specific user. |
At least one of channel or user is required before the metric can go live. A warning appears if the selected channel or user no longer exists in Slack.
Notification message template
The notification template controls the body of the Slack message. It's per-metric (not org-wide) and uses Slack markdown. Click Insert a variable to pick from the available template variables.
The default template for a new metric:
Template variables
| Variable | Label | Segment-specific? |
|---|---|---|
| {{ metric_name }} | Metric Name | No |
| {{ metric_description }} | Metric Description | No |
| {{ severity }} | Severity | No |
| {{ execution_time }} | Execution Time | No |
| {{ current_value }} | Current Value | Yes — changes per segment |
| {{ segment_name }} | Segment Name | Yes — the segment combination that fired |
Additional variables are generated dynamically:
- —SQL metrics: one variable per mapped result column, named after the column.
- —Calculated columns: one variable per calculated column, named after the column.
- —Threshold filters: named threshold conditions generate variables like
{{ filter name }},{{ filter name }} - Compared Value,{{ filter name }} - Threshold Value, and (for standard deviation){{ filter name }} - Standard Deviation.
{{ current_value }} and {{ segment_name }}) are hidden in the variable picker for the main aggregated message when aggregated mode is on — use them in the Per Segment Notification Message instead.Aggregated mode
When segments are enabled on the metric, you can toggle Aggregate segments into 1 message. When on, one Slack message is sent per metric run — all breaching segments are listed within that single message using the Per Segment Notification Message template.
When aggregated mode is off (default), each breaching segment sends its own Slack message. For metrics with many segments, aggregated mode reduces noise significantly.
Default per-segment template (rendered once per breaching segment inside the aggregated message):
Email notifications
Toggle Also send to email to send an email alongside the Slack alert. Configure:
| Field | Required | Description |
|---|---|---|
| Email Recipients | Yes (if email on) | Comma-separated email addresses |
| Email Subject | No | Defaults to {{ metric_name }} |
| Email Body | No | Plain text. If left empty, the Slack notification message text is used. |
Trigger configuration
The Trigger Configuration accordion inside the Notification section controls when alerts actually fire and how they behave during sustained threshold breaches.
Allow snoozing (default: on)
This setting controls what happens when a threshold stays breached across multiple consecutive runs:
| Setting | Behavior |
|---|---|
| On (default) | Lighthouse fires an alert on the first run that breaches the threshold, then stays silent for as long as that segment remains in breach. A new alert fires only when the breach clears and then occurs again in a later run. |
| Off | Lighthouse fires an alert on every scheduled run where the threshold is breached. A metric running every hour could send dozens of alerts for a single sustained incident. |
Action execution behavior
| Option | Behavior |
|---|---|
| Always (on first match) | Default. Alert fires the first time the threshold is breached in a run. |
| After consecutive triggers | Alert fires only after N consecutive metric runs all breach the threshold. Filters out short-lived anomalies. |
When After consecutive triggers is selected, set a trigger threshold of N (minimum 1). For example, with N = 3 and an hourly schedule, you'll only get alerted after 3 straight hours of threshold breach — a single bad data point won't fire.
Test notification
The Test button in the editor footer (not inside the Notification accordion) sends a test Slack message using the current form values. The form must be valid before the test runs. Test messages are labeled in Slack so they're distinguishable from real alerts.
Summary
The Summary section is a read-only review panel — not a save step. It surfaces validation errors and shows a human-readable preview of your configuration before you go live.
Metric configuration summary
Runs validation on the metric builder fields. If the configuration is invalid, a red error card lists the specific issues. If it's valid, it shows a sentence-form summary of the metric definition — aggregation, time window, filters, and thresholds in plain language.
Schedule summary
Runs validation on the schedule. If invalid, an error card lists the issues. If valid, displays the schedule in plain language: frequency, days of week, time range, timezone. Badges appear for Snoozing enabled and Rounds to nearest hour when those options are on.
Going live
A metric can be enabled (status → Live) only when all three are complete:
| Requirement | Detail |
|---|---|
| Schedule | A valid schedule with an interval at or above your plan's minimum. |
| Threshold | At least one threshold condition configured in the Metric Builder. |
| Notification destination | At least one Slack channel or DM user in the Notification section. |
Save the metric first if you want to stay in Draft while you configure it. Use Save and Go Live to enable it immediately.
Metrics list
The metrics list at /metrics shows all metrics your account has access to. Filters and table columns are both customizable.
Filters
| Filter | Matches on |
|---|---|
| Search | Metric name or numeric ID |
| Severity | S0–S5 (multi-select) |
| Tags | Metrics that have any of the selected tags |
| Owners | Metrics assigned to any of the selected users |
| Status | Draft / Live / Paused / Invalid (in 'Show more') |
| Data source | Which warehouse connection the metric belongs to (in 'Show more') |
| Data set | Which dataset the metric is built on (in 'Show more') |
| Slack app | Which Slack workspace the metric sends to (in 'Show more') |
| Slack channel | Which Slack channel (in 'Show more') |
| Slack user | Which DM user (in 'Show more') |
Table columns
| Column | Content |
|---|---|
| Type | Business or SQL icon |
| Status | Draft / Live / Paused / Invalid |
| ID | Sequential numeric identifier |
| Name | Metric name (link to editor) |
| Severity | S0–S5 badge |
| Tags | KPI tag badges (up to 10; overflow shows +N) |
| Schedule | Human-readable schedule summary |
| Last Run | Execution status and timestamp of most recent run |
| AI Suggestions | Suggestion run status and quick actions |
| Metric Summary | Info icon → tooltip with the plain-language metric definition |
| Owner | User avatar |
| Next Run | Scheduled time of next execution |
| Last Trigger | When the metric last fired an alert |
Columns are hideable and reorderable via the column settings control in the table header. Description is not available as a column.
Overview page
The /overview page shows active alert states — segments that are currently in breach — not the full metrics catalog. It's the landing page after onboarding and is the fastest way to see what's actively triggered right now.