# NGM API Trace ID 与 Statements List 日志增强

## Summary

- 给所有 NGM Gin 请求统一补 `X-Trace-ID` 响应头，包括 `/ngm/api/v1/statements/*`、`/ngm/api/v1/slow_query/*` 以及 DBAAS 转发路径。
- 让 NGM access log 和 `/statements/list` 业务日志都能打印同一个 `trace_id`。
- 默认响应头代表 NGM 控制面请求 trace，方便用浏览器响应里的 `X-Trace-ID` 回查 Clinic backend 日志。

## Key Changes

- 在 `pkg/ngm` 增加全局 trace middleware，并在 `InitNgmApi` 中放到 `otelgin.Middleware` 后面：
  - 如果当前 request context 已有有效 trace id，直接复用。
  - 如果没有，则在原 request context 上生成新的 OpenTelemetry span context，保留请求取消/超时链路。
  - 在 `c.Next()` 前后都设置 `X-Trace-ID`，最终响应头始终和 NGM 日志 trace_id 对齐。
- 调整 NGM 的 `gin.LoggerWithConfig` formatter：
  - 保留现有 skip paths。
  - 日志格式增加 `trace_id=<id>`，参考 `cmd/server/main.go` 的现有实现。
- 增强 `pkg/ngm/statements/service.go` 的 `ListHandler` 日志：
  - 使用 `github.com/pingcap-inc/clinic/pkg/log` 的 context-aware logger。
  - 不混用 `github.com/pingcap/log` 和 `github.com/pingcap-inc/clinic/pkg/log`；本文件统一导入 `github.com/pingcap-inc/clinic/pkg/log`，不使用 `ctxlog` 等别名。
  - bind/validate、storage target resolve、query 执行失败都带 trace_id。
  - 成功路径增加完成日志，记录 provider、region、org_id、project_id、cluster_id、deploy_type、shared_tier、begin/end time、fields/schemas/stmt_types 数量、has_text、result_count、duration。
  - 不打印 SQL 搜索文本和响应内容，避免敏感信息进入日志。

## Public API / Behavior

- 新增响应头：`X-Trace-ID`，值为 32 位 hex trace id。
- 不改变任何 NGM API 的 response body、status code、query/header 参数。
- 代理到 O11y 的接口即使上游返回自己的 `X-Trace-ID`，最终对外响应仍以 NGM trace id 为准。

## Test Plan

- 新增/更新 NGM middleware 测试：
  - 无 trace context 时自动生成 `X-Trace-ID`。
  - 已有 trace context 时复用原 trace id。
  - handler/proxy 写入其他 `X-Trace-ID` 时，最终响应头仍为 NGM trace id。
- 新增 `/statements/list` handler 覆盖或轻量验证：
  - 成功响应包含 `X-Trace-ID`。
  - fake query 接收到的 context 含有效 trace id。
- 检查 `pkg/ngm/statements/service.go` 不再包含 `ctxlog` 或 `github.com/pingcap/log`。
- 运行目标测试：
  - `go test ./pkg/ngm/... ./cmd/ngm_api/...`
  - 若本地私有 `github.com/tidbcloud/...` 依赖无权限导致失败，记录为环境限制；当前探索中也发现已有 `pkg/ngm/statements/impl` 与 `pkg/ngm/topsql/vm` 基线测试失败，需和本次变更区分。