본문 바로가기
WIKI 기술 지식 베이스

커스텀 메트릭용 에이전트 측 필터링

원문 보기 위키 갱신

커스텀 메트릭용 에이전트 측 필터링 (Agent-Side Filtering for Custom Metrics)

사용하지 않거나 원치 않는 커스텀 메트릭을 Datadog 에이전트 단에서 바로 걸러내고 싶을 때가 있죠. 에이전트 측 필터링은 이런 커스텀 메트릭을 Datadog로 보내기 전에 에이전트에서 필터링해, 인덱싱되는 메트릭과 수집(ingested)되는 메트릭 볼륨을 모두 크게 줄여 줘요.

필터링은 에이전트 레벨에서 수행되지만, 관리 자체는 Datadog UI에서 중앙에서 하기 때문에 팀 전체에 완전한 가시성과 통제력을 주는 구조예요. Datadog에서 필터링 정책(policy)을 만들고 수정하고 관리하면서, 메트릭 거버넌스(governance)를 투명하게 운영할 수 있어요.

출처: 문서

본문

에이전트 측 필터링은 아직 Preview 단계의 기능이에요.

개요 (Overview)

에이전트 측 필터링을 사용하면 쓰지 않거나 원치 않는 커스텀 메트릭(DogStatsD에서 오는 것과 에이전트 통합에서 오는 것 모두)을 Datadog로 보내기 전에, Datadog 에이전트에서 바로 걸러낼 수 있어요. 이렇게 하면 인덱싱되는 커스텀 메트릭 볼륨과 수집되는 볼륨을 모두 크게 줄일 수 있습니다.

필터링은 에이전트 레벨에서 수행되지만 관리 자체는 Datadog UI에서 중앙으로 이뤄져요. 팀이 전체 가시성과 통제권을 갖는 구조죠. Datadog에서 필터링 정책을 만들고 수정하고 관리하면서 메트릭 거버넌스를 투명하게 운영할 수 있습니다.

필터링 정책을 만들거나 수정하려면 metric_tags_write RBAC 권한이 필요해요. 모든 사용자는 필터링 정책을 볼 수 있습니다.

사전 요구사항 (Prerequisites)

  • Datadog 에이전트 v7.67.0 이상으로 업그레이드하세요.
    • DogStatsD 메트릭을 필터링하려면 v7.70.0 이상을 권장해요.
    • 에이전트 통합 메트릭에는 v7.74.0 이상이 필요합니다.
  • org_management 권한이 있다면, 조직에 대해 Remote Configuration을 활성화하세요.
  • api_keys_write 권한이 있다면, 에이전트가 사용하는 API 키에 Remote Configuration 기능을 활성화하세요. API 키에 Remote Configuration을 활성화한 뒤에는 변경 사항이 적용되도록 에이전트를 다시 시작해야 해요.

메트릭 필터링 정책 만들기 (Create a metric filtering policy)

메트릭 필터링 정책은 Metrics Settings 페이지나 Metrics Summary 페이지에서 만들 수 있어요.

메트릭 필터링 정책은 Remote Configuration이 활성화된 v7.67.0+ 에이전트(에이전트 통합 메트릭은 v7.74.0+) 모두에 적용돼요. 더 오래된 에이전트 버전이나 Remote Configuration이 비활성화된 에이전트에는 필터링 정책이 적용되지 않습니다.

정책 변경 사항은 1~2분 안에 에이전트로 배포됩니다.

Metrics Settings 페이지에서 만들기

  1. + Create Policy를 클릭하세요.
  2. Filter metrics를 클릭하세요.
  3. 새 정책에 대한 설명을 입력하세요.
  4. Metrics to Filter 드롭다운에서 필터링할 메트릭을 선택하거나 Upload CSV를 클릭하세요.
    • CSV를 업로드하려면 파일을 선택하고 Open을 클릭하면 돼요. CSV 여러 개를 사용해 정책을 만들 수도 있습니다.
  5. 필터링할 메트릭 목록이 만족스러우면 Save and Filter를 클릭하세요.

Metrics Summary 페이지에서 만들기

Metrics Summary 페이지에서도 메트릭 필터링 정책을 만들 수 있어요. 다음 방법 중 원하는 것을 쓰면 됩니다.

메트릭 쿼리에서 만들기

  1. 검색창에 메트릭 쿼리를 입력하세요.
  2. 화면 오른쪽의 세로 점 3개 버튼을 클릭하세요.
  3. Filter metrics를 클릭하세요.
  4. Choose policy 드롭다운에서 New Policy를 클릭하고 정책 설명을 입력하세요.
  5. Metrics to Filter를 검토하세요. 목록에서 메트릭을 제거하려면 해당 행 오른쪽의 X를, 메트릭을 추가하려면 + Include More Metrics를 클릭하면 돼요.
  6. Save and Filter를 클릭하세요.

정책 편집기에서 만들기

  1. 화면 오른쪽의 세로 점 3개 버튼을 클릭하세요.
  2. Filter metrics를 클릭하세요.
  3. Choose policy 드롭다운에서 New Policy를 클릭하고 정책 설명을 입력하세요.
  4. Metrics to Filter 필드에 메트릭 쿼리를 입력하거나, 드롭다운에서 메트릭을 하나씩 선택하세요. 목록에서 메트릭을 제거하려면 해당 행 오른쪽의 X를 클릭하면 돼요.
  5. Save and Filter를 클릭하세요.

CSV 업로드로 만들기

  1. 화면 오른쪽의 세로 점 3개 버튼을 클릭하세요.
  2. Filter metrics를 클릭하세요.
  3. Choose policy 드롭다운에서 New Policy를 클릭하고 정책 설명을 입력하세요.
  4. Metrics to Filter 필드 오른쪽의 Upload CSV를 클릭하세요.
  5. CSV 파일을 선택하고 Open을 클릭하세요.
  6. 나열된 메트릭을 검토하세요. 메트릭을 제거하려면 해당 행 오른쪽의 X를 클릭하면 돼요. 필요하면 CSV 파일을 추가로 업로드하거나 Metrics to Filter 필드를 통해 메트릭을 추가할 수 있어요.
  7. Save and Filter를 클릭하세요.

메트릭 필터링 정책 수정하기 (Edit a metric filtering policy)

메트릭 필터링 정책은 Metrics Settings 페이지나 Metrics Summary 페이지에서 수정할 수 있어요.

Metrics Settings 페이지에서 수정하기

  1. 수정할 정책을 클릭하세요.
  2. Edit을 클릭하세요.
  3. Metrics to Filter 드롭다운에서 필터링할 메트릭을 선택하거나 Upload CSV를 클릭하세요.
    • CSV를 업로드하려면 파일을 선택하고 Open을 클릭하면 돼요.
  4. Save and Filter를 클릭하세요.

Metrics Summary 페이지에서 수정하기

Metrics Summary 페이지에서도 메트릭 필터링 정책을 수정할 수 있어요. 다음 방법 중 원하는 것을 쓰면 됩니다.

메트릭 쿼리에서 수정하기

  1. 검색창에 메트릭 쿼리를 입력하세요.
  2. 화면 오른쪽의 세로 점 3개 버튼을 클릭하세요.
  3. Filter metrics를 클릭하세요.
  4. Choose policy 드롭다운에서 수정할 정책을 선택하세요.
  5. Metrics to Filter와 Existing metrics in policy 목록을 검토하세요. 메트릭을 제거하려면 해당 행 오른쪽의 X를, 메트릭을 추가하려면 + Include More Metrics를 클릭하면 돼요.
  6. Save and Filter를 클릭하세요.

정책 편집기에서 수정하기

  1. 화면 오른쪽의 세로 점 3개 버튼을 클릭하세요.
  2. Filter metrics를 클릭하세요.
  3. Choose policy 드롭다운에서 수정할 정책을 선택하세요.
  4. Metrics to Filter 드롭다운에서 메트릭을 하나씩 선택하세요. 목록에서 메트릭을 제거하려면 해당 행 오른쪽의 X를 클릭하면 돼요.
  5. Save and Filter를 클릭하세요.

CSV 업로드로 수정하기

  1. 화면 오른쪽의 세로 점 3개 버튼을 클릭하세요.
  2. Filter metrics를 클릭하세요.
  3. Choose policy 드롭다운에서 수정할 정책을 선택하세요.
  4. Metrics to Filter 필드 오른쪽의 Upload CSV를 클릭하세요.
  5. CSV 파일을 선택하고 Open을 클릭하세요.
  6. Metrics to Filter와 Existing metrics in policy 목록을 검토하세요. 메트릭을 제거하려면 해당 행 오른쪽의 X를, 메트릭을 추가하려면 + Include More Metrics를 클릭하면 돼요.
  7. Save and Filter를 클릭하세요.

모든 정책과 필터링된 메트릭 보기 (View all policies and filtered metrics)

모든 정책과 필터링된 메트릭은 Metrics Settings 페이지에서 볼 수 있어요.

설정 버튼을 클릭하거나, 내비게이션 바에서 Metrics를 클릭해 바로 설정으로 갈 수도 있습니다.

모든 정책 보기 (View all policies)

사이드바에서 Policies 탭을 선택하면 모든 정책 목록이 나와요. 사이드바가 보이지 않으면 Show Sidebar 버튼을 클릭하세요.

수정이나 삭제를 위해 메트릭 필터링 정책을 클릭하면 상세 보기가 열립니다.

모든 필터링된 메트릭 보기 (View all filtered metrics)

사이드바에서 Filtered Metrics 탭을 선택하면 필터링된 모든 메트릭 목록이 나와요. 사이드바가 보이지 않으면 Show Sidebar 버튼을 클릭하세요.

ATTACHED POLICIES 열에서 필터링된 메트릭에 연결된 정책을 클릭하면 수정하거나 삭제할 수 있습니다.

정책 삭제하기 (Delete policies)

메트릭 필터링 정책은 Metrics Settings 페이지에서 삭제할 수 있어요.

  1. 삭제할 메트릭 필터링 정책을 클릭하세요.
  2. 페이지 오른쪽 위의 Delete를 선택하세요.

API로 메트릭 필터링 정책 관리하기 (Manage metric filtering policies through the API)

⚠️ 주의 — 커스텀 메트릭용 에이전트 측 필터링이 Preview 기간에는 이 엔드포인트들이 변경될 수 있어요.

이 엔드포인트들은 유효한 Datadog API 키와 애플리케이션 키가 필요해요. 자세한 내용은 API 레퍼런스의 Getting started를 참고하세요.

필터링된 메트릭 정책 만들기 (Create a filtered metric policy)

선택한 Datadog 사이트의 베이스 URL은 다음과 같아요: <YOUR_DATADOG_API_URL>

아래 예시에서 <BASE_URL>을 베이스 URL로 바꿔 주세요.

POST <BASE_URL>/api/unstable/remote_config/products/metric_control/filtered_metrics/policies

요청 본문 예시 (Example body)
{
  "data": {
    "type": "filtered_metrics",
    "attributes": {
      "policy_name": "my policy",
      "metric_names": [
        "metric.name.one",
        "metric.name.two"
      ]
    }
  }
}

필터링된 메트릭 정책 업데이트 (부분 업데이트) (Update a filtered metric policy - partial update)

선택한 Datadog 사이트의 베이스 URL은 다음과 같아요: <YOUR_DATADOG_API_URL>

아래 예시에서 <BASE_URL>을 베이스 URL로 바꿔 주세요.

PATCH <BASE_URL>/api/unstable/remote_config/products/metric_control/filtered_metrics/policies/{policy-id}

요청 본문 예시 (Example body)
{
  "data": {
    "type": "filtered_metrics",
    "attributes": {
      "policy_name": "my policy",
      "metrics_to_add": [
        "metric.name.three",
        "metric.name.four"
      ],
      "metrics_to_remove": [
        "metric.name.five",
        "metric.name.six"
      ]
    }
  }
}

필터링된 메트릭 정책 업데이트 (전체 교체) (Update a filtered metric policy - full replace)

선택한 Datadog 사이트의 베이스 URL은 다음과 같아요: <YOUR_DATADOG_API_URL>

아래 예시에서 <BASE_URL>을 베이스 URL로 바꿔 주세요.

PUT <BASE_URL>/api/unstable/remote_config/products/metric_control/filtered_metrics/policies/{policy-id}

요청 본문 예시 (Example body)
{
  "data": {
    "type": "filtered_metrics",
    "attributes": {
      "policy_name": "my policy",
      "metric_names": [
        "metric.name.seven",
        "metric.name.eight"
      ]
    }
  }
}

정책 삭제하기 (Delete a policy)

선택한 Datadog 사이트의 베이스 URL은 다음과 같아요: <YOUR_DATADOG_API_URL>

아래 예시에서 <BASE_URL>을 베이스 URL로 바꿔 주세요.

DELETE <BASE_URL>/api/unstable/remote_config/products/metric_control/filtered_metrics/policies/{policy-id}

필터링된 메트릭 정책 조회하기 (Get a filtered metric policy)

선택한 Datadog 사이트의 베이스 URL은 다음과 같아요: <YOUR_DATADOG_API_URL>

아래 예시에서 <BASE_URL>을 베이스 URL로 바꿔 주세요.

GET <BASE_URL>/api/unstable/remote_config/products/metric_control/filtered_metrics/policies/{policy-id}

응답 본문 예시 (Example response body)
{
  "data": [
    {
      "type": "filtered_metrics",
      "id": "metric.name.one",
      "attributes": {
        "updated_timestamp": 1745954352
      }
    },
    {
      "type": "filtered_metrics",
      "id": "metric.name.two"
      "attributes": {
        "updated_timestamp": 1745954389
      }
    }
    // ... up to ~10,000 entries
  ],
  "links": {
    "self": "/api/unstable/remote_config/products/metric_control/filtered_metrics/policies/{policy-id}?page[offset]=200&page[limit]=100",
    "next": "/api/unstable/remote_config/products/metric_control/filtered_metrics/policies/{policy-id}?page[offset]=300&page[limit]=100",
    "prev": "/api/unstable/remote_config/products/metric_control/filtered_metrics/policies/{policy-id}?page[offset]=100&page[limit]=100",
    "first": "/api/unstable/remote_config/products/metric_control/filtered_metrics/policies/{policy-id}?page[offset]=0&page[limit]=100",
    "last": "/api/unstable/remote_config/products/metric_control/filtered_metrics/policies/{policy-id}?page[offset]=9900&page[limit]=100"
  },
  "meta": {
    "agent_coverage_percent": 100,
    "agents_with_latest_policy_count": 4,
    "deployment_failure": {
        "failed_agent_count": 0,
        "failure_message": ""
    },
    "deployment_status": "Deployed to all Agents",
    "deployment_strategy": "all",
    "policy_name": "test_policy_1",
    "total": 7,
    "total_agent_count": 4,
    "updated_by": "[email protected]",
    "updated_timestamp": 1758912365
  }
}

필터링된 메트릭 정책 목록 조회하기 (List filtered metric policies)

선택한 Datadog 사이트의 베이스 URL은 다음과 같아요: <YOUR_DATADOG_API_URL>

아래 예시에서 <BASE_URL>을 베이스 URL로 바꿔 주세요.

GET <BASE_URL>/api/unstable/remote_config/products/metric_control/filtered_metrics/policies

응답 본문 예시 (Example response body)
{
    "data": [
        {
            "id": "06b-fab-47e",
            "type": "filtered_metrics",
            "attributes": {
                "count": 85,
                "deployment_status": "Deployed to all Agents",
                "deployment_strategy": "all",
                "policy_name": "policy one",
                "updated_by": "[email protected]",
                "updated_timestamp": 1758547485,
                "version": 4            
            }
        },
        {
            "id": "07b-201-47e",
            "type": "filtered_metrics",
            "attributes": {
                "count": 8,
                "deployment_status": "Deployed to all Agents",
                "deployment_strategy": "all",
                "policy_name": "policy two",
                "updated_by": "[email protected]",
                "updated_timestamp": 1758547212,
                "version": 1
            }
        }
    ]
}

Preview 제한사항 (Preview limitations)

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

  • 필터링할 수 있는 메트릭 이름은 최대 10,000개예요.
  • 에이전트에 미치는 리소스 사용량 영향은 메모리(RSS) 최대 10MB로 제한되며, CPU 사용량의 증가는 없습니다.
  • DogStatsD 또는 에이전트 통합에서 받은 커스텀 메트릭만 지원됩니다.

더 알아보기 (Learn more)