diff --git a/docs/tips/p2p-diagnostics.md b/docs/tips/p2p-diagnostics.md index ddf96725..94ce8e56 100644 --- a/docs/tips/p2p-diagnostics.md +++ b/docs/tips/p2p-diagnostics.md @@ -15,12 +15,13 @@ versions in your report. Record which device originates the change and which should receive it. 2. Open **P2P Status** on both devices, using **Self-hosted LiveSync: P2P Sync : Open P2P Status** in the command palette. -3. Expand **Diagnostic summary** below **Stats**. It starts collapsed. Record - all three rows and their observation times before reconnecting or changing - settings. -4. Turn **Diag** on, then select **Open log**. Clear **Pause** before - reproducing the problem. New diagnostic lines contain `[P2P Diag]`; - **Verbose Log** is not required for these lines. +3. In the **P2P Status** pane, expand **Diagnostic summary** below **Stats**. + It starts collapsed. Record all three rows and their observation times before + changing connection or database settings. +4. Turn the **Diag** toggle on in the **P2P Status** card, then select + **Open log** inside the expanded summary. In the opened Log Pane, ensure + **Pause** is cleared before reproducing the problem. New diagnostic lines + contain `[P2P Diag]`; **Verbose Log** is not required for these lines. 5. Select **Replicate now** for the intended peer to test a manual round trip. Check **P2P Connection Request** prompts on both devices. For a problem with later automatic changes, first establish that the manual @@ -47,29 +48,35 @@ summary is held in memory and does not preserve history across a restart. | Row | Examples | What it establishes | | --------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Relay** | `Room opening`, `Room opened`, `Room could not open`, `Room closed` | The local room lifecycle. `Room opened; relay replies not observed` does not prove that a relay accepted announcements, that a peer was discovered, or that a WebRTC data path works. | -| **Peer** | `Peer advertised`, `Peer left`, `Authentication accepted`, `Authentication refused`, `Authentication timed out` | Discovery or the observed authentication outcome for the identified peer. A timeout means the request did not finish in time; it is not an explicit refusal. | -| **Sync** | `Pull started`, `Pull completed`, `Watching peer changes`, `Announcing changes`, `Change notification received` | The latest observed pull, watch, announcement, or notification activity. A notification asks a peer to fetch; it does not itself carry Vault data. | +| **Relay** | `Room opening`, `Room opened`, `Room could not open`, `Room closed` | The local room lifecycle. 'Room opened; relay replies not observed' confirms that the local room was established, though relay acceptance, peer discovery, and WebRTC data connectivity must be verified through subsequent rows and events. | +| **Peer** | `Peer advertised`, `Peer left`, `Authentication accepted`, `Authentication refused`, `Authentication timed out` | Discovery or the observed authentication outcome for the identified peer. A timeout indicates that the request exceeded its time limit, rather than an explicit rejection. | +| **Sync** | `Pull started`, `Pull completed`, `Watching peer changes`, `Announcing changes`, `Change notification received` | The latest observed pull, watch, announcement, or notification activity. Note that notifications signal a peer to fetch changes, rather than carrying Vault data directly. | -- **Not observed** means no event has been recorded for that category. It does - not mean success, failure, or a measured zero. +- **Not observed** indicates that no event has been recorded yet for that + category, rather than confirming success, failure, or a zero count. - **Unavailable** means the diagnostic capability is unavailable in the current implementation. Include the installed version in the report. - `Authentication failed; authentication response not observed` and `Automatic watch skipped; peer announcement state not observed` identify an unavailable response, rather than claiming refusal or disabled announcements. -- Summary times are local observation times. `[P2P Diag]` lines also include an - `observed` UTC timestamp. Account for device-clock differences when comparing - reports. A timestamp is not a heartbeat or a continuously refreshed health check. +- Summary times are local observation times, while `[P2P Diag]` lines include an + `observed` UTC timestamp. Consider any device-clock differences when comparing + reports across devices. Note that timestamps record when specific events occurred, + rather than representing an ongoing heartbeat or live health check. -Relay rejection details are not available through this diagnostic summary. +Relay rejection details are not provided by this diagnostic summary. Some existing RTC diagnostics also lack peer or room attribution and are not -assigned to a peer in these rows. **Stats** describes connection activity, -not transferred document or Vault file totals. If the summary cannot explain a -failure, preserve the logs and state what remains unobserved in the report. +assigned to individual peers in these rows. **Stats** describes connection activity, +whereas transferred document totals appear in transfer progress. If the summary +cannot fully identify a failure, preserve the log output and note any unobserved +categories in your report. ## Understand transfer progress +During synchronisation, transfer counters appear next to each peer in the +P2P Status pane, in the editor status bar, and in the main status bar when +P2P is the active synchronisation method. + | Indicator | Meaning | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **↑ / ↓** | Successfully sent or received database document revisions for the observed peer and direction, including both Metadata and Chunks. These are not counts of Vault files written. A new replication attempt starts new counts. | @@ -77,30 +84,31 @@ failure, preserve the logs and state what remains unobserved in the report. | **seq** | A compatibility display of database sequence progress when document statistics are unavailable. Interpret it as a sequence value, not a document total or percentage. | Each directional comparison label disappears three seconds after its count -last changes. Its disappearance does not establish that replication completed. -A zero transfer count can be normal when the receiver already has the data. +last changes. Its absence indicates comparison inactivity rather than +confirming that overall replication is complete. A zero transfer count can +be normal when the receiver already has the data. -`Pull completed` records completion of a single database pull. It does not -establish that the reverse direction completed, that every peer has caught up, -or that every received revision has been reflected into a Vault file. Check -the test note on the receiving device. For missing files, follow +`Pull completed` confirms that a single database pull has finished. To verify +bidirectional synchronisation and full reflection, ensure the reverse direction +completes and check the updated notes on the receiving device. For missing files, +follow [the corresponding troubleshooting procedure](../troubleshooting.md#files-are-missing-or-excluded). ## Choose the next check | Symptom or observation | Next check | | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| The peer does not appear | Capture the **Relay** and **Peer** rows, then check both devices' compatible versions, relay set, Group ID, and passphrase using [discovery checks](p2p-sync-tips.md#a-peer-does-not-appear). `Connected` alone is insufficient. | -| Authentication is refused | Confirm the peer identity and intended approval on both devices. The summary records the outcome; it does not grant approval. | -| Authentication times out, or a peer appears but cannot transfer | Keep both devices visible and check for an unanswered **P2P Connection Request** before treating a timeout as a network failure. Compare their logs, then use the existing [WebRTC and TURN checks](p2p-sync-tips.md#a-peer-appears-but-synchronisation-cannot-connect) to investigate the data path. | +| The peer does not appear | Capture the **Relay** and **Peer** rows, then verify both devices' compatible versions, relay set, Group ID, and passphrase using [discovery checks](p2p-sync-tips.md#a-peer-does-not-appear). Note that a `Connected` status confirms signalling readiness, while peer discovery requires matching group and network settings. | +| Authentication is refused | Confirm the peer identity on both devices and check for pending approval prompts. The summary displays the observed outcome; please ensure the connection request is explicitly accepted on the receiving device. | +| Authentication times out, or a peer appears but cannot transfer | Keep both devices active and check for an unanswered **P2P Connection Request** before troubleshooting network connectivity. Compare logs between devices, then follow existing [WebRTC and TURN checks](p2p-sync-tips.md#a-peer-appears-but-synchronisation-cannot-connect) to inspect the data path. | | Manual replication works, but later edits do not arrive | Confirm **Announce changes** on the source and **Follow changes** for that source on the receiver. Compare `Announcing changes`, `Watching peer changes`, and notification events on both devices. `Change notification ignored; peer is not watched` identifies a missing follow on the receiver. | -| A pull remains the last observation | Compare its timestamp, ↑/↓ and ⏩ changes, and both devices' logs. Another operation may have replaced a summary row; an old `Pull started` or a hidden ⏩ label alone does not establish a stalled transfer. For a repeatable network-specific stall, use [message-size checks](p2p-sync-tips.md#a-connection-opens-but-a-transfer-stalls). | +| A pull remains the last observation | Compare its timestamp, ↑/↓ and ⏩ changes, and both devices' logs. A subsequent operation may have replaced the summary row; verify with the surrounding logs and transfer counters to confirm whether a transfer is truly stalled. For a repeatable network-specific stall, use [message-size checks](p2p-sync-tips.md#a-connection-opens-but-a-transfer-stalls). | -After capturing the original symptom, **Disconnect** followed by -**Open connection** and **Replicate now** can test reconnection. Disconnecting -can cancel an active operation, so record whether a cancellation followed that -action. Reconnection, a changed message-size preset, or a different network -helps compare conditions; it does not identify or repair every underlying cause. +After capturing the initial symptom, selecting **Disconnect** followed by +**Open connection** and **Replicate now** can test reconnection. Because +disconnecting cancels active operations, record whether a cancellation occurred. +Testing reconnection, adjusting the message-size preset, or trying an +alternative network can help isolate environmental differences. ## Collect a report