Metrics Endpoint
PowerSync exposes instance metrics via a Prometheus-compatible endpoint. This allows you to integrate with Prometheus or other monitoring systems that scrape Prometheus endpoints.It’s not recommended to scrape the Prometheus endpoint manually, we suggest using Prometheus or other compatible tools. PowerSync does not currently support pushing to OpenTelemetry collectors.
Configuration
- To enable metrics, update your PowerSync YAML file to include the
prometheus_portand set a port number.
service.yaml
- Update your Docker compose file to forward the
prometheus_port.
docker-compose.yaml
If you’re running multiple containers (e.g. splitting up replication containers and API containers) you need to scrape the metrics separately for each container.
Metrics
API containers report sync metrics and replication containers report replication and storage metrics, with all metrics available from containers that run both roles.Sync Metrics
Replication Metrics
Storage Metrics
The
attributed gauges have sync_config_id and sync_config_state labels. They are available since Service version 1.26.0 and only report values with MongoDB bucket storage.
Sync Connection Monitoring
powersync_sync_connections_total
Allows you to monitor sync connection errors and rejected attempts, identify recurring error codes or rejection reasons.
Available since Service version 1.28.0.
Fields
Each series has anoutcome, close_reason, error_code and transport (http_stream or rsocket) labels.
Outcomes, Close Reasons, and Error Codes
Outcomes, Close Reasons, and Error Codes
Outcome ok
Closed without a stream error.- Close reasons:
client_closed,service_closed,process_shutdown, orunknown - Includes token expiry, Sync Config switches, and client-side failures. Does not confirm successful sync.
- Error code is omitted.
Outcome error
Closed with a stream error.- Close reason:
stream_error - Error code: PowerSync error code or
other
Outcome rejected
Connection attempt rejected.storage_error and sync_config_error are failures to load or parse the active Sync Config.See Error Codes for the meaning of each PSYNC_ code.Use Case Examples
Below are some queries to help you troubleshoot sync connection issues.Did Connection Failures Increase After a Deployment?
Graph this query across the deployment window to check for increased errors or rejections:Which Errors Are Interrupting Sync?
If sync is interrupted, check which stream errors occurred in the last hour:Why Can’t Clients Establish a Sync Connection?
If clients cannot start syncing, check for rejected attempts in the last hour:powersync_concurrent_connections remains the gauge for streams that are currently open.Requests that fail authentication or validation are not counted.Series are not initialized to zero, so rate() and increase() can miss the first error or rejection.