---
name: tidbcloud-serverless-pool-routing
description: Resolve a TiDB Cloud Serverless (Starter/Essential) shared-pool name such as us-west-2-f01 into the routing identities (pool, vendor, vendor-region, control_plane_info) required by the serverless parent metrics and logs APIs. Use when querying metrics or logs for a serverless/starter/essential/essential-v1 pool and the caller only gives a region pool name like us-west-2-f01 or na-south-1-a01.
---

# TiDB Cloud Serverless Pool Routing

## Overview

Serverless parent observability APIs (metrics and logs) route by the Grafana
`control_plane_info` value `<pool>/<vendor-region>/<application>`, for example
`us-west-2-f04/aws-us-west-2/devtier-infra`. This value is long and
inconvenient to request from callers, who usually know only the pool (region
cluster) name, such as `us-west-2-f01`.

This skill derives every routing identity from the pool name alone. Feed its
output to the `clinic-api` serverless parent metrics/logs endpoints and to
`tidbcloud-serverless-daily-inspection`.

## Pool Name Format

A Serverless shared-pool name has four dash-separated segments:

```text
xx-xx-xx-xx
us-west-2-f01
na-south-1-a01
```

Parse rules:

1. The full `xx-xx-xx-xx` string is the **pool** (the Grafana `projectID`).
2. The first character of the last segment is the **vendor code**:

   | Code | Vendor     |
   |------|------------|
   | `f`  | `aws`      |
   | `a`  | `alicloud` |

   Any other leading character is unknown: stop and ask the caller; do not
   guess a vendor.
3. The **vendor-region** is `<vendor>-<first three segments>`:
   - `us-west-2-f01` → `aws-us-west-2`
   - `na-south-1-a01` → `alicloud-na-south-1`
4. The **control_plane_info** is `<pool>/<vendor-region>/<application>`:
   - `us-west-2-f04` → `us-west-2-f04/aws-us-west-2/devtier-infra`
   - `application` defaults to `devtier-infra`, the Serverless infra
     application ID used by the parent APIs. Do not invent other application
     IDs; if a dashboard shows a different third segment, use the dashboard
     value.

## Derived Values

| Value | Rule | Example (`us-west-2-f01`) |
|-------|------|---------------------------|
| `pool` | the input itself | `us-west-2-f01` |
| `vendor` | first char of the 4th segment | `aws` |
| `vendor_region` | `<vendor>-<seg1>-<seg2>-<seg3>` | `aws-us-west-2` |
| `control_plane_info` | `<pool>/<vendor_region>/<application>` | `us-west-2-f01/aws-us-west-2/devtier-infra` |
| PromQL `control_plane_info` label | first two segments of the routing value | `us-west-2-f01/aws-us-west-2` |
| Loki datasource | `Loki-<vendor_region>` | `Loki-aws-us-west-2` |
| Loki `cluster` label (prod) | `prod-<pool>` | `prod-us-west-2-f01` |

The last two rows are downstream facts documented in `clinic-api`: the parent
logs proxy resolves the system Loki datasource from provider/region and
injects `cluster="{env}-{projectID}"` (`prod-<pool>` in prod). The routing
contract itself is `control_plane_info`; PromQL selectors use only its first
two segments as the `control_plane_info` metric label.

`k8s_cluster_info` is NOT derivable from the pool name. Skills that require
it (for example `tidbcloud-serverless-daily-inspection`) must still obtain
it from the Serverless dashboard variable/metric-label series.

## Helper Script

Use `scripts/resolve_serverless_pool.py` for a deterministic resolution. Run
the helper with the loaded `tidbcloud-serverless-pool-routing` skill directory
as the shell working directory. It accepts either a bare pool name or a full
`control_plane_info` value (which it validates for pool/vendor-region
consistency):

```bash
python3 scripts/resolve_serverless_pool.py us-west-2-f01
```

Output (`key=value` lines with validated, shell-quoted values):

```text
pool=us-west-2-f01
vendor=aws
vendor_region=aws-us-west-2
application=devtier-infra
control_plane_info=us-west-2-f01/aws-us-west-2/devtier-infra
promql_control_plane_info=us-west-2-f01/aws-us-west-2
loki_datasource=Loki-aws-us-west-2
prod_loki_cluster=prod-us-west-2-f01
```

Options:

- `--json` prints the same fields as one JSON object.
- `--application APP` overrides the default `devtier-infra` application ID.
- A full value such as `us-west-2-f01/aws-us-west-2/devtier-infra` is
  validated and decomposed; a mismatched vendor-region is rejected.

## Querying Metrics and Logs

Example request: "query the average CPU usage of all TiKV nodes in the last
10 minutes for serverless cluster `us-west-2-f01`".

1. Resolve the pool name: `control_plane_info=us-west-2-f01/aws-us-west-2/devtier-infra`.
2. Query the `clinic-api` serverless parent metrics endpoint
   `/data-proxy/serverless-parent-metrics/api/v1/query_range` with
   `control_plane_info` as the routing parameter and a PromQL selector that
   binds the two-segment label:

   ```bash
   curl -sS -G "${CLINIC_ENDPOINT}/data-proxy/serverless-parent-metrics/api/v1/query_range" \
     -H "Authorization: Bearer ${CLINIC_API_KEY}" \
     --data-urlencode "control_plane_info=us-west-2-f01/aws-us-west-2/devtier-infra" \
     --data-urlencode 'query=avg(rate(process_cpu_seconds_total{control_plane_info="us-west-2-f01/aws-us-west-2",namespace="tidb-serverless",component="tikv"}[5m]))' \
     --data-urlencode "start=<now-10m RFC3339>" \
     --data-urlencode "end=<now RFC3339>" \
     --data-urlencode "step=30s"
   ```

3. For logs, call `/data-proxy/serverless-parent-logs/api/v1/query_range`
   with the same routing parameter; the proxy injects
   `cluster="prod-us-west-2-f01"` in prod. Do not invent
   `control_plane_info` as a LogQL label.

See `clinic-api` (`data-proxy` subskill) for the full endpoint contract.

## Rules

- The pool name must have exactly four non-empty dash-separated segments.
- Only `f` (aws) and `a` (alicloud) are known vendor codes. For any other
  code, stop and ask the caller.
- Never infer routing identities from a logical cluster ID, tenant, keyspace,
  or organization.
- `application` defaults to `devtier-infra`; use a dashboard-observed value
  when it differs, and never fabricate one.