# Insights

> Falak Insights groups exceptions into issues, flags slow routes, jobs and queries with thresholds, and detects scheduled tasks that did not run.

Source: https://falak.sh/docs/observability/insights/

**Insights** is Falak's application-level view: which exceptions happen, which routes, jobs and queries are slow, and which scheduled tasks did not run. It is fed by the [APM packages](/docs/observability/apm-laravel/) and by cron heartbeats from the agent.

## Issues

An **issue** groups occurrences of the same problem.

| Kind | Created when |
|---|---|
| `exception` | An exception is reported; grouped by its normalized type and top 3 in-app stack frames |
| `performance` | A [threshold](#thresholds) is breached |
| `heartbeat` | A scheduled task misses its run |

Each issue has a **status** (`open`, `resolved`, `ignored`), a **priority** (`none`, `low`, `medium`, `high`, `urgent`), an assignee, comments, a timeline of occurrences and the affected users.

![An issue's detail page: exception type and message, stack trace, occurrence timeline, affected users, status, priority and assignee.](./_images/observability-issues-issue.png)

1. Open **Observability → Issues** (or the site's **Observability** tab).
2. Filter by status and kind.
3. Open an issue to see the stack trace, the request or job, and the timeline.
4. Resolve, ignore, assign, set priority or comment (`insights.manage`).

A resolved issue that happens again **regresses** and reopens.

Stored sizes: message up to 4 KiB, stack trace up to 16 KiB.

## Thresholds

Thresholds turn slowness into issues. Configure them per site (service panel → **Observability**, or **Observability → Issues** settings):

| Field | Allowed values |
|---|---|
| Event type | Routes (`request`), Jobs (`job`), Queries (`query`), Commands (`command`), Scheduled tasks (`scheduled_task`), Outgoing requests (`outgoing_request`) |
| Name pattern | Optional; which routes/jobs/queries it applies to |
| Metric | `p95` or `max` |
| Threshold | Milliseconds (1 – 86 400 000) |
| Window | Minutes (1–1440) |
| Minimum count | Ignore windows with fewer events |

At most 25 distinct names may breach one threshold per evaluation.

## Heartbeats

Every scheduled job with **Heartbeat** on — including the Laravel scheduler — reports each run. Falak knows each job's schedule, so a run that does not arrive within the grace period (120 s by default, `FALAK_INSIGHTS_HEARTBEAT_GRACE`, adjustable per monitor 0–86400 s) is **missed**: it opens a `heartbeat` issue and fires `insights.heartbeat_missed` (critical).

![Observability → Heartbeats: scheduled tasks with their recent runs as green and red slots.](./_images/observability-heartbeats.png)

Monitors are created automatically when schedules are applied, so a job that never runs is detected too. Removed jobs stop being expected.

## Alerts from Insights

| Alert type | Severity |
|---|---|
| `insights.issue_opened` | warning |
| `insights.issue_regressed` | warning |
| `insights.issue_resolved` | info |
| `insights.threshold_breached` | warning |
| `insights.heartbeat_missed` | critical |

Route them in [Alerts](/docs/observability/alerts/).

## Retention

Occurrences, per-minute aggregates and heartbeat runs are kept for 30 days (`FALAK_INSIGHTS_RETENTION_DAYS`). Issues and their counters are kept.

## Next steps