規格：內嵌指標格式

CloudWatch 內嵌指標格式是一種 JSON 規格，用來指示 CloudWatch Logs 自動擷取內嵌在結構化日誌事件中的指標值。您可以使用 CloudWatch 來根據擷取的指標值繪製圖表和建立警示。本節說明內嵌指標格式規格慣例和內嵌指標格式文件結構。

內嵌指標格式規格慣例

本格式規格中的關鍵字「必須」、「禁止」、「必要」、「可」、「不可」、「應」、「不應」、「建議」、「能」和「選用」應按照 Key Words RFC2119 中的說明解釋。

本格式規格中的術語「JSON」、「JSON 文字」、「JSON 值」、「成員」、「元素」、「物件」、「陣列」、「數字」、「字串」、「布林」、「True」、「False」和「Null」應按照 JavaScript Object Notation RFC8259 中的定義解釋。

注意

如果您打算在使用內嵌指標格式建立的指標上建立警示，請參閱在以內嵌指標格式建立的指標上設定警示以取得相關建議。

內嵌指標格式文件結構

本節說明內嵌指標格式文件的結構。內嵌指標格式文件是定義在 JavaScript Object Notation RFC8259 中。

除非另有說明，否則此規格定義的物件「禁止」包含任何其他成員。未經此規格辨識的成員「必須」遭到忽略。此規格中定義的成員區分大小寫。

內嵌指標格式受到與標準 CloudWatch Logs 事件相同的限制，且大小上限為 1 MB。

借助內嵌指標格式，您可以透過在您帳戶的 AWS/Logs 命名空間中發佈的指標追蹤 EMF 日誌的處理進度。這些指標可用於追蹤從 EMF 產生指標失敗的情形，以及失敗是否因剖析或驗證造成。如需詳細資訊，請參閱使用 CloudWatch 指標進行監控。

根節點

LogEvent 訊息「必須」是有效的 JSON 物件，且在 LogEvent 訊息字串的開頭和結尾不得包含任何其他資料。如需 LogEvent 結構的詳細資訊，請參閱 InputLogEvent。

內嵌指標格式文件「必須」在根節點上包含以下最上層成員。這是一個中繼資料物件物件。


{
 "_aws": {
    "CloudWatchMetrics": [ ... ]
  }
}

根節點必須包含所有由 MetricDirective 物件中參考定義的目標成員成員。

根節點「能」包含任何其他未包含在以上需求內的成員。這些成員的值「必須」是有效的 JSON 類型。

中繼資料物件

_aws 成員可以用來表示與承載相關的中繼資料，通知下游服務應如何處理 LogEvent。其值「必須」是物件且「必須」包含下列成員：

CloudWatchMetrics— MetricDirective 物件的陣列，用來指示 CloudWatch 從 LogEvent 的根節點擷取指標。
```
{
  "_aws": {
    "CloudWatchMetrics": [ ... ]
  }
}
```
時間戳記— 數字，表示用於從事件擷取的指標的時間戳記。其值「必須」表示為 UTC 時間 1970 年 1 月 1 日上午 00:00:00 之後的毫秒數。
```
{
  "_aws": {
    "Timestamp": 1559748430481
  }
}
```

MetricDirective 物件

MetricDirective 物件會指示下游服務 LogEvent 包含將擷取並發佈至 CloudWatch 的指標。MetricDirectives「必須」包含下列成員：

命名空間— 字串，可表示指標的 CloudWatch 命名空間。
維度— A DimensionSet 陣列。
指標— MetricDefinition 物件的陣列。此陣列「禁止」包含超過 100 個 MetricDefinition 物件。

DimensionSet 陣列

DimensionSet 是一個字串陣列，包含將套用至文件中所有指標的維度索引鍵。此陣列中的值「必須」也是根節點上的成員，稱為目標成員。

DimensionSet 不得包含超過 30 個維度索引鍵。DimensionSet 可能為空。

目標成員「必須」擁有字串值。此值不得包含超過 1,024 個字元。目標成員定義了將作為指標身分一部分發佈的維度。每個使用的 DimensionSet 都會在 CloudWatch 中建立新指標。如需維度的詳細資訊，請參閱維度和維度。


{
 "_aws": {
   "CloudWatchMetrics": [
     {
       "Dimensions": [ [ "functionVersion" ] ],
       ...
     }
   ]
 },
 "functionVersion": "$LATEST"
}

注意

請在設定您的指標擷取時注意，因為這會影響您的自訂指標用量和對應的帳單。如果您不小心建立了以高基數維度 (例如 requestId) 為基礎的指標，根據設計，內嵌指標格式會建立自訂指標，對應至每個獨特的維度組合。如需詳細資訊，請參閱維度。

MetricDefinition 物件

MetricDefinition 是一個「必須」包含以下成員的物件：

名稱— 字串參考值至指標目標成員。指標目標「必須」是數值或數值的陣列。

MetricDefinition 物件「可能」包含以下成員：

單位— 選用字串值，表示對應指標的測量單位。值「應」為有效的 CloudWatch 指標單位。如需有效單位的資訊，請參閱 MetricDatum。如果沒有提供值，則會使用預設值 NONE。
StorageResolution — 選用的整數值，表示對應指標的儲存解析度。若將此值設定為 1，則會將此指標指定為高解析度指標，CloudWatch 將以亞分 (sub-minute) 層級的解析度 (精細度可達一秒) 儲存指標。若將此指標設定為 60，則會將此指標指定為標準解析度，CloudWatch 會以 1 分鐘的解析度儲存。此值應為 CloudWatch 支援的有效解析度：1 或 60。若沒有提供值，則會使用預設值 60。

如需高解析度指標的詳細資訊，請參閱高解析度指標。

注意

如果您打算在使用內嵌指標格式建立的指標上建立警示，請參閱在以內嵌指標格式建立的指標上設定警示以取得相關建議。


{
  "_aws": {
    "CloudWatchMetrics": [
      {
        "Metrics": [
          {
            "Name": "Time",
            "Unit": "Milliseconds",
            "StorageResolution": 60
          }
        ],
        ...
      }
    ]
  },
  "Time": 1
}

參考值

參考值是參考根節點上目標成員成員的字串值。這些參考「不應」與 RFC6901 中說明的 JSON 指標混淆。目標值不可為巢狀。

目標成員

有效目標「必須」是根節點上的成員，且不可為巢狀物件。例如，"A.a" 的 _reference_ 值「必須」符合以下成員：


{ "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 的自訂遙測。

注意

實體資訊可協助 CloudWatch 建立應用程式遙測資料的完整樣貌，以及其在基礎設施內的關係。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

使用用戶端程式庫

使用 PutLogEvents API 傳送手動建立的內嵌指標格式日誌