에이전트 측 태그 집계

원문 보기 위키 갱신 2026.10.05

에이전트 측 태그 집계 (Agent-Side Tag Aggregation)

태그 카디널리티(cardinality)가 커지면 커스텀 메트릭 볼륨이 늘어나고 비용도 올라가기 마련이죠. 에이전트 측 태그 집계는 이런 커스텀 메트릭 볼륨을 줄여 주는 기능입니다. 원치 않는 태그를 걸러내고, 선택한 커스텀 메트릭을 에이전트에서 다시 집계(re-aggregate)한 뒤 Datadog로 보내요.

실제 집계는 에이전트가 로컬에서 수행하지만, 규칙 자체는 Datadog UI에서 중앙으로 관리해요. 그래서 팀이 태그 집계 동작을 한곳에서 설정·조회·수정할 수 있고, 조건을 갖춘 에이전트가 수집(ingestion) 전에 그 규칙을 적용합니다.

출처: 문서

본문

에이전트 측 태그 집계는 아직 Preview 단계의 기능이에요.

개요 (Overview)

에이전트 측 태그 집계를 사용하면 커스텀 메트릭 볼륨을 줄일 수 있어요. 원치 않는 태그를 걸러내고, 선택한 커스텀 메트릭을 Datadog로 보내기 전에 Datadog 에이전트에서 다시 집계합니다.

사전 요구사항 (Prerequisites)

에이전트 측 태그 집계 규칙을 만들거나 수정하려면 metric_tags_write RBAC 권한이 필요해요. 모든 사용자는 기존 태그 집계 규칙을 볼 수 있습니다.

에이전트 측 태그 집계 규칙을 만들기 전에 아래 섹션에서 설명하는 단계를 먼저 완료해야 해요.

에이전트가 사용하는 API 키에서 Remote Configuration을 활성화하세요.
Agent Data Plane을 활성화하세요.

에이전트 측 태그 집계는 에이전트 7.80.0 이상에서 지원돼요. Datadog은 기존 에이전트 구성 옵션과의 넓은 하위 호환성을 포함하는 7.81.0 이상을 권장합니다.

Remote Configuration 활성화 (Enable Remote Configuration)

Remote Configuration은 조직과 에이전트가 사용하는 API 키 모두에서 활성화되어 있어야 해요. Remote Configuration 보안 모델에 대한 자세한 내용은 Remote Configuration 보안 백서를 참고하세요.

자세한 지침은 Remote Configuration 문서에 정리되어 있어요. 단계를 요약하면 다음과 같습니다.

org_management 권한으로 조직에 대해 Remote Configuration을 활성화하세요.
api_keys_write 권한으로 에이전트가 사용하는 API 키에서 Remote Configuration 기능을 활성화하세요.
API 키에 Remote Configuration을 활성화한 뒤 에이전트를 다시 시작하세요. API 키 기능 변경은 에이전트를 다시 시작해야 적용됩니다.

Agent Data Plane 활성화 (Enable the Agent Data Plane)

에이전트를 7.80.0 이상(7.81.0 이상 권장)으로 업그레이드하고 Agent Data Plane을 활성화하세요. 에이전트 측 태그 집계는 에이전트 프로세스와 컨테이너의 리소스 사용량을 함께 낮춰 주는 고성능 데이터 파이프라인인 Agent Data Plane이 필요합니다.

Agent Data Plane이 활성화되면:

Kubernetes 환경에서는 새 agent-data-plane 컨테이너가 실행됩니다.
Linux 환경에서는 새 agent-data-plane systemd 서비스와 프로세스가 실행됩니다.

Datadog Operator

Operator 1.27.0 이상을 사용한다면 DatadogAgent CRD에 다음을 추가하세요:

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  features:
    dataPlane:
      enabled: true # enable the Agent Data Plane feature
  override:
    nodeAgent:
      image:
        tag: "7.81.0" # use 7.81.0 or later

Helm

Helm 차트 3.202.5 이상을 사용한다면 values.yaml에 다음을 추가하세요:

datadog:
  dataPlane:
    enabled: true
  dogstatsd:
    enabled: true # enable the Agent Data Plane feature
agents:
  image:
    tag: "7.81.0" # use 7.81.0 or later

Linux VM

에이전트 7.80.0 이상(7.81.0 이상 권장)을 사용한다면 datadog.yaml에 다음을 추가하세요:

data_plane:
  enabled: true

동작 원리 (How it works)

태그 집계는 에이전트가 로컬에서 수행하지만, 규칙은 Datadog UI에서 중앙으로 관리돼요. 이 덕분에 팀이 태그 집계 동작을 설정·조회·수정할 수 있는 단일 지점을 갖게 되고, 조건을 갖춘 에이전트는 수집 전에 그 규칙을 적용합니다.

에이전트 측 태그 집계용으로 구성된 각 커스텀 메트릭에 대해 유지하거나 제거할 태그는 해당 메트릭의 태그 구성에 따라 정해져요. 이 구성은 Tag Indexing 규칙과 메트릭별 Metrics without Limits™ 태그 오버라이드에서 결정됩니다.

규칙이 적용되는 방식 (How rules are applied)

에이전트 측 태그 집계 규칙은 다음 요구사항을 모두 충족하는 에이전트에만 적용돼요.

에이전트 버전 7.80.0 이상
Remote Configuration 활성화
Agent Data Plane 활성화

7.80.0보다 이전 버전의 에이전트, Remote Configuration이 비활성화된 에이전트, Agent Data Plane이 비활성화된 에이전트에는 에이전트 측 태그 집계 규칙이 적용되지 않습니다.

규칙 업데이트는 보통 약 1분 안에 조건을 갖춘 에이전트로 배포되며, 최대 2분까지 걸릴 수 있어요.

커스텀 메트릭의 태그 구성이 Tag Indexing 규칙이나 메트릭별 태그 오버라이드를 통해 변경되면, 해당 커스텀 메트릭을 포함하는 에이전트 측 태그 집계 규칙은 자동으로 업데이트됩니다. 이 업데이트는 최대 30분까지 걸릴 수 있습니다.

태그가 처리되는 방식 (How tags are handled)

에이전트 측 태그 집계는 메트릭을 Datadog로 보내기 전에 태그를 걸러낼 수 있어요. 다만 host 태그나 호스트 레벨 태그는 제거할 수 없습니다.

태그가 제거되면 에이전트는 수집 전에 일치하는 메트릭 포인트를 다시 집계해요. 이렇게 하면 Datadog로 제출되는 고유 태그 조합 수를 줄여 수집되는 커스텀 메트릭 볼륨을 낮출 수 있습니다.

DogStatsD count·rate 동작 (DogStatsD count and rate behavior)

DogStatsD count 또는 rate 메트릭이 에이전트 측 태그 집계용으로 구성되면, sum by 외의 집계를 사용하는 쿼리는 다른 결과를 반환할 수 있어요.

그 이유는 에이전트가 태그를 제거한 뒤 count와 rate 메트릭에 대해 sum을 사용해 메트릭 포인트를 다시 집계하기 때문이에요. sum by 외의 집계(예: avg by)에 의존하는 쿼리는 에이전트 측 태그 집계를 쓸 때 더는 같은 방식으로 동작하지 않을 수 있습니다. 이 동작에 대한 자세한 내용은 아래 예시를 참고하세요.

에이전트 측 태그 집계 규칙 만들기 (Create Agent-side tag aggregation rules)

Remote Configuration과 Agent Data Plane이 활성화된 뒤에는 Datadog UI에서 에이전트 측 태그 집계를 구성할 수 있어요.

규칙을 만들려면:

Metric Summary 페이지나 Custom Metrics Volume 페이지로 이동하세요.
에이전트 측 태그 집계용으로 커스텀 메트릭을 하나 이상 선택하세요.

태그 집계 규칙은 Metric Settings 페이지에서 볼 수 있으며, 거기서 직접 만들고 수정할 수도 있어요.

Preview 제한사항 (Preview limitations)

첫 Preview 릴리스에는 다음과 같은 제한사항이 있어요.

에이전트 측 태그 집계용으로 구성할 수 있는 메트릭 이름은 최대 500개예요.
DogStatsD distribution 메트릭과 DogStatsD count·rate 메트릭만 지원됩니다.
Windows와 macOS는 지원되지 않아요.
API를 통한 에이전트 측 태그 집계 규칙 관리는 지원되지 않습니다.

에이전트 측 태그 집계 규칙이 구성되면 Agent Data Plane의 리소스 사용량이 CPU 최대 10%, resident set size(RSS) 최대 25%까지 증가할 수 있어요. 이 한계는 Preview 기간 동안 에이전트에 미치는 리소스 영향이 최소화되도록 하기 위한 것입니다.

예시: count·rate 메트릭에 미치는 쿼리 영향 (Example: Query impact on count and rate metrics)

예시 구성 (Example setup)

값과 태그가 동일한 count·rate 메트릭 두 개가 내보내집니다(10초마다 1씩 증가, 한 번은 org:1로, 한 번은 org:2로):

둘 다 org 태그 키를 제외하는 동일한 Tag Indexing 또는 Metrics without Limits™ 규칙으로 구성돼요.
하나는 태그 집계용으로 구성되고, 다른 하나는 그렇지 않아요.

쿼리 결과 (Query results)

다음 표는 태그 집계가 비활성화/활성화되었을 때 에이전트가 두 count·rate 메트릭을 어떻게 처리하는지 비교해요.

	태그 집계 비활성화	태그 집계 활성화
`org` 태그	에이전트가 유지	에이전트가 제거
Datadog로 보내는 포인트 (10초당)	2 (`org:1`의 값 `1`, `org:2`의 값 `1`)	1 (값 `2`, `org` 태그 없음)
`sum by {*}` 결과	`2`	`2`
`avg by {*}` 결과	`1`	`2`

태그 집계가 비활성화되면 에이전트는 org 태그를 유지하고 포인트 2개를 보내요. Tag Indexing과 Metrics without Limits™는 org 태그가 인덱싱에서 제외되더라도 avg by 결과를 보존합니다.

태그 집계가 활성화되면 에이전트는 org 태그를 제거하고 두 포인트를 sum으로 하나로 다시 집계해요. 이렇게 하면 수집되는 카디널리티와 볼륨은 줄지만, avg by 결과는 달라집니다.

에이전트가 수행하는 sum 집계는 count·rate 메트릭에서 가장 흔하고 유용한 쿼리인 sum by를 사용하는 쿼리의 결과를 보존해요. avg by나 min by, max by 같은 다른 집계를 사용하는 쿼리의 결과는 보존하지 않습니다.