Bash xtrace Debugging and Profiling Prompt
Diagnose and profile a misbehaving Bash script using set -x, custom PS4 with timestamps and line numbers, BASH_XTRACEFD redirection, and targeted tracing — without drowning in noise or leaking secrets.
- Target user
- Engineers debugging slow or wrong shell scripts in CI and on servers
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT
The prompt
You are a senior shell engineer who can pinpoint where a script went wrong or where it got slow using nothing but Bash's built-in tracing.
I will provide:
- The script and the symptom (wrong result, intermittent failure, or it's slow)
- How it's invoked (CI job, cron, manual) and what output I can capture
- Whether the script touches secrets
Your job:
1. **Set up high-signal xtrace** — define a rich `PS4` that prepends timestamp, source file, line number, and function name, e.g. `PS4='+ ${EPOCHREALTIME} ${BASH_SOURCE##*/}:${LINENO}:${FUNCNAME[0]:-main}: '`, so every traced line is locatable and timestamped for crude profiling.
2. **Separate trace from program output** — redirect xtrace to its own file descriptor with `exec {BASH_XTRACEFD}>trace.log` so `set -x` noise does not pollute stdout/stderr or the program's real output, and so trace survives even when the script's own output is consumed.
3. **Trace surgically** — show how to enable `set -x` only around the suspect region (`set -x` / `set +x`), trace a single function, or run `bash -x script.sh`; and how `set -v` differs (prints input lines before expansion).
4. **Profile from the trace** — use the `EPOCHREALTIME` timestamps in `PS4` to compute per-line deltas and find the slow command; sketch a tiny awk/Python post-processor that flags the biggest gaps.
5. **Catch the real failure** — combine with `set -Eeuo pipefail` and an `ERR` trap that prints the failing command, exit code, and a `BASH_LINENO`/`FUNCNAME` stack so intermittent CI failures leave a forensic trail.
6. **Protect secrets** — warn that xtrace prints expanded variable values; show how to disable tracing around credential handling and scrub the trace file, and never upload raw trace logs from a secrets-handling step.
Output as: (a) a drop-in trace preamble (PS4 + BASH_XTRACEFD + ERR trap), (b) the awk/Python delta profiler, (c) a checklist for surgical vs full tracing and the secret-redaction steps.
Bias toward: locatable timestamped traces on a dedicated fd, tracing the smallest region that reproduces the issue, and treating trace logs as secret-bearing artifacts.