Monitoring and Alerting

• 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 or replication issues or usage activity *
  • Includes Issue Alerts and/or Usage Alerts
• Alert Notifications: Set up Email notifications or Webhooks to report events (like issue or usage alerts) to external systems *

​

Summary of Feature Availability (by PowerSync Cloud Plan)

​

Usage Metrics

​

View Usage Metrics

• Filter options: data by time range.
• Granularity: See data in a daily, hourly or minute granularity.
• Aggregates: View and copy aggregates for each usage metric.

​

Instance Logs

• Service/API logs: Reflect sync processes from the PowerSync Service to clients.
• Replicator logs: Reflect replication activity from your source database to the PowerSync Service.

​

View Instance Logs

• Filter Options: Filter logs by level (Note, Error, Warning, Debug) and by date range.
• Sorting: Sort logs by newest or oldest first.
• Metadata: Display 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.

​

Custom Metadata in Sync Logs

​

How to Use Custom Metadata

import { PowerSyncDatabase } from '@powersync/web'; // Update this to the appropriate SDK package

const powerSync = new PowerSyncDatabase({
  schema: AppSchema,
  database: {
    dbFilename: 'powersync.db'
  }
});

// Set custom metadata when connecting
powerSync.connect(connector, {
  appMetadata: {
    app_version: '1.2.3',
    feature_flag: 'new_sync_flow'
  }
});

import 'package:powersync/powersync.dart';

final powerSync = PowerSyncDatabase(
  schema: AppSchema,
  path: 'powersync.db'
);
await powerSync.initialize();

// Set custom metadata when connecting
const options = SyncOptions(
  appMetadata: {
    'app_version': '1.2.3',
    'feature_flag': 'new_sync_flow'
  }
);
powerSync.connect(
  connector: MyConnector(),
  options: options
);

import com.powersync.DatabaseDriverFactory
import com.powersync.PowerSyncDatabase

// Android
val driverFactory = DatabaseDriverFactory(this)
// iOS & Desktop
// val driverFactory = DatabaseDriverFactory()

val powerSync = PowerSyncDatabase({
  factory: driverFactory,
  schema: AppSchema,
  dbFilename: "powersync.db"
})

// Set custom metadata when connecting
powerSync.connect(
  connector = MyConnector(),
  appMetadata = mapOf(
    "app_version" to "1.2.3",
    "feature_flag" to "new_sync_flow"
  )
)

​

View Custom Metadata in Logs

• Keep metadata values concise. app_metadata is limited to 20 keys, with each string value capped at 100 characters.
• Avoid including sensitive information in metadata as it will appear in logs.
• Metadata is set per connection. Reconnect with new metadata when user context or app state changes (e.g., feature flags).

​

Issue Alerts

​

Configure Issue Alerts

• Alert Name: Give your alert a descriptive name to help identify it
• 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
• Severity Levels: Choose which severity levels should trigger this alert:
  • Warning: For non-critical issues
  • Fatal: For critical issues that require immediate attention

​

Usage Alerts

​

Configure Usage Alerts

• 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
  • Operations Replicated
  • Peak Concurrent Connections
  • Storage Size
  These metrics correspond to the data shown in the Usage Metrics workspace and align with the PowerSync Service parameters outlined in our pricing.
• 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
• 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
• Condition: Set whether the alert triggers when usage goes Above or Below the specified threshold
• Threshold Value: The numeric limit for the selected metric (in bytes for size-based metrics; count for all other metrics)

​

Alert Notifications

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

​

Email Rules

​

Set Up Email Rules

• 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
• Enabled: Toggle to control whether the email rule is active

​

Webhooks

​

Set Up Webhooks

• 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
• Enabled: Toggle to control whether the webhook rule is active
• Retries: Configure the number of retry attempts for failed webhook deliveries

​

Webhook Signature Verification

import { createHmac } from 'crypto';

// Extract the signature from the request headers
const signature = request.header('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.body, '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");
}