Migrar das métricas Classic para OTel

Os clientes que atualmente publicam métricas personalizadas por meio do PutMetricData ou do EMF podem migrar de forma incremental para o caminho OTel. Não há um dia de corte — a migração acontece de workload em workload, no seu próprio ritmo.

Abordagem de migração

A migração segue quatro fases:

Etapa 1: instrumentar com SDK do OTel (gravação dupla)

Adicione o SDK do OTel junto com suas chamadas PutMetricData existentes. Ambos os caminhos podem ser publicados simultaneamente — você não perde dados.

# 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"})

Etapa 2: verificar no Query Studio

Para verificar se suas métricas do OTel estão chegando, abra o console do CloudWatch e navegue até o Query Studio. Pesquise sua métrica:

http_request_duration_seconds

Confirme se os dados aparecem com os rótulos que você espera.

Etapa 3: recriar alarmes nas métricas do OTel

Crie novos alarmes que consultem as métricas do OTel usando expressões PromQL. O exemplo mostrado a seguir mostra um alarme Classic e seu equivalente OTel.

Alarme Classic:

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

Equivalente ao OTel (alarme 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 ...

Execute os dois alarmes em paralelo até ter certeza de que a versão OTel é acionada corretamente.

Etapa 4: interromper a publicação do Classic

Depois de validar seus alarmes e painéis do OTel, remova as chamadas PutMetricData do código da aplicação. As métricas Classic deixam de gerar cobranças imediatamente.

Mapeamento do nome da métrica

A tabela a seguir mostra nomes comuns de métricas Classic e seus equivalentes OTel sugeridos.

E quanto às métricas fornecidas pela AWS?

Você não precisa migrar manualmente as métricas fornecidas pela AWS (CPU do Amazon EC2, conexões do Amazon RDS etc.). Ative o OTel Vended Metric Enrichment para torná-las consultáveis por meio do PromQL automaticamente. Para obter mais informações, consulte Métricas fornecidas pela AWS no formato do OpenTelemetry.