사양: 임베디드 지표 형식

CloudWatch 임베디드 지표 형식은 구조화된 로그 이벤트에 포함된 지표 값을 자동으로 추출하도록 CloudWatch Logs에 지시하는 데 사용되는 JSON 사양입니다. 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로 제한됩니다.

포함된 지표 형식을 사용하면 계정의 AWS/Logs 네임스페이스에 게시된 지표별로 EMF 로그 처리를 추적할 수 있습니다. 이를 사용하여 EMF에서 실패한 지표 생성과 구문 분석 또는 검증으로 인한 오류 발생 여부를 추적할 수 있습니다. 자세한 내용을 알아보려면 CloudWatch 지표를 사용한 모니터링을 참조하세요.

루트 노드

LogEvent 메시지는 LogEvent 메시지 문자열의 시작 또는 끝에 추가 데이터가 없는 유효한 JSON 객체여야 합니다. LogEvent 구조에 대한 자세한 내용은 InputLogEvent를 참조하세요.

임베디드 지표 형식 문서는 루트 노드에 다음과 같은 최상위 멤버를 포함해야 합니다. 이는 메타데이터 객체 객체입니다.


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

루트 노드에는 MetricDirective 객체의 참조로 정의된 모든 대상 멤버 멤버가 포함되어야 합니다.

루트 노드는 위의 요구 사항에 포함되지 않은 다른 멤버를 포함할 수 있습니다. 이러한 멤버의 값은 유효한 JSON 유형이어야 합니다.

메타데이터 객체

_aws 멤버는 다운스트림 서비스에 LogEvent를 처리하는 방법을 알려주는 페이로드에 대한 메타데이터를 나타내는 데 사용할 수 있습니다. 값은 객체여야 하며 다음 멤버를 포함해야 합니다.

CloudWatchMetrics - LogEvent의 루트 노드에서 지표를 추출하도록 CloudWatch에 지시하는데 사용되는 MetricDirective 객체의 배열입니다.
```
{
  "_aws": {
    "CloudWatchMetrics": [ ... ]
  }
}
```
Timestamp - 이벤트에서 추출된 지표에 사용되는 타임스탬프를 나타내는 숫자입니다. 값은 1970년 1월 1일 00:00:00 UTC 이후 경과된 시간(밀리초)으로 표시해야 합니다.
```
{
  "_aws": {
    "Timestamp": 1559748430481
  }
}
```

MetricDirective 객체

MetricDirective 객체는 추출하여 CloudWatch에 게시될 지표를 LogEvent가 포함하도록 다운스트림 서비스에 지시합니다. MetricDirectives에는 다음 멤버가 포함되어야 합니다.

Namespace - 지표의 CloudWatch 네임스페이스를 나타내는 문자열입니다.
Dimensions - DimensionSet 배열입니다.
Metrics - MetricDefinition 객체의 배열입니다. 이 배열에 100개를 초과하는 MetricDefinition 객체가 포함되어서는 안 됩니다.

DimensionSet 배열

DimensionSet는 문서의 모든 지표에 적용될 차원 키를 포함하는 문자열 배열입니다. 또한 이 배열 내의 값은 대상 멤버라고 하는 루트 노드의 멤버여야 합니다.

DimensionSet에는 30개를 초과하는 차원 키가 포함되어서는 안 됩니다. DimensionSet는 비어 있을 수 있습니다.

대상 멤버에는 문자열 값이 있어야 합니다. 이 값은 1024자를 초과하는 문자를 포함해서는 안 됩니다. 대상 멤버는 지표 ID의 일부로 게시될 차원을 정의합니다. 사용된 모든 DimensionSet는 CloudWatch에 새 지표를 생성합니다. 차원에 대한 자세한 내용은 차원 및 차원을 참조하세요.


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

참고

지표 추출을 구성할 때는 사용자 지정 지표 사용 및 해당 청구서에 영향을 미치므로 주의해야 합니다. 높은 카디널리티 차원(예: requestId)을 기반으로 지표를 실수로 생성하는 경우 기본적으로 임베디드 지표 형식은 각 고유 차원 조합에 해당하는 사용자 지정 지표를 생성합니다. 자세한 내용은 차원 단원을 참조하세요.

MetricDefinition 객체

MetricDefinition은 다음 멤버를 포함해야 하는 객체입니다.

Name - 대상 멤버 지표에 대한 참조 값 문자열입니다. 지표 대상은 숫자 값 또는 숫자 값의 배열이어야 합니다.

MetricDefinition 객체에는 다음 멤버가 포함될 수 있습니다.

Unit - 해당 지표에 대한 측정 단위를 나타내는 선택적 문자열 값입니다. 값은 유효한 CloudWatch 지표 단위여야 합니다. 유효한 단위에 대한 자세한 내용은 MetricDatum을 참조하세요. 값이 제공되지 않으면 기본값인 NONE으로 가정합니다.
StorageResolution - 해당 지표에 대한 스토리지 해상도를 나타내는 선택적 정수 값입니다. 이 값을 1로 설정하면 이 지표가 고해상도 지표로 지정되므로 CloudWatch는 1분 미만의 해상도로 지표를 1초까지 저장합니다. 이 값을 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
                                            ]
                                         }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

클라이언트 라이브러리 사용

PutLogEvents API를 사용하여 수동으로 생성된 임베디드 지표 형식 로그 전송