# 사양: 임베디드 지표 형식
CloudWatch 임베디드 지표 형식은 구조화된 로그 이벤트에 포함된 지표 값을 자동으로 추출하도록 CloudWatch Logs에 지시하는 데 사용되는 JSON 사양입니다. CloudWatch를 사용하여 추출된 지표 값에 대한 그래프를 작성하고 경보를 생성할 수 있습니다. 이 섹션에서는 임베디드 지표 형식 사양 규칙과 임베디드 지표 형식 문서 구조를 설명합니다.
## 임베디드 지표 형식 사양 규칙
이 형식 사양의 “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY” 및 “OPTIONAL” 키워드는 [키워드 RFC2119](http://tools.ietf.org/html/rfc2119)에 설명된 대로 해석됩니다.
이 형식 사양의 "JSON", "JSON text", "JSON value", "member", "element", "object", "array", "number", "string", "boolean", "true", "false" 및 "null" 용어는 [JavaScript 객체 표기법 RFC8259](https://tools.ietf.org/html/rfc8259)에 정의된 대로 해석됩니다.
**참고**
임베디드 지표 형식을 사용하여 만든 지표의 경보를 만들려는 경우 [임베디드 지표 형식으로 만든 지표의 경보 설정](CloudWatch_Embedded_Metric_Format_Alarms.md)에서 권장 사항을 참조하세요.
## 임베디드 지표 형식 문서 구조
이 섹션에서는 임베디드 지표 형식 문서의 구조에 대해 설명합니다. 임베디드 지표 형식 문서는 [JavaScript 객체 표기법 RFC8259](https://tools.ietf.org/html/rfc8259)에 정의되어 있습니다.
별도의 언급이 없는 한 이 사양에 의해 정의된 객체에 추가 멤버가 포함되어서는 안 됩니다. 이 사양에 의해 인식되지 않는 멤버는 무시해야 합니다. 이 사양에 정의된 멤버는 대/소문자를 구분합니다.
임베디드 지표 형식은 표준 CloudWatch Logs 이벤트와 동일한 제한이 적용되며 최대 크기가 1MB로 제한됩니다.
포함된 지표 형식을 사용하면 계정의 `AWS/Logs` 네임스페이스에 게시된 지표별로 EMF 로그 처리를 추적할 수 있습니다. 이를 사용하여 EMF에서 실패한 지표 생성과 구문 분석 또는 검증으로 인한 오류 발생 여부를 추적할 수 있습니다. 자세한 내용을 알아보려면 [CloudWatch 지표를 사용한 모니터링](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html)을 참조하세요.
### 루트 노드
LogEvent 메시지는 LogEvent 메시지 문자열의 시작 또는 끝에 추가 데이터가 없는 유효한 JSON 객체여야 합니다. 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** - LogEvent의 루트 노드에서 지표를 추출하도록 CloudWatch에 지시하는데 사용되는 [MetricDirective 객체](#CloudWatch_Embedded_Metric_Format_Specification_structure_metricdirective)의 배열입니다.
```
{
"_aws": {
"CloudWatchMetrics": [ ... ]
}
}
```
+ **Timestamp** - 이벤트에서 추출된 지표에 사용되는 타임스탬프를 나타내는 숫자입니다. 값은 1970년 1월 1일 00:00:00 UTC 이후 경과된 시간(밀리초)으로 표시해야 합니다.
```
{
"_aws": {
"Timestamp": 1559748430481
}
}
```
### MetricDirective 객체
MetricDirective 객체는 추출하여 CloudWatch에 게시될 지표를 LogEvent가 포함하도록 다운스트림 서비스에 지시합니다. MetricDirectives에는 다음 멤버가 포함되어야 합니다.
+ **Namespace** - 지표의 CloudWatch 네임스페이스를 나타내는 문자열입니다.
+ **Dimensions** - [DimensionSet 배열](#CloudWatch_Embedded_Metric_Format_Specification_structure_dimensionset)입니다.
+ **Metrics** - [MetricDefinition 객체](#CloudWatch_Embedded_Metric_Format_Specification_structure_metricdefinition) 객체의 배열입니다. 이 배열에 100개를 초과하는 MetricDefinition 객체가 포함되어서는 안 됩니다.
### DimensionSet 배열
DimensionSet는 문서의 모든 지표에 적용될 차원 키를 포함하는 문자열 배열입니다. 또한 이 배열 내의 값은 [대상 멤버](#CloudWatch_Embedded_Metric_Format_Specification_structure_target)라고 하는 루트 노드의 멤버여야 합니다.
DimensionSet에는 30개를 초과하는 차원 키가 포함되어서는 안 됩니다. DimensionSet는 비어 있을 수 있습니다.
대상 멤버에는 문자열 값이 있어야 합니다. 이 값은 1024자를 초과하는 문자를 포함해서는 안 됩니다. 대상 멤버는 지표 ID의 일부로 게시될 차원을 정의합니다. 사용된 모든 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은 다음 멤버를 포함해야 하는 객체입니다.
+ **Name** - [대상 멤버](#CloudWatch_Embedded_Metric_Format_Specification_structure_target) 지표에 대한 [참조 값](#CloudWatch_Embedded_Metric_Format_Specification_structure_referencevalues) 문자열입니다. 지표 대상은 숫자 값 또는 숫자 값의 배열이어야 합니다.
MetricDefinition 객체에는 다음 멤버가 포함될 수 있습니다.
+ **Unit** - 해당 지표에 대한 측정 단위를 나타내는 선택적 문자열 값입니다. 값은 유효한 CloudWatch 지표 단위여야 합니다. 유효한 단위에 대한 자세한 내용은 [MetricDatum](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_MetricDatum.html)을 참조하세요. 값이 제공되지 않으면 기본값인 NONE으로 가정합니다.
+ **StorageResolution** - 해당 지표에 대한 스토리지 해상도를 나타내는 선택적 정수 값입니다. 이 값을 1로 설정하면 이 지표가 고해상도 지표로 지정되므로 CloudWatch는 1분 미만의 해상도로 지표를 1초까지 저장합니다. 이 값을 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가 애플리케이션의 원격 측정 데이터 및 인프라 내 관계를 종합적으로 파악하는 데 도움이 됩니다.