规范:嵌入式指标格式 - Amazon CloudWatch
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

规范:嵌入式指标格式

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 中所述。

嵌入式指标格式规范 PutLogEvents 请求格式

在使用 CloudWatch Logs PutLogEvents API 发送嵌入式指标格式文档时,客户端必须使用以下日志格式标头:

x-amzn-logs-format: json/emf

在 Lambda 上,您不需要自己设置此标题。以嵌入式指标格式将 JSON 写到标准输出就足够了。虽然 Lambda 可能会在日志事件前附加元数据(如时间戳和请求 ID),但此元数据后的有效嵌入式指标格式文档被视为有效。

嵌入式指标格式文档结构

此部分介绍了嵌入式指标格式文档的结构,该文档由日志格式标头 x-amzn-logs-format: json/emf 标识。嵌入式指标格式文档用 JavaScript 对象表示法 RFC8259 进行定义。

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

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

根节点

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 不得包含 9 个以上的维度键。

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

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

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

MetricDefinition 对象

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

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

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

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

参考值

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

目标成员

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

{ "A.a" }

它不得与嵌套成员匹配:

{ "A": { "a" } }

目标成员的有效值取决于引用它们的对象。例如,指标目标必须是一个数值,或者数值数组,而维度目标必须是字符串值。

嵌入式指标格式示例和 JSON 架构

以下是嵌入式指标格式的有效示例。

{ "_aws": { "Timestamp": 1574109732004, "CloudWatchMetrics": [ { "Namespace": "lambda-function-metrics", "Dimensions": [["functionVersion"]], "Metrics": [ { "Name": "time", "Unit": "Milliseconds" } ] } ] }, "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 }, "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": 1, "maxItems": 9, "items": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Dimensions/items/items", "type": "string", "title": "DimensionReference", "examples": [ "Operation" ], "pattern": "^(.*)$", "minItems": 1 } } }, "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": "^(.*)$" }, "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)$" } } } } } } } } } } }