# Changelog --- ### 2026-08-31 - fix(clinic-api): make TiCDC List and Detail helpers preserve HTTP error bodies and return status 22 without requiring curl `--fail-with-body` - fix(clinic-api): accept and URL-encode opaque TiCDC kernel changefeed IDs such as `cfd-*` instead of requiring unsigned integers - docs(clinic-api): record Starter and Essential TiCDC metadata support while retaining the Essential v2 exclusion --- ### 2026-08-26 - fix(clinic-api): make org-scoped cluster list helpers request `include_total=false` by default, document pagination through `has_more`, and retain explicit exact-total opt-in --- ### 2026-08-21 - feat(clinic-api): add the `ticdc` sub-skill and internal canonical Data Proxy helpers for TiCDC changefeed metadata List and Detail - docs(clinic-api): document that Detail takes the kernel/internal changefeed `id` returned by List, not `display_id`, and uses the internal Clinic API key boundary ### 2026-08-18 - docs(clinic-api): document the count-free default for the `/dashboard/clusters2` global search helper, `has_more` pagination, and explicit exact-total opt-in - fix(clinic-api): keep exact-ID compatibility metadata lookups on `/dashboard/clusters2` and request `include_total=false` - fix(clinic-api): make global `/dashboard/clusters2` search helpers request `include_total=false` by default and support explicit exact-total opt-in --- ### 2026-08-17 - fix(clinic-api): route global cluster discovery and advanced provider, deploy-type-v2, status, version, tenant-plan, control-plane, region, and sorting filters through the capability-preserving search helper - feat(clinic-api): add repeatable filter flags to `clinic_search_clusters` and matching `ClinicAPI.search_clusters(...)` list parameters while preserving the historical positional shell form - docs(clinic-api): distinguish exact metadata, ordinary org-scoped lists, and global/advanced discovery; warn that unsupported canonical list parameters are silently ignored --- ### 2026-08-11 - feat(clinic-api): document canonical BYOC logs, metrics, Slow Query, Top SQL, live Statements, and physical-only Continuous Profiling inventory in a unified `byoc-diagnostics` sub-skill - feat(clinic-api): add documented shell/Python helper contracts for BYOC diagnosis and non-BYOC Top RU `summary-plan` - behavior(clinic-api): keep BYOC Slow Query, Top SQL, Statements, and profiling inventory customer-side through O11y; explicitly prohibit S3/Athena/warehouse fallback - fix(clinic-api): document that exact BYOC data-plane metrics do not inject `tidb_cluster_id` and must use the physical Kubernetes namespace; other tiers and BYOC cluster-store scoping remain unchanged - compatibility(clinic-api): retain existing warehouse SQL for supported non-BYOC tiers and existing NGM profiling/download workflows - docs(clinic-api): document trusted Python CA-bundle recovery for `CERTIFICATE_VERIFY_FAILED` without disabling TLS verification --- ### 2026-07-22 - feat(clinic-api): make the canonical `/data-proxy/api/v1` resource APIs the default for cluster metadata/detail, components, activity events, SQL query/batch/schema/capabilities, metrics, business logs, datasource-scoped system logs, and Top RU - feat(clinic-api): add canonical helpers for org cluster lists, activity events, same-cluster SQL batches, capabilities, SQL Statements, Top RU summary/user stats, Prometheus metrics, Loki series, and system-log datasource resources - docs(clinic-api): define canonical `{orgID}` as the TiDB Cloud/DBAAS org ID (`tenantID` in the legacy Dashboard response); reserve Dashboard `orgID` for explicit legacy Clinic paths - compatibility(clinic-api): retain existing API paths and expose explicit `clinic_legacy_*` helpers while keeping canonical helpers as the default skill workflow - docs(clinic-api): record SQL Statements provider status: AWS Premium production E2E pass, GCP/Azure positive samples pending, and AliCloud unsupported --- ### 2026-07-10 - feat(clinic-api): add NGM slow query list helpers for Starter/Essential/shared clusters: shell `clinic_ngm_slow_query_list` and Python `ClinicAPI.ngm_slow_query_list` - docs(clinic-api): document that Starter/Essential/shared slow query should use NGM when Data Proxy SQL lacks `slowQueryS3Url` - fix(clinic-api): normalize NGM slow query `starter` / `essential` / `shared` deploy types to `shared`, and prefer `tenantID` for NGM `x-org-id` - docs(clinic-api): document NGM slow query headers, Unix-second window parameters, fields/order/limit filters, and a prod limit-1 example shape --- ### 2026-06-18 - feat(clinic-api): add LogStats support to the Data Proxy sub-skill, including `log_stats` schema/query docs, AWS Dedicated/Premium boundary notes, and Delta table caveats - feat(clinic-api): add `data-proxy/scripts/clinic-data-proxy.sh` shell helpers: `clinic_dataproxy_query`, `clinic_dataproxy_schema`, `clinic_log_stats_schema`, `clinic_log_stats_summary`, `clinic_log_stats_top`, and `clinic_log_stats_search` - feat(clinic-api): add Python helper methods and CLI commands for `log_stats_schema`, `log_stats_summary`, `log_stats_top`, and `log_stats_search` --- ### 2026-05-27 - feat(clinic-api): add system logs helpers `clinic_system_logs_datasources`, `clinic_system_logs_query_range`, `clinic_system_logs_labels`, and `clinic_system_logs_label_values`; default datasource helper value is `Loki-aws-us-west-2`, override via `CLINIC_SYSTEM_LOGS_DATASOURCE` - docs(clinic-api): Loki sub-skill now documents `/data-proxy/system-logs/api/v1/...`, datasource discovery, and explicit datasource selection for control-plane logs - feat(clinic-api): add `clinic_system_logs_datasources_table` for readable datasource discovery and `clinic_system_logs_datasource_for_region ` for provider/region-based datasource selection - feat(clinic-api): add `clinic_system_logs_series` for system log stream discovery with `match[]` - docs(clinic-api): clarify that system logs datasources are served by Clinic Data Proxy's own `system_endpoints` config, migrated from Grafana Loki datasources but not read from Grafana at runtime --- ### 2026-05-15 - fix(clinic-api): `clinic_get_topology` now uses the topology REST path for dedicated / resource pool / premium / BYOC clusters, so topology output includes runtime image tag and storage fields such as IOPS / throughput when available - docs(clinic-api): Cluster metadata docs now direct topology, image tag, CPU, memory, node count, and storage questions to `clinic_get_topology`; Get Cluster is documented only for cluster metadata --- ### 2026-04-16 - docs(clinic-api): move TiKV / TiFlash exceeded IOPS and pod-attributed disk IOPS definitions into `metrics_3_other.md` under `DataPlane Infrastructure Metrics`; `metrics/SUBSKILL.md` now references those metric names instead of inlining PromQL - docs(clinic-api): add `tikv_exceeded_iops`, `tiflash_exceeded_iops`, `tikv_node_disk_iops`, and `tiflash_node_disk_iops` to `metrics_3_other.md`, with caveat for multi-pod-per-node layouts - docs(clinic-api): align `tikv_exceeded_iops` / `tiflash_exceeded_iops` with the working dashboard query shape and document that empty results usually indicate variable / string-construction issues rather than a real “no exceed” state - docs(clinic-api): storage IOPS troubleshooting now prefers `*_exceeded_iops` first and falls back to `*_node_disk_iops` when the exceeded metric returns no data - docs(clinic-api): empty `*_exceeded_iops` results must first trigger validation of `namespace`, `instance`, and literal `"$1"` handling before using `*_node_disk_iops` as fallback - docs(clinic-api): when Clinic Data Proxy still returns empty for `*_exceeded_iops`, use `query_series(kube_pod_info)` + raw `query_range` on the infrastructure metric and join client-side by `instance=node` - feat(clinic-api): `clinic_api.py` adds reusable client-side join helpers `query_range_join_instance_to_pod`, `query_exceeded_iops_by_pod`, and `query_node_disk_iops_by_pod`; exceeded IOPS helper defaults to `rate_window="2m"` to better match the dashboard --- ### 2026-04-07 - feat(clinic-api): **`scripts/clinic-download-dir.sh`** — shared **`_clinic_default_download_dir`** (**`CLINIC_DIAGNOSTIC_DOWNLOAD_DIR`** or **`$PWD`**); **`clinic_continuous_profiling_download`** / **`clinic_continuous_profiling_fetch`** use it when output path is omitted; stderr **`wrote `** on success - feat(clinic-api): add **`diagnostic-files`** sub-skill — NGM list/download for **Dedicated** **plan_replayer** and **oom_record** (`plan_replayer/list`, `oom_record/list`, `oom_record/files`); shell helpers `clinic_diagnostic_*` in `diagnostic-files/scripts/clinic-diagnostic-files.sh` and `clinic-shell.sh` integration - behavior(clinic-api): **`clinic_diagnostic_download_file`** default directory — **`CLINIC_DIAGNOSTIC_DOWNLOAD_DIR`** if set, else **`$PWD`** at download time; removed **`CLINIC_SHELL_WORKDIR`** fallback (**`clinic-shell.sh`** no longer sets it); stderr **`wrote `** - docs(clinic-api): **`diagnostic-files/SUBSKILL.md`** — offline import-free analysis: **plan_replayer** zip scan; **oom_record** `goroutine*` / `running_sql*` text and **`heap*`** zip → inner profile via **`go tool pprof`** --- ### 2026-04-03 - docs(clinic-api): Loki (Clinic Data Proxy) — **`|~` regex must use backticks** `` `...` `` (not `"..."`) so `(?i)\[error\]` / `(?i)\[warn(ing)?\]` work; double-quoted `|~` still hits `invalid char escape`; bash examples use single-quoted LogQL; **`limit` ~1000** (`loki/SUBSKILL.md`, `SKILL.md`) - refactor(clinic-api): rename aggregator script **`clinic-token.sh` → `clinic-shell.sh`** (reflects API-key auth + full shell helper bundle, not OAuth tokens); update all skill references - fix(clinic-api): `clinic_get_topology` no longer calls resource-pool components for **shared** / **starter** / **essential** clusters (topology unsupported); docs updated - feat(clinic-api): add **continuous profiling** (NGM ConProf) — `continuous-profiling` sub-skill, shell helpers `clinic_continuous_profiling_*`, NGM headers (`x-org-id` = tenantID, etc.), and `clinic-shell.sh` integration - refactor(clinic-api): **split clinic-api shell scripts by sub-skill** — `scripts/clinic-shell.sh` only aggregates; implementations live in `scripts/clinic-auth.sh`, `cluster-metadata/scripts/clinic-cluster.sh`, `loki/scripts/clinic-loki.sh`, `continuous-profiling/scripts/clinic-continuous-profiling.sh` - docs(clinic-api): data-proxy sub-skill documents TopSQL table `topsql`, partition `date`, key columns, and analysis SQL examples --- ### 2026-03-20 - docs(clinic-api): Slow Query supports AliCloud and GCP; Azure not yet supported - docs(clinic-api): use MySQL standard SQL for Slow Query; identifiers auto-converted; use vendor dialect only for dialect-specific functions - docs(clinic-api): add Resource Pool Components API; supports premium/byoc; use clusterID for current cluster, parentID for resource pool --- ### 2026-03-19 - docs(clinic-api): require correct SQL dialect for /data-proxy/query (Athena for AWS, BigQuery for GCP) --- ### 2026-03-18 - 97da8df fix: remove get deploy type first for query loki log ### 2026-03-17 - docs(clinic-api): add required workflow - query deployTypeV2 first, then choose Loki LogQL pattern by deploy type - f00da96 fix: auto inject label for clinic-api metrics and loki ### 2026-03-13 - feat: add Cluster Events (Activity Hub) API documentation - 104a0a1 fix: set metrics label by deploy type ### 2026-03-12 - 61df06f feat: support get shared cluster logs - b45e60f feat: support get shared cluster logs ### 2026-03-11 - 06366b9 Update SKILL.md - ea243ab fix: labels for clinic-api loki proxy - 7b2777d fix: labels for clinic-api loki proxy - 47922ce Merge pull request #43 from tidbcloud/nizheming/clinic-api-key-auth - e87b521 docs(clinic-api): reorder core metrics - query performance first - 0607f42 docs(clinic-api): regenerate metrics files with process-level priority - 39a3a52 docs(clinic-api): replace node metrics with process-level metrics in core - 03b04b3 docs(clinic-api): add TiDB 8.5.4 METRICS_SCHEMA reference documentation - 9840142 fix clinic-token zsh compatibility and update docs (#36) ### 2026-03-10 - a81e6d1 Apply suggestion from @lanfuchao - 7396a9d Fix SQL database name in API documentation - 805a39f Fix example request and update parameter descriptions - 2693ef7 Merge pull request #34 from tidbcloud/eric/add-loki-proxy - 110a1f4 feat: add loki proxy - c2d7113 update clinci skill ### 2026-03-08 - 7ac5747 docs: add parameter schema for List/Search Clusters API - ef51fe1 docs: add Table Schema API to clinic-api skill - 4f30bff docs: comprehensive update clinic-api skill with Data Proxy API documentation ### 2026-03-04 - 97f7fb8 feat(clinic-api): switch from JWT session to API Key authentication ### 2026-02-23 - 86c786c docs(clinic-api): add support for tenant name and cluster name search ### 2026-02-13 - 0e73a88 Add clinic-api and o11y-metrics-api skills for TiDB Cloud