mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-10-11 15:19:08 +02:00
port mintlify to fumadocs
This commit is contained in:
miloschwartz
@@ -0,0 +1,214 @@
|
||||
---
|
||||
title: "Alert Rules"
|
||||
description: "Subscribe to Pangolin events on sites, resources, and health checks and deliver email, webhooks, or integrations"
|
||||
---
|
||||
|
||||
<Note>
|
||||
Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition).
|
||||
</Note>
|
||||
|
||||
Alert rules let you react to changes in Pangolin: you pick a source (what to watch), a trigger (which change matters), and one or more actions (what to do). For example, when a site moves from online to offline, email your admins and support; when a [health check](/manage/alerting/health-checks) or resource becomes unhealthy, call a webhook so a tool like Zapier can fan out the event.
|
||||
|
||||
## Where to create rules
|
||||
|
||||
Create and manage rules from the Alert rules page under Alerting for your organization.
|
||||
|
||||
You can also start a rule from a site or resource detail page: use Create alert rule near the uptime graph to prefill context and keep the flow short.
|
||||
|
||||
## Actions
|
||||
|
||||
When a trigger fires, Pangolin can:
|
||||
|
||||
- Send email (recipients described below).
|
||||
- Call a webhook with a JSON payload (see [Webhook payloads](#webhook-payloads)).
|
||||
- Open an incident or ticket in PagerDuty, Opsgenie, ServiceNow, or incident.io.
|
||||
|
||||
You can attach several actions to the same rule (for example email plus a webhook).
|
||||
|
||||
### Email
|
||||
|
||||
Choose users in your Pangolin organization, entire roles, and/or arbitrary email addresses that should receive the message when the condition is met.
|
||||
|
||||
### Webhooks
|
||||
|
||||
Webhook actions issue an HTTP request to your endpoint when the trigger runs. Payloads are JSON and follow the shapes in [Webhook payloads](#webhook-payloads).
|
||||
|
||||
## Creating an alert rule
|
||||
|
||||
<Frame caption="Create alert rule: source (e.g. all sites), trigger (e.g. site status changes), and actions (email)">
|
||||
<img src="/images/create-alert-rule.png" alt="Create alert rule wizard in the Pangolin dashboard" />
|
||||
</Frame>
|
||||
|
||||
### 1. Source
|
||||
|
||||
Choose what entity the rule watches:
|
||||
|
||||
| Source type | Meaning |
|
||||
| --- | --- |
|
||||
| Site | One or more [sites](/manage/sites/understanding-sites) |
|
||||
| Resource | One or more resources in the org |
|
||||
| Health check | One or more [health checks](/manage/alerting/health-checks) |
|
||||
|
||||
For each type, decide whether the rule applies to all of that kind (for example all sites) or only specific sites, resources, or health checks you select.
|
||||
|
||||
### 2. Trigger
|
||||
|
||||
Available triggers depend on the source type. For sites, options include coming online, going offline, or any status change. For resources and health checks, you get healthy, unhealthy, and combined toggle-style triggers that match how those entities change state-the dashboard only lists combinations that apply to what you selected.
|
||||
|
||||
Pick the condition that should fire the rule (for example site status changes when you care about both online and offline transitions).
|
||||
|
||||
### 3. Actions
|
||||
|
||||
Configure what happens when the trigger runs: add one or more actions (email, webhook, or a vendor integration). Use Add action to stack multiple destinations for the same rule.
|
||||
|
||||
## Webhook payloads
|
||||
|
||||
Webhook bodies are JSON. Every event includes `event`, ISO-8601 `timestamp`, and a `data` object. The event name tells you what changed; `data` always includes `orgId` and entity-specific fields.
|
||||
|
||||
`{{data}}` is an object and must be treated as such. If you can not support a object, you can also use the flattened fields shown in the examples below. For example `{{orgId}}`, `{{siteId}}`, and `{{siteName}}` are all available on a site alert.
|
||||
|
||||
### Site events
|
||||
|
||||
#### `site_online`
|
||||
|
||||
A site came back online.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "site_online",
|
||||
"timestamp": "2025-06-15T12:34:56.789Z",
|
||||
"data": {
|
||||
"orgId": "org_abc123",
|
||||
"siteId": 42,
|
||||
"siteName": "us-east-prod"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `site_offline`
|
||||
|
||||
A site went offline.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "site_offline",
|
||||
"timestamp": "2025-06-15T12:34:56.789Z",
|
||||
"data": {
|
||||
"orgId": "org_abc123",
|
||||
"siteId": 42,
|
||||
"siteName": "us-east-prod"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `site_toggle`
|
||||
|
||||
Fires when site connectivity changes, alongside both `site_online` and `site_offline`. Use this when you only care that status flipped, not which direction. `siteId` is always present in `data`.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "site_toggle",
|
||||
"timestamp": "2025-06-15T12:34:56.789Z",
|
||||
"data": {
|
||||
"orgId": "org_abc123",
|
||||
"siteId": 42,
|
||||
"siteName": "us-east-prod"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Health check events
|
||||
|
||||
#### `health_check_healthy`
|
||||
|
||||
A health check recovered.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "health_check_healthy",
|
||||
"timestamp": "2025-06-15T12:34:56.789Z",
|
||||
"data": {
|
||||
"orgId": "org_abc123",
|
||||
"healthCheckName": "API /healthz"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `health_check_unhealthy`
|
||||
|
||||
A health check is failing.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "health_check_unhealthy",
|
||||
"timestamp": "2025-06-15T12:34:56.789Z",
|
||||
"data": {
|
||||
"orgId": "org_abc123",
|
||||
"healthCheckName": "API /healthz"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `health_check_toggle`
|
||||
|
||||
Fires alongside healthy and unhealthy transitions. `healthCheckId` is included in `data` for this combined event.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "health_check_toggle",
|
||||
"timestamp": "2025-06-15T12:34:56.789Z",
|
||||
"data": {
|
||||
"orgId": "org_abc123",
|
||||
"healthCheckId": 7,
|
||||
"healthCheckName": "API /healthz"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Resource events
|
||||
|
||||
#### `resource_healthy`
|
||||
|
||||
A resource recovered.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "resource_healthy",
|
||||
"timestamp": "2025-06-15T12:34:56.789Z",
|
||||
"data": {
|
||||
"orgId": "org_abc123",
|
||||
"resourceName": "internal-dashboard"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `resource_unhealthy`
|
||||
|
||||
A resource is unhealthy.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "resource_unhealthy",
|
||||
"timestamp": "2025-06-15T12:34:56.789Z",
|
||||
"data": {
|
||||
"orgId": "org_abc123",
|
||||
"resourceName": "internal-dashboard"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `resource_toggle`
|
||||
|
||||
Fires alongside healthy and unhealthy transitions, or when a resource is enabled or disabled. `resourceId` is included in `data`.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "resource_toggle",
|
||||
"timestamp": "2025-06-15T12:34:56.789Z",
|
||||
"data": {
|
||||
"orgId": "org_abc123",
|
||||
"resourceId": 15,
|
||||
"resourceName": "internal-dashboard"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: "Health Checks"
|
||||
description: "Monitor reachability and response for public resource targets and arbitrary endpoints from your sites"
|
||||
---
|
||||
|
||||
A health check is a periodic probe that decides whether something on your network is up and responding the way you expect. Pangolin runs these checks from your sites so they reflect reachability from the connector’s perspective, not only from wherever an administrator happens to be.
|
||||
|
||||
## Health Checks on Public Resource Targets
|
||||
|
||||
You can attach health checks to individual targets on public resources. When a target fails its health check, Pangolin treats it as unhealthy: it is removed from rotation and load balancing until it passes again, so traffic is not sent to a broken upstream. That behavior is configured per target alongside your proxy settings.
|
||||
|
||||
For step-by-step setup, states (healthy / unhealthy / unknown), and routing implications, see [Health checks & failover](/manage/resources/public/healthchecks-failover).
|
||||
|
||||
## Health Checks in Alerting
|
||||
|
||||
Under Alerting → Health checks for your organization, you get a single view of health checks tied to public resource targets, so you can see status across resources without opening each resource separately.
|
||||
|
||||
<Frame caption="Create health check in the Pangolin dashboard">
|
||||
<img src="/images/create-healthcheck.png" alt="Create health check form in the Pangolin dashboard" />
|
||||
</Frame>
|
||||
|
||||
### Arbitrary Health Checks
|
||||
|
||||
<Note>
|
||||
Arbitrary health checks are only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition). Health checks attached to public resource targets are available in all editions.
|
||||
</Note>
|
||||
|
||||
In addition to target-linked checks, you can create standalone health checks that are not attached to any routable resource target. They work the same way at the probe layer, with the same protocols and timing concepts, but only represent reachability for an address your sites can reach (for example an IP or hostname on a remote LAN). You choose which site runs the check so it stays within an addressable range for that connector.
|
||||
|
||||
These are useful when you care about whether a system is up, even if it is not modeled as a Pangolin resource like a network printer, an IP camera, a legacy server, or anything else that should be watched from the site’s network. Pair them with [Alert rules](/manage/alerting/alert-rules) to send notifications when something goes unhealthy or recovers.
|
||||
|
||||
## Check Types
|
||||
|
||||
There are two kinds of checks: HTTP and TCP.
|
||||
|
||||
### HTTP
|
||||
|
||||
An HTTP health check issues an HTTP or HTTPS request to a URL you specify. You can tune the scheme (`http` or `https`), HTTP method (for example `GET` or `POST`), path, headers, expected status codes, and anything else needed to match how the service exposes a liveness endpoint. Success means the response satisfies your criteria (including status code and optional body rules, depending on configuration).
|
||||
|
||||
### TCP
|
||||
|
||||
A TCP health check does not speak application data: it tries to open a TCP connection to a host and port. If the TCP handshake completes, the check is treated as passing; if nothing answers or the connection is refused or times out, it fails. That is ideal for services that only expose a plain port (databases, cameras, PLCs) or when you only care that the host is reachable on a given port.
|
||||
|
||||
## Timing and Thresholds
|
||||
|
||||
Both HTTP and TCP checks support configuration for how often probes run when things are healthy versus when they are failing, how many successes or failures are required before flipping state, and related tuning (for example healthy interval, unhealthy interval, healthy threshold, unhealthy threshold). Exact field names appear in the dashboard; the intent is to avoid flapping—brief blips should not instantly mark a host down, and recovery should be confirmed before treating it as fully healthy again.
|
||||
|
||||
## How the pieces fit together
|
||||
|
||||
- Target-linked health checks on public resources drive routing: unhealthy targets drop out of the pool until they recover.
|
||||
- Arbitrary checks track reachability for addresses your sites can reach—dashboard visibility and [Alert rules](/manage/alerting/alert-rules)—even when there is no Pangolin resource for that system.
|
||||
Reference in New Issue
Block a user