Debugging and Troubleshooting

Debugging and troubleshooting documentation for Geode covering query debugging, connection issues, performance problems, error diagnosis, logging configuration, distributed tracing, and systematic troubleshooting approaches. <h3 id="query-debugging" class="position-relative d-flex align-items-center group"> Query Debugging <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="query-debugging" aria-haspopup="dialog" aria-label="Share link: Query Debugging"> Share link </button> </h3><div id="headingShareModal" class="heading-share-modal" role="dialog" aria-modal="true" aria-labelledby="headingShareTitle" hidden> <div class="hsm-dialog" role="document"> <div class="hsm-header"> <h2 id="headingShareTitle" class="h6 mb-0 fw-bold">Share this section</h2> <button type="button" class="hsm-close" aria-label="Close"> </button> </div> <div class="hsm-body"> <label for="headingShareInput" class="form-label small text-muted mb-1 text-uppercase fw-bold" style="font-size: 0.7rem; letter-spacing: 0.5px;">Permalink</label> <div class="input-group mb-4 hsm-url-group"> <input id="headingShareInput" type="text" class="form-control font-monospace" readonly aria-readonly="true" style="font-size: 0.85rem;" /> <button class="btn btn-primary hsm-copy" type="button" aria-label="Copy" title="Copy"> </button> </div> <div class="small fw-bold mb-2 text-muted text-uppercase" style="font-size: 0.7rem; letter-spacing: 0.5px;">Share via</div> <div class="hsm-share-grid"> <a id="share-twitter" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Twitter </a> <a id="share-linkedin" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> LinkedIn </a> <a id="share-facebook" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Facebook </a> </div> </div> </div> </div> <style> .heading-share-modal { position: fixed; inset: 0; display: flex; justify-content: center; align-items: center; background: rgba(0, 0, 0, 0.6); z-index: 1050; padding: 1rem; backdrop-filter: blur(4px); -webkit-backdrop-filter: blur(4px); } .heading-share-modal[hidden] { display: none !important; } .hsm-dialog { max-width: 420px; width: 100%; background: var(--bs-body-bg, #fff); color: var(--bs-body-color, #212529); border: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); border-radius: 1rem; box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25); overflow: hidden; animation: hsm-fade-in 0.2s ease-out; } @keyframes hsm-fade-in { from { opacity: 0; transform: scale(0.95); } to { opacity: 1; transform: scale(1); } } [data-bs-theme="dark"] .hsm-dialog { background: #1e293b; border-color: rgba(255,255,255,0.1); color: #f8f9fa; } .hsm-header { display: flex; justify-content: space-between; align-items: center; padding: 1rem 1.5rem; border-bottom: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); background: rgba(0,0,0,0.02); } [data-bs-theme="dark"] .hsm-header { background: rgba(255,255,255,0.02); border-color: rgba(255,255,255,0.1); } .hsm-close { background: transparent; border: none; color: inherit; opacity: 0.5; padding: 0.25rem 0.5rem; border-radius: 0.25rem; font-size: 1.2rem; line-height: 1; transition: opacity 0.2s; } .hsm-close:hover { opacity: 1; } .hsm-body { padding: 1.5rem; } .hsm-url-group { display: flex !important; align-items: stretch; } .hsm-url-group .form-control { flex: 1; min-width: 0; margin: 0; background: var(--bs-secondary-bg, #f8f9fa); border-color: var(--bs-border-color, #dee2e6); border-top-right-radius: 0; border-bottom-right-radius: 0; height: 42px; } .hsm-url-group .btn { flex: 0 0 auto; margin: 0; margin-left: -1px; border-top-left-radius: 0; border-bottom-left-radius: 0; height: 42px; display: flex; align-items: center; justify-content: center; padding: 0 1.25rem; z-index: 2; } [data-bs-theme="dark"] .hsm-url-group .form-control { background: #0f172a; border-color: #334155; color: #e2e8f0; } .hsm-share-grid { display: flex; flex-direction: column; gap: 0.5rem; } .hsm-share-grid .btn { display: flex; align-items: center; justify-content: center; font-size: 0.9rem; padding: 0.6rem; border-color: var(--bs-border-color); width: 100%; } [data-bs-theme="dark"] .hsm-share-grid .btn { color: #e2e8f0; border-color: #475569; } [data-bs-theme="dark"] .hsm-share-grid .btn:hover { background: #334155; border-color: #cbd5e1; } </style> <script> (function(){ const modal = document.getElementById('headingShareModal'); if(!modal) return; const input = modal.querySelector('#headingShareInput'); const copyBtn = modal.querySelector('.hsm-copy'); const twitter = modal.querySelector('#share-twitter'); const linkedin = modal.querySelector('#share-linkedin'); const facebook = modal.querySelector('#share-facebook'); const closeBtn = modal.querySelector('.hsm-close'); let lastFocus=null; let trapBound=false; function buildUrl(id){ return window.location.origin + window.location.pathname + '#' + id; } function isOpen(){ return !modal.hasAttribute('hidden'); } function hydrate(id){ const url=buildUrl(id); input.value=url; const enc=encodeURIComponent(url); const text=encodeURIComponent(document.title); if(twitter) twitter.href=`https://twitter.com/intent/tweet?url=${enc}&text=${text}`; if(linkedin) linkedin.href=`https://www.linkedin.com/sharing/share-offsite/?url=${enc}`; if(facebook) facebook.href=`https://www.facebook.com/sharer/sharer.php?u=${enc}`; } function openModal(id){ lastFocus=document.activeElement; hydrate(id); if(!isOpen()){ modal.removeAttribute('hidden'); } requestAnimationFrame(()=>{ input.focus(); }); trapFocus(); } function closeModal(){ if(!isOpen()) return; modal.setAttribute('hidden',''); if(lastFocus && typeof lastFocus.focus==='function') lastFocus.focus(); } function copyCurrent(){ try{ navigator.clipboard.writeText(input.value).then(()=>feedback(true),()=>fallback()); } catch(e){ fallback(); } } function fallback(){ input.select(); try{ document.execCommand('copy'); feedback(true);}catch(e){ feedback(false);} } function feedback(ok){ if(!copyBtn) return; const icon=copyBtn.querySelector('i'); if(!icon) return; const prev=copyBtn.getAttribute('data-prev')||icon.className; if(!copyBtn.getAttribute('data-prev')) copyBtn.setAttribute('data-prev',prev); icon.className= ok ? 'fa-duotone fa-clipboard-check':'fa-duotone fa-circle-exclamation'; setTimeout(()=>{ icon.className=prev; },1800); } function handleShareClick(e){ e.preventDefault(); const btn=e.currentTarget; const id=btn.getAttribute('data-share-target'); if(id) openModal(id); } function bindShareButtons(){ document.querySelectorAll('.h-share').forEach(btn=>{ if(!btn.dataset.hShareBound){ btn.addEventListener('click', handleShareClick); btn.dataset.hShareBound='1'; } }); } bindShareButtons(); if(document.readyState==='loading'){ document.addEventListener('DOMContentLoaded', bindShareButtons); } else { requestAnimationFrame(bindShareButtons); } document.addEventListener('click', function(e){ const shareBtn=e.target.closest && e.target.closest('.h-share'); if(shareBtn && !shareBtn.dataset.hShareBound){ handleShareClick.call(shareBtn, e); } }, true); document.addEventListener('click', e=>{ if(e.target===modal) closeModal(); if(e.target.closest && e.target.closest('.hsm-close')){ e.preventDefault(); closeModal(); } if(copyBtn && (e.target===copyBtn || (e.target.closest && e.target.closest('.hsm-copy')))) { e.preventDefault(); copyCurrent(); } }); document.addEventListener('keydown', e=>{ if(e.key==='Escape' && isOpen()) closeModal(); }); function trapFocus(){ if(trapBound) return; trapBound=true; modal.addEventListener('keydown', f=>{ if(f.key==='Tab' && isOpen()){ const focusable=[...modal.querySelectorAll('a[href],button,input,textarea,select,[tabindex]:not([tabindex="-1"])')].filter(el=>!el.hasAttribute('disabled')); if(!focusable.length) return; const first=focusable[0]; const last=focusable[focusable.length-1]; if(f.shiftKey && document.activeElement===first){ f.preventDefault(); last.focus(); } else if(!f.shiftKey && document.activeElement===last){ f.preventDefault(); first.focus(); } } }); } if(closeBtn) closeBtn.addEventListener('click', e=>{ e.preventDefault(); closeModal(); }); })(); </script> <h4 id="using-explain" class="position-relative d-flex align-items-center group"> Using EXPLAIN <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="using-explain" aria-haspopup="dialog" aria-label="Share link: Using EXPLAIN"> Share link </button> </h4>Understand query execution without running it: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">EXPLAIN MATCH (u:User {email: $email})-[:PURCHASED]->(p:Product) WHERE p.price > 100 RETURN p.name, p.price ORDER BY p.price DESC </code></pre></div>Output shows: <ul> <li>Execution plan operators</li> <li>Index usage</li> <li>Estimated cardinalities</li> <li>Join strategies</li> </ul> <h4 id="using-profile" class="position-relative d-flex align-items-center group"> Using PROFILE <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="using-profile" aria-haspopup="dialog" aria-label="Share link: Using PROFILE"> Share link </button> </h4>Measure actual query performance: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">PROFILE MATCH (u:User)-[:FOLLOWS*2..3]->(recommendation:User) WHERE NOT EXISTS {MATCH (u)-[:FOLLOWS]->(recommendation)} RETURN recommendation.name, COUNT(*) AS score ORDER BY score DESC LIMIT 10 </code></pre></div>Profile provides: <ul> <li>Actual execution times per operator</li> <li>Actual vs. estimated row counts</li> <li>Memory usage</li> <li>Cache hits/misses</li> </ul> <h4 id="debugging-slow-queries" class="position-relative d-flex align-items-center group"> Debugging Slow Queries <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="debugging-slow-queries" aria-haspopup="dialog" aria-label="Share link: Debugging Slow Queries"> Share link </button> </h4>Step-by-step approach: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">import geode_client async def debug_slow_query(client, query, params=None): """Debug slow query execution.""" # Step 1: Profile the query profiled, _ = await client.query(f"PROFILE {query}", params) print("=== Profile Results ===") print_profile(profiled) # Step 2: Check for full table scans explained, _ = await client.query(f"EXPLAIN {query}", params) if has_full_scan(explained): print("WARNING: Query contains full table scan") print("Consider adding index on scanned properties") # Step 3: Verify index usage indexes, _ = await client.query("SHOW INDEXES") print("=== Available Indexes ===") for idx in indexes: print(f" {idx['name']}: {idx['columns']}") # Step 4: Check statistics freshness stats, _ = await client.query("SELECT * FROM system.statistics") if is_stale(stats): print("WARNING: Statistics may be outdated") print("Run: ANALYZE") </code></pre></div> <h4 id="common-query-issues" class="position-relative d-flex align-items-center group"> Common Query Issues <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="common-query-issues" aria-haspopup="dialog" aria-label="Share link: Common Query Issues"> Share link </button> </h4>Issue: Unexpected results count <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Check what's actually matching result, _ = await client.query(""" MATCH (u:User) WHERE u.email = $email RETURN COUNT(*) AS user_count """, {"email": "[email protected]"}) print(f"Found {result.rows[0]['user_count']} users") # Expected 1, got 0 # Debug: Check exact data all_users, _ = await client.query("MATCH (u:User) RETURN u.email") print("All emails:", [u["u.email"] for u in all_users]) # Common issues: # - Email case sensitivity: use lower() function # - Whitespace: use trim() # - Wrong parameter name </code></pre></div>Issue: Empty result set <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Original query returns nothing MATCH (a:User {name: 'Alice'})-[:KNOWS]->(b:User) RETURN b.name -- Debug step 1: Check if Alice exists MATCH (a:User) WHERE a.name = 'Alice' RETURN a -- Debug step 2: Check if relationships exist MATCH (a:User {name: 'Alice'})-[r]-() RETURN type(r), count(r) -- Debug step 3: Check relationship direction MATCH (a:User {name: 'Alice'})<-[:KNOWS]-(b:User) RETURN b.name -- Try reverse direction </code></pre></div> <h3 id="connection-debugging" class="position-relative d-flex align-items-center group"> Connection Debugging <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="connection-debugging" aria-haspopup="dialog" aria-label="Share link: Connection Debugging"> Share link </button> </h3> <h4 id="connection-issues" class="position-relative d-flex align-items-center group"> Connection Issues <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="connection-issues" aria-haspopup="dialog" aria-label="Share link: Connection Issues"> Share link </button> </h4>Cannot connect to server: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">import geode_client import logging import asyncio logging.basicConfig(level=logging.DEBUG) async def check_connection(): try: client = geode_client.open_database("quic://localhost:3141") async with client.connection() as conn: await asyncio.wait_for(conn.query("RETURN 1 AS ok"), timeout=5.0) return "success" except geode_client.GeodeConnectionError as e: return f"failed: {e}" # Check: # 1. Is server running? `ps aux | grep geode` # 2. Is port correct? Default is 3141 # 3. Firewall blocking? `telnet localhost 3141` # 4. TLS certificate issues? </code></pre></div>TLS/Certificate errors: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Disable certificate verification (dev only!) client = geode_client.Client( host="localhost", port=3141, skip_verify=True # NEVER use in production ) # Or provide a trusted CA certificate client = geode_client.Client( host="localhost", port=3141, ca_cert="/path/to/ca.pem" ) </code></pre></div>Connection timeouts: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Increase timeout with asyncio wait_for client = geode_client.open_database("quic://localhost:3141") async with client.connection() as conn: await asyncio.wait_for(conn.query("RETURN 1 AS ok"), timeout=60.0) </code></pre></div> <h4 id="authentication-issues" class="position-relative d-flex align-items-center group"> Authentication Issues <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="authentication-issues" aria-haspopup="dialog" aria-label="Share link: Authentication Issues"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">try: client = geode_client.open_database("quic://localhost:3141") async with client.connection() as conn: auth = geode_client.AuthClient(conn) await auth.login("alice", "wrong_password") except geode_client.AuthError as e: print(f"Authentication failed: {e}") # Check: # 1. Username correct? # 2. Password correct? # 3. User exists in Geode? # 4. Check server logs for auth failures </code></pre></div> <h3 id="performance-debugging" class="position-relative d-flex align-items-center group"> Performance Debugging <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="performance-debugging" aria-haspopup="dialog" aria-label="Share link: Performance Debugging"> Share link </button> </h3> <h4 id="identifying-bottlenecks" class="position-relative d-flex align-items-center group"> Identifying Bottlenecks <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="identifying-bottlenecks" aria-haspopup="dialog" aria-label="Share link: Identifying Bottlenecks"> Share link </button> </h4>Monitor query execution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- View slow queries SELECT query_id, query_text, execution_time_ms, rows_returned FROM system.query_log WHERE execution_time_ms > 1000 ORDER BY execution_time_ms DESC LIMIT 20 </code></pre></div>Check resource usage: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Cache hit rates SELECT * FROM system.cache_statistics -- Active connections SELECT COUNT(*) FROM system.sessions WHERE active = true -- Lock contention SELECT * FROM system.locks WHERE waiting = true </code></pre></div> <h4 id="memory-issues" class="position-relative d-flex align-items-center group"> Memory Issues <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="memory-issues" aria-haspopup="dialog" aria-label="Share link: Memory Issues"> Share link </button> </h4>Out of memory errors: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Reduce result set size result, _ = await client.query(""" MATCH (n:Node) RETURN n LIMIT 10000 -- Add limit """) # Use pagination offset = 0 page_size = 1000 while True: page, _ = await client.query(""" MATCH (n:Node) RETURN n ORDER BY n.id SKIP $offset LIMIT $page_size """, {"offset": offset, "page_size": page_size}) if not page: break process_page(page) offset += page_size </code></pre></div>Check server memory: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Server status ./geode status # System memory free -h # Geode process memory ps aux | grep geode </code></pre></div> <h3 id="error-diagnosis" class="position-relative d-flex align-items-center group"> Error Diagnosis <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="error-diagnosis" aria-haspopup="dialog" aria-label="Share link: Error Diagnosis"> Share link </button> </h3> <h4 id="understanding-error-messages" class="position-relative d-flex align-items-center group"> Understanding Error Messages <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="understanding-error-messages" aria-haspopup="dialog" aria-label="Share link: Understanding Error Messages"> Share link </button> </h4>Syntax errors: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">Error: Syntax error at line 2, column 15 MATCH (u:User) WERE u.name = 'Alice' ^~~~ Expected: WHERE </code></pre></div>Fix: Correct typo (<code>WERE</code> → <code>WHERE</code>) Constraint violations: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gdscript3" data-lang="gdscript3">Error: Constraint violation: Unique constraint violated Index: user_email_unique Value: '[email protected]' already exists </code></pre></div>Fix: Check for existing data before INSERT, or use MERGE Transaction conflicts: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">Error: Transaction aborted due to serialization failure Conflicting transaction: txn_456 Retry recommended </code></pre></div>Fix: Implement retry logic with exponential backoff <h4 id="error-handling-patterns" class="position-relative d-flex align-items-center group"> Error Handling Patterns <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="error-handling-patterns" aria-haspopup="dialog" aria-label="Share link: Error Handling Patterns"> Share link </button> </h4>Python error handling: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">from geode_client import GeodeError, QueryError async def execute_with_retry(client, query, params=None, max_retries=3): """Execute query with automatic retry on conflicts.""" for attempt in range(max_retries): try: page, _ = await client.query(query, params) return page except QueryError as exc: message = str(exc).lower() if "40502" in message: if attempt == max_retries - 1: raise await asyncio.sleep(2 ** attempt) # Exponential backoff continue if "syntax" in message: logging.error(f"Syntax error: {exc}") raise logging.warning(f"Query failed: {exc}") raise </code></pre></div> <h3 id="logging-and-monitoring" class="position-relative d-flex align-items-center group"> Logging and Monitoring <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="logging-and-monitoring" aria-haspopup="dialog" aria-label="Share link: Logging and Monitoring"> Share link </button> </h3> <h4 id="client-side-logging" class="position-relative d-flex align-items-center group"> Client-Side Logging <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="client-side-logging" aria-haspopup="dialog" aria-label="Share link: Client-Side Logging"> Share link </button> </h4>Python logging: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">import logging # Enable debug logging logging.basicConfig( level=logging.DEBUG, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s' ) # Geode client logs all operations client = geode_client.open_database("localhost:3141") # Custom logging logger = logging.getLogger("myapp") logger.info("Executing user query") result, _ = await client.query("MATCH (u:User) RETURN count(u)") logger.info(f"Found {result.rows[0]['count(u)']} users") </code></pre></div>Go logging: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go">import ( "log" "geodedb.com/geode" ) // Enable debug logging geode.SetLogLevel(geode.LogLevelDebug) // Execute with logging log.Println("Connecting to Geode") db, err := geode.Connect(ctx, "localhost:3141") if err != nil { log.Fatalf("Connection failed: %v", err) } </code></pre></div> <h4 id="server-side-logging" class="position-relative d-flex align-items-center group"> Server-Side Logging <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="server-side-logging" aria-haspopup="dialog" aria-label="Share link: Server-Side Logging"> Share link </button> </h4>Configure log level: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Start server with debug logging ./geode serve --log-level debug # Or in config # geode.yaml logging: level: debug file: /var/log/geode/geode.log rotate: true max_size: 100MB max_files: 10 </code></pre></div>Log categories: <ul> <li><code>query</code>: Query execution</li> <li><code>transaction</code>: Transaction lifecycle</li> <li><code>storage</code>: Storage operations</li> <li><code>network</code>: Network communication</li> <li><code>auth</code>: Authentication/authorization</li> </ul> <h4 id="distributed-tracing" class="position-relative d-flex align-items-center group"> Distributed Tracing <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="distributed-tracing" aria-haspopup="dialog" aria-label="Share link: Distributed Tracing"> Share link </button> </h4>Enable tracing with OpenTelemetry: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">from opentelemetry import trace from opentelemetry.instrumentation.geode import GeodeInstrumentor # Initialize tracing tracer_provider = trace.TracerProvider() trace.set_tracer_provider(tracer_provider) # Instrument Geode client GeodeInstrumentor().instrument() # Queries automatically traced async with tracer.start_as_current_span("user_query"): result, _ = await client.query("MATCH (u:User) RETURN u") </code></pre></div> <h3 id="troubleshooting-checklist" class="position-relative d-flex align-items-center group"> Troubleshooting Checklist <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="troubleshooting-checklist" aria-haspopup="dialog" aria-label="Share link: Troubleshooting Checklist"> Share link </button> </h3> <h4 id="before-filing-bug-report" class="position-relative d-flex align-items-center group"> Before Filing Bug Report <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="before-filing-bug-report" aria-haspopup="dialog" aria-label="Share link: Before Filing Bug Report"> Share link </button> </h4><ol> <li>Reproduce the issue: Can you consistently trigger it?</li> <li>Check version: <code>./geode version</code> - Is it the latest?</li> <li>Review logs: Server and client logs for errors</li> <li>Isolate the problem: Minimal reproducible example</li> <li>Check documentation: Is this expected behavior?</li> <li>Search existing issues: Has someone reported this?</li> </ol> <h4 id="information-to-include" class="position-relative d-flex align-items-center group"> Information to Include <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="information-to-include" aria-haspopup="dialog" aria-label="Share link: Information to Include"> Share link </button> </h4><ul> <li>Geode version</li> <li>Client library version</li> <li>Operating system</li> <li>Query that triggers the issue</li> <li>Error message (full stack trace)</li> <li>Relevant log excerpts</li> <li>Steps to reproduce</li> </ul> <h3 id="related-topics" class="position-relative d-flex align-items-center group"> Related Topics <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="related-topics" aria-haspopup="dialog" aria-label="Share link: Related Topics"> Share link </button> </h3><ul> <li><a href="/tags/monitoring/" >Monitoring</a> - Production monitoring</li> <li><a href="/tags/profiling/" >Profiling</a> - Performance profiling</li> </ul> <h3 id="further-reading" class="position-relative d-flex align-items-center group"> Further Reading <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="further-reading" aria-haspopup="dialog" aria-label="Share link: Further Reading"> Share link </button> </h3><ul> <li><a href="/docs/query/explain-profile/" >Explain and Profile</a> - Query plan analysis and profiling</li> <li><a href="/docs/reference/error-codes/" >Error Codes</a> - Error code reference</li> <li><a href="/docs/query/performance-tuning/" >Performance Tuning</a> - Optimization techniques</li> <li><a href="/docs/guides/troubleshooting/" >Troubleshooting Guide</a> - Common issues and solutions</li> </ul> <h3 id="advanced-debugging-techniques" class="position-relative d-flex align-items-center group"> Advanced Debugging Techniques <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="advanced-debugging-techniques" aria-haspopup="dialog" aria-label="Share link: Advanced Debugging Techniques"> Share link </button> </h3> <h4 id="query-performance-debugging" class="position-relative d-flex align-items-center group"> Query Performance Debugging <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="query-performance-debugging" aria-haspopup="dialog" aria-label="Share link: Query Performance Debugging"> Share link </button> </h4>Systematic performance analysis: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">class QueryDebugger: def __init__(self, client): self.client = client async def analyze_query(self, query, params=None): """Comprehensive query analysis""" report = {} # 1. Get explain plan explain, _ = await self.client.query(f"EXPLAIN {query}", params) report['explain'] = self.parse_explain(explain) # 2. Profile execution profile, _ = await self.client.query(f"PROFILE {query}", params) report['profile'] = self.parse_profile(profile) # 3. Check index usage indexes, _ = await self.client.query("SHOW INDEXES") report['indexes_used'] = self.find_used_indexes(explain, indexes) report['indexes_missing'] = self.suggest_indexes(explain, indexes) # 4. Analyze cardinality report['cardinality'] = await self.analyze_cardinality(query, params) # 5. Check for anti-patterns report['anti_patterns'] = self.detect_anti_patterns(query) return report def detect_anti_patterns(self, query): """Detect common query anti-patterns""" issues = [] # Cartesian product if 'MATCH' in query and query.count('MATCH') > 1 and 'WHERE' not in query: issues.append({ 'type': 'cartesian_product', 'severity': 'high', 'message': 'Multiple MATCH clauses without WHERE may cause cartesian product' }) # Unbounded variable-length path if re.search(r'\[\*\]', query): issues.append({ 'type': 'unbounded_path', 'severity': 'critical', 'message': 'Unbounded variable-length path can cause performance issues' }) # Missing LIMIT if 'RETURN' in query and 'LIMIT' not in query: issues.append({ 'type': 'missing_limit', 'severity': 'medium', 'message': 'Query without LIMIT may return unbounded results' }) return issues async def analyze_cardinality(self, query, params): """Analyze result set cardinality""" # Extract pattern from query pattern = self.extract_pattern(query) # Estimate cardinality estimate, _ = await self.client.query(f""" EXPLAIN {query} """, params) return { 'estimated_rows': estimate.get('estimated_rows'), 'pattern_selectivity': estimate.get('selectivity') } </code></pre></div> <h4 id="connection-debugging-1" class="position-relative d-flex align-items-center group"> Connection Debugging <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="connection-debugging-1" aria-haspopup="dialog" aria-label="Share link: Connection Debugging"> Share link </button> </h4>Diagnose connection issues: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">import asyncio import logging import time import geode_client async def debug_connection(url, timeout=10): """Debug connection issues.""" results = {} client = geode_client.open_database(url) # 1. Test basic connectivity try: async with client.connection() as conn: await asyncio.wait_for(conn.query("RETURN 1 AS ok"), timeout=timeout) results['connectivity'] = 'success' except asyncio.TimeoutError: results['connectivity'] = 'timeout' results['error'] = f'Connection timeout after {timeout}s' return results except Exception as e: results['connectivity'] = 'failed' results['error'] = str(e) return results # 2. Test query execution try: async with client.connection() as conn: await conn.query("MATCH (n) RETURN n LIMIT 1") results['query_execution'] = 'success' except Exception as e: results['query_execution'] = 'failed' results['query_error'] = str(e) # 3. Measure latency latencies = [] async with client.connection() as conn: for _ in range(10): start = time.time() await conn.query("RETURN 1 AS ok") latencies.append((time.time() - start) * 1000) results['latency'] = { 'min': min(latencies), 'max': max(latencies), 'avg': sum(latencies) / len(latencies), 'p95': sorted(latencies)[int(len(latencies) * 0.95)] } return results </code></pre></div> <h4 id="transaction-debugging" class="position-relative d-flex align-items-center group"> Transaction Debugging <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="transaction-debugging" aria-haspopup="dialog" aria-label="Share link: Transaction Debugging"> Share link </button> </h4>Debug transaction issues: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">class TransactionDebugger: def __init__(self, client): self.client = client self.logger = logging.getLogger(__name__) async def debug_transaction(self, operation): """Debug transaction execution with detailed logging.""" async with self.client.connection() as conn: await conn.begin() try: self.logger.info("Transaction started") result = await operation(conn) await conn.commit() self.logger.info("Transaction committed") return result except Exception as exc: self.logger.error(f"Transaction failed: {exc}") await conn.rollback() raise </code></pre></div> <h4 id="memory-profiling" class="position-relative d-flex align-items-center group"> Memory Profiling <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="memory-profiling" aria-haspopup="dialog" aria-label="Share link: Memory Profiling"> Share link </button> </h4>Track memory usage: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">import tracemalloc import psutil class MemoryProfiler: def __init__(self): self.snapshots = [] async def profile_query(self, client, query, params=None): """Profile memory usage during query execution""" # Start tracing tracemalloc.start() process = psutil.Process() # Initial snapshot mem_before = process.memory_info().rss / 1024 / 1024 # MB snapshot_before = tracemalloc.take_snapshot() # Execute query result, _ = await client.query(query, params) # Final snapshot mem_after = process.memory_info().rss / 1024 / 1024 # MB snapshot_after = tracemalloc.take_snapshot() # Calculate differences top_stats = snapshot_after.compare_to(snapshot_before, 'lineno') # Stop tracing tracemalloc.stop() return { 'memory_used_mb': mem_after - mem_before, 'top_allocations': [ { 'file': stat.traceback.format()[0], 'size_mb': stat.size_diff / 1024 / 1024 } for stat in top_stats[:10] ], 'result_size': len(result.rows) } </code></pre></div> <h4 id="distributed-tracing-1" class="position-relative d-flex align-items-center group"> Distributed Tracing <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="distributed-tracing-1" aria-haspopup="dialog" aria-label="Share link: Distributed Tracing"> Share link </button> </h4>End-to-end request tracing: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">from opentelemetry import trace from opentelemetry.instrumentation.geode import GeodeInstrumentor # Initialize tracing tracer = trace.get_tracer(__name__) GeodeInstrumentor().instrument() async def traced_operation(client): """Operation with distributed tracing""" with tracer.start_as_current_span("user_registration") as span: span.set_attribute("user.email", "[email protected]") # Database operation is automatically traced result, _ = await client.query(""" CREATE (u:User { name: $name, email: $email }) RETURN u.id """, {"name": "Alice", "email": "[email protected]"}) span.set_attribute("user.id", result.rows[0]['u.id']) # Additional span for email sending with tracer.start_as_current_span("send_welcome_email"): await send_email(result.rows[0]['u.id']) return result </code></pre></div> <h4 id="error-analysis" class="position-relative d-flex align-items-center group"> Error Analysis <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="error-analysis" aria-haspopup="dialog" aria-label="Share link: Error Analysis"> Share link </button> </h4>Systematic error diagnosis: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">class ErrorAnalyzer: def __init__(self): self.error_patterns = { 'UniqueConstraintViolation': self.handle_unique_violation, 'SerializationFailure': self.handle_serialization_failure, 'SyntaxError': self.handle_syntax_error, 'ConnectionError': self.handle_connection_error } async def analyze_error(self, error, context): """Analyze and provide remediation for errors""" error_type = type(error).__name__ if error_type in self.error_patterns: handler = self.error_patterns[error_type] return await handler(error, context) return { 'type': 'unknown', 'message': str(error), 'suggestion': 'Check server logs for details' } async def handle_unique_violation(self, error, context): """Handle unique constraint violations""" # Extract violated constraint constraint = error.constraint_name value = error.violated_value return { 'type': 'UniqueConstraintViolation', 'constraint': constraint, 'value': value, 'suggestion': f'Value "{value}" already exists. Use MERGE instead of CREATE, or change the value.', 'query_fix': f'MERGE (n:Node {{key: $value}}) ON CREATE SET n.created_at = datetime()' } async def handle_serialization_failure(self, error, context): """Handle serialization failures""" return { 'type': 'SerializationFailure', 'message': 'Transaction aborted due to concurrent modification', 'suggestion': 'Implement retry logic with exponential backoff', 'code_example': ''' @retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1)) async def operation(): async with client.connection() as tx: await tx.begin() # Your operation here pass ''' } </code></pre></div>Browse the tagged content below to discover comprehensive debugging guides, troubleshooting techniques, and diagnostic tools for Geode applications.

Popular

Related Articles

Troubleshooting Guide

Query Profiling Guide

Error Handling Guide