> ## Documentation Index
> Fetch the complete documentation index at: https://docs.isofold.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Debugging

> Tools and strategies for investigating Isofold behavior in production or staging.

## 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

```bash theme={null}
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:

```bash theme={null}
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

```text theme={null}
[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:

```bash theme={null}
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:

```sql theme={null}
-- 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](/billing/reports)