​
Debugging Overview

When things go wrong—or when you’re curious about how a query was optimized—Isofold provides visibility into each stage of the pipeline.

This page covers how to:

  • Trace a query end-to-end
  • View rewrites and diffs
  • Enable deeper logging
  • Isolate unexpected behavior

​
Use Trace IDs

Every request through Isofold gets a high-entropy X-Isofold-Trace-Id header.

You can:

  • Pass your own trace ID from the client
  • Extract it from logs
  • Use it to correlate logs and metrics across systems
curl -H "X-Isofold-Trace-Id: debug-1234" https://myteam.proxy.isofold.com/...

Trace IDs are propagated through rewrites, warehouse calls, and logs.

​
Enable Debug Logs

To enable detailed logs in a self-hosted deployment:

export ISOFOLD_LOG_LEVEL=debug

This exposes:

  • Parsed + rewritten SQL
  • Cost estimates
  • Verification results
  • Execution metadata (duration, errors, plan nodes if available)

​
Log Output Example

[debug] trace_id=abc123 rewrite:
  FROM: SELECT * FROM users
  TO:   SELECT id, email FROM users

[cost] dry_run=ok original=$0.29 rewritten=$0.12
[result] verified=true row_count=1024

​
Query Diffing

You can view structured query diffs via:

  • Dashboard → Queries → Diff tab
  • API → /v1/queries/:id/diff
  • Verification mode output

​
Using Verification Mode

To catch subtle changes in output:

export ISOFOLD_VERIFY_MODE=true

This will:

  • Execute both the original and rewritten query
  • Compare outputs for exact match
  • Log mismatch with row-level inspection

​
Bypass Rewrite for a Query

If a query is sensitive or problematic, bypass rewriting:

  • Add a comment in the SQL:
-- isofold:skip
SELECT * FROM payments WHERE status = 'error'
  • Or configure a passthrough rule in your team settings

​
Metrics and Observability

Isofold exposes standard metrics when self-hosted:

  • Prometheus endpoint (/metrics)
  • Latency histograms
  • Rewrite coverage and success rate
  • Error types and frequencies

Want to learn more about which queries are being optimized and how much you’re saving? Go to Reports