public/obsidian-livesync
1
0 Fork 0
mirror of https://github.com/vrtmrz/obsidian-livesync.git synced 2026-11-14 20:20:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: refine tone and clarify P2P diagnostic guidance

Browse Source
This commit is contained in:
vorotamoroz committed 2026-11-07 02:32:06 +00:00
1 parent a5d3769cc1
commit e2d0cfa9f6
1 file changed
+41 -33
Download Patch File Download Diff File Expand all files Collapse all files
docs/tips/p2p-diagnostics.md
+41 -33
View File
@@ -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