# Datasource Routing and Query Semantics

## Goal

Dedicated and TiDB-X cannot share one datasource strategy.
The feature adds service-plan-aware routing and query matching so Premium, Essential, and Starter can use the same integration products through the correct observability backend.

## Routing Model

Datasource selection is controlled by service plan.

At a high level:

- Dedicated uses the existing Dedicated bizType
- Premium uses the Premium NextGen bizType
- Essential and Starter use the devtier-style bizType

This affects both:

- Prometheus pipeline
- OTel pipeline for Datadog and NewRelic

## Environment Mapping

The current route intent is:

| Service Plan | Dev | Staging | Prod |
| --- | --- | --- | --- |
| Dedicated | `dev-tidbcloud` | `staging-tidbcloud` | `tidbcloud` |
| Premium | `dev-tidbcloud-nextgen` | `staging-tidbcloud-nextgen` | `prod-tidbcloud-nextgen` |
| Essential | `dev-devtier` | `staging-devtier` | `prod-devtier` |
| Starter | `dev-devtier` | `staging-devtier` | `prod-devtier` |

## Query Matcher Semantics

### Premium

- query matcher uses `tidb_cluster_id`
- current implementation keeps this behavior for DB, CDC, and storage metrics

### Essential / Starter

- TiDB-layer DB metrics query by `cluster_id`
- shared-series metrics use `cluster_id -> keyspace_id` lookup, then query by `keyspace_id`
- `project_id` is no longer a query matcher label

### Dedicated

- unchanged

## Shared Resource Pool Metrics

TiDB-X clusters are mostly TiDB-facing at the product layer.
TiKV and TiFlash metrics come from shared resource-pool series instead of per-cluster dedicated storage nodes.

This means storage and some CDC-related paths require special handling:

- resolve tenant identity correctly
- query shared series safely
- avoid reusing Dedicated namespace assumptions

## URL / Datasource Differences

Compared with Dedicated:

- TiDB-X datasource URLs do not use `projectID`
- routing is determined by `bizTypeConfigs` and `ServicePlan`
- pipeline config must carry enough service-plan information for runtime routing to stay stable

## What to Verify in Code Review

- bizType selection matches service plan
- Premium uses `tidb_cluster_id`
- Essential and Starter use `cluster_id` for TiDB-layer metrics
- shared-series paths resolve `keyspace_id` where required
- Dedicated routing remains unchanged

## Related Docs

- `02-cluster-metadata-and-service-plan.md`
- `04-metric-output-and-coverage.md`