Skip to content

Update alerts documentation #307

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
benitav merged 1 commit into from
Dec 11, 2025
Merged

Update alerts documentation #307

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
194 changes: 57 additions & 137 deletions usage/tools/monitoring-and-alerting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@

* **Monitor Service and Replication Activity**: Track your PowerSync Service and replication logs with [Instance Logs](#instance-logs)

* **Configure Alerts**: Set up alerts for replication issues or usage activity \*
* **Configure Alerts**: Set up alerts for connection or replication issues or usage activity \*

* Includes [Issue Alerts](#issue-alerts) and/or [Usage Alerts](#usage-alerts)

Expand Down Expand Up @@ -108,7 +108,7 @@

## Issue Alerts

Issue alerts capture potential problems with your instance, such as connection or sync issues.
Issue alerts capture potential problems with your instance, such as connection or replication issues.

<Note>
**Availability**
Expand All @@ -118,41 +118,27 @@

### Configure Issue Alerts

<Note>
Issue alerts configuration is currently available in the [legacy dashboard](https://powersync.journeyapps.com/). This feature will be available in the new dashboard soon.
</Note>

Issue alerts are set up per instance. To set up a new alert, navigate to your **PowerSync Project tree**, right-click on the "Issue Alerts" option under the selected instance, and follow the prompts.

<Frame>
<img src="/images/resources/instance-alerts-dashboard.png" width="50%" />
</Frame>

You can set up alerts that trigger under certain conditions:

* **Connection Issues**: Trigger when there is a connection problem
Issue alerts are set up per instance. To set up a new alert, navigate to the **Alerts** section in the [PowerSync Dashboard](https://dashboard.powersync.com/) and click **Create Issue Alert**.

* **Replication/Sync Issues**: Trigger when there is an issue with a replication or sync process
When creating or editing an issue alert, you can configure:

#### Severity Level
* **Alert Name**: Give your alert a descriptive name to help identify it

You also have the option to set the severity level of the alerts. For example, you can configure alerts to trigger only for `warning` and/or `fatal` issues. Free and Pro plan customers can only configure `fatal` alerts.
* **Issue Type**: Select the type of issue to monitor from the dropdown:
* **Database Connection Issue**: Trigger when there is a connection problem
* **Replication Issue**: Trigger when there is an issue with the replication process

### View Issue Alerts
* **Severity Levels**: Choose which severity levels should trigger this alert:
* **Warning**: For non-critical issues
* **Fatal**: For critical issues that require immediate attention

<Note>
Viewing issue alerts is currently available in the [legacy dashboard](https://powersync.journeyapps.com/). This feature will be available in the new dashboard soon.
</Note>

Once you have created an alert, you can right-click on it to open the alert logs. The logs panel includes the option to filter alerts by date range.

<Frame>
<img src="/images/resources/view-issue-alert-logs-cmd.png" />
</Frame>

### **Configure Notifications**
<Warning>
**Important: Set Up Notification Rules**

See [Alert Notifications](#alert-notifications) below to be notified when an issue alert is triggered.
Creating an issue alert only defines *what* to monitor. To actually receive notifications when alerts trigger, you must also set up [Email Rules](#email-notifications) or [Webhooks](#webhooks) and configure them to notify for "Issue alert state change" events. See the [Alert Notifications](#alert-notifications) section below.
</Warning>

## Usage Alerts

Expand All @@ -166,26 +152,14 @@

### Configure Usage Alerts

<Note>
Usage alerts configuration is currently available in the [legacy dashboard](https://powersync.journeyapps.com/). This feature will be available in the new dashboard soon.
</Note>
Usage alerts are set up per instance. Navigate to the **Alerts** section in the [PowerSync Dashboard](https://dashboard.powersync.com/) and click **Create Usage Alert**.

Usage alerts are set up per instance. Navigate to your **PowerSync Project** tree, and click on the plus icon for the **Usage Alerts** option under your selected instance to create a new alert.

<Frame>
<img src="/images/resources/instance-alerts-dashboard.png" width="50%" />
</Frame>

Usage alerts have the following configuration options:

<Frame>
<img src="/images/resources/usage-alert-config.png" width="75%" />
</Frame>
When creating or editing a usage alert, you can configure:

* **Alert Name**: A descriptive name for your alert to help identify it
* **Alert Name**: Give your alert a descriptive name to help identify it

* **Metric**: Select from the following usage metrics to monitor:

* Data Synced
* Data Replicated
* Operations Synced
Expand All @@ -197,141 +171,94 @@
These metrics correspond to the data shown in the [Usage Metrics](#view-usage-metrics) workspace and align with the PowerSync Service parameters outlined in our [pricing](https://www.powersync.com/pricing).
</Note>

* **Window (minutes)**: The number of minutes to look back when evaluating usage. All usage data points within this time window are included when determining if the configured threshold has been crossed
* **Window**: The number of minutes to look back when evaluating usage. All usage data points within this time window are included when determining if the configured threshold has been crossed

* **Calculation**: Choose how to aggregate all data points within the window before comparing to the threshold:
* **Aggregation**: Choose how to aggregate all data points within the window before comparing to the threshold:
* **Avg**: Calculate the average of all values
* **Max**: Use the highest value
* **Min**: Use the lowest value

* **Average over window**: Calculate the average of all values
* **Max over window**: Use the highest value
* **Min over window**: Use the lowest value
* **Condition**: Set whether the alert triggers when usage goes **Above** or **Below** the specified threshold

* **Threshold Condition**: Set whether the alert triggers when usage goes **Above** or **Below** the specified value
* **Threshold Value**: The numeric limit for the selected metric (in bytes for size-based metrics; count for all other metrics)

* **Threshold Value**: The numeric limit for the selected metric (in bytes for size-based metrics; count for all others)

### View Usage Alert Logs
<Warning>
**Important: Set Up Notification Rules**

<Note>
Viewing usage alert logs is currently available in the [legacy dashboard](https://powersync.journeyapps.com/). This feature will be available in the new dashboard soon.
</Note>

Once you have created an alert, you can right-click on it to open the alert logs. The logs panel includes the option to filter alerts by date range.
<Frame>
<img src="/images/resources/view-usage-alert-logs-cmd.png" />
</Frame>

### **Configure Notifications**

See [Alert Notifications](#alert-notifications) below to be notified when a usage alert is triggered.
Creating a usage alert only defines *what* to monitor. To actually receive notifications when alerts trigger, you must also set up [Email Rules](#email-notifications) or [Webhooks](#webhooks) and configure them to notify for "Usage alert state change" events. See the [Alert Notifications](#alert-notifications) section below.
</Warning>

## Alert Notifications

You can set up notifications to be informed of issue or metric alerts, as well as deploy state changes. PowerSync provides multiple notification methods that trigger both when an alert becomes active and when it returns to normal (indicating the monitored conditions are back within acceptable thresholds).
Set up notification rules to be informed of issue or usage alerts, as well as deploy state changes. PowerSync provides multiple notification methods that trigger both when an alert becomes active and when it returns to normal (indicating the monitored conditions are back within acceptable thresholds).

* **Email Notifications**: Send alerts directly to your email address
* **Email Rules**: Send alerts directly to your email address
* **Webhooks**: Notify external systems and services

<Note>
**Availability**

* **Email notifications**: Available on all plans (**Free**, **Pro**, **Team** and **Enterprise**)
* **Email Rules**: Available on all plans (**Free**, **Pro**, **Team** and **Enterprise**)

* **Webhooks**: Available on **Pro**, **Team** and **Enterprise** plans
</Note>

### Email Notifications
### Email Rules

Email notifications allow you to receive alerts directly to your email address when specific events occur in PowerSync.
Email rules allow you to receive alerts directly to your email address when specific events occur in PowerSync.

#### Set Up Email Notifications
#### Set Up Email Rules

<Note>
Email rules configuration is currently available in the [legacy dashboard](https://powersync.journeyapps.com/). This feature will be available in the new dashboard soon.
</Note>
Navigate to the **Alerts** section in the [PowerSync Dashboard](https://dashboard.powersync.com/) and scroll down to the **Notification Rules** section. Click **Create Email Rule** to set up email notifications.

Navigate to the **Email Rules** section in your **PowerSync Project** tree, and click on the plus icon to create a new email rule for your project.

<Info>
<Warning>
Accounts on the Free plan are restricted to a single email rule; customers on paid plans can create an unlimited number of email rules.
</Info>

<Frame>
<img src="/images/resources/instance-alerts-dashboard.png" width="50%" />
</Frame>
</Warning>

#### Configuration
When creating or editing an email rule, you can configure:

* **Email Address**: Specify the email address that will receive the notifications
* **Recipient Email**: Specify the email address that will receive the notifications (required)

* **Event Triggers**: Select one or more of the following events to trigger the email notification:
* **Usage alert state change**: Fired when a usage alert changes between 'monitoring' and 'alerting' (a threshold has been crossed)
* **Issue alert state change**: Fired when an issue alert changes between 'monitoring' and 'alerting' (the instance has active issues)
* **Deploy state change**: Fired when an instance deploy starts, completes or fails. This includes deprovisioning an instance

Check warning on line 226 in usage/tools/monitoring-and-alerting.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

usage/tools/monitoring-and-alerting.mdx#L226 

Did you really mean 'deprovisioning'?

* Issue alert state change

* Usage alert state change (Team & Enterprise plan only)

* Deploy state change
* **Enabled**: Toggle to control whether the email rule is active

* **Enable/Disable**: Control whether the email rule is active

### Webhooks

Webhooks enable you to notify external systems when specific events occur in PowerSync.

#### Set Up Webhooks

<Note>
Webhook configuration is currently available in the [legacy dashboard](https://powersync.journeyapps.com/). This feature will be available in the new dashboard soon.
</Note>
Navigate to the **Alerts** section in the [PowerSync Dashboard](https://dashboard.powersync.com/) and scroll down to the **Notification Rules** section. Click **Create Webhook Rule** to set up webhook notifications.

Navigate to the **Webhooks** section in your **PowerSync Project** tree, and click on the plus icon to create a new webhook for your project.
When creating or editing a webhook rule, you can configure:

<Frame>
<img src="/images/resources/instance-alerts-dashboard.png" width="50%" />
</Frame>

#### Webhook Configuration

* **Specify Webhook Endpoint**: Define the endpoint that will receive the webhook request (starting with `https://`).
* **Webhook Endpoint (URL)**: Define the endpoint that will receive the webhook request (starting with `https://`) (required)

* **Event Triggers**: Select one or more of the following events to trigger the webhook:
* **Usage alert state change**: Fired when a usage alert changes between 'monitoring' and 'alerting' (a threshold has been crossed)
* **Issue alert state change**: Fired when an issue alert changes between 'monitoring' and 'alerting' (the instance has active issues)
* **Deploy state change**: Fired when an instance deploy starts, completes or fails. This includes deprovisioning an instance

Check warning on line 246 in usage/tools/monitoring-and-alerting.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

usage/tools/monitoring-and-alerting.mdx#L246 

Did you really mean 'deprovisioning'?

* Issue alert state change

* Usage alert state change (Team & Enterprise plan only)
* **Enabled**: Toggle to control whether the webhook rule is active

* Deploy state change
* **Retries**: Configure the number of retry attempts for failed webhook deliveries

You can control how webhooks operate:

* Enable, disable, or pause a webhook
<Check>
After creating a webhook, a secret is automatically generated and copied to your clipboard. Store this secret since you'll need it to verify the webhook request signature.
</Check>

* If paused, invocations can still be generated and queued, but they won't be processed

* If disabled, invocations won't be generated

* Choose sequential or concurrent execution

* If concurrent, you can set the maximum number of concurrent invocations

* Configure retry attempts for failed webhook deliveries

#### Webhook Secret

After creating a webhook, a secret is automatically generated and copied to your clipboard. Store this secret since you'll need it to verify the webhook request signature. See [Webhook Signature Verification](#webhook-signature-verification)

#### Test Webhooks

A test webhook can be sent to your specified endpoint to verify your setup. Right-click on a webhook in the **PowerSync project** tree and select the **Test Webhook** option:

<Frame>
<img src="/images/resources/test-webhook-cmd.png" />
</Frame>

#### Webhook Signature Verification
### Webhook Signature Verification

Every webhook request contains an `x-journey-signature` header, which is a base64-encoded HMAC (Hash-based Message Authentication Code). To verify the request, you need to compute the HMAC using the shared secret that was generated when you created the webhook, and compare it to the value in the `x-journey-signature` header.

**JavaScript Example**
**JavaScript Example:**

```javascript
import { createHmac } from 'crypto';
Expand All @@ -352,10 +279,3 @@
}
```

#### Regenerate Secret

You can regenerate the secret used to validate the webhook signature. Right-click on a webhook in the PowerSync project tree and select the **Regenerate secret** option.

#### View Webhook Invocation Logs

You can review webhook invocation logs in the Dashboard and filter them by date. Right-click on a webhook in the **PowerSync project** tree and select the **View webhook invocation logs** option.