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

docs: explain the P2P diagnostic workflow

Browse Source 
Guide users through Diagnostic summary, Diag logging, transfer progress,
symptom checks, and evidence collection from both devices. Link the guide
from the P2P, troubleshooting, reporting, and documentation entry points.
Keep transport compatibility and observation limits explicit.

Validated with the troubleshooting documentation Inspector, 145 local
references, 34 heading anchors, and current English UI labels. Runtime
source and translations are unchanged.
This commit is contained in:
vorotamoroz committed 2026-11-06 15:53:55 +00:00
1 parent eea78e44db
commit 966b6384f4
6 files changed
+137 -4
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/tips/p2p-diagnostics.md
+130
View File
@@ -0,0 +1,130 @@
# Diagnose P2P synchronisation
Use **P2P Status** to distinguish peer discovery, authentication, and data
transfer before changing connection or database settings.
Participating devices must use
[compatible P2P transport versions](../p2p.md#updating-a-p2p-group).
If your version does not show **Diagnostic summary**, use
[Peer-to-Peer Synchronisation Tips](p2p-sync-tips.md) and include the installed
versions in your report.
## Capture one attempt
1. Keep both devices online, with Obsidian visible and the devices awake.
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.
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
operation works, then make a small, non-private test edit on the source.
Observe the receiving device as well as the source.
6. Record the last relevant messages and progress on both devices, then
[collect a report](#collect-a-report) before restarting or retrying.
The summary continues updating with **Diag** off. **Diag** controls new detailed
output in the Log Pane; enabling it does not replay earlier hidden lines.
Diagnostic messages also enter the existing recent report history while
**Diag** is off. Opening the Log Pane displays messages already in its display
buffer. Repeated unchanged non-failure observations may be omitted, so the log
is not a record of every network message. **Pause** affects only the log display;
replication and the summary continue updating.
## Read the summary
Each row holds the latest recorded observation in one category on this device.
A new event from another peer can replace that row. Evidence can remain after
a peer leaves or a connection closes; use the peer identifier and timestamp
rather than reading the rows as a current connection-health checklist. The
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. |
- **Not observed** means no event has been recorded for that category. It does
not mean success, failure, or a measured zero.
- **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.
Relay rejection details are not available through 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.
## Understand transfer progress
| 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. |
| **⏩↑ / ⏩↓** | Changes-feed entries compared in that direction, including entries already held by the receiver. The count can advance while no revisions need transferring. |
| **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.
`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
[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. |
| 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). |
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.
## Collect a report
Collect evidence from both the source and receiving devices around the same
attempt. Include:
- the plug-in or client version on each device, and which device originated the change;
- the **Diagnostic summary** rows and times, plus the surrounding `[P2P Diag]`
lines and any other relevant errors;
- whether the peer appeared, whether manual **Replicate now** worked, and the
observed ↑/↓, ⏩, or `seq` values;
- whether **Announce changes** and **Follow changes** were enabled, and whether
either application was in the background or the device had been asleep; and
- the network types and whether TURN or a VPN was used, especially when the
same devices work on one network but not another.
Run **Generate full report for opening the issue with debug info** before the
recent history is overwritten. It includes up to 1,000 recent log lines,
including verbose diagnostic messages even when **Verbose Log** is off.
For a problem which crosses a restart, follow the existing
[persistent logging procedure](../to_issue_reporting.md#a-problem-which-crosses-a-restart).
Review the complete report using the
[issue-reporting redaction guidance](../to_issue_reporting.md#full-livesync-report).
New `[P2P Diag]` messages use fixed descriptions and shortened peer identifiers,
but other log messages can still contain private information. Keep consistent
device aliases across the reports when replacing private identifiers.
docs/tips/p2p-sync-tips.md
+2
View File
@@ -67,6 +67,8 @@ Keep Obsidian visible and the device awake during initial transfer, rebuild, or
## Collect evidence
Use the [P2P diagnostic guide](p2p-diagnostics.md) to capture the latest observations, enable **Diag**, and compare transfer progress and logs on both devices before changing settings.
If the same room works on one network but not another, include both network types in the report. Run `Generate full report for opening the issue with debug info`, remove credentials and private relay details, and state whether:
- both devices reached `Connected`;