Monitoring and Alerting

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

• Monitor Usage: View time-series and aggregated usage data with Usage Metrics
• 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 Cloud plan. See the table below for a summary. More details are provided further below.

​

Summary of Feature Availability (by PowerSync Cloud Plan)

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

​

Usage Metrics

View time-series and aggregated usage data for your PowerSync instance(s), including storage size, concurrent connections, and synced data and operations. This data lets you monitor activity, spot patterns or spikes, and easily budget while tracking your position within our Cloud pricing plans.

​

View Usage Metrics

Access usage metrics in the Dashboard, in the Metrics workspace:

You have following options:

• Filter options: data by time range.
• Granularity: See data in a daily or hourly granularity.
• Aggregates: View and copy aggregates for each usage metric.
• CSV: Download data as CSV for custom calculations.

​

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.

​

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.

​

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.

​

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.

​

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.