# TiDB X Local Validation Workspace Guide

## Goal

This guide describes a mostly automated local validation loop for `metrics-integration`:

- cover four cluster types: `Dedicated`, `Premium`, `Essential`, `Starter`
- cover three output paths:
  - `Prometheus`
  - `OTel -> Datadog path`
  - `OTel -> New Relic path`

Current behavior:

- `Dedicated` produces both `main` and `feature` outputs for comparison
- `Premium`, `Essential`, and `Starter` currently produce feature-branch outputs only

## Current Script Capabilities

Existing script directory:

```text
metrics-integration/test-scripts
```

Important scripts:

- `run-all.sh`
  - prepares the `main` worktree
  - builds both `feature` and `main` pipeline binaries
  - generates test configs from `test.env`
  - runs Prometheus and OTel tests
- `run-prometheus-test.sh`
  - `feature` covers all four cluster types
  - `main` currently covers `Dedicated` only
- `run-otel-test.sh`
  - `feature` covers all four cluster types and both `dd` and `nr`
  - `main` currently covers `Dedicated` only
- `diff-results.sh`
  - mainly compares `Dedicated` outputs between `main` and `feature`

This means the current loop already supports:

- full `main vs feature` comparison for `Dedicated`
- feature-result collection and summary for `Premium`, `Essential`, and `Starter`

## Directory Layout

```text
metrics-integration/
  test-scripts/
  test-configs/
  test-results/
```

## Prerequisites

Required local dependencies:

- `go`
- `git`
- `docker`
- `curl`
- `jq`
- `nc`
- `mirrord`

Assumptions:

- current working directory is the repository root
- `metrics-integration` is the local validation workspace
- you can access TiDB Cloud and O11Y-related environments

## Step 1: Expose O11Y Global and Regional locally

Enter:

```bash
cd metrics-integration/global
```

Run port-forward with mirrord:

```bash
MIRRORD_CHECK_VERSION=false mirrord port-forward \
  --config-file .mirrord/port-forward.yaml \
  -L 29080:www.gs.us-west-2.aws.observability.tidbcloud.com:80 \
  -L 29482:www.ds.us-east-1-serverless.aws.observability.tidbcloud.com:443 \
  -L 29483:www.ds.us-east-1-premium.aws.observability.tidbcloud.com:443
```

Meaning:

- `29080`: O11Y Global
- `29482`: O11Y Regional Data Server for `Starter` / `Essential`
- `29483`: O11Y Regional Data Server for `Premium`

## Step 2: Prepare four test clusters

Prepare one cluster for each service plan:

- `Dedicated`
- `Premium`
- `Essential`
- `Starter`

## Step 3: Configure `test.env`

Use the template:

```bash
cp test-scripts/test.env.template test-scripts/test.env
```

Fill in:

- cluster ids
- required auth or routing values
- local forwarding toggles if needed

## Step 4: Run the full test loop

```bash
bash test-scripts/run-all.sh
```

## Step 5: Inspect outputs

Expected result categories:

- `prometheus/*.txt`
- `otel-dd/*.ndjson`
- `otel-nr/*.ndjson`

Recommended checks:

- Prometheus output is non-empty and contains `tidbcloud_` metrics
- Datadog OTel output is non-empty and contains `tidb_cloud.` metrics
- New Relic OTel output is non-empty and contains `tidb_cloud.` metrics
- the same semantic metric exists across all three paths

Examples:

- Prometheus: `tidbcloud_db_query_per_second`
- Datadog / New Relic: `tidb_cloud.db_query_per_second`

## Expected Outcome

After running this workflow, you should have:

- a local artifact set for all three export paths
- `main vs feature` comparison for Dedicated
- feature output coverage for NextGen plans

This local loop should be completed before moving to real-platform validation.