本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 發布自訂指標
您可以使用 OpenTelemetry Protocol (OTLP) 或 CloudWatch API，將自己的指標發佈至 CloudWatch。
## 使用 OpenTelemetry 發佈指標 （建議）
對於新的實作，我們建議您使用 OpenTelemetry 將自訂指標發佈至 CloudWatch。OpenTelemetry 提供與廠商無關的檢測，具有更豐富的描述性標籤，並支援指標類型，包括量測計、總和、長條圖和指數長條圖。
若要使用 OpenTelemetry 發佈指標，請將 OpenTelemetry Collector 或 SDK 設定為將指標傳送至 CloudWatch OTLP 端點。透過 OTLP 傳送的指標可使用 CloudWatch Query Studio 中的 Prometheus 查詢語言 (PromQL) 進行查詢。您也可以在這些指標上設定 PromQL 型 CloudWatch 警示。
與 CloudWatch API 方法的主要差異：
| 功能 | OpenTelemetry (OTLP) | CloudWatch API (PutMetricData) |
| --- | --- | --- |
| 每個指標的標籤 | 最多 150 個 | 最多 30 個維度 |
| 指標類型 | 計量、總和、長條圖、指數長條圖 | 單一值、統計資料集 |
| 精細程度 | 擷取到傳送的解析度 | 1 秒 （高解析度） 或 1 分鐘 （標準） |
| 查詢語言 | PromQL | GetMetricStatistics、Metrics Insights |
| 警示 | 以 PromQL 為基礎的 CloudWatch 警示 | 標準 CloudWatch 警示 |
| 檢測 | 與廠商無關的 OpenTelemetry 開發套件和收集器 SDKs | AWS SDK 或 CLI |
若要開始使用，請參閱[使用 OpenTelemetry 傳送指標](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OpenTelemetry-Sections.html)。
## 使用 CloudWatch API 發佈指標
您也可以使用 PutMetricData API 或 發佈自訂指標 AWS CLI。此方法使用 CloudWatch 命名空間、指標名稱和維度。
**Topics**
+ [使用 OpenTelemetry 發佈指標 （建議）](#publishMetricsOTLP)
+ [使用 CloudWatch API 發佈指標](#publishMetricsCWAPI)
+ [高解析度指標](#high-resolution-metrics)
+ [使用維度](#usingDimensions)
+ [發布單一資料點](#publishingDataPoints)
+ [發布統計資料集](#publishingDataPoints1)
+ [發布零值](#publishingZero)
+ [停止發布指標](#CloudWatch-Stop-Publishing-Metrics)
## 高解析度指標
每個指標皆為下列其中一種：
+ 標準解析度，包含 1 分鐘精細度的資料
+ 高解析度，包含 1 秒鐘精細度的資料
AWS 服務產生的指標預設為標準解析度。當您發布自訂指標時，可將它定義為標準解析度或高解析度。當您發布高解析度指標時，CloudWatch 會將它以 1 秒鐘解析度儲存，您可以用 1 秒鐘、5 秒鐘、10 秒鐘、30 秒鐘或 60 秒鐘的任何倍數來讀取及擷取它。
高解析度的指標可讓您以高於分鐘層級的精細度，更即時地深入了解您應用程式的活動。請注意，對自訂指標進行的每個 `PutMetricData` 呼叫皆需付費，因此經常對高解析度指標呼叫 `PutMetricData` 將導致更高的費用。如需 CloudWatch 定價的詳細資訊，請參閱 [Amazon CloudWatch 定價](https://aws.amazon.com/cloudwatch/pricing/)。
如果您在高解析度指標設定警示，您可以指定期間為 10 秒或 30 秒的高解析度警示，或者設定期間為 60 秒的任何倍數的定期警示。期間為 10 或 30 秒的高解析度警示將產生更高的費用。
## 使用維度
在自訂指標中，`--dimensions` 參數是很常見的。維度可更進一步釐清指標內容及其存放的資料。指派給一個指標的維度最多可有 30 個，每個維度皆以名值對定義。
當您使用不同的命令時，指定維度的方式也不同。使用 [put-metric-data](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/put-metric-data.html) 時，您以 *MyName*=*MyValue* 指定各個維度，而使用 [get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html) 或 [put-metric-alarm](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/put-metric-alarm.html) 時，則使用 `Name=`*MyName*、`Value=`*MyValue* 格式。例如，以下命令會發布包含 `InstanceId` 和 `InstanceType` 兩個維度的 `Buffers` 指標。
```
aws cloudwatch put-metric-data --metric-name Buffers --namespace MyNameSpace --unit Bytes --value 231434333 --dimensions InstanceId=1-23456789,InstanceType=m1.small
```
此命令擷取相同指標的統計資料。以逗號分隔單一維度的名稱和值部分，但如果您有多個維度，請維度與維度之間使用空格。
```
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
```
如果單一指標包含多個維度，當您使用 [get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html) 時，您必須為每個維度指定值。例如，Simple Storage Service (Amazon S3) 指標 `BucketSizeBytes` 包含維度 `BucketName` 和 `StorageType`，因此您必須使用 [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
```
請使用 [list-metrics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/list-metrics.html) 命令查看針對指標所定義的維度。
## 發布單一資料點
若要為新的或現有的指標發布單一資料點，請使用 [put-metric-data](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/put-metric-data.html) 命令與一個值和時間戳記。例如，以下每個動作都會發布一個資料點。
```
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
```
如果您以新指標名稱呼叫此命令，CloudWatch 將為您建立指標。否則，CloudWatch 會將您的資料與您指定的現有指標建立關聯。
**注意**
當您建立指標時，使用 [get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html) 命令擷取新指標的統計資料，最多可能需要 2 分鐘。不過，使用 [list-metrics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/list-metrics.html) 命令擷取的指標清單可能需要長達 15 分鐘，才會顯示新的指標。
雖然您可以使用千分之一秒精細度的時間戳記來發布資料點，CloudWatch 仍會以一秒的最低精細度彙總資料。CloudWatch 記錄每個期間收到的值的平均 (所有項目總和除以項目數)，以及相同期間的範本數量、最大值及最小值。例如，之前範例的 `PageViewCount` 指標包含三個資料點，其時間戳記僅相差幾秒。如果您將區間設定為 1 分鐘，CloudWatch 將彙總這三個資料點，因為它們的時間戳記皆在一分鐘的期間內。
您可以使用 **get-metric-statistics** 命令，根據您發布的資料點來擷取統計資料。
```
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
```
以下為範例輸出。
```
{
"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"
}
```
## 發布統計資料集
您可以彙總資料，再發布到 CloudWatch。如果您在每分鐘有多個資料點，彙總資料可大幅減少呼叫 **put-metric-data** 的次數。例如，您可以使用 `--statistic-values` 參數，將資料彙總到統計資料集，並以一次呼叫發布此統計資料集，而非針對 3 秒內發生的三個資料點多次呼叫 **put-metric-data**。
```
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
```
CloudWatch 需要原始資料點求來計算百分位。如果已用統計資料集發布資料，除非以下條件之一為 true，否則您就無法擷取此資料的百分位統計資料：
+ 統計資料集的 `SampleCount` 設定為 1。
+ 統計資料集的 `Minimum` 和 `Maximum` 相等。
## 發布零值
當您的資料更為零散，而且您有一些期間沒有關聯的資料，那麼您可以選擇為該期間發布零值 (`0`) 或無值。如果您使用定期呼叫來 `PutMetricData` 以監控應用程式的狀態，您可能會想要發布零而非無值。例如，您可以設定 CloudWatch 警示，當您的應用程式無法每 5 分鐘發布指標時通知您。您希望這類應用程式在無需關聯資料的期間發布零。
如果您想追蹤資料點的總數，或希望統計資料如最低值和平均值包含 0 值的資料點，那麼您也會希望發布零。
## 停止發布指標
若要停止向 CloudWatch 發布自訂指標，請變更應用程式或服務的程式碼，以停止使用 **PutMetricData**。CloudWatch 不會從應用程式中提取指標，只會接收推送給它的內容，因此，若要停止發布您的指標，必須在來源位置停止這些指標。