메트릭 제출: 커스텀 Agent Check

커스텀 Agent Check을 만들면 함수를 사용해 메트릭을 제출할 수 있어요. 메트릭 타입에 따라 사용할 수 있는 함수가 달라지며, 사용하는 함수에 따라 제출 방식과 Datadog에 저장되는 실제 메트릭 타입이 달라질 수 있어요. 이 문서에서는 monotonic_count(), count(), gauge(), rate(), histogram() 함수의 사용법과 파라미터, 그리고 커스텀 Agent Check 예제를 함께 살펴봐요.

출처: 문서

본문

함수는 커스텀 Agent check으로 메트릭을 제출하는 데 사용돼요. 메트릭 타입에 따라 사용할 수 있는 함수가 달라지죠. 사용하는 함수에 따라 제출 방식과 Datadog에 저장되는 실제 메트릭 타입이 달라질 수 있어요.

함수

{% tab title="Count" %} monotonic_count()

이 함수는 항상 증가하는 원시(raw) COUNT 메트릭을 추적하는 데 사용해요. Datadog Agent는 제출 간의 델타(delta)를 계산해요. 이전 샘플보다 값이 낮은 샘플은 무시되는데, 낮은 값은 보통 기반이 되는 원시 COUNT 메트릭이 리셋되었음을 나타내죠. 이 함수는 체크 실행 중에 여러 번 호출할 수 있어요.

예를 들어 샘플 2, 3, 6, 7을 제출하면 첫 번째 체크 실행 동안 값 5(7-2)가 전송돼요. 같은 monotonic_count에 샘플 10, 11을 제출하면 두 번째 체크 실행 동안 값 4(11-7)가 전송됩니다.

참고: 이 함수로 제출된 메트릭은 Datadog에서 COUNT 메트릭 타입으로 저장돼요. 저장된 타임시리즈의 각 값은 샘플 간 메트릭 값의 델타(시간 정규화되지 않음)예요.

함수 템플릿:

self.monotonic_count(name, value, tags=None, hostname=None, device_name=None)

count()

이 함수는 체크 간격 동안 발생한 이벤트 수를 제출해요. 체크 실행 중에 여러 번 호출할 수 있으며, 각 샘플은 전송되는 값에 더해져요.

참고: 이 함수로 제출된 메트릭은 Datadog에서 COUNT 메트릭 타입으로 저장돼요.

함수 템플릿:

self.count(name, value, tags=None, hostname=None, device_name=None)

{% /tab %}

{% tab title="Gauge" %} gauge()

이 함수는 주어진 타임스탬프에서 메트릭 값을 제출해요. 체크 실행 중에 메트릭에 대해 여러 번 호출하면 마지막 샘플만 사용돼요.

참고: 이 함수로 제출된 메트릭은 Datadog에서 GAUGE 메트릭 타입으로 저장돼요.

함수 템플릿:

self.gauge(name, value, tags=None, hostname=None, device_name=None)

{% /tab %}

{% tab title="Rate" %} rate()

이 함수는 RATE 메트릭의 샘플링된 원시 값을 제출해요. Datadog Agent는 두 제출 사이의 메트릭 값 델타를 계산하고, 이를 제출 간격으로 나누어 rate를 구해요. 이 함수는 체크 중에 한 번만 호출해야 해요. 그렇지 않으면 이전에 제출된 값보다 작은 값은 모두 버려지거든요.

참고: 이 함수로 제출된 메트릭은 Datadog에서 GAUGE 메트릭 타입으로 저장돼요. 저장된 타임시리즈의 각 값은 샘플 간 메트릭 값의 시간 정규화된 델타예요.

함수 템플릿:

self.rate(name, value, tags=None, hostname=None, device_name=None)

{% /tab %}

{% tab title="Histogram" %} histogram()

이 함수는 체크 간격 동안 발생한 히스토그램 메트릭의 샘플을 제출해요. 체크 실행 중에 여러 번 호출할 수 있으며, 각 샘플은 이 메트릭 값 집합의 통계적 분포에 추가돼요.

참고: 생성되는 모든 메트릭 집계는 Datadog에서 GAUGE 메트릭 타입으로 저장되며, <METRIC_NAME>.count만 RATE 메트릭 타입으로 저장돼요.

함수 템플릿:

self.histogram(name, value, tags=None, hostname=None, device_name=None)

{% /tab %}

튜토리얼

모든 메트릭 타입을 주기적으로 보내는 커스텀 Agent check를 만드는 단계는 다음과 같아요.

1. Agent 구성 디렉토리 루트의 conf.d/ 폴더에 metrics_example.d/ 디렉토리를 만드세요.

2. metrics_example.d/ 폴더에 다음 내용으로 빈 구성 파일 metrics_example.yaml을 만드세요.

   instances: [{}]
   

3. conf.d/ 폴더에서 한 단계 위로 올라가 checks.d/ 폴더로 이동하세요. 아래 내용으로 metrics_example.py라는 커스텀 체크 파일을 만드세요.

   import random
   
   from datadog_checks.base import AgentCheck
   
   __version__ = "1.0.0"
   
   class MyClass(AgentCheck):
       def check(self, instance):
           self.count(
               "example_metric.count",
               2,
               tags=["env:dev","metric_submission_type:count"],
           )
           self.count(
               "example_metric.decrement",
               -1,
               tags=["env:dev","metric_submission_type:count"],
           )
           self.count(
               "example_metric.increment",
               1,
               tags=["env:dev","metric_submission_type:count"],
           )
           self.rate(
               "example_metric.rate",
               1,
               tags=["env:dev","metric_submission_type:rate"],
           )
           self.gauge(
               "example_metric.gauge",
               random.randint(0, 10),
               tags=["env:dev","metric_submission_type:gauge"],
           )
           self.monotonic_count(
               "example_metric.monotonic_count",
               2,
               tags=["env:dev","metric_submission_type:monotonic_count"],
           )
   
           # Calling the functions below twice simulates
           # several metrics submissions during one Agent run.
           self.histogram(
               "example_metric.histogram",
               random.randint(0, 10),
               tags=["env:dev","metric_submission_type:histogram"],
           )
           self.histogram(
               "example_metric.histogram",
               random.randint(0, 10),
               tags=["env:dev","metric_submission_type:histogram"],
           )
   

4. Agent를 다시 시작하세요.

5. Agent의 status 하위 명령으로 커스텀 체크가 올바르게 실행되는지 확인하세요. Checks 섹션에서 metrics_example을 찾아보세요.

   =========
   Collector
   =========
   
     Running Checks
     ==============
   
       (...)
   
       metrics_example (1.0.0)
       -----------------------
         Instance ID: metrics_example:d884b5186b651429 [OK]
         Total Runs: 2
         Metric Samples: Last Run: 8, Total: 16
         Events: Last Run: 0, Total: 0
         Service Checks: Last Run: 0, Total: 0
         Average Execution Time : 2ms
   
       (...)
   

6. Metric Summary 페이지에서 메트릭이 Datadog에 정상적으로 보고되는지 확인하세요.

더 알아보기 (Learn more)

추가로 도움이 되는 문서, 링크, 글:

• Write an Agent Custom Check