> For the complete documentation index, see [llms.txt](https://docs.vergeos-demo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vergeos-demo.com/learn-the-platform/module-9-monitoring-and-troubleshooting/02-alerts.md).

# Subscriptions & Alerts

## Proactive Monitoring with Subscriptions

Dashboards and logs are reactive -- you see problems when you look. **Subscriptions** make VergeOS monitoring proactive by delivering email notifications when conditions change or on a regular schedule. Every VergeOS environment should have a core set of subscriptions configured from day one so that administrators learn about issues before end users do.

Subscriptions require a working **SMTP configuration** (covered later on this page). Once SMTP is in place, any dashboard, tier, network, VM, tenant, or other VergeOS object can have one or more subscriptions attached to it.

```mermaid
graph LR
    subgraph triggers["Subscription Engine"]
        direction TB
        OD["On-Demand<br/>(Event / Threshold)"]
        SC["Scheduled<br/>(Timed Reports)"]
    end

    subgraph delivery["Delivery"]
        SMTP["SMTP Server"]
        QUEUE["Mail Queue"]
        INBOX["Admin Inbox"]
    end

    OD -->|threshold crossed| SMTP
    SC -->|interval elapsed| SMTP
    SMTP --> QUEUE --> INBOX

    style triggers fill:#f0f4ff,stroke:#336
    style delivery fill:#f0fff4,stroke:#363
```

## Subscription Types

VergeOS provides two complementary subscription types. An effectively monitored environment uses **both** types together -- on-demand subscriptions for immediate issue awareness, and scheduled subscriptions for trend tracking and daily oversight.

### On-Demand Subscriptions

On-demand subscriptions are **event-driven or threshold-triggered** alerts. They fire as soon as a condition is met, ensuring administrators are notified of potential issues in near real-time.

Common triggers for on-demand subscriptions include:

| Trigger Category      | Example                                                        |
| --------------------- | -------------------------------------------------------------- |
| **Storage threshold** | vSAN tier reaches a specified percentage of capacity used      |
| **Update available**  | New VergeOS update packages are ready to install               |
| **Errors / Warnings** | Any error or warning event is logged on a monitored object     |
| **Status changes**    | A node goes offline, a VM stops unexpectedly, a network faults |

On-demand subscriptions are the first line of defense -- they tell you something needs attention **right now**.

### Scheduled Subscriptions

Scheduled subscriptions deliver **dashboard or listing information at configured time intervals**. They are designed to provide regular summaries of system health and assist administrators with everyday supervision and trend tracking.

Examples of scheduled subscriptions:

* **System dashboard** sent daily at 7:00 AM -- gives the team a morning health snapshot
* **vSAN tier dashboard** sent weekly -- tracks capacity growth trends over time
* **VM listing** sent weekly -- reviews running workload inventory
* **Tenant dashboard** sent daily -- monitors tenant resource consumption

{% hint style="success" %}
**Efficient Monitoring**

A well-monitored VergeOS environment will have **multiple on-demand and scheduled subscriptions** configured. On-demand subscriptions catch acute events; scheduled subscriptions reveal slow-moving trends like gradual capacity consumption.
{% endhint %}

## Creating a Subscription

Subscriptions are managed from **System > Subscriptions** in the VergeOS UI. The creation workflow walks you through the following fields:

### Step-by-Step Configuration

1. Navigate to **System > Subscriptions** from the Cloud Dashboard
2. Select **New** from the left menu
3. Configure the subscription fields:

| Field                    | Description                                                                                                                              |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**                 | A unique label for the subscription (used in the list view and email subject lines)                                                      |
| **Owner Type**           | **User** (individual recipient) or **Group** (team of recipients)                                                                        |
| **Owner**                | Select the specific user or group from the dropdown                                                                                      |
| **Target Type**          | The category of VergeOS object to monitor (e.g., Cluster, vSAN Tier, Network, VM, Tenant, System)                                        |
| **Target**               | The specific instance of that object type (e.g., "Tier 1 - SSD", "Production Network", "Node 1")                                         |
| **Type**                 | **On-Demand** (triggered) or **Scheduled** (timed)                                                                                       |
| **Subscription Profile** | Required -- defines the report/alert content and, for on-demand, the comparison logic; the options shown are filtered by **Target Type** |
| **Suspend**              | Optionally pause notifications until a date/time or indefinitely (useful during maintenance windows)                                     |

### On-Demand Settings

When the subscription type is set to **On-Demand**, additional fields appear:

| Field                    | Description                                                                                                                                                                                       |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Subscription Profile** | Required template that encodes both what to watch (`onchange_fields`) and how it is compared (`new`, `gt0`, `gt`, `anyval`, or `different`) -- the available profiles are filtered by Target Type |
| **Throttle**             | Minimum minutes between repeated alerts for the same condition -- prevents inbox flooding (max 60 minutes)                                                                                        |
| **Reminder Interval**    | How often to re-send the alert while the condition persists (e.g., every 4 hours)                                                                                                                 |

The **throttle** setting is critical for noisy environments. Without it, a flapping condition (e.g., a temperature sensor oscillating around a threshold) could generate hundreds of emails. Throttle is capped at **60 minutes** (the field maximum); pick a value between 15 and 60 minutes for most alerts, using 60 when you want the longest gap the system allows.

The **reminder interval** ensures that a persistent problem is not forgotten. If a vSAN tier is at 90% capacity and no one acts on the initial alert, the reminder will re-notify at the configured interval until the condition clears.

### Scheduled Settings

When the subscription type is set to **Scheduled**, you configure the delivery timing:

| Field         | Description                                           |
| ------------- | ----------------------------------------------------- |
| **Frequency** | How often the report is sent (e.g., daily, weekly)    |
| **Time**      | The time of day the report is generated and delivered |
| **Day**       | For weekly schedules, which day of the week           |

## Subscription Profiles and Targeting

VergeOS subscriptions are flexible in their targeting — you can create subscriptions against virtually any object in the system:

### System-Level

Monitor the overall system dashboard, cluster health, or update availability across the entire environment.

### Storage-Level

Track individual vSAN tiers for capacity thresholds, drive errors, or degraded redundancy states.

### Network-Level

Alert on network faults, connectivity changes, or traffic anomalies on specific internal or external networks.

### Workload-Level

Monitor individual VMs or tenant environments for status changes, resource exhaustion, or error events.

This granular targeting means you can build a subscription strategy that matches your operational model -- broad system-level alerts for the infrastructure team, and specific VM or tenant alerts for application owners or MSP customers.

## Common Alert Configurations

The following subscription configurations represent best practices for most VergeOS deployments. Consider these as a **starting template** and customize based on your environment.

### Storage Capacity Alerts

| Setting                  | Value                                                                                 |
| ------------------------ | ------------------------------------------------------------------------------------- |
| **Target Type**          | vSAN Tier                                                                             |
| **Target**               | Each tier individually (Tier 1, Tier 2, etc.)                                         |
| **Type**                 | On-Demand                                                                             |
| **Subscription Profile** | A vSAN-tier capacity profile (e.g., "Tier Used %") that compares usage to a threshold |
| **Throttle**             | 60 minutes                                                                            |
| **Reminder**             | 4 hours                                                                               |

Create separate subscriptions at multiple thresholds (80% warning, 90% critical) to provide escalating urgency.

### Node Offline Detection

| Setting                  | Value                                                          |
| ------------------------ | -------------------------------------------------------------- |
| **Target Type**          | Node                                                           |
| **Target**               | Each node individually                                         |
| **Type**                 | On-Demand                                                      |
| **Subscription Profile** | A node-status profile that detects a transition out of Running |
| **Throttle**             | 15 minutes                                                     |
| **Reminder**             | 1 hour                                                         |

### vSAN Degraded State

| Setting                  | Value                                                            |
| ------------------------ | ---------------------------------------------------------------- |
| **Target Type**          | vSAN Tier                                                        |
| **Target**               | Each tier individually                                           |
| **Type**                 | On-Demand                                                        |
| **Subscription Profile** | A vSAN-tier health profile that fires on error or warning events |
| **Throttle**             | 30 minutes                                                       |
| **Reminder**             | 2 hours                                                          |

### Update Availability

| Setting                  | Value                                                                |
| ------------------------ | -------------------------------------------------------------------- |
| **Target Type**          | System                                                               |
| **Type**                 | On-Demand                                                            |
| **Subscription Profile** | An update-availability profile that detects new installable packages |
| **Throttle**             | 60 minutes (the maximum)                                             |
| **Reminder**             | 7 days                                                               |

### Daily System Health Report

| Setting         | Value            |
| --------------- | ---------------- |
| **Target Type** | System Dashboard |
| **Type**        | Scheduled        |
| **Frequency**   | Daily            |
| **Time**        | 7:00 AM          |

## SMTP Configuration Prerequisite

Subscriptions rely entirely on email delivery. Before any subscription can send notifications, **SMTP must be configured** at **System > SMTP** in the VergeOS UI.

VergeOS provides a built-in mail server that can either send email **directly** or route through an **SMTP relay** service.

### SMTP Settings

Navigate to **System > SMTP > Edit Settings** and configure the following:

| Setting                    | Description                                                                                     |
| -------------------------- | ----------------------------------------------------------------------------------------------- |
| **Use TLS**                | Enable/disable TLS encryption -- always enable when supported by the relay or receiving server  |
| **Hostname**               | FQDN of the sending server -- must resolve in DNS with proper SPF, DMARC, and reverse DNS       |
| **From Name**              | Display name that appears in email messages (e.g., "VergeOS Alerts")                            |
| **From Address**           | Source email address for all subscription emails                                                |
| **Relay Host**             | Address of an external SMTP relay server (leave blank for direct sending)                       |
| **Relay Port**             | TCP port for the relay -- 25 (unencrypted), 587 (TLS/STARTTLS), or 465 (legacy SSL)             |
| **Use SASL Authorization** | Enable when the relay requires authentication -- reveals the Username and Password fields below |
| **Username**               | SASL username for relay authentication (shown when SASL Authorization is enabled)               |
| **Password**               | SASL password for relay authentication (shown when SASL Authorization is enabled)               |

### Direct Send vs. Relay

| Approach        | Pros                                            | Cons                                                     |
| --------------- | ----------------------------------------------- | -------------------------------------------------------- |
| **Direct Send** | No external dependencies, immediate delivery    | Requires proper DNS/SPF/DMARC/rDNS, may be spam-filtered |
| **SMTP Relay**  | Better deliverability, simpler DNS requirements | Depends on external service, may have rate limits        |

{% hint style="success" %}
**Practical Recommendation**

Many customers opt for a commercial SMTP relay service (e.g., SendGrid, Amazon SES, or an internal Exchange relay) because it simplifies DNS configuration, improves deliverability, and avoids spam filtering issues. The relay provider will supply the correct host, port, and credentials for your SMTP configuration.
{% endhint %}

### DNS and Deliverability Requirements

When using **direct send** (no relay), the following DNS records must be properly configured to avoid email being rejected or marked as spam:

* **SPF record** -- Authorizes the VergeOS server IP to send email for the configured domain
* **DMARC record** -- Defines the domain's email authentication policy
* **Reverse DNS (PTR)** -- The sending IP must have a PTR record that matches the configured hostname
* **MX record** -- While not required for sending, proper MX configuration helps establish domain legitimacy

### SMTP Dashboard and Monitoring

The **SMTP Dashboard** (System > SMTP) provides operational visibility into email delivery:

* **Mail Queue** -- View pending messages, retry status, and delivery failures
* **Mail Log** -- Audit trail of all sent messages with timestamps and delivery status
* **Test Email** -- Send a test message to verify configuration before relying on it for production alerts

Always send a **test email** after configuring SMTP and before creating subscriptions. This validates end-to-end delivery including DNS resolution, TLS negotiation, relay authentication, and inbox placement.

## Subscription Management

### Viewing and Editing Subscriptions

All configured subscriptions are listed at **System > Subscriptions**. From this view you can:

* See the owner, target, type, and status of each subscription
* Edit existing subscriptions to adjust thresholds, throttle intervals, or recipients
* Delete subscriptions that are no longer needed
* Quickly identify which objects have alert coverage and which do not

### Multi-Tenant Considerations

In multi-tenant environments, subscriptions can be configured **at each tenant level independently**. This means:

* The **service provider** configures system-level subscriptions on the host environment
* Each **tenant administrator** can configure their own subscriptions within their tenant scope
* Tenant subscriptions only have visibility into their own resources -- they cannot see or alert on host-level objects

This isolation ensures that MSP customers can self-manage their own alerting without requiring provider intervention.

{% hint style="info" %}
**Coming from VMware or Nutanix?**

In VergeOS, a single **subscription** unifies the condition (via its Subscription Profile), routing (Owner + SMTP), and any scheduled dashboard reports in one object -- so you configure all three together against the same target instead of stitching together separate constructs.
{% endhint %}

## Key Takeaways

### Two Subscription Types

**On-Demand** for immediate event/threshold alerts and **Scheduled** for recurring dashboard reports. Use both together for full coverage.

### SMTP First

Configure and test SMTP delivery before creating any subscriptions. Direct send or relay -- both work, but relay is often simpler to maintain.

### Throttle and Remind

Use throttle settings to prevent alert storms and reminder intervals to ensure persistent issues are not forgotten.

### Target Anything

Subscriptions can target any VergeOS object -- systems, clusters, tiers, networks, VMs, and tenants -- for maximum monitoring flexibility.


---

# 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.vergeos-demo.com/learn-the-platform/module-9-monitoring-and-troubleshooting/02-alerts.md?ask=<question>
```

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.