# Publicar métricas personalizadas
Você também pode publicar suas próprias métricas no CloudWatch usando o OpenTelemetry Protocol (OTLP) ou a API do CloudWatch.
## Publicar métricas usando o OpenTelemetry (recomendado)
Para novas implementações, recomendamos usar o OpenTelemetry para publicar métricas personalizadas no CloudWatch. O OpenTelemetry fornece instrumentação independente de fornecedor com rótulos descritivos mais ricos e suporte para tipos de métricas, incluindo medidor, soma, histograma e histograma exponencial.
Para publicar métricas usando o OpenTelemetry, configure o OpenTelemetry Collector ou SDK para enviar métricas para o endpoint do OTLP do CloudWatch. As métricas enviadas por meio do OTLP estão disponíveis para consulta usando o Prometheus Query Language (PromQL) no CloudWatch Query Studio. Você também pode definir alarmes baseados no PromQL do CloudWatch nessas métricas.
Principais diferenças em relação à abordagem da API do CloudWatch:
| Recurso | OpenTelemetry (OTLP) | API do CloudWatch (PutMetricData) |
| --- | --- | --- |
| Rótulos por métrica | Até 150 | Até 30 dimensões |
| Tipos de métricas | Medidor, soma, histograma, histograma exponencial | Valores únicos, conjuntos de estatísticas |
| Granularity | Ingerido na resolução enviada | 1 segundo (alta resolução) ou 1 minuto (padrão) |
| Linguagem da consulta | PromQL | GetMetricStatistics, Metrics Insights |
| Alarmes | Alarmes do CloudWatch baseados no PromQL | Alarmes padrão do CloudWatch |
| Instrumentação | OpenTelemetry SDKs e Collectors independentes de fornecedores | AWS SDK ou CLI |
Para começar, consulte [Envio de métricas usando o OpenTelemetry](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OpenTelemetry-Sections.html).
## Publicar métricas usando a API do CloudWatch
Você também pode publicar métricas personalizadas usando a API PutMetricData ou a AWS CLI. Essa abordagem usa namespaces, nomes de métricas e dimensões do CloudWatch.
**Topics**
+ [Publicar métricas usando o OpenTelemetry (recomendado)](#publishMetricsOTLP)
+ [Publicar métricas usando a API do CloudWatch](#publishMetricsCWAPI)
+ [Métricas de alta resolução](#high-resolution-metrics)
+ [Usar dimensões](#usingDimensions)
+ [Publicar pontos de dados únicos](#publishingDataPoints)
+ [Publicar conjuntos de estatísticas](#publishingDataPoints1)
+ [Publicar o valor zero](#publishingZero)
+ [Parar de publicar métricas](#CloudWatch-Stop-Publishing-Metrics)
## Métricas de alta resolução
Cada métrica é um dos seguintes:
+ Resolução padrão, com dados de granularidade de um minuto
+ Resolução alta, com dados de granularidade de um segundo
Por padrão, as métricas produzidas por serviços da AWS têm resolução padrão. Quando você publica uma métrica personalizada, pode defini-la com resolução padrão ou alta. Quando você publica uma métrica de alta resolução, o CloudWatch a armazena com uma resolução de 1 segundo. Você pode ler e recuperar essa métrica no período de 1 segundo, 5 segundos, 10 segundos, 30 segundos ou em qualquer múltiplo de 60 segundos.
As métricas de alta resolução podem também dar a você insight mais imediato da atividade de subminuto da seu aplicativo. Lembre-se de que cada chamada `PutMetricData` de uma métrica personalizada é cobrada. Portanto, chamar `PutMetricData` com mais frequência em uma métrica de alta resolução pode resultar em tarifas mais altas. Para obter mais informações sobre os preços do CloudWatch, consulte [Preço do Amazon CloudWatch](https://aws.amazon.com/cloudwatch/pricing/).
Se você definir um alarme em uma métrica de alta resolução, pode especificar um alarme de alta resolução com um período de 10 ou 30 segundos ou pode definir um alarme regular com um período de qualquer múltiplo de 60 segundos. Há uma tarifa maior para alarmes de alta resolução com um período de 10 ou 30 segundos.
## Usar dimensões
Em métricas personalizadas, o parâmetro `--dimensions` é comum. Uma dimensão esclarece com mais detalhes qual é a métrica e quais dados ela armazena. Você pode ter até 30 dimensões atribuídas a uma métrica. Cada dimensão é definida por um par de nome e valor.
A forma como você especifica uma dimensão é diferente quando você usa comandos diferentes. Com [put-metric-data](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/put-metric-data.html), você especifica cada dimensão como *MyName*=*MyValue*, e com [get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html) ou [put-metric-alarm](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/put-metric-alarm.html) você usa o formato `Name=`*MyName*, `Value=`*MyValue*. Por exemplo, o seguinte comando publica uma métrica `Buffers` com duas dimensões denominadas `InstanceId` e `InstanceType`.
```
aws cloudwatch put-metric-data --metric-name Buffers --namespace MyNameSpace --unit Bytes --value 231434333 --dimensions InstanceId=1-23456789,InstanceType=m1.small
```
Este comando recupera as estatísticas para esta mesma métrica. Separe as partes de nome e valor de uma única dimensão com vírgulas, mas, se tiver várias dimensões, use um espaço entre uma dimensão e a próxima.
```
aws cloudwatch get-metric-statistics --metric-name Buffers --namespace MyNameSpace --dimensions Name=InstanceId,Value=1-23456789 Name=InstanceType,Value=m1.small --start-time 2016-10-15T04:00:00Z --end-time 2016-10-19T07:00:00Z --statistics Average --period 60
```
Se uma única métrica incluir várias dimensões, você deverá especificar um valor para cada dimensão definida ao usar [get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html). Por exemplo, a métrica `BucketSizeBytes` do Amazon S3 inclui as dimensões `BucketName` e `StorageType`. Portanto, você deve especificar as duas dimensões com [get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html).
```
aws cloudwatch get-metric-statistics --metric-name BucketSizeBytes --start-time 2017-01-23T14:23:00Z --end-time 2017-01-26T19:30:00Z --period 3600 --namespace AWS/S3 --statistics Maximum --dimensions Name=BucketName,Value=amzn-s3-demo-bucket Name=StorageType,Value=StandardStorage --output table
```
Para ver quais dimensões estão definidas para uma métrica, use o comando [list-metrics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/list-metrics.html).
## Publicar pontos de dados únicos
Para publicar um único ponto de dados para uma métrica nova ou existente, use o comando [put-metric-data](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/put-metric-data.html) com um valor e um time stamp. Por exemplo, cada uma das seguintes ações publica um ponto de dados.
```
aws cloudwatch put-metric-data --metric-name PageViewCount --namespace MyService --value 2 --timestamp 2016-10-20T12:00:00.000Z
aws cloudwatch put-metric-data --metric-name PageViewCount --namespace MyService --value 4 --timestamp 2016-10-20T12:00:01.000Z
aws cloudwatch put-metric-data --metric-name PageViewCount --namespace MyService --value 5 --timestamp 2016-10-20T12:00:02.000Z
```
Se você chamar esse comando com um novo nome da métrica, o CloudWatch criará uma métrica para você. Caso contrário, o CloudWatch associará os dados com a métrica existente que você especificou.
**nota**
Ao criar uma métrica, pode levar até dois minutos antes que seja possível recuperar as estatísticas para a nova métrica usando o comando [get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html). No entanto, pode levar até 15 minutos até que a nova métrica apareça na lista de métricas recuperadas com o comando [list-metrics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/list-metrics.html).
Embora você possa publicar pontos de dados com carimbos de data/hora com precisão de milésimo de segundo, o CloudWatch agrega os dados com a precisão mínima de um segundo. O CloudWatch registra a média (soma de todos os itens dividida pelo número de itens) dos valores recebidos para cada período, bem como o número de amostras, o valor máximo e o valor mínimo para o mesmo período. Por exemplo, a métrica `PageViewCount` dos exemplos anteriores contém três pontos de dados com time stamps com apenas alguns segundos de intervalo. Se você tiver o período definido como 1 minuto, o CloudWatch agregará os três pontos de dados, pois eles têm carimbos de data/hora em um período de 1 minuto.
Você pode usar o comando **get-metric-statistics** para recuperar estatísticas com base nos pontos de dados publicados.
```
aws cloudwatch get-metric-statistics --namespace MyService --metric-name PageViewCount \
--statistics "Sum" "Maximum" "Minimum" "Average" "SampleCount" \
--start-time 2016-10-20T12:00:00.000Z --end-time 2016-10-20T12:05:00.000Z --period 60
```
O seguinte é um exemplo de saída.
```
{
"Datapoints": [
{
"SampleCount": 3.0,
"Timestamp": "2016-10-20T12:00:00Z",
"Average": 3.6666666666666665,
"Maximum": 5.0,
"Minimum": 2.0,
"Sum": 11.0,
"Unit": "None"
}
],
"Label": "PageViewCount"
}
```
## Publicar conjuntos de estatísticas
Você pode agregar seus dados antes de publicá-los no CloudWatch. Quando você tem vários pontos de dados por minuto, a agregação de dados reduz o número de chamadas para **put-metric-data**. Por exemplo, em vez de chamar **put-metric-data** várias vezes para três pontos de dados com três segundos de diferença um do outro, é possível agregar os dados em um conjunto de estatísticas publicado com uma chamada, usando o parâmetro `--statistic-values`.
```
aws cloudwatch put-metric-data --metric-name PageViewCount --namespace MyService --statistic-values Sum=11,Minimum=2,Maximum=5,SampleCount=3 --timestamp 2016-10-14T12:00:00.000Z
```
O CloudWatch precisa dos pontos e dados brutos para calcular percentis. Se você publicar dados usando um conjunto de estatísticas, não poderá recuperar estatísticas de percentis para esses dados, a menos que uma das seguintes condições seja verdadeira:
+ O `SampleCount` do conjunto de estatísticas é 1.
+ O `Minimum` e o `Maximum` do conjunto de estatísticas são iguais
## Publicar o valor zero
Quando os dados são mais esporádicos e você tem períodos sem dados associados, você pode optar por publicar o valor zero (`0`) para esse período ou nenhum valor. Se você usar chamadas periódicas para `PutMetricData` a fim de monitorar a integridade do seu aplicativo, talvez queira publicar zero em vez de nenhum valor. Por exemplo, é possível definir um alarme do CloudWatch para notificar você, se a aplicação não publicar métricas a cada cinco minutos. É recomendável que esse aplicativo publique zeros para períodos sem dados associados.
Você também pode publicar zeros se desejar rastrear o número total de pontos de dados ou se quiser que estatísticas como mínima e média incluam pontos de dados com o valor 0.
## Parar de publicar métricas
Para parar de publicar métricas personalizadas no CloudWatch, altere o código da aplicação ou do serviço de forma a parar de usar **PutMetricData**. O CloudWatch não extrai métricas de aplicações. Ele apenas recebe o que é enviado para ele. Portanto, para parar de publicar suas métricas, é necessário interrompê-las na fonte.