规范：嵌入式指标格式 - Amazon CloudWatch
约定嵌入式指标格式文档结构
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

规范：嵌入式指标格式

CloudWatch 嵌入式指标格式是一个 JSON 规范，用于指示 CloudWatch Logs 自动提取结构化日志事件中嵌入的指标值。您可以使用 CloudWatch 基于提取的指标值绘制图表并创建告警。

嵌入式指标格式规范约定

此格式规范中的关键字“MUST”、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、“RECOMMENDED”、“MAY”和“OPTIONAL”的解释如关键字 RFC2119 中所述。

此格式规范中的属于“JSON”、“JSON text”、“JSON value”、“member”、“element”、“object”、“array”、“number”、“string”、“boolean”、“true”、“false”和“null”的解释如 JavaScript 对象表示法 RFC8259 中所述。

注意

如果您计划为使用嵌入式指标格式创建的指标创建告警，请参阅 为使用嵌入式指标格式创建的指标设置警报 获取相关建议。

嵌入式指标格式文档结构

此节介绍了嵌入式指标格式文档的结构。嵌入式指标格式文档用 JavaScript 对象表示法 RFC8259 进行定义。

除非另有说明，否则此规范定义的对象不得包含任何其他成员。必须忽略此规范无法识别的成员。此规范中定义的成员是区分大小写的。

嵌入式指标格式受与标准 CloudWatch Logs 事件相同的限制，并且其最大大小限制为 256KB。

通过嵌入式指标格式，您可以按指标跟踪发布在您账户的 Amazon/Logs 命名空间中的 EMF 日志的处理。可通过这些日志跟踪 EMF 中指标生成失败的情况，以及失败的原因是解析还是验证。有关更多详细信息，请参阅使用 CloudWatch 指标监控。

根节点

LogEvent 消息必须是一个有效的 JSON 对象，并且 LogEvent 消息字符串的开头或结尾没有其他数据。有关 LogEvent 结构的更多信息，请参阅 InputLogEvent。

嵌入式指标格式文档必须包含根节点上的以下顶级成员。这是一个 元数据对象 对象。

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

根节点必须包含由 MetricDirective 对象 中的引用定义的所有 目标成员 成员。

根节点可以包含上述要求中未包含的任何其他成员。这些成员的值必须是有效的 JSON 类型。

元数据对象

_aws 成员可用于表示有关负载的元数据，告知下游服务应如何处理 LogEvent。该值必须是一个对象，并且必须包含以下成员：

  • CloudWatchMetrics – 一个 MetricDirective 对象 数组，用于指示 CloudWatch 从 LogEvent 的根节点提取指标。

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

  • 时间戳 – 一个数字，表示用于从事件中提取的指标的时间戳。值必须表示为自 1970 年 1 月 1 日 00:00:00 UTC 以来的毫秒数。

    {
  "_aws": {
    "Timestamp": 1559748430481
  }
}

MetricDirective 对象

MetricDirective 对象指示下游服务 LogEvent 包含将提取并发布到 CloudWatch 的指标。MetricDirectives 必须包含以下成员：

  • 命名空间 – 一个表示指标的 CloudWatch 命名空间的字符串。

  • 维度 – 一个 DimensionSet 数组。

  • 指标 – 一个 MetricDefinition 对象数组。此数组不得包含 100 个以上的 MetricDefinition 对象。

DimensionSet 数组

DimensionSet 是一个字符串数组，其中包含将应用于文档中的所有指标的维度键。此数组中的值也必须是根节点上的成员 - 称为 目标成员

DimensionSet 不得包含 30 个以上的维度键。DimensionSet 可以为空。

目标成员必须具有字符串值。此值不得包含 1024 个以上的字符。目标成员定义了将作为指标标识的一部分发布的维度。使用的每个 DimensionSet 都会在 CloudWatch 中创建一个新指标。有关维度的更多信息，请参阅维度和维度。

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

配置指标提取时请务必小心，因为它会影响自定义指标的使用和相应的账单。如果您无意中创建了基于高基数维度的指标（例如 requestId），则嵌入式指标格式将通过设计创建与每个唯一维度组合对应的自定义指标。有关更多信息，请参阅维度。

MetricDefinition 对象

MetricDefinition 是一个必须包含以下成员的对象：

MetricDefinition 对象可以包含以下成员：

  • 单位 – 一个可选字符串值，表示相应指标的度量单位。值应是有效的 CloudWatch 指标单位。有关有效单位的信息，请参阅 MetricDatum。如果未提供值，则假定默认值为 NONE。

  • StorageResolution – 可选整数值，表示相应指标的存储分辨率。将此值设置为 1，这样会将此指标指定为高分辨率指标，以便 CloudWatch 以亚分钟分辨率将指标存储到 1 秒。将此值设置为 60，这样会将此指标指定为标准分辨率，CloudWatch 以 1 分钟分辨率存储该指标。值应是支持 CloudWatch 的有效分辨率，即 1 或 60。如果未提供值，则假定默认值为 60。

    有关高精度指标的更多信息，请参阅 高精度指标。

注意

如果您计划为使用嵌入式指标格式创建的指标创建告警，请参阅 为使用嵌入式指标格式创建的指标设置警报 获取相关建议。

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

参考值

参考值是引用根节点上的 目标成员 成员的字符串值。这些引用不应与 RFC6901 中描述的 JSON 指针混淆。无法嵌套目标值。

目标成员

有效目标必须是根节点上的成员，而不能是嵌套对象。例如，"A.a" 的参考值必须与以下成员匹配：

{ "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
                                            ]
                                         }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}