# 从 Classic 指标迁移到 OTel 指标
<a name="metrics-otel-migrate"></a>

当前通过 PutMetricData 或 EMF 发布自定义指标的客户，可按工作负载逐步迁移到 OTel 路径。无需一次性全量切换，您可根据自身节奏，按工作负载逐个完成迁移。

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

迁移分为四个阶段：

1. **双写**：同时通过经典指标路径与 OTel 路径发布指标。

1. **验证**：在 Query Studio 中通过 PromQL 确认 OTel 指标正常展示。

1. **重构消费端**：更新警报规则与控制面板，改用 PromQL 及 OTel 指标名称。

1. **切换下线**：确认 OTel 指标消费端运行正常后，停止经典指标路径的指标发布。

## 步骤 1：接入 OTel SDK（双写）
<a name="metrics-otel-migrate-step1"></a>

在现有 PutMetricData 调用上新增 OTel SDK。新旧两条指标的发布路径可同步运行，不会造成数据丢失。

```
# 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 指标。下方示例对比经典指标警报与等效 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>

下表列出常用经典指标名称及推荐的 OTel 等效名称。


| 经典指标名称 | 推荐的 OTel 名称 | 备注 | 
| --- | --- | --- | 
| RequestLatency (ms) | http\_request\_duration\_seconds | 转换为秒（OTel 规范） | 
| RequestCount | http\_requests\_total | 计数器指标，需添加 `_total` 后缀 | 
| ErrorCount | http\_server\_errors\_total | 使用 `_total` 后缀 | 
| QueueDepth | queue\_depth | 仪表盘指标，无需添加后缀 | 

## Amazon 已出售指标该如何处理？
<a name="metrics-otel-migrate-vended-metrics"></a>

无需手动迁移 Amazon 已出售指标（例如 Amazon EC2 CPU 使用率、Amazon RDS 连接数）。只需开启 OTel 已出售指标增强功能，即可直接通过 PromQL 查询这类指标。有关更多信息，请参阅 [采用 OpenTelemetry 格式的 Amazon 已出售指标](CloudWatch-OTelEnrichment.md)。