obsidian-debug-bundle

# Obsidian Debug Bundle ## Overview Collect all necessary diagnostic information for Obsidian plugin bug reports and support requests. ## Prerequisites - Obsidian plugin with issues - Access to vault configuration - Terminal/command line access ## Instructions ### Step 1: Create Debug Bundle Script ```bash #!/bin/bash # obsidian-debug-bundle.sh BUNDLE_DIR="obsidian-debug-$(date +%Y%m%d-%H%M%S)" mkdir -p "$BUNDLE_DIR" echo "=== Obsidian Plugin Debug Bundle ===" > "$BUNDLE_DIR/summary.txt" echo "Generated: $(date)" >> "$BUNDLE_DIR/summary.txt" echo "" >> "$BUNDLE_DIR/summary.txt" ``` ### Step 2: Collect System Information ```bash # System info echo "--- System Information ---" >> "$BUNDLE_DIR/summary.txt" echo "OS: $(uname -s)" >> "$BUNDLE_DIR/summary.txt" echo "OS Version: $(uname -r)" >> "$BUNDLE_DIR/summary.txt" echo "Node.js: $(node --version 2>/dev/null || echo 'not installed')" >> "$BUNDLE_DIR/summary.txt" echo "npm: $(npm --version 2>/dev/null || echo 'not installed')" >> "$BUNDLE_DIR/summary.txt" echo "" >> "$BUNDLE_DIR/summary.txt" ``` ### Step 3: Collect Plugin Information ```bash # Plugin directory (adjust path as needed) PLUGIN_DIR="/path/to/your/plugin" # Plugin metadata echo "--- Plugin Information ---" >> "$BUNDLE_DIR/summary.txt" if [ -f "$PLUGIN_DIR/manifest.json" ]; then echo "Manifest:" >> "$BUNDLE_DIR/summary.txt" cat "$PLUGIN_DIR/manifest.json" >> "$BUNDLE_DIR/summary.txt" cp "$PLUGIN_DIR/manifest.json" "$BUNDLE_DIR/" fi echo "" >> "$BUNDLE_DIR/summary.txt" # Package versions if [ -f "$PLUGIN_DIR/package.json" ]; then echo "--- Dependencies ---" >> "$BUNDLE_DIR/summary.txt" cat "$PLUGIN_DIR/package.json" | grep -A 50 '"dependencies"' | head -60 >> "$BUNDLE_DIR/summary.txt" echo "" >> "$BUNDLE_DIR/summary.txt" fi # TypeScript config if [ -f "$PLUGIN_DIR/tsconfig.json" ]; then cp "$PLUGIN_DIR/tsconfig.json" "$BUNDLE_DIR/" fi ``` ### Step 4: Collect Vault Information ```bash # Vault information (adjust path) VAULT_DIR="$HOME/ObsidianVault" echo "--- Vault Information ---" >> "$BUNDLE_DIR/summary.txt" if [ -d "$VAULT_DIR/.obsidian" ]; then echo "Vault exists: YES" >> "$BUNDLE_DIR/summary.txt" # Installed plugins (names only, no sensitive data) echo "Installed plugins:" >> "$BUNDLE_DIR/summary.txt" ls "$VAULT_DIR/.obsidian/plugins/" 2>/dev/null >> "$BUNDLE_DIR/summary.txt" # Enabled plugins if [ -f "$VAULT_DIR/.obsidian/community-plugins.json" ]; then echo "Enabled plugins:" >> "$BUNDLE_DIR/summary.txt" cat "$VAULT_DIR/.obsidian/community-plugins.json" >> "$BUNDLE_DIR/summary.txt" fi fi echo "" >> "$BUNDLE_DIR/summary.txt" ``` ### Step 5: Collect Error Logs (from Console) ```markdown ## Manual Console Log Collection 1. Open Obsidian 2. Press Ctrl/Cmd+Shift+I to open Developer Tools 3. Go to Console tab 4. Right-click in console area 5. Select "Save as..." → save to debug bundle directory 6. Name it "console-log.txt" ``` ### Step 6: Collect Plugin Data (Sanitized) ```typescript // Add to your plugin for debug export export function exportDebugData(plugin: Plugin): object { return { pluginId: plugin.manifest.id, pluginVersion: plugin.manifest.version, obsidianVersion: process.versions?.electron ? 'desktop' : 'mobile', settings: sanitizeSettings(plugin.settings), timestamp: new Date().toISOString(), }; } function sanitizeSettings(settings: any): any { const sanitized = { ...settings }; // Remove sensitive fields const sensitiveKeys = ['apiKey', 'token', 'password', 'secret']; for (const key of sensitiveKeys) { if (key in sanitized) { sanitized[key] = '[REDACTED]'; } } return sanitized; } ``` ### Step 7: Package Bundle ```bash # Create archive tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR" echo "Bundle created: $BUNDLE_DIR.tar.gz" # Optional: Calculate checksum sha256sum "$BUNDLE_DIR.tar.gz" > "$BUNDLE_DIR.tar.gz.sha256" ``` ## Output - `obsidian-debug-YYYYMMDD-HHMMSS.tar.gz` archive containing: - `summary.txt` - System and plugin info - `manifest.json` - Plugin manifest - `tsconfig.json` - TypeScript configuration - `console-log.txt` - Console output (manual) - `plugin-data.json` - Sanitized plugin data ## Error Handling | Item | Purpose | Privacy | |------|---------|---------| | System info | Environment check | Safe | | Plugin manifest | Version/config | Safe | | Dependencies | Compatibility | Safe | | Console logs | Error messages | Review before sharing | | Settings | Configuration | REDACT secrets | | Vault path | Location | DO NOT share | ## Examples ### Automated Debug Command ```typescript // Add debug export command to plugin this.addCommand({ id: 'export-debug-data', name: 'Export Debug Data', callback: async () => { const debugData = { manifest: this.manifest, settings: this.sanitizeSettings(), obsidianVersion: this.app.version, plugins: Object.keys((this.app as any).plugins.plugins), }; const blob = new Blob([JSON.stringify(debugData, null, 2)], { type: 'application/json' }); const url = URL.createObjectURL(blob); const a = document.createElement('a'); a.href = url; a.download = `${this.manifest.id}-debug.json`; a.click(); URL.revokeObjectURL(url); new Notice('Debug data exported'); }, }); private sanitizeSettings(): any { const settings = { ...this.settings }; // Redact sensitive values for (const key of Object.keys(settings)) { if (key.toLowerCase().includes('key') || key.toLowerCase().includes('token') || key.toLowerCase().includes('secret')) { settings[key] = '[REDACTED]'; } } return settings; } ``` ### Minimal Bug Report Template ```markdown ## Bug Report **Plugin:** [Name] v[Version] **Obsidian:** v[Version] **OS:** [Windows/macOS/Linux] ### Steps to Reproduce 1. 2. 3. ### Expected Behavior [What should happen] ### Actual Behavior [What actually happens] ### Console Errors ``` [Paste errors here] ``` ### Debug Bundle [Attach obsidian-debug-*.tar.gz] ``` ### Privacy Checklist Before Sharing - [ ] API keys removed - [ ] Personal paths sanitized - [ ] Note content not included - [ ] Vault name generic or removed - [ ] No personal identifiers ## Resources - [Obsidian Bug Reports](https://forum.obsidian.md/c/bug-reports/7) - [Plugin Developer Help](https://forum.obsidian.md/c/developers/14) - [Obsidian Discord #plugin-dev](https://discord.gg/obsidianmd) ## Next Steps For rate limit issues, see `obsidian-rate-limits`.