# Clinic TiCDC Diagnostic Fields

Read this file only for a selected `ticdc-*` Scenario. For
`ticdc-deployment-topology`, use `ticdc_changefeed_architecture_evidence` with
the exact runner-owned source cluster, canonical range, and ticket's
business-facing changefeed display ID. For other TiCDC scenarios, start with
`ticdc_changefeeds_list` and use that display ID to select the entry.

## Independent metadata dimensions

- `ticdcCluster.version`: independent TiCDC version/build; it is not the source
  TiDB version.
- `ticdcCluster.deployType`: dedicated versus shared deployment only.
- `ticdcCluster.controlPlaneArch`: use only when non-empty; do not infer it from
  version or deployment type.
- top-level changefeed `arch`: Dataflow/Dataflow-NG API/control-plane identity;
  it is not proof of TiCDC kernel new/classic architecture.
- `ticdcCluster.sourceClusterMatches`: exact source-cluster association.
- changefeed and TiCDC cluster status plus downstream type: state and sink
  context, not architecture evidence.

When kernel architecture remains load-bearing and the explicit field is empty,
the typed architecture operation deterministically counts the safe `newarch`
marker over the task creation/deployment window. Count-only evidence for
`newarch=true` or `TiCDC(new arch) server created` supports new architecture
only when its returned binding is exact. Zero rows, a non-exact binding, an
out-of-range creation window, or a retention-limited query leaves it unknown.

## New-architecture metric families

Use these exact Prometheus families only after new architecture is established:

- task-level progress: `ticdc_maintainer_checkpoint_ts_lag`,
  `ticdc_maintainer_resolved_ts_lag`;
- dispatcher progress and scale: `ticdc_dispatchermanager_checkpoint_ts_lag`,
  `ticdc_dispatchermanager_resolved_ts_lag`,
  `ticdc_dispatchermanager_table_dispatcher_count`;
- Log Service/Event Service: `ticdc_event_service_resolved_ts_lag`,
  `ticdc_event_service_available_memory_quota`,
  `ticdc_event_service_pending_scan_task_count`,
  `ticdc_event_service_scan_duration_bucket`;
- Event Store: `ticdc_event_store_resolved_ts_lag`,
  `ticdc_event_store_subscription_resolved_ts_lag_bucket`,
  `ticdc_event_store_register_dispatcher_start_ts_lag_bucket`,
  `ticdc_event_store_write_queue_duration_bucket`,
  `ticdc_event_store_write_worker_io_duration_sum`,
  `ticdc_event_store_write_worker_total_duration_sum`,
  `ticdc_event_store_pebble_write_stall_total`;
- downstream: `ticdc_sink_execution_error`,
  `ticdc_sink_txn_queue_duration_bucket`,
  `ticdc_sink_txn_worker_flush_duration_bucket`,
  `ticdc_sink_kafka_producer_request_latency`,
  `ticdc_sink_kafka_producer_in_flight_requests`,
  `ticdc_sink_cloud_storage_pending_post_enqueue`, and
  `ticdc_sink_cloud_storage_spool_disk_quota_waiters`.

## Classic-architecture metric families

Use these only after classic architecture is established, or when the exact
metric labels themselves are the bounded compatibility evidence and the
architecture remains explicit as unknown:

- changefeed progress: `ticdc_owner_checkpoint_ts_lag`,
  `ticdc_owner_resolved_ts_lag`, `ticdc_owner_checkpoint_ts`, and
  `ticdc_owner_resolved_ts`;
- slow-table/puller progress: `ticdc_scheduler_slow_table_checkpoint_ts`,
  `ticdc_scheduler_slow_table_puller_resolved_ts_lag`;
- classic sink/redo: `ticdc_sink_txn_worker_flush_duration_bucket`,
  `ticdc_sink_execution_error`, `ticdc_redo_checkpoint_ts`, and
  `ticdc_redo_resolved_ts`;
- upstream TiKV CDC: `tikv_cdc_min_resolved_ts`,
  `tikv_cdc_captured_region_total`, and initial-scan duration metrics exposed
  by the selected target.

## Query rules

- Filter to the exact changefeed and preserve the returned label set before
  comparing two series. Do not guess whether the label is `changefeed`,
  `changefeed_id`, or another variant.
- Compare ResolvedTS and CheckpointTS on the same target and absolute window.
- Use rate/increase for counters and histogram quantiles only with matching
  bucket labels. Preserve units and aggregation.
- An unsupported, empty, or differently labelled family is a query gap. Repair
  the selector once or use one already-authorized adjacent surface; never call
  it healthy evidence.
- Activities and bounded logs are primary for lifecycle/configuration questions;
  metrics are primary for replication progress. Correctness requires the exact
  table/DDL/error signature and must not be inferred from aggregate lag alone.