jedarden/miroir
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
miroir/docs
History
jedarden c5238b1bcd docs(troubleshooting): add common issues guide and diagnostic playbook (P11.5) 
Implements P11.5 acceptance criteria:
- Created docs/troubleshooting.md with 10 common issues
- Created docs/troubleshooting/diagnostics.md with systematic diagnostic playbook
- Documented 3 required plan §11 issues (primary key required, degraded search results, stuck tasks)
- Added 7 additional issues from Phase 9 chaos testing and operations
- Cross-linked from README, migration runbook, and dump import guide

Documented issues:
1. "primary key required" - Miroir vs Meilisearch difference
2. Search returns fewer results - degraded node handling
3. Task polling stuck - per-node task status recovery
4. Node drain blocked - RF constraints
5. Migration stuck after coordinator crash - recovery procedures
6. High memory usage on Redis - cleanup procedures
7. Index creation fails - topology inconsistency
8. Alias flip conflicts - single vs multi alias types
9. Search timeout during migration - throttling options
10. CDC cursor out of sync - recovery and re-index

Diagnostic playbook covers:
- Cluster health checks (pods, nodes, resources)
- Topology verification and node agreement
- Metrics analysis (degraded shards, task queue, latency)
- Log analysis for error patterns
- Task status inspection
- Anti-entropy status
- External dependency checks
- Self-diagnostics and canary tests

Closes: miroir-uyx.5
2026-05-24 14:02:13 -04:00
..
benchmarks miroir-zc2.3: Validate 2× transient load caveat for online resharding (P12.OP3) 2026-05-20 07:24:22 -04:00
ctl docs(miroir-ctl): add subcommand runbooks and help text (P11.4, miroir-uyx.4) 2026-05-24 11:47:36 -04:00
dump-import miroir-zc2.5: Fix dump import compatibility matrix enhancement bead refs 2026-05-20 07:16:06 -04:00
horizontal-scaling P6.11: Add single-pod oversized mode support (§14.10 vertical scaling escape valve) 2026-05-20 07:29:39 -04:00
migrations docs(troubleshooting): add common issues guide and diagnostic playbook (P11.5) 2026-05-24 14:02:13 -04:00
notes Phase 3 (miroir-r3j): Task Registry + Persistence — Verification complete 2026-05-09 05:40:08 -04:00
onboarding bf-1p4v: Verify compile error already fixed 2026-05-20 06:49:04 -04:00
operations P3.3.d: Fix compilation - add missing local_search_ui_rate_limiter field 2026-04-26 11:18:02 -04:00
plan feat(logging): add structured JSON logging tests and docs (plan §10, P7.5) 2026-05-24 10:00:21 -04:00
research Merge remote-tracking branch 'origin/master' 2026-05-24 05:21:32 -04:00
runbooks P10.2: nodeMasterKey zero-downtime rotation flow 2026-04-19 15:49:40 -04:00
troubleshooting docs(troubleshooting): add common issues guide and diagnostic playbook (P11.5) 2026-05-24 14:02:13 -04:00
arm64-support.md OP#6: Add ARM64 (aarch64-unknown-linux-musl) target support 2026-05-08 15:25:12 -04:00
chaos_testing_report.md P12.OP1: Shard migration write safety - chaos testing 2026-05-08 15:29:48 -04:00
migration_runbook.md docs(troubleshooting): add common issues guide and diagnostic playbook (P11.5) 2026-05-24 14:02:13 -04:00
redis-memory-accounting.md Phase 3 (miroir-r3j): Task Registry + Persistence — Complete 2026-05-09 02:29:38 -04:00
redis-memory.md P3: Complete Phase 3 — Task Registry + Persistence (SQLite + Redis) 2026-05-02 16:52:25 -04:00
trade-offs.md OP#3: Document S-change (resharding) vs N-change (node scaling) trade-offs 2026-05-08 15:25:53 -04:00
troubleshooting.md docs(troubleshooting): add common issues guide and diagnostic playbook (P11.5) 2026-05-24 14:02:13 -04:00
versioning-policy.md bf-35t4: Commit current main state before merge 2026-05-19 22:52:18 -04:00