Debugging

When something is wrong with a running TiDB — locally or in production — the first stop is usually the HTTP status server, the slow log, and the structured logs.

Logs

• Logging goes through github.com/pingcap/log wrapped by pkg/util/logutil/log.go. Always log via the logutil helpers; they attach connection ID, session vars, and SQL digest where appropriate.
• Default log file: configured via --log-file or log.file.filename in the TOML config (pkg/config/config.go).
• Log level is set via --L / --log-level or log.level. Levels: debug, info, warn, error, fatal.
• Set log level at runtime via the HTTP API:

  curl -X POST -d '{"level":"debug"}' http://localhost:10080/log/level

  See docs/tidb_http_api.md for the full HTTP surface.

Slow log

• Default location: tidb-slow.log next to the main log.
• Threshold: tidb_slow_log_threshold system variable (default 300 ms).
• Format and parser: pkg/executor/slow_query.go parses the slow log into INFORMATION_SCHEMA.SLOW_QUERY and CLUSTER_SLOW_QUERY.
• Aggregated view: INFORMATION_SCHEMA.STATEMENTS_SUMMARY and STATEMENTS_SUMMARY_HISTORY (built by pkg/util/stmtsummary/v2/).

HTTP introspection

The TiDB status server (default :10080) exposes a large surface documented in docs/tidb_http_api.md. Useful endpoints when debugging:

Endpoint	What it shows
/info	Server version, build info
/info/all	Cluster-wide view
/debug/pprof/...	Go pprof (cpu, heap, goroutine, block)
/metrics	Prometheus metrics
/schema	Current infoschema
/ddl/history	Recent DDL jobs
/regions/<table>	Region distribution for a table
/stats/dump/<db>/<table>	Statistics snapshot for replay
/log/level	Get/set runtime log level
/plan_replayer/dump	Dump a plan replayer bundle
/binlog/recover	Resume binlog after pause

In-process diagnostics

• Plan replayer: PLAN REPLAYER DUMP EXPLAIN ... collects the SQL, plan, statistics, schema, and config needed to reproduce a query plan elsewhere. The dump logic is in pkg/domain/plan_replayer.go / plan_replayer_dump.go.
• EXPLAIN and EXPLAIN ANALYZE: implemented in pkg/executor/explain.go and pkg/planner/core/encode.go. Verbose runtime stats come from pkg/util/execdetails/.
• Top-N slow queries held in memory: pkg/domain/topn_slow_query.go.
• Deadlock history: pkg/util/deadlockhistory/ exposes INFORMATION_SCHEMA.DEADLOCKS.
• Plan cache: INFORMATION_SCHEMA.TIDB_PLAN_CACHE_STATUS and tidb_decode_plan / tidb_decode_binary_plan SQL functions help inspect cached plans.

Failpoints in production-like debugging

Failpoints are compiled out unless tests explicitly enable them, but the same library can be poked at runtime via the HTTP endpoint registered by pkg/server/http_status.go (/fail/...) when the binary is built with failpoint support. In practice this is only useful when reproducing test failures locally; production binaries have failpoints disabled.

Common error categories

• Lock conflict, write conflict, GC too early — see pkg/store/driver/error/ and the TiKV-side semantics doc. The tidb_disable_txn_auto_retry and tidb_retry_limit system variables control retry behaviour.
• DDL stuck — ADMIN SHOW DDL JOBS and ADMIN CANCEL DDL JOBS <id>. Implementations in pkg/executor/operate_ddl_jobs.go and pkg/ddl/ddl.go.
• Plan regressions — capture with tidb_capture_plan_baselines and force a known-good plan via CREATE BINDING (see pkg/bindinfo/).
• Statistics stale — SHOW STATS_HEALTHY, ANALYZE TABLE. Auto-analyze logic lives in pkg/statistics/handle/autoanalyze/.
• Resource control — INFORMATION_SCHEMA.RESOURCE_GROUPS, mysql.tidb_runaway_queries table; logic in pkg/resourcegroup/runaway/.

Where to read more

• HTTP API: docs/tidb_http_api.md.
• DDL state machines: docs/agents/ddl/README.md.
• Statistics: pkg/statistics/ (start at handle/handle.go).
• Slow log format: pkg/executor/slow_query.go.