Monitoring and Alerting

Overview of monitoring and alerting functionality for PowerSync instances

You can monitor activity and alert on issues and usage for your PowerSync instance(s):

• Monitor Service and Replication Activity: Track your PowerSync service and replication logs with Instance Logs

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

  • Includes Issue Alerts and/or Metric Alerts

• Webhooks: Set up Webhooks to report events (like issue or metric alerts) to external systems *

These features can assist with troubleshooting common issues (e.g. replication errors due to a logical replication slot problem), investigating usage spikes, or being notified when usage exceeds a specific threshold.

* The availability of these features depends on your PowerSync subscription. See the table below for a summary. More details are provided further below.

Summary of Feature Availability (by Pricing Plan)

Monitoring and alerting functionality varies by plan, and is being rolled out in phases. This table provides a summary of availability:

Feature	Free	Pro	Team & Enterprise
Instance Logs	Available	Available	Available
Log retention period	24 hours	7 days	30 days
Issue Alerts	Fatal alerts (Coming soon)	Fatal alerts (Coming soon)	Fully configurable
Metric Alerts	Not available	Not available	Fully configurable
Alert Notifications	Email (Coming soon)	Webhooks Email (Coming soon)	Webhooks Email (Coming soon)

Self-hosting PowerSync

Similar monitoring and alerting functionality is planned for PowerSync Open Edition users and Enterprise Edition customers.

We plan to publish alerting APIs for Open Edition users, and an alerting service with customization options and webhook integration for Enterprise Edition customers.

Until this is available, please chat to us on our Discord to discuss your use case or any questions.

Instance Logs

You can review logs for your PowerSync instance(s) to troubleshoot replication or sync issues. Logs capture activity from the PowerSync Service and Replicator processes.

• Service logs: Reflect sync activity from the PowerSync Service to clients.

• Replicator logs: Reflect replication activity from your source database to the PowerSync Service.

Availability

The log retention period varies by plan:

• Free plan: Logs from the last 24 hours

• Pro plan: Logs from the last 7 days

• Team & Enterprise plans: Logs from the last 30 days

View Instance Logs

Access instance logs through the Dashboard, in the Instance logs workspace (or by searching for the panel using the command palette):

You can manage logs with the following options:

• Filter Options: Filter logs by level (Info, Error, Warning, Debug) and by date range.

• Sorting: Sort logs by newest or oldest first.

• Service Logs Metadata: Include metadata like user_id and user_agent in the logs if available.

• View Mode: Tail logs in real-time or view them statically.

• Stack Traces: Option to show or hide stack traces for errors.

Issue Alerts

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

Availability

• Coming soon: Free and Pro plan customers will be able to opt in to receive fatal issue alerts.

• Team and Enterprise customers can customize the issue type and severity level for which an alert should trigger.

Configure Issue Alerts

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.

You can set up alerts that trigger under certain conditions:

• Connection Issues: Trigger when there is a connection problem

• Replication/Sync Issues: Trigger when there is an issue with a replication or sync process

Severity Level

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.

View Issue Alerts

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.

This command and other configuration options are also available from the command palette (SHIFT+SHIFT):

Alert Notifications

See Webhooks below to notify external systems when an alert is triggered.

---

Metric Alerts

Metric alerts trigger when specific usage metrics exceed a defined threshold. This helps with troubleshooting usage spikes, or unexpected usage activity.

Availability

Metrics alerts are available on Team and Enterprise plans.

Configure Metric Alerts

Metric alerts are set up per instance. Navigate to your PowerSync Project tree, and right-click on the Metric Alerts option under your selected instance to create a new alert.

You can set alerts for the following usage metrics:

• Data Synced

• Data Replicated

• Operations Synced

• Operations Replicated

• Peak Concurrent Connections

• Storage Size

Thresholds can be set to trigger alerts when usage exceeds or falls below a specified value.

View Metric Alert Logs

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.

This command and other configuration options are also available from the command palette (SHIFT+SHIFT):

Alert Notifications

See Webhooks below to notify external systems when an alert is triggered.

Webhooks

Webhooks enable you to notify external systems when specific events occur in PowerSync, such as issue or metric alerts.

Availability

• Webhooks are currently available on Team and Enterprise plans.

• Coming soon: Pro plan customers will be able to set up webhooks for Issue alerts.

• Email notifications will be available in a future release (also for Free plan users).

Set Up Webhooks

Navigate to the Webhooks section in your PowerSync Project tree, and right-click on it to create a new webhook for your project.

Configuration

• Specify Webhook Endpoint: Define the endpoint that will receive the webhook request (starting with https://).

• Event Triggers: Select one or more of the following events to trigger the webhook:

  • Issue alert state change

  • Metric alert state change (Team & Enterprise customer only)

  • Deploy state change (Team & Enterprise customer only)

You can control how webhooks operate:

• Enable, disable, or pause a webhook

  • 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

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:

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

import { createHmac } from 'crypto';

// Extract the signature from the request headers
const signature = request.headers['x-journey-signature'];

// Create an HMAC using your webhook secret and the request body
let verify = createHmac('sha256', '<webhook_secret_here>') // The secret provided during webhook setup
    .update(Buffer.from(request.rawBody, 'utf-8')) 
    .digest('base64');

// Compare the computed HMAC with the signature from the request
if (signature === verify) {
    console.log("success");
} else {
    console.log("verification failed");
}

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.