---
name: clinic-diagnostic-files
description: |
  Diagnostic file lists and downloads through clinic-cli: plan replayer and OOM records.
---

# Diagnostic files

Use the parent CLI commands:

```text
python3 .opencode/skills/builtin/clinic-cli/scripts/clinic_cli.py diagnostic-files --help
python3 .opencode/skills/builtin/clinic-cli/scripts/clinic_cli.py diagnostic-file-download --help
```

List diagnostic files:

```text
python3 .opencode/skills/builtin/clinic-cli/scripts/clinic_cli.py diagnostic-files \
  --cluster-id <cluster_id> \
  --file-type plan_replayer \
  --start <start_unix> \
  --end <end_unix>
```

Download a file:

```text
python3 .opencode/skills/builtin/clinic-cli/scripts/clinic_cli.py diagnostic-file-download \
  --cluster-id <cluster_id> \
  --file-type plan_replayer \
  --key <file_key> \
  --filename <filename> \
  --unzip
```

The command output returns the downloaded path.

## File types

| Type | Use for |
| --- | --- |
| `plan_replayer` | Optimizer plan, schema/stats context, and SQL plan investigation. |
| `oom_record` | OOM-related goroutine, running SQL, heap, or memory artifacts. |
| `diagnostic` | Generic diagnostic file download when the key is known. |

## Analysis notes

### Plan replayer

- Inspect `errors.txt` when present.
- Review EXPLAIN / plan / optimizer text for row estimate gaps, index choice, join order, and hints.
- Check schema and stats metadata when the incident points to plan regression.
- Full plan parity may require a TiDB environment; static inspection is still useful for triage.

### OOM record

- Review goroutine and running SQL text files first.
- Use heap profiles when present to identify allocation hotspots.
- Correlate OOM records with memory metrics and logs before assigning root cause.

Avoid exposing customer SQL verbatim when a digest, redacted sample, or summarized plan issue is enough.