오류 그룹화 (Error Grouping)

원문 보기 위키 갱신 2026.10.05

Error Tracking이 유사한 오류를 이슈(issue)로 그룹화하고 커스텀 그룹화를 구성하는 방법을 안내해요.

출처: 문서

본문

기본 그룹화

Error Tracking은 유사한 오류를 이슈로 지능적으로 그룹화해요. 이 그룹화는 다음 오류 속성을 기반으로 해요:

service: 오류가 발생한 서비스.
error.type 또는 error.kind: 오류의 클래스.
error.message: 오류에 대한 설명.
error.stack: 가장 의미 있는 최상위 스택 프레임의 파일 이름과 함수 이름. 자세한 내용은 Error Tracking의 스택 트레이스를 참조하세요.

오류 스택 트레이스는 오류가 발생한 시점부터 Datadog 계측이 오류를 캡처할 때까지 오류가 따른 코드 경로예요. Error Tracking은 최상위 스택 프레임(오류의 위치)을 평가해 이를 사용해 오류를 그룹화해요.

두 오류에 대해 스택 프레임 속성이 다르면 두 오류는 서로 다른 이슈로 그룹화돼요. 예를 들어 Error Tracking은 서비스나 오류 유형을 가로질러 이슈를 그룹화하지 않아요. Error Tracking은 또한 숫자, 문장 부호, 따옴표나 괄호 사이의 모든 것을 무시해요. 단어와 같은 토큰만 사용돼요.

참고:

최적의 그룹화를 위해 오류 메시지의 변수를 따옴표나 괄호로 감싸세요.
그룹화 정확도를 높이기 위해 Error Tracking은 버전, ID, 날짜 같은 가변 스택 프레임 속성을 제거해요.

커스텀 그룹화

Error Tracking은 기본 전략으로 유사한 오류를 이슈로 지능적으로 그룹화해요. 커스텀 핑거프린팅을 사용하면 그룹화 결정을 완전히 제어하고 오류 스팬에 대한 그룹화 동작을 커스터마이즈할 수 있어요.

오류에 error.fingerprint를 제공해 그룹화를 커스터마이즈할 수 있어요. 핑거프린트는 오류 소스에 따라 속성 또는 태그로 제공돼요 (자세한 내용은 설정 참조). error.fingerprint의 값은 특정 형식이나 요구 사항이 없지만 내용은 문자열이어야 해요.

error.fingerprint가 제공되면 그룹화 동작은 다음 규칙을 따르며, 다음을 참고해요:

커스텀 그룹화는 기본 전략보다 우선해요.
커스텀 그룹화는 오류의 하위 집합에만 적용할 수 있으며 기본 전략과 공존할 수 있어요.
error.fingerprint의 내용은 수정 없이 있는 그대로 사용돼요 (표준화된 핑거프린트 형식으로 변환되긴 해요).
같은 서비스에서 온 오류와 같은 error.fingerprint 속성은 같은 이슈로 그룹화돼요.
service 속성이 다른 오류는 서로 다른 이슈로 그룹화돼요.

설정

커스텀 그룹화에는 오류 스팬과 error.fingerprint 문자열 스팬 태그만 필요해요.

아직 Datadog으로 APM 트레이스를 수집하지 않는다면 APM을 설정하려면 APM 문서를 참조하세요.

예시

이미 APM 스팬을 보내고 있다면 오류 스팬에 새 error.fingerprint 태그를 추가해요.

Python 예시:

with tracer.trace("throws.an.error") as span:
  span.set_tag('error.fingerprint', 'my-custom-grouping-material')
  raise Exception("Something went wrong")

예외가 발생할 때 활성 스팬이 있으면 예외 정보가 캡처되어 스팬에 연결돼요.

이 경우 my-custom-grouping-material이 Error Tracking에서 이러한 오류 스팬을 단일 이슈로 그룹화하는 데 사용돼요.