APM 데이터 양자화 (Quantization of APM Data)

원문 보기 위키 갱신 2026.10.05

수집(ingestion) 과정에서 Datadog는 span 또는 resource 이름의 무작위 전역 고유 ID(GUID), 숫자 ID, 쿼리 매개변수 값 같은 APM 데이터에 *양자화(quantization)*를 적용해요. 그 결과로 생기는 정규화(normalization)는 이러한 무작위 패턴으로 인한 이름 오염을 줄여 줘요. 분석 목적상 동일한 span과 resource를 함께 그룹화하기 때문이에요.

출처: 문서

본문

개요 (Overview)

수집 과정에서 Datadog는 span 또는 resource 이름에 나타나는 무작위 전역 고유 ID(GUID), 숫자 ID, 쿼리 매개변수 값 등의 APM 데이터에 양자화를 적용합니다. 결과로 생기는 정규화는 이러한 무작위 패턴으로 인한 이름 오염을 줄여 줍니다. 분석 목적상 동일하다고 판단되는 span과 resource를 함께 그룹화하기 때문이에요.

resource 또는 span 이름의 특정 패턴은 다음 정적 문자열로 대체됩니다:

GUID: {guid}
숫자 ID(비알파벳 문자로 둘러싸인 6자리 이상의 숫자 또는 문자열 끝에 있는 숫자): {num}
쿼리 매개변수 값: {val}

이러한 대체는 다음에 영향을 미칩니다:

트레이스 메트릭 이름,
해당 메트릭의 resource name 태그,
수집된 모든 span의 resource 및 span 이름.

양자화 예시 (Quantization examples)

예를 들어, span name이 find_user_2461685a_80c9_4d9e_85e9_a3b0e9e3ea84라면 find_user_{guid}로 이름이 바뀌고, 결과로 생기는 트레이스 메트릭은 다음과 같아요:

trace.find_user_guid
trace.find_user_guid.hits
trace.find_user_guid.errors
trace.find_user_guid.duration
trace.find_user_guid.apdex (서비스에 Apdex가 구성된 경우)

트레이스 검색에서 이러한 span을 검색하려면 쿼리는 operation_name:"find_user_{guid}"입니다.

resource name이 SELECT ? FROM TABLE temp_128390123이라면 SELECT ? FROM TABLE temp_{num}으로 이름이 바뀌고, 메트릭 정규화 태그는 resource_name:select_from_table_temp_num가 돼요.

트레이스 검색에서 이러한 span을 검색하려면 쿼리는 resource_name:"SELECT ? FROM TABLE temp_{num}"입니다.

기본 양자화를 피하기 위한 계측 변경 (Changing instrumentation to avoid default quantization)

참고: 계측 또는 Agent에서 span 및 resource 이름을 상류에서 변경하면 새 메트릭과 태그가 생성됩니다. 양자화된 데이터에 쿼리를 사용한다면 새 이름으로 동작하도록 해당 쿼리를 업데이트해야 해요.

코드 내 계측 (In-code instrumentation)

애플리케이션이 에이전트리스(agentless) 설정에서 실행되거나 코드에서 좀 더 직접적으로 계측 변경을 선호한다면, span 이름과 resource 이름에 대한 커스텀 구성을 만드는 방법에 대해 애플리케이션 런타임의 SDK 문서를 참고하세요.

Agent 구성 (Agent configuration)

Go 호환 정규식을 통해 고유한 대체 문자열을 설정하려면 replace_tags YAML 구성 옵션을 사용할 수 있어요:

apm_config:
  replace_tags:
    # span 이름의 끝에 있는 숫자 ID를 "x"로 대체:
    - name: "span.name"
      pattern: "get_id_[0-9]+"
      repl: "get_id_x"
    # resource 경로의 숫자 ID를 대체:
    - name: "resource.name"
      pattern: "/users/[0-9]+/"
      repl: "/users/{user_id}/"

또는 값이 JSON 문자열인 DD_APM_REPLACE_TAGS 환경 변수를 사용할 수 있어요:

export DD_APM_REPLACE_TAGS = '[{"name": "span.name", "pattern": "get id_[0-9]+", "repl": "get id_x"}, {...}, …]'

트레이서별 구성 (Tracer-specific configuration)

일부 트레이서는 resource 이름 생성을 직접 커스터마이즈할 수 있는 옵션을 제공합니다:

{% tab title="Java" %} Java 트레이서는 dd.trace.http.server.path-resource-name-mapping 옵션으로 HTTP resource 이름을 커스터마이즈할 수 있게 해 주며, Ant 스타일 패턴을 사용해 HTTP 요청 경로를 커스텀 resource 이름에 매핑합니다.

자세한 내용은 Java SDK 구성 문서를 읽어보세요. {% /tab %}

{% tab title="PHP" %} PHP 트레이서는 URI 정규화를 위한 여러 옵션을 제공합니다:

DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX — ID에 해당하는 경로 조각을 식별합니다.
DD_TRACE_RESOURCE_URI_MAPPING_INCOMING — 들어오는 요청의 resource 이름을 정규화합니다.
DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING — 나가는 요청의 resource 이름을 정규화합니다.

자세한 내용은 PHP SDK 구성 문서를 읽어보세요. {% /tab %}