本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 規格：內嵌指標格式
CloudWatch 內嵌指標格式是一種 JSON 規格，用來指示 CloudWatch Logs 自動擷取內嵌在結構化日誌事件中的指標值。您可以使用 CloudWatch 來根據擷取的指標值繪製圖表和建立警示。本節主要介紹內嵌指標格式規格慣例和內嵌指標格式文件結構。
## 內嵌指標格式規格慣例
本格式規格中的關鍵字「必須」、「禁止」、「必要」、「可」、「不可」、「應」、「不應」、「建議」、「能」和「選用」應按照 [Key Words RFC2119](http://tools.ietf.org/html/rfc2119) 中的說明解釋。
本格式規格中的術語「JSON」、「JSON 文字」、「JSON 值」、「成員」、「元素」、「物件」、「陣列」、「數字」、「字串」、「布林」、「True」、「False」和「Null」應按照 [JavaScript Object Notation RFC8259](https://tools.ietf.org/html/rfc8259) 中的定義解釋。
**注意**
如果您打算在使用內嵌指標格式建立的指標上建立警示，請參閱[在以內嵌指標格式建立的指標上設定警示](CloudWatch_Embedded_Metric_Format_Alarms.md)以取得相關建議。
## 內嵌指標格式文件結構
本節說明內嵌指標格式文件的結構。內嵌指標格式文件是定義在 [JavaScript Object Notation RFC8259](https://tools.ietf.org/html/rfc8259) 中。
除非另有說明，否則此規格定義的物件「禁止」包含任何其他成員。未經此規格辨識的成員「必須」遭到忽略。此規格中定義的成員區分大小寫。
內嵌指標格式會受制於與標準 CloudWatch Logs 事件相同的限制，且大小上限為 1 MB。
借助內嵌指標格式，您可以透過在您帳戶的 `AWS/Logs` 命名空間中發布的指標追蹤 EMF 日誌的處理進度。這些指標可用於追蹤從 EMF 產生指標失敗的情形，以及失敗是否因剖析或驗證造成。如需詳細資訊，請參閱[使用 CloudWatch 指標進行監控](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html)。
### 根節點
LogEvent 訊息「必須」是有效的 JSON 物件，且在 LogEvent 訊息字串的開頭和結尾不得包含任何其他資料。如需 LogEvent 結構的詳細資訊，請參閱 [InputLogEvent](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_InputLogEvent.html)。
內嵌指標格式文件「必須」在根節點上包含以下最上層成員。這是一個 [中繼資料物件](#CloudWatch_Embedded_Metric_Format_Specification_structure_metadata) 物件。
```
{
"_aws": {
"CloudWatchMetrics": [ ... ]
}
}
```
根節點必須包含所有由 [MetricDirective 物件](#CloudWatch_Embedded_Metric_Format_Specification_structure_metricdirective) 中參考定義的 [目標成員](#CloudWatch_Embedded_Metric_Format_Specification_structure_target) 成員。
根節點「能」包含任何其他未包含在以上需求內的成員。這些成員的值「必須」是有效的 JSON 類型。
### 中繼資料物件
`_aws` 成員可以用來表示與承載相關的中繼資料，通知下游服務應如何處理 LogEvent。其值「必須」是物件且「必須」包含下列成員：
+ **CloudWatchMetrics**— [MetricDirective 物件](#CloudWatch_Embedded_Metric_Format_Specification_structure_metricdirective) 的陣列，用來指示 CloudWatch 從 LogEvent 的根節點擷取指標。
```
{
"_aws": {
"CloudWatchMetrics": [ ... ]
}
}
```
+ **時間戳記**— 數字，表示用於從事件擷取的指標的時間戳記。其值「必須」表示為 UTC 時間 1970 年 1 月 1 日上午 00:00:00 之後的毫秒數。
```
{
"_aws": {
"Timestamp": 1559748430481
}
}
```
### MetricDirective 物件
MetricDirective 物件會指示下游服務 LogEvent 包含將擷取並發布至 CloudWatch 的指標。MetricDirectives「必須」包含下列成員：
+ **命名空間**— 字串，可表示指標的 CloudWatch 命名空間。
+ **維度**— A [DimensionSet 陣列](#CloudWatch_Embedded_Metric_Format_Specification_structure_dimensionset)。
+ **指標**— [MetricDefinition 物件](#CloudWatch_Embedded_Metric_Format_Specification_structure_metricdefinition) 物件的陣列。此陣列「禁止」包含超過 100 個 MetricDefinition 物件。
### DimensionSet 陣列
DimensionSet 是一個字串陣列，包含將套用至文件中所有指標的維度索引鍵。此陣列中的值「必須」也是根節點上的成員，稱為 [目標成員](#CloudWatch_Embedded_Metric_Format_Specification_structure_target)。
DimensionSet 不得包含超過 30 個維度索引鍵。DimensionSet 可能為空。
目標成員「必須」擁有字串值。此值不得包含超過 1,024 個字元。目標成員定義了將作為指標身分一部分發布的維度。每個使用的 DimensionSet 都會在 CloudWatch 中建立新指標。如需維度的詳細資訊，請參閱[維度](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_Dimension.html)和[維度](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Dimension)。
```
{
"_aws": {
"CloudWatchMetrics": [
{
"Dimensions": [ [ "functionVersion" ] ],
...
}
]
},
"functionVersion": "$LATEST"
}
```
**注意**
請在設定您的指標擷取時注意，因為這會影響您的自訂指標用量和對應的帳單。如果您不小心建立了以高基數維度 (例如 `requestId`) 為基礎的指標，根據設計，內嵌指標格式會建立自訂指標，對應至每個獨特的維度組合。如需詳細資訊，請參閱[維度](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Dimension)。
### MetricDefinition 物件
MetricDefinition 是一個「必須」包含以下成員的物件：
+ **名稱**— 字串 [參考值](#CloudWatch_Embedded_Metric_Format_Specification_structure_referencevalues) 至指標 [目標成員](#CloudWatch_Embedded_Metric_Format_Specification_structure_target)。指標目標「必須」是數值或數值的陣列。
MetricDefinition 物件「可能」包含以下成員：
+ **單位**— 選用字串值，表示對應指標的測量單位。值「應」為有效的 CloudWatch 指標單位。如需有效單位的資訊，請參閱 [MetricDatum](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_MetricDatum.html)。如果沒有提供值，則會使用預設值 NONE。
+ **StorageResolution** — 選用的整數值，表示對應指標的儲存解析度。若將此值設定為 1，則會將此指標指定為高解析度指標，CloudWatch 將以亞分 (sub-minute) 層級的解析度 (精細度可達一秒) 儲存指標。若將此指標設定為 60，則會將此指標指定為標準解析度，CloudWatch 會以 1 分鐘的解析度儲存。此值應為 CloudWatch 支援的有效解析度：1 或 60。若沒有提供值，則會使用預設值 60。
如需高解析度指標的詳細資訊，請參閱 [高解析度指標](publishingMetrics.md#high-resolution-metrics)。
**注意**
如果您打算在使用內嵌指標格式建立的指標上建立警示，請參閱[在以內嵌指標格式建立的指標上設定警示](CloudWatch_Embedded_Metric_Format_Alarms.md)以取得相關建議。
```
{
"_aws": {
"CloudWatchMetrics": [
{
"Metrics": [
{
"Name": "Time",
"Unit": "Milliseconds",
"StorageResolution": 60
}
],
...
}
]
},
"Time": 1
}
```
### 參考值
參考值是參考根節點上 [目標成員](#CloudWatch_Embedded_Metric_Format_Specification_structure_target) 成員的字串值。這些參考「不應」與 [RFC6901](https://tools.ietf.org/html/rfc6901) 中說明的 JSON 指標混淆。目標值不可為巢狀。
### 目標成員
有效目標「必須」是根節點上的成員，且不可為巢狀物件。例如，`"A.a"` 的 \$1reference\$1 值「必須」符合以下成員：
```
{ "A.a" }
```
其「禁止」與巢狀成員相符：
```
{ "A": { "a" } }
```
目標成員的有效值取決於參考目標成員的項目。指標目標「必須」是數值或數值的陣列。數值陣列指標目標不得超過 100 個成員。維度目標「必須」擁有字串值。
### 內嵌指標格式範例和 JSON 結構描述
以下是內嵌指標格式的有效範例。
```
{
"_aws": {
"Timestamp": 1574109732004,
"CloudWatchMetrics": [
{
"Namespace": "lambda-function-metrics",
"Dimensions": [["functionVersion"]],
"Metrics": [
{
"Name": "time",
"Unit": "Milliseconds",
"StorageResolution": 60
}
]
}
]
},
"functionVersion": "$LATEST",
"time": 100,
"requestId": "989ffbf8-9ace-4817-a57c-e4dd734019ee"
}
```
您可以使用以下結構描述來驗證內嵌指標格式文件。
```
{
"type": "object",
"title": "Root Node",
"required": [
"_aws"
],
"properties": {
"_aws": {
"$id": "#/properties/_aws",
"type": "object",
"title": "Metadata",
"required": [
"Timestamp",
"CloudWatchMetrics"
],
"properties": {
"Timestamp": {
"$id": "#/properties/_aws/properties/Timestamp",
"type": "integer",
"title": "The Timestamp Schema",
"examples": [
1565375354953
]
},
"CloudWatchMetrics": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics",
"type": "array",
"title": "MetricDirectives",
"items": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items",
"type": "object",
"title": "MetricDirective",
"required": [
"Namespace",
"Dimensions",
"Metrics"
],
"properties": {
"Namespace": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Namespace",
"type": "string",
"title": "CloudWatch Metrics Namespace",
"examples": [
"MyApp"
],
"pattern": "^(.*)$",
"minLength": 1,
"maxLength": 1024
},
"Dimensions": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Dimensions",
"type": "array",
"title": "The Dimensions Schema",
"minItems": 1,
"items": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Dimensions/items",
"type": "array",
"title": "DimensionSet",
"minItems": 0,
"maxItems": 30,
"items": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Dimensions/items/items",
"type": "string",
"title": "DimensionReference",
"examples": [
"Operation"
],
"pattern": "^(.*)$",
"minLength": 1,
"maxLength": 250
}
}
},
"Metrics": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics",
"type": "array",
"title": "MetricDefinitions",
"items": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics/items",
"type": "object",
"title": "MetricDefinition",
"required": [
"Name"
],
"properties": {
"Name": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics/items/properties/Name",
"type": "string",
"title": "MetricName",
"examples": [
"ProcessingLatency"
],
"pattern": "^(.*)$",
"minLength": 1,
"maxLength": 1024
},
"Unit": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics/items/properties/Unit",
"type": "string",
"title": "MetricUnit",
"examples": [
"Milliseconds"
],
"pattern": "^(Seconds|Microseconds|Milliseconds|Bytes|Kilobytes|Megabytes|Gigabytes|Terabytes|Bits|Kilobits|Megabits|Gigabits|Terabits|Percent|Count|Bytes\\/Second|Kilobytes\\/Second|Megabytes\\/Second|Gigabytes\\/Second|Terabytes\\/Second|Bits\\/Second|Kilobits\\/Second|Megabits\\/Second|Gigabits\\/Second|Terabits\\/Second|Count\\/Second|None)$"
},
"StorageResolution": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics/items/properties/StorageResolution",
"type": "integer",
"title": "StorageResolution",
"examples": [
60
]
}
}
}
}
}
}
}
}
}
}
}
```
## EMF 格式的實體資訊
當您使用內嵌指標格式 (EMF) 將日誌發布至 Amazon CloudWatch 時，可以在日誌事件中包含實體資訊。本節說明如何指定實體資訊，以及 CloudWatch 如何處理此資訊。
### 實體類型
當 `PutLogEvents` 請求中未指定實體時，CloudWatch 將從 EMF 日誌內容中搜尋實體資訊：
+ **服務類型實體**
必要欄位：`Service` 和 `Environment`
+ **資源類型實體**
必要欄位：`ResourceType` 和 `Identifier`
### 平台屬性
CloudWatch 會根據這些屬性自動決定平台類型：
+ **Kubernetes (K8s)：**
必要：`K8s.Cluster`
選用：`K8s.Namespace`、`K8s.Workload`、`K8s.Node`、`K8s.Pod`、`EC2.InstanceId`、`EC2.AutoScalingGroup`
+ **Amazon EKS**
必要：`EKS.Cluster`
選用：`K8s.Namespace`、`K8s.Workload`、`K8s.Node`、`K8s.Pod`、`EC2.InstanceId`
+ **Amazon ECS：**
必要：`ECS.Cluster`
選用：`ECS.Service`、`ECS.Task`
+ **Amazon EC2**
必要：`EC2.InstanceId`
選用：`EC2.AutoScalingGroup`
+ **Lambda：**
必要：`Lambda.Function`
+ **一般主機：**
必要：`Host`
### EMF 日誌格式範例
```
{
"_aws": {
"CloudWatchMetrics": [
{
"Metrics": [
{"Name": "RequestLatency", "Unit": "Milliseconds"}
],
"Namespace": "MyApplication"
}
]
},
"Service": "PaymentService",
"Environment": "Production",
"K8s.Cluster": "main-cluster",
"K8s.Namespace": "payment-ns",
"K8s.Pod": "payment-pod-123",
"K8s.Node": "worker-node-1",
"K8s.Workload": "payment-deployment",
"RequestLatency": 135.5,
"timestamp": 1622163600000
}
```
### 產生的實體
上述 EMF 日誌將產生下列實體：
```
{
"KeyAttributes": {
"Type": "Service",
"Name": "PaymentService",
"Environment": "Production"
},
"Attributes": {
"PlatformType": "K8s",
"K8s.Cluster": "main-cluster",
"K8s.Namespace": "payment-ns",
"K8s.Pod": "payment-pod-123",
"K8s.Node": "worker-node-1",
"K8s.Workload": "payment-deployment"
}
}
```
### 實體處理
CloudWatch 會處理實體資訊，如下所示：
+ **KeyAttributes：**
+ 根據必要欄位確定實體類型
+ 對於服務類型，擷取服務名稱和環境
+ 這些會成為實體的主要識別符
+ **屬性**：
+ 根據包含的平台屬性設定 PlatformType
+ 包含所有相關平台特定資訊
+ 維護遙測資料的關係內容
CloudWatch 使用此實體資訊來建立不同遙測資料片段之間的關係，進而增強應用程式和基礎結構的可觀測性及內容分析。如需詳細資訊，請參閱[如何將相關資訊新增至傳送到 CloudWatch 的自訂遙測](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/adding-your-own-related-telemetry.html)。
**注意**
實體資訊有助於 CloudWatch 建立應用程式的遙測資料全貌，並呈現其在基礎結構中的關聯性。