> For the complete documentation index, see [llms.txt](https://docs.lumi-ai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lumi-ai.com/using-lumi/best-practices/monitoring-and-alerting-best-practices.md).
# Monitoring and Alerting Best Practices
### When to use monitoring and alerts?
Use monitoring and alerts when you want Lumi to proactively track recurring business conditions, such as:
* A metric crosses a business-critical threshold
* A KPI changes more than expected
* A recurring report needs to stay current without manual reruns
* A team needs to know when operational performance changes
* A data quality issue appears in a trusted workflow
* A stakeholder needs a consistent view of important metrics over time
Examples:
| Use case | Business condition to monitor |
| ----------------- | -------------------------------------------------------- |
| Sales performance | Weekly revenue falls below target |
| Operations | On-time shipment rate falls below an acceptable level |
| Support | Open ticket volume exceeds the team’s operating capacity |
| Finance | Gross margin falls below an approved threshold |
| Data quality | A data quality check returns failed results |
### 1. Start with an actionable business question
Before creating an alert, define the business question the alert is meant to monitor.
Why this matters: Alerts are most useful when they tell a user that something requires attention. If the business question is vague, it may be difficult to translate into a clear logical statement.
Less useful business question:
* Are sales changing?
More useful business question:
* Has weekly net revenue for the Northeast region dropped more than 15% compared to the previous 4-week average?
Why the second question is better:
* It identifies the metric: weekly net revenue
* It identifies the segment: Northeast region
* It defines the condition: dropped more than 15%
* It defines the comparison period: previous 4-week average
* It suggests a clear reason for follow-up
Before creating the alert, confirm:
* What metric should be monitored?
* What condition should trigger the alert?
* What comparison value should be used?
* Does the condition require a time period, segment, or filter?
* Who needs to be notified?
* What should the recipient do after the alert fires?
### 2. Translate the question into clear alert logic
Alerts are created by selecting structured conditions from dropdowns. Before configuring an alert, translate the business question into a logical statement that Lumi can evaluate.
A typical alert condition should define:
* The metric or field being monitored
* The operator or condition
* The comparison value
* Any relevant filters, segments, or time periods
* The users who should be notified
| Business intent | Example alert logic |
| -------------------------------------- | ------------------------------------------------ |
| Monitor declining shipment performance | On-time shipment rate is less than 75% |
| Monitor low inventory | Inventory quantity is less than reorder point |
| Monitor support backlog | Open ticket count is greater than target backlog |
| Monitor revenue risk | Weekly revenue is less than target |
| Monitor data quality | Data quality status equals failed |
Use the clearest available dropdown options to express the condition. If the condition you need is more complex than the available alert logic supports, consider creating or validating the underlying metric in Query Builder before adding it to a Board.
### 2. Validate the metric before alerting on it
Use Chat, Query Builder, or an existing Board card to confirm that the metric returns the expected result before configuring an alert.
Why this matters: An alert is only as reliable as the metric behind it. If the query uses the wrong table, filter, join, date range, or aggregation, users may receive misleading alerts.
Validate the following before using a metric for monitoring:
* The correct Knowledge Base is selected
* The metric uses the right source tables
* The date range and time grain are correct
* Filters match the intended business scope
* The result matches known benchmarks or stakeholder expectations
* The metric appears in a format that can be used in the alert condition
* The available dropdown condition accurately represents the business rule
For analyst-owned or high-stakes metrics, use Query Builder to define and test the logic before publishing the result to a Board.
### 3. Use Boards for recurring monitoring, not one-time exploration
Use Chat to explore a question. Use Boards when the insight should be saved, refreshed, shared, or monitored over time.
Why this matters: Alerts need a stable insight to monitor. Boards provide the recurring context for saved metrics, refreshed results, and shared visibility.
Use Chat for:
* Why did revenue drop last week?
* Which customers drove the largest change?
* Show me the top products by margin this month.
Use monitoring and alerts for structured conditions such as:
* Weekly revenue is less than target
* On-time shipment rate is less than 75%
* Open order count is greater than the expected operating range
* Data quality status equals failed
### 4. Choose a refresh cadence that matches the business workflow
Set the refresh cadence based on how often the data changes and how quickly the team can respond.
Why this matters: Refreshing too infrequently can delay action. Refreshing too often can create unnecessary noise, especially when the underlying data does not update as frequently.
| Monitoring scenario | Recommended refresh pattern |
| -------------------------------- | ---------------------------------------------------------- |
| Executive KPI review | Daily, weekly, or aligned to business review cycles |
| Operational exception monitoring | As often as the source data is meaningfully updated |
| Financial or month-end reporting | Aligned to close, reconciliation, or reporting cadence |
| Data quality monitoring | Aligned to data load or pipeline refresh timing |
| Low-volatility metrics | Less frequent refreshes to avoid unnecessary notifications |
If a Board card fails to refresh, review the card and Knowledge Base logic before relying on the alert.
### 6. Set specific conditions that are stable and actionable
Choose alert conditions that clearly indicate when someone should investigate or act.
Why this matters: Conditions that are too broad, too sensitive, or disconnected from business action can create alert fatigue.
Less useful condition design:
* Revenue changed
* Inventory changed
* Orders look unusual
More useful condition design:
* Weekly revenue is less than target
* Inventory quantity is less than reorder point
* Open order count is greater than the expected operating range
* On-time shipment rate is less than 75%
* Data quality status equals failed
When setting conditions, consider:
* Metric: What value should Lumi monitor?
* Operator: What comparison should trigger the alert?
* Value: What threshold or status should be used?
* Time period: What date range or refresh period should apply?
* Segment: Should the rule apply to a specific region, customer group, product, or team?
* Stability: Will normal variation cause too many alerts?
* Actionability: Does the condition clearly imply follow-up?
### 6. Send alerts to the right owners
Choose recipients based on who can investigate or respond to the alert.
Why this matters: Alerts are less effective when they are sent to too many people, sent to the wrong team, or sent without a clear owner.
Before adding recipients, confirm:
* Who owns the metric?
* Who can investigate the root cause?
* Who needs to be informed but does not need to act?
* Should the alert go to an individual, a team, or a shared workflow?
* What should the recipient do after receiving the alert?
Example:
If an on-time shipment alert fires, the Operations team may need to investigate immediately, while leadership may only need to review the trend during a weekly business review.
### 8. Provide enough context for investigation
Make sure the Board card, title, description, visualization, and surrounding Board context help users understand what the alert means.
Why this matters: Because alert conditions are configured as structured logical statements, the surrounding Board context is important. When an alert fires, users should be able to quickly understand what changed, why it matters, and where to investigate next.
To make alerts easier to investigate:
* Use clear Board card titles
* Include the metric, segment, and time period in the card title or description
* Choose a visualization that makes the monitored value easy to interpret
* Group related metrics together on the same Board
* Keep the Board focused on a clear business workflow
* Use Chat or Query Builder to investigate the underlying drivers
### 9. Review and maintain alerts over time
Review alerts regularly to make sure they still reflect current business priorities, trusted data logic, and the right ownership model.
Why this matters: Business definitions, Knowledge Base logic, source data, Board cards, and team responsibilities can change. Alerts that are not maintained can become noisy, stale, or misleading.
Review alerts when:
* A Knowledge Base is updated
* Source tables, joins, or business definitions change
* A Board card fails to refresh
* The monitored metric is renamed, removed, or redefined
* The selected alert condition no longer reflects the intended business rule
* The monitored metric is no longer a priority
* Alert recipients or ownership changes
* Users report that an alert is too noisy or not useful
> Debugging
>
> If an alert does not behave as expected, first check whether the Board card refreshed successfully. Then confirm that the selected metric, dropdown condition, comparison value, and recipients still match the intended business rule.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.lumi-ai.com/using-lumi/best-practices/monitoring-and-alerting-best-practices.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.