本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 從 Classic 遷移至 OTel 指標
<a name="metrics-otel-migrate"></a>

目前透過 PutMetricData 或 EMF 發佈自訂指標的客戶可以逐步遷移至 OTel 路徑。沒有標記日 — 遷移會依照工作負載按照您自己的步調發生工作負載。

## 遷移方法
<a name="metrics-otel-migrate-approach"></a>

遷移遵循四個階段：

1. **雙寫入** — 同時透過 Classic 和 OTel 路徑發佈指標。

1. **驗證** - 透過 PromQL 確認 OTel 指標出現在 Query Studio 中。

1. **重新建立取用**者 — 更新警示和儀表板以使用 PromQL 和 OTel 指標名稱。

1. **切換** — 驗證 OTel 取用者後停止 Classic 發佈。

## 步驟 1：使用 OTel SDK 檢測 （雙寫入）
<a name="metrics-otel-migrate-step1"></a>

將 OTel 開發套件與現有的 PutMetricData 呼叫一起新增。這兩個路徑可以同時發佈 - 您不會遺失資料。

```
# Existing Classic publishing (keep running during migration)
cloudwatch.put_metric_data(
    Namespace='MyApp',
    MetricData=[{'MetricName': 'RequestLatency', 'Value': 42.5, 'Unit': 'Milliseconds'}]
)

# New OTel publishing (add this)
from opentelemetry import metrics
meter = metrics.get_meter("my-app")
histogram = meter.create_histogram("http_request_duration_seconds")
histogram.record(0.0425, {"method": "GET", "path": "/api/users"})
```

## 步驟 2：在 Query Studio 中驗證
<a name="metrics-otel-migrate-step2"></a>

若要確認您的 OTel 指標已到達，請開啟 CloudWatch 主控台並導覽至 Query Studio。搜尋您的指標：

```
http_request_duration_seconds
```

確認資料與您預期的標籤一起顯示。

## 步驟 3：在 OTel 指標上重新建立警示
<a name="metrics-otel-migrate-step3"></a>

建立使用 PromQL 表達式查詢 OTel 指標的新警示。下列範例顯示 Classic 警示及其 OTel 對等項目。

**傳統警示：**

```
aws cloudwatch put-metric-alarm \
  --alarm-name "high-latency" \
  --namespace "MyApp" \
  --metric-name "RequestLatency" \
  --statistic Average --threshold 100 ...
```

**OTel 對等 (PromQL 警示）：**

```
aws cloudwatch put-metric-alarm \
  --alarm-name "high-latency-otel" \
  --metrics '[{"Id":"q1","Expression":"avg(http_request_duration_seconds{path=\"/api/users\"}) * 1000","Period":300,"ReturnData":true}]' \
  --threshold 100 ...
```

平行執行兩個警示，直到您確定 OTel 版本正確觸發為止。

## 步驟 4：停止傳統發佈
<a name="metrics-otel-migrate-step4"></a>

驗證 OTel 警示和儀表板之後，請從應用程式程式碼中移除 PutMetricData 呼叫。傳統指標會立即停止產生費用。

## 指標名稱映射
<a name="metrics-otel-migrate-name-mapping"></a>

下表顯示常見的 Classic 指標名稱及其建議的 OTel 對等項目。


| 傳統名稱 | 建議的 OTel 名稱 | 備註 | 
| --- | --- | --- | 
| RequestLatency （毫秒） | http\_request\_duration\_seconds | 轉換為秒 (OTel 慣例） | 
| RequestCount | http\_requests\_total | 計數器使用`_total`尾碼 | 
| ErrorCount | http\_server\_errors\_total | 使用`_total`尾碼 | 
| QueueDepth | queue\_depth | 計量 — 不需要字尾 | 

## AWS 付費指標呢？
<a name="metrics-otel-migrate-vended-metrics"></a>

您不需要手動遷移 AWS 付費指標 (Amazon EC2 CPU、Amazon RDS 連線等）。啟用 OTel Vended Metric Enrichment，讓它們可以透過 PromQL 自動查詢。如需詳細資訊，請參閱[AWS 以 OpenTelemetry 格式提供的指標](CloudWatch-OTelEnrichment.md)。