# TiDB-X Current Code Metrics Status

Inspection date: `2026-03-27`

## Scope

This note summarizes what the current `pipeline` code actually emits for TiDB-X plans:

- Premium
- Essential
- Starter

The code paths reviewed are:

- `pipeline/internal/service/prometheus/registry.go`
- `pipeline/internal/datasource/central_thanos/central_thanos.go`
- `pipeline/internal/datasource/central_thanos/queries_nextgen.go`
- `pipeline/internal/datasource/central_thanos/prometheus_builder.go`
- `pipeline/internal/otel_collector/processor/thanos/thanos.go`
- `pipeline/internal/otel_collector/processor/thanos/transform.go`
- `pipeline/internal/metadata/generated_metrics.go`
- `pipeline/central/metrics/prom/metric_model.go`

## Current Inventory

| export path | Premium | Essential | Starter | current code status |
| --- | --- | --- | --- | --- |
| Prometheus | 19 metrics | 14 metrics | 14 metrics | Premium: DB 10 + CDC 5 + RU 2 + storage 2; Essential/Starter: DB 10 + RU 2 + storage 2 |
| Datadog | 18 metrics | 14 metrics | 14 metrics | Premium: DB 10 + CDC 4 + RU 2 + storage 2; Essential/Starter: DB 10 + RU 2 + storage 2 |
| New Relic | 18 metrics | 14 metrics | 14 metrics | Premium: DB 10 + CDC 4 + RU 2 + storage 2; Essential/Starter: DB 10 + RU 2 + storage 2 |

The only current Prometheus vs OTel inventory gap is:

- Prometheus exports `tidbcloud_changefeed_checkpoint_ts`
- OTel metadata defines `tidb_cloud.cdc_checkpoint_ts`, but the thanos processor does not currently call `QueryTiCDCCheckpointTS`, so Datadog / New Relic do not emit it

## Metric Groups

### DB Performance Metrics

All TiDB-X plans currently emit the same 10 DB-performance metrics on all three export paths:

- total connection
- active connections
- disconnections
- database time
- query per second
- failed queries
- command per second
- queries using plan cache ops
- average query duration
- transaction per second

Current code shape:

- Prometheus uses `VecMetric.asInstanceLevelElement()` to rename `cluster_*` to `instance_*` and drop `project_*`, `instance`, and `component`
- OTel uses `transformMetricsForServicePlan()` to apply the same instance-level output model for all NextGen plans
- Premium DB aggregate queries match on `tidb_cluster_id="<cluster_id>"`
- Essential / Starter DB aggregate queries match on `cluster_id="<cluster_id>"`

## CDC Metrics

Current Prometheus CDC inventory for TiDB-X Premium:

- `tidbcloud_changefeed_latency`
- `tidbcloud_changefeed_checkpoint_ts`
- `tidbcloud_changefeed_status`
- `tidbcloud_changefeed_Replica_rows`
- `tidbcloud_ticdc_owner_resolved_ts_lag`

Current Datadog / New Relic CDC inventory for TiDB-X Premium:

- `tidb_cloud.cdc_changefeed_latency`
- `tidb_cloud.cdc_changefeed_status`
- `tidb_cloud.cdc_changefeed_replica_rows`
- `tidb_cloud.cdc_changefeed_resolved_ts_lag`

Current matcher behavior:

- Premium CDC queries use `tidb_cluster_id="<cluster_id>"`
- Essential / Starter do not expose CDC metrics

Current gap:

- `pipeline/internal/metadata/generated_metrics.go` defines `tidb_cloud.cdc_checkpoint_ts`
- `pipeline/internal/otel_collector/processor/thanos/metric_builder_wrapper.go` defines `RecordQueryCdcCheckpointTs`
- `pipeline/internal/otel_collector/processor/thanos/thanos.go` does not wire that metric into `queryThenRecord`

So the current codebase is not yet cross-export consistent for CDC checkpoint timestamp.

## RU Metrics

All TiDB-X plans currently emit these 2 RU metrics on all three export paths:

- read request unit
- write request unit

Current matcher behavior:

- Premium RU queries use `tidb_cluster_id=~".*<cluster_id>"`
- Essential / Starter RU queries use `cluster_id=~".*<cluster_id>"`

Current exposed labels:

- `resource_group`
- `instance_id`
- `instance_name`

The existing `01` to `09` static-check tables were missing this RU group before this refresh.

## Storage Metrics

All TiDB-X plans currently emit these 2 storage metrics on all three export paths:

- `db_row_storage_used_bytes`
- `db_columnar_storage_used_bytes`

Current query shape:

- `quantile_over_time(0.5, sum(avg by(keyspace_id, region_id) (...))[5m]) or vector(0)`

Current code behavior:

- row-based and columnar storage both use the same frontend-aligned smoothing pattern
- Essential / Starter storage queries use `keyspace_id` shared-series matching
- Premium storage queries use `tidb_cluster_id`
- `or vector(0)` keeps newly created or TiFlash-disabled clusters from returning empty

Current risk that still remains in code:

- the query still aggregates at `region_id` granularity before summing
- this keeps the known large-tenant scale risk in place

## Current Bottom Line

The current TiDB-X code is closer to the intended instance-level model than the earlier review baseline, but it still has two concrete gaps:

- Datadog / New Relic are missing `cdc_checkpoint_ts`
- storage metrics still depend on per-region aggregation