모니터링되는 태그 키 관리

모니터링되는 태그 키 관리 (Managing monitored tag keys)

Amazon EC2 Capacity Manager를 사용하면 Amazon EC2 리소스에서 태그 키(예: environment 또는 team)를 선택해 용량 데이터를 분석할 때 차원(dimensions)으로 사용할 수 있어요. 태그 키가 활성화되면 Region, Instance Type, Availability Zone처럼 태그 값으로 지표를 그룹화하고 필터링할 수 있어요.

출처: 문서

본문

각 계정은 최대 5개의 태그 키를 모니터링할 수 있어요. Capacity Manager 제공 태그는 이 한도에 포함되지 않아요.

Capacity Manager 제공 태그 (Capacity Manager-provided tags)

Capacity Manager는 모든 계정에 대해 기본 태그 집합을 포함해요. 이 태그들은 태그 키 한도에 포함되지 않아요. Capacity Manager 제공 태그는 일반적으로 사용되는 그룹화 차원을 나타내며 다음을 포함해요.

• aws:autoscaling:groupName — EC2 Auto Scaling Group
• aws:eks:cluster-name — EKS 클러스터 이름
• eks:kubernetes-node-pool-name — EKS Kubernetes 노드 풀
• karpenter.sh/nodepool — Karpenter 노드 풀

Capacity Manager 제공 태그는 GetCapacityManagerMonitoredTagKeys에 CapacityManagerProvided가 true로 설정되어 나타나고, 고객이 활성화하거나 비활성화할 수 없어요. Capacity Manager가 처음 활성화되면 Capacity Manager 제공 태그는 activating 상태에서 시작해, Capacity Manager가 Capacity Manager 제공 태그를 포함한 첫 데이터 포인트를 받으면(일반적으로 1~2시간 내) activated 상태로 전환돼요.

태그 수명주기 (Tag lifecycle)

모니터링되는 태그 키는 다음 상태를 거쳐 진행돼요.

Status	Description
activating	The tag key is registered. Capacity Manager is preparing to collect data for this tag. You cannot query metrics using a tag in this status.
activated	Tag data is being ingested and is queryable through the metric APIs and in data exports.
suspended	The tag key has exceeded the threshold of 100,000 unique tag values. The tag still counts toward your limit, but Capacity Manager no longer ingests data for it. If your tag value usage decreases below the threshold for a sustained period, the tag is reactivated automatically.
deactivating	The tag key is being removed. It will no longer appear in GetCapacityManagerMonitoredTagKeys after deactivation completes.

태그가 suspended 상태이면 GetCapacityManagerMonitoredTagKeys는 다음 상태 메시지를 반환해요: "Tag suspended due to too many tag values. Reduce the usage of the tag or deactivate it."

참고 태그 키를 비활성화한 후 같은 키를 다시 활성화하면, 다시 활성화한 이후 수집된 데이터만 쿼리할 수 있어요. 이전 활성화의 과거 데이터는 접근할 수 없어요. EarliestDatapointTimestamp는 각 새 활성화마다 재설정돼요.

모니터링되는 태그 키 활성화 및 비활성화 (Activate and deactivate monitored tag keys)

태그 키를 활성화해서 차원으로 모니터링을 시작하거나, 더 이상 필요 없는 태그 키를 비활성화할 수 있어요. 활성화는 비동기적이에요. 태그는 activating 상태로 들어가고, Capacity Manager가 해당 태그에 대한 데이터를 받기 시작하면 activated 상태로 전환돼요. 비활성화는 태그 키를 모니터링 세트에서 제거해요.

참고 태그 키를 활성화할 때는 키 이름만 입력해요(예: environment). Capacity Manager가 자동으로 지표를 그룹화하고 필터링하는 차원으로 사용할 수 있게 해줘요.

콘솔 (Console)

모니터링되는 태그 키 활성화 또는 비활성화하기: Amazon EC2 콘솔(https://console.aws.amazon.com/ec2/)을 엽니다. 탐색 창에서 Capacity Manager를 선택해요. Settings 탭을 선택해요. Monitored tag keys 섹션에서 Manage tag keys를 선택해요. 태그 키를 활성화하려면 태그 키 이름을 입력하고 Add를 선택해요. 태그 키를 비활성화하려면 태그 키를 선택하고 Remove를 선택해요. Save changes를 선택해요.

AWS CLI

태그 키 활성화하기: 다음 명령으로 태그 키 하나 이상을 활성화해요.

aws ec2 update-capacity-manager-monitored-tag-keys \
    --activate-tag-keys "environment" "teamId"

출력은 태그 키와 초기 상태를 보여줘요.

{
    "CapacityManagerTagKeys": [
        {
            "TagKey": "environment",
            "Status": "activating"
        },
        {
            "TagKey": "teamId",
            "Status": "activating"
        }
    ]
}

태그 키 비활성화하기: 다음 명령으로 태그 키 하나 이상을 비활성화해요.

aws ec2 update-capacity-manager-monitored-tag-keys \
    --deactivate-tag-keys "project"

출력은 갱신된 상태를 보여줘요.

{
    "CapacityManagerTagKeys": [
        {
            "TagKey": "project",
            "Status": "deactivating"
        }
    ]
}

같은 요청에서 태그 키를 활성화하고 비활성화할 수 있어요.

aws ec2 update-capacity-manager-monitored-tag-keys \
    --activate-tag-keys "environment" "teamId" \
    --deactivate-tag-keys "project"

모니터링되는 태그 키 보기 (View monitored tag keys)

계정의 모든 모니터링되는 태그 키를, 현재 상태와 데이터를 사용할 수 있는 가장 이른 타임스탬프를 포함해 볼 수 있어요.

콘솔 (Console)

모니터링되는 태그 키 보기: Amazon EC2 콘솔(https://console.aws.amazon.com/ec2/)을 엽니다. 탐색 창에서 Capacity Manager를 선택해요. Settings 탭을 선택해요. Monitored tag keys 섹션에서 태그 키, 상태, Capacity Manager 제공 태그인지 여부를 확인해요.

AWS CLI

모니터링되는 태그 키 보기: 다음 명령을 실행해요.

aws ec2 get-capacity-manager-monitored-tag-keys

출력은 모든 태그 키를 나열하며, Capacity Manager 제공 태그와 고객 관리 태그를 포함해요.

{
    "CapacityManagerTagKeys": [
        {
            "TagKey": "aws:autoscaling:groupName",
            "Status": "activated",
            "CapacityManagerProvided": true,
            "earliestDatapointTimestamp": "2026-04-08T00:00:00"
        },
        {
            "TagKey": "environment",
            "Status": "activated",
            "CapacityManagerProvided": false,
            "earliestDatapointTimestamp": "2025-08-11T22:00:00"
        }
    ]
}

CapacityManagerProvided 필드는 태그가 Capacity Manager 제공 태그(true)인지 고객 관리 태그(false)인지 나타내요. Capacity Manager 제공 태그는 태그 키 한도에 포함되지 않아요. EarliestDatapointTimestamp는 해당 태그 키에 대해 데이터를 사용할 수 있는 가장 이른 시점을 나타내요.

태그 차원을 사용한 지표 쿼리 (Query metrics using tag dimensions)

태그 키가 activated 상태에 도달하면 GetCapacityManagerMetricDimensions와 GetCapacityManagerMetricData에서 차원으로 사용할 수 있어요.

태그 차원으로 그룹화된 지표 쿼리하기

다음 명령을 사용해요.

aws ec2 get-capacity-manager-metric-dimensions \
    --group-by tag:environment account-id \
    --filter-by 'DimensionCondition={Dimension=tag:environment,Comparison=equals,Values=[prod]}'

태그 차원으로 그룹화하면 결과에 계정의 모든 리소스가 포함돼요 — 태그가 있는 리소스뿐만 아니라요. 태그 값이 없는 리소스는 빈 문자열 값으로 별도의 버킷으로 그룹화돼요. 예를 들어 계정이 특정 기간에 800 vCPU 시간을 사용했고 그 리소스 중 일부에만 environment 태그가 있다면, environment 태그 키로 그룹화하면 다음이 반환될 수 있어요.

• prod — 300 vCPU hours
• staging — 200 vCPU hours
• "" (빈 문자열) — environment 태그가 없는 리소스의 300 vCPU hours

이렇게 하면 모든 버킷의 합계가 전체 사용량을 차지하도록 보장해요. 필터 값으로 빈 문자열을 전달해 태그가 없는 리소스를 명시적으로 필터링할 수 있어요.

--filter-by 'DimensionCondition={Dimension=tag:environment,Comparison=equals,Values=[""]}'

참고 아직 activating 상태인 태그 키로 쿼리하면 400 오류로 거부돼요. 쿼리하기 전에 태그 상태가 activated로 바뀔 때까지 기다려요. GetCapacityManagerMonitoredTagKeys로 상태를 확인할 수 있어요.

참고 제공된 태그 차원의 EarliestDatapointTimestamp보다 이른 시작 시간을 가진 쿼리는 거부돼요. GetCapacityManagerMonitoredTagKeys를 사용해 각 태그에 대해 데이터가 언제 사용 가능해졌는지 확인해요.

데이터 내보내기의 태그 (Tags in data exports)

태그 모니터링을 활성화하면 데이터 내보내기에 활성화된 태그 키와 Capacity Manager 제공 태그가 추가 열로 포함돼요. 태그 열은 tag:environment, tag:team 같은 헤더로 모든 표준 열 뒤에 나타나요. 태그 열은 알파벳순으로 정렬돼요.

내보내기에는 activated 상태의 태그만 포함돼요. Capacity Manager는 activating, deactivating, suspended 상태의 태그를 제외해요.

참고 새 태그 키를 활성화하면 기존 데이터 내보내기에 새 태그가 자동으로 포함되지 않아요. 새로 활성화된 태그 키를 열로 포함하려면 새 데이터 내보내기를 만들어야 해요.

Organizations와 위임 관리자 (Organizations and delegated administrator)

계정이 조직 수준 Capacity Manager가 활성화된 AWS Organization의 일부이면, 각 계정(조직 관리자와 위임 관리자)이 독립적으로 태그 키를 활성화, 비활성화, 쿼리할 수 있어요. 각 계정은 자체 태그 상태, EarliestDatapointTimestamp, 태그 키 한도를 유지해요.

계정은 자체적으로 활성화한 태그 키에 대한 지표 데이터만 쿼리할 수 있어요. 조직 관리자와 위임 관리자가 같은 태그 키(예: environment)를 활성화하면, 각 계정은 자체 활성화 상태와 데이터 가용성을 독립적으로 추적해요.

위임 관리자가 태그 키를 비활성화하면, 조직 관리자가 같은 태그 키를 여전히 활성화한 상태여도 위임 관리자는 더 이상 해당 태그의 데이터를 쿼리할 수 없어요.

고려 사항 (Considerations)

• 태그 값 갱신: 새 리소스의 태그 값과 기존 리소스에 새로 적용된 태그는 몇 시간 내에 사용할 수 있어요. 리소스의 기존 태그 값을 변경하면 갱신된 값이 Capacity Manager에 반영되는 데 최대 24시간이 걸릴 수 있어요.
• 활성화 시간: 태그 키를 활성화한 후 태그가 activated 상태로 전환되고 데이터를 쿼리할 수 있게 되기까지 최대 24시간이 걸릴 수 있어요. EarliestDatapointTimestamp는 데이터가 사용 가능한 시점을 나타내며, 태그가 활성화된 시점을 나타내는 것은 아니에요.
• 태그 키 한도: 각 계정은 최대 5개의 태그 키를 모니터링할 수 있어요. Capacity Manager 제공 태그는 이 한도에 포함되지 않아요.
• 태그 키 문자 요구 사항: 태그 키는 유니코드 문자, 숫자, 공백, 그리고 _ . : / = + @ - 문자를 포함할 수 있어요. 태그 키는 128자를 초과할 수 없어요.
• 재활성화: 같은 태그 키를 비활성화하고 다시 활성화하면 새 데이터만 사용할 수 있어요. EarliestDatapointTimestamp는 각 활성화마다 재설정돼요.
• 중단된 태그: 각 태그 키는 최대 100,000개의 고유 태그 값을 지원해요. 태그 키가 이 임계값을 초과하면 suspended 상태로 이동돼요. 태그는 여전히 한도에 포함되지만 데이터는 더 이상 수집되지 않아요. 태그의 고유 값 수를 줄이거나 비활성화해서 다른 태그 키를 위한 공간을 확보해요.

더 알아보기 (Learn more)

• EC2 Capacity Manager 활성화