From 1bd5ca00c3d17a550faaa2d01247137179c7353d Mon Sep 17 00:00:00 2001 From: LucDeCaf Date: Thu, 6 Aug 2026 15:51:51 +0200 Subject: [PATCH 1/4] Document replication batches and flushed updates meanings --- architecture/powersync-service.mdx | 9 ++++++++ maintenance-ops/monitoring-and-alerting.mdx | 25 +++++++++++++++++++++ 2 files changed, 34 insertions(+) diff --git a/architecture/powersync-service.mdx b/architecture/powersync-service.mdx index 90c0c5e1..b1b4bb08 100644 --- a/architecture/powersync-service.mdx +++ b/architecture/powersync-service.mdx @@ -93,6 +93,15 @@ After that, data is incrementally replicated using a change data capture stream. The PowerSync Service preserves source transaction boundaries when replicating. For Convex, mutations are ACID transactions. When a mutation writes multiple documents, Convex exposes those writes in `document_deltas` with the same commit timestamp, and PowerSync replicates all writes from the same mutation together as one batch. Clients do not observe a partial result from a single Convex mutation. +### Replication Batches + +Replication is batched. The Service accumulates changes in memory and periodically flushes them to bucket storage. Each flush writes three different kinds of record: + +- **Bucket operations**: entries appended to the [operation history](#operation-history) of each affected bucket, as `PUT` or `REMOVE` operations. A single source row produces one operation per bucket it belongs to, so a row that is shared across many buckets produces many operations. +- **Parameter index entries**: lookup entries that let the Service resolve which buckets a client should sync. These are written for rows that feed a stream's parameters rather than its data. +- **Source records**: one record per source row, holding the row along with the buckets and lookups it currently belongs to. The Service compares against this record to work out which bucket operations and parameter index entries to remove when the row later changes or is deleted. + +Each flush is logged with these counts, along with the size and duration of the write. See [Instance Logs](/maintenance-ops/monitoring-and-alerting#instance-logs) for how to view them. ## Streaming Sync diff --git a/maintenance-ops/monitoring-and-alerting.mdx b/maintenance-ops/monitoring-and-alerting.mdx index 7e866391..a16e6860 100644 --- a/maintenance-ops/monitoring-and-alerting.mdx +++ b/maintenance-ops/monitoring-and-alerting.mdx @@ -263,6 +263,31 @@ rid: For diagnosing sync latency, see [Diagnosing Sync Latency](/debugging/troubleshooting#diagnosing-sync-latency). +### Replication Flush Entries + +Replication logs record a `Flushed` entry each time a batch of replicated changes is written to bucket storage. These entries are the most direct view of replication throughput: + +``` +Flushed: 1200 ops, 30 index entries, 450 records. 512kb in 240ms. Last op_id: 88421. Replication lag: 3s +``` + +The counts are also available as structured properties under `flushed` on each entry: + +| Property | Description | +| ------------------------- | --------------------------------------------------------------------------------- | +| `bucket_ops_count` | Bucket operations appended to operation history. | +| `parameter_indexes_count` | Parameter lookup entries written for rows that feed stream parameters. | +| `source_records_count` | Source rows persisted, along with the buckets and lookups they belong to. | +| `size` | Size of the flush in bytes. | +| `duration` | Time taken to write the batch, in milliseconds. | +| `replication_lag_seconds` | Age of the oldest uncommitted change in the batch, in seconds. | + +For what each of the three counts represents, see [Replication Batches](/architecture/powersync-service#replication-batches). + + + `replication_lag_seconds` is only present when the Service can determine the oldest uncommitted change in the batch. + + ## Custom Metadata in Sync Logs Custom metadata in sync logs allows clients to attach additional context to their PowerSync connection for improved observability and analytics. This metadata appears in the Sync & API logs, making it easier to track, debug, and analyze sync behavior across your app. For example, you can tag connections with app version, feature flags, or business context. From 976cac3820d5bed5132e9e97837876d9b618fe9c Mon Sep 17 00:00:00 2001 From: LucDeCaf Date: Fri, 7 Aug 2026 09:41:41 +0200 Subject: [PATCH 2/4] Bot feedback --- maintenance-ops/monitoring-and-alerting.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/maintenance-ops/monitoring-and-alerting.mdx b/maintenance-ops/monitoring-and-alerting.mdx index a16e6860..085ba930 100644 --- a/maintenance-ops/monitoring-and-alerting.mdx +++ b/maintenance-ops/monitoring-and-alerting.mdx @@ -271,12 +271,12 @@ Replication logs record a `Flushed` entry each time a batch of replicated change Flushed: 1200 ops, 30 index entries, 450 records. 512kb in 240ms. Last op_id: 88421. Replication lag: 3s ``` -The counts are also available as structured properties under `flushed` on each entry: +These values are also available as structured properties under `flushed` on each entry: | Property | Description | | ------------------------- | --------------------------------------------------------------------------------- | | `bucket_ops_count` | Bucket operations appended to operation history. | -| `parameter_indexes_count` | Parameter lookup entries written for rows that feed stream parameters. | +| `parameter_indexes_count` | Parameter index entries written for rows that feed stream parameters. | | `source_records_count` | Source rows persisted, along with the buckets and lookups they belong to. | | `size` | Size of the flush in bytes. | | `duration` | Time taken to write the batch, in milliseconds. | From c8545457c9ac7451f1d5fa6d0d8a32995e4716d0 Mon Sep 17 00:00:00 2001 From: Luc de Cafmeyer Date: Fri, 7 Aug 2026 12:29:13 +0200 Subject: [PATCH 3/4] Update maintenance-ops/monitoring-and-alerting.mdx Co-authored-by: benitav --- maintenance-ops/monitoring-and-alerting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/maintenance-ops/monitoring-and-alerting.mdx b/maintenance-ops/monitoring-and-alerting.mdx index 085ba930..314e2e44 100644 --- a/maintenance-ops/monitoring-and-alerting.mdx +++ b/maintenance-ops/monitoring-and-alerting.mdx @@ -282,7 +282,7 @@ These values are also available as structured properties under `flushed` on each | `duration` | Time taken to write the batch, in milliseconds. | | `replication_lag_seconds` | Age of the oldest uncommitted change in the batch, in seconds. | -For what each of the three counts represents, see [Replication Batches](/architecture/powersync-service#replication-batches). +Learn more about these counts in [Replication Batches](/architecture/powersync-service#replication-batches). `replication_lag_seconds` is only present when the Service can determine the oldest uncommitted change in the batch. From b63d36f543ec045cc9101c54859a8f91e7cb6752 Mon Sep 17 00:00:00 2001 From: Luc de Cafmeyer Date: Fri, 7 Aug 2026 12:30:55 +0200 Subject: [PATCH 4/4] Update architecture/powersync-service.mdx Co-authored-by: stevensJourney <51082125+stevensJourney@users.noreply.github.com> --- architecture/powersync-service.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/architecture/powersync-service.mdx b/architecture/powersync-service.mdx index b1b4bb08..792266e0 100644 --- a/architecture/powersync-service.mdx +++ b/architecture/powersync-service.mdx @@ -98,7 +98,7 @@ The PowerSync Service preserves source transaction boundaries when replicating. Replication is batched. The Service accumulates changes in memory and periodically flushes them to bucket storage. Each flush writes three different kinds of record: - **Bucket operations**: entries appended to the [operation history](#operation-history) of each affected bucket, as `PUT` or `REMOVE` operations. A single source row produces one operation per bucket it belongs to, so a row that is shared across many buckets produces many operations. -- **Parameter index entries**: lookup entries that let the Service resolve which buckets a client should sync. These are written for rows that feed a stream's parameters rather than its data. +- **Parameter index entries**: lookup entries that let the Service resolve which buckets a client should sync. These are written for rows that feed a stream's parameters. - **Source records**: one record per source row, holding the row along with the buckets and lookups it currently belongs to. The Service compares against this record to work out which bucket operations and parameter index entries to remove when the row later changes or is deleted. Each flush is logged with these counts, along with the size and duration of the write. See [Instance Logs](/maintenance-ops/monitoring-and-alerting#instance-logs) for how to view them.