데이터그램 형식 및 쉘 사용

이 섹션에서는 DogStatsD가 수락하는 메트릭, 이벤트 및 서비스 검사의 원시 데이터그램 형식을 지정합니다. 원시 데이터그램은 UTF-8로 인코딩됩니다. DogStatsD 클라이언트 라이브러리를 사용하는 경우에는 건너 뛰어도 되는 부분이지만, 사용자 고유의 라이브러리를 작성하거나 쉘을 사용하여 메트릭을 전송하는 경우에는 반드시 확인하세요.

DogStatsD 프로토콜

<METRIC_NAME>:<VALUE>|<TYPE>|@<SAMPLE_RATE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>

파라미터필수설명
<METRIC_NAME>YesASCII 영숫자, 밑줄 및 마침표만 포함하는 문자열입니다. 메트릭 네이밍 정책을 참조하세요.
<VALUE>Yes정수 또는 부동 소수.
<TYPE>Yesc는 카운트, g는 게이지, ms는 타이머, h는 히스토그램, s는 세트, d는 분포를 뜻합니다. 자세한 내용을 확인하려면 메트릭 유형를 참조하세요.
<SAMPLE_RATE>아니요01 사이의 부동 소소수점은 카운트, 히스토그램, 분포 및 타이머 메트릭에만 사용할 수 있습니다. 시간의 100%를 샘플링하는 기본값은 1입니다.
<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>아니요쉼표로 구분된 문자열 목록입니다. 키/값 태그(env:prod)에 콜론을 사용합니다. 태그 정의에 대한 지침은 태그 시작하기를 참조하세요.

다음은 데이터그램의 예시입니다:

  • page.views:1|c: page.views카운트 메트릭을 증가시켜 줍니다.
  • fuel.level:0.5|g: 연료통의 반이 비었음을 기록합니다.
  • song.length:240|h|@0.5: song.length히스토그램을 절반만 보낸 것처럼 샘플링합니다.
  • users.uniques:1234|s: 사이트에 대한 고유 방문자를 추적합니다.
  • users.online:1|c|#country:china: 활성 사용자 카운트 메트릭과 태그를 원산지별로 증가시켜 줍니다.
  • users.online:1|c|@0.5|#country:china: 활성화된 중국 사용자를 추적하고 샘플링 속도를 사용합니다.

DogStatsD 프로토콜 v1.1

에이전트>=v6.25.0 && <v7.0.0 또는 >=v7.25.0를 시작으로 값 패킹이 가능합니다. 이것은 SET를 제외한 모든 메트릭 유형을 지원합니다. 값은 다음과 같이 :로 구분됩니다:

<METRIC_NAME>:<VALUE1>:<VALUE2>:<VALUE3>|<TYPE>|@<SAMPLE_RATE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>

TYPE, SAMPLE_RATETAGS는 모든 값 사이에 공유됩니다. 이렇게 하면 각각 하나의 값으로 여러 개의 메시지를 보내는 보내는 것보다 동일한 메트릭을 생성합니다. 이는 히스토그램, 타이밍 및 분포 메트릭에 유용합니다.

데이터그램 예시

  • page.views:1:2:32|d: 값 1,2, 32를 사용하여 page.views분포 메트릭을 세 번 샘플링합니다.
  • song.length:240:234|h|@0.5: song.length히스토그램을 절반씩 두 번 보낸 것처럼 샘플링합니다. 각 값에는 0.5의 샘플링 속도가 적용됩니다.

DogStatsD 프로토콜 v1.2

에이전트 >=v6.35.0 && <v7.0.0 또는 >=v7.35.0부터 새 컨테이너 ID 필드가 지원됩니다. Datadog 에이전트는 컨테이너 ID 값을 사용하여 추가 컨테이너 태그로 DogStatsD 메트릭을 강화합니다.

컨테이너 ID에는 다음과 같이 c: 접두사가 붙습니다:

<METRIC_NAME>:<VALUE>|<TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>|c:<CONTAINER_ID>

참고:datadog.yaml파일 또는 환경 변수DD_DOGSTATSD_ORIGIN_DETECTION_CLIENT=true에서 dogstatsd_origin_detection_clienttrue로 설정하여 Datadog 에이전트에 컨테이너 ID 필드를 추출하고 해당 컨테이너 태그를 부착하도록 지시합니다.

데이터그램 예시

  • page.views:1|g|#env:dev|c:83c0a99c0a54c0c187f461c7980e9b57f3f6a8b0c918c8d93df19a9de6f3fe1d: Datadog 에이전트는 image_nameimage_tag같은 컨테이너 태그를 page.views메트릭에 추가합니다.

컨테이너 태그에 대한 자세한 내용은 Kubernetes/Docker 태깅 설명서를 참조하세요.

DogStatsD 프로토콜 v1.3

에이전트 v6.40.0+v7.40.0+는 부수적인 Unix 타임스탬프 필드를 지원합니다.

이 필드가 제공되면, Datadog 에이전트는 태그로 메트릭을 보강하는 것 외에는 메트릭에 대해 어떠한 처리도 하지 않습니다(애그리게이션 없음). 이 필드는 애플리케이션에서 이미 메트릭을 집계하고 있으며, 추가 처리 없이 해당 메트릭을 Datadog으로 보내려는 경우에 유용할 수 있습니다.

유닉스 타임스탬프는 과거의 유효한 양수여야 합니다. 게이지 및 카운트 메트릭만 지원됩니다.

값은 유닉스 타임스탬프 (UTC)이며 다음과 같이 T가 접두사로 붙어야 합니다:

<METRIC_NAME>:<VALUE>|<TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>|T<METRIC_TIMESTAMP>

데이터그램 예시

  • page.views:15|c|#env:dev|T1656581400: 2022년 6월 30일 오전 9시 30분 UTC에 15페이지가 조회되었음을 나타내는 카운트

DogStatsD 프로토콜 v1.4

에이전트 >=v7.51.0부터 컨테이너 ID 필드에 새 Inode 값이 지원됩니다. 이제 컨테이너 ID 필드에 값 2개를 포함할 수 있어, DogStatsD 메트릭을 추가 컨테이너 태그로 보강할 수 있습니다.

  • 컨테이너 ID(사용 가능할 경우)
  • 컨테이너 ID를 사용할 수 없을 경우 cgroup node inode

컨테이너 ID의 접두사는 여전히 c:이고, 값은 다음 중 하나입니다.

  • c:ci-<CONTAINER_ID>
  • c:in-<CGROUP_INODE>

다음은 이제 사용하지 않는 형식이지만, 하위 버전 호환성을 유지하기 위해 계속해서 지원하는 형식입니다.

  • c:<CONTAINER_ID>

DogStatsD 프로토콜 v1.5

에이전트 >=v7.57.0 버전부터 새 External Data 필드가 지원됩니다. Datadog 에이전트는 컨테이너 ID를 사용할 수 없을 경우 External Data 값을 사용해 추가 컨테이너 태그로 DogStatsD 메트릭을 보강합니다.

컨테이너 ID에는 다음과 같이 e: 접두사가 붙습니다.

<METRIC_NAME>:<VALUE>|<TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>|e:<EXTERNAL_DATA>

Datadog 에이전트 승인 컨트롤러가 이 데이터를 제공하고, 이 데이터에는 다음이 포함됩니다.

  • 컨테이너가 init 컨테이너인지 여부를 표현하는 부울
  • 컨테이너 이름
  • 파드 UID

형식은 다음과 같습니다.

it-INIT_CONTAINER,cn-CONTAINER_NAME,pu-POD_UID

다음과 같이 표시됩니다.

it-false,cn-nginx-webserver,pu-75a2b6d5-3949-4afb-ad0d-92ff0674e759

DogStatsD 프로토콜 v1.6

에이전트 버전 >=v7.64.0부터 새 카디널리티 필드가 지원됩니다. Datadog 에이전트는 카디널리티를 사용해 해당 카디널리티와 대응하는 추가 컨테이너 태그로 DogStatsD 메트릭을 보강합니다.

카디널리티 필드는 card: 접두사가 붙습니다. 다음 예를 참고하세요.

<METRIC_NAME>:<VALUE>|<TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>|card:<CARDINALITY>

카디널리티는 다음 태그 보강에 영향을 미칩니다.

카디널리티에서 사용할 수 있는 값은 다음과 같습니다.

  • none
  • low
  • orchestrator
  • high

_e{<TITLE_UTF8_LENGTH>,<TEXT_UTF8_LENGTH>}:<TITLE>|<TEXT>|d:<TIMESTAMP>|h:<HOSTNAME>|p:<PRIORITY>|t:<ALERT_TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>

파라미터필수설명
_eYes데이터그램은 _e로 시작해야 합니다.
<TITLE>Yes이벤트 타이틀입니다.
<TEXT>Yes이벤트 텍스트입니다. \\n로 줄 바꿈을 삽입합니다.
<TITLE_UTF8_LENGTH>YesUTF-8로 인코딩된 <TITLE>의 길이(바이트)
<TEXT_UTF8_LENGTH>YesUTF-8로 인코딩된<TEXT>의 길이(바이트)
d:<TIMESTAMP>No이벤트에 타임스탬프를 추가합니다. 기본값은 현재 Unix epoch 타임스탬프입니다.
h:<HOSTNAME>No이벤트에 호스트 이름을 추가합니다. 기본값은 Datadog 에이전트 인스턴스입니다.
k:<AGGREGATION_KEY>No애그리게이션 키를 추가하여 동일한 키를 가진 다른 이벤트와 이벤트를 그룹화합니다. 기본값 없습니다.
p:<PRIORITY>Nonormal 또는 low로 설정합니다. 기본값은 normal입니다.
s:<SOURCE_TYPE_NAME>No소스 유형을 이벤트에 추가합니다. 기본값은 없습니다.
t:<ALERT_TYPE>Noerror, warning, info 또는 success로 설정합니다. 기본값은 info입니다.
#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>No태그의 콜론은 태그 목록 문자열의 일부이며 다른 파라미터와 같은 파싱 목적이 없습니다. 기본값은 없습니다.

다음은 데이터그램의 예시입니다:

## Send an exception
_e{21,36}:An exception occurred|Cannot parse CSV file from 10.0.0.17|t:warning|#err_type:bad_file

## Send an event with a newline in the text
_e{21,42}:An exception occurred|Cannot parse JSON request:\\n{"foo: "bar"}|p:low|#err_type:bad_request

_sc|<NAME>|<STATUS>|d:<TIMESTAMP>|h:<HOSTNAME>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>|m:<SERVICE_CHECK_MESSAGE>

파라미터필수설명
_scYes데이터그램은 반드시 _sc로 시작해야 합니다.
<NAME>Yes서비스 검사 이름입니다.
<STATUS>Yes검사 상태(OK = 0, WARNING = 1 , Critical = 2, UNKNOWN = 3 )에 해당하는 정수입니다.
d:<TIMESTAMP>No검사에 타임스탬프를 추가합니다. 기본값은 현재 Unix epoch 타임스탬프입니다.
h:<HOSTNAME>No이벤트에 호스트 이름을 추가합니다(기본값 없음).
#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>No이벤트의 태그를 설정합니다. 쉼표로 구분된 문자열 목록입니다(기본값 없음).
m:<SERVICE_CHECK_MESSAGE>No서비스 점검의 현재 상태를 설명하는 메시지입니다. 이 항목은 메타데이터 항목 중 마지막에 위치해야 합니다(기본값 없음).

데이터그램 예시입니다:

# 원격 연결에 대한 CRITICAL 상태 전송
_sc|Redis connection|2|#env:dev|m:Redis connection timed out after 10s

DogStatsD 및 쉘을 사용하여 메트릭을 전송합니다.

Linux 및 기타 Unix 계열 OS의 경우 Bash를 사용합니다. Windows의 경우 PowerShell 및 PowerShell-statsd(네트워크 비트를 처리하는 간단한 PowerShell 기능)을 사용합니다.

DogStatsD는 메트릭, 이벤트 또는 서비스 검사 정보가 포함된 메시지를 생성하여 로컬로 설치된 에이전트에 컬렉터로 보냅니다. 대상 IP 주소는 127.0.0.1이고, UDP를 통한 컬렉터 포트는 8125입니다. 에이전트 설정에 대한 자세한 내용은 DogStatsD을 참조하세요.

메트릭 전송 형식은 다음과 같습니다:

<METRIC_NAME>:<VALUE>|<TYPE>|@<SAMPLE_RATE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>

아래 예시에서는 shell태그와 함께 custom_metric로 호출되는 게이지 메트릭에 대한 데이터 포인트를 전송합니다.

Linux의 경우:

echo -n "custom_metric:60|g|#shell" >/dev/udp/localhost/8125
echo -n "custom_metric:60|g|#shell" | nc -4u -w0 127.0.0.1 8125
echo -n "custom.metric.name:1|c"|nc -4u -w1 localhost 8125

Windows의 경우:

PS C:\> .\send-statsd.ps1 "custom_metric:123|g|#shell"

파이썬(Python)이 있는 모든 플랫폼의 경우 (Windows에서는 에이전트의 내장 파이썬(Python) 인터프리터를 사용할 수 있으며, 에이전트 버전이 6.11 이하면 %ProgramFiles%\Datadog\Datadog Agent\embedded\python.exe에, 에이전트 버전 6.12 이상이면%ProgramFiles%\Datadog\Datadog Agent\embedded<PYTHON_MAJOR_VERSION>\python.exe에 위치 ):

파이썬 2

import socket
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) # UDP
sock.sendto("custom_metric:60|g|#shell", ("localhost", 8125))

Python 3

import socket
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) # UDP
sock.sendto("custom_metric:60|g|#shell", ("localhost", 8125))

이벤트 전송 형식은 다음과 같습니다:

_e{<TITLE>.length,<TEXT>.length}:<TITLE>|<TEXT>|d:<DATE_EVENT>|h:<HOSTNAME>|p:<PRIORITY>|t:<ALERT_TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>.

아래 예시에서는 이벤트 제목과 본문의 크기를 계산합니다.

Linux의 경우:

$ title="셸의 이벤트"

$ text="Bash에서 보냈습니다!"

$ echo "_e{${#title},${#text}}:$title|$text|#shell,bash"  >/dev/udp/localhost/8125

Windows의 경우:

PS C:> $title = "셸의 이벤트"
PS C:> $text = "PowerShell에서 보냈습니다!!"
PS C:> .\send-statsd.ps1 "_e{$($title.length),$($text.Length)}:$title|$text|#shell,PowerShell"

서비스 검사를 보내는 형식은 다음과 같습니다:

_sc|<NAME>|<STATUS>|d:<TIMESTAMP>|h:<HOSTNAME>|#<TAG_KEY_1>:<TAG_VALUE_1>|m:<SERVICE_CHECK_MESSAGE>

Linux의 경우:

echo -n "_sc|Redis connection|2|#env:dev|m:Redis connection timed out after 10s" >/dev/udp/localhost/8125

Windows의 경우:

PS C:\> .\send-statsd.ps1 "_sc|Redis connection|2|#env:dev|m:Redis connection timed out after 10s"

컨테이너화된 환경에서 메트릭, 이벤트 또는 서비스 검사를 전송하려면, 설치 유형에 따라 Kubernetes에서 APM 설정하기Kubernetes의 DogStatsD를 참조하세요. Docker APM 설명서도 도움이 될 수 있습니다.

참고 자료