오류 그룹화(Error Grouping)

원문 보기 위키 갱신 2026.10.05

오류가 이슈로 그룹화되는 방식을 이해해요.

출처: 문서

본문

기본 그룹화

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로 로그를 수집하고 있지 않다면 로그 관리 문서를 참고해 로그를 설정하세요.

source 태그(언어 지정)가 올바르게 구성되어 있는지 확인하세요.

이 섹션은 다음 기준을 충족하는 사용자에게만 적용돼요: 선택된 Context 값이 주어진 목록('Server, Show all')에 포함되어 있어야 해요.

Server

이미 JSON 형식으로 로깅하고 있다면 오류 로그에 새 error.fingerprint 속성을 추가하세요.

다음은 JSON 형식 로거에 대한 Python 예시예요.

import logging
import json_log_formatter

formatter = json_log_formatter.JSONFormatter()

json_handler = logging.FileHandler(filename='/var/log/my-log.json')
json_handler.setFormatter(formatter)

logger = logging.getLogger('my_json')
logger.addHandler(json_handler)
logger.setLevel(logging.INFO)

logger.error('Error processing request', extra={'error.fingerprint': 'my-custom-grouping-material'})

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

이 섹션은 다음 기준을 충족하는 사용자에게만 적용돼요: 선택된 Context 값이 주어진 목록('Android, Show all')에 포함되어 있어야 해요.

Android

커스텀 그룹화를 사용하려면 Datadog Android SDK 2.7.0 이상이 필요해요.

Datadog 모바일 SDK에서 오류를 로깅할 때 로그 호출에 미리 정의된 속성을 추가해 커스텀 오류 핑거프린트를 추가할 수 있어요.

val errorFingerprint = "my-custom-grouping-material"
val attributes = mapOf(LogAttributes.ERROR_FINGERPRINT to errorFingerprint)
logger.e("My error message", error, attributes)

또는 로그 매퍼에서 핑거프린트를 추가하거나 조정할 수 있어요.

val mapper = object : EventMapper<LogEvent> {
    override fun map(event: LogEvent): LogEvent {
        event.fingerprint = "my-custom-grouping-material"
        return event
    }
}
val logsConfiguration = LogsConfiguration.Builder()
    .setEventMapper(mapper)
    .build()
Logs.enable(logsConfiguration)

이 섹션은 다음 기준을 충족하는 사용자에게만 적용돼요: 선택된 Context 값이 주어진 목록('Flutter, Show all')에 포함되어 있어야 해요.

Flutter

커스텀 그룹화를 사용하려면 Datadog Flutter SDK 2.4.0 이상이 필요해요.

Datadog 모바일 SDK에서 오류를 로깅할 때 로그 호출에 미리 정의된 속성을 추가해 커스텀 오류 핑거프린트를 추가할 수 있어요.

final errorFingerprint = "my-custom-grouping-material";
logger.error(
  'My error message',
  errorStackTrace: st,
  attributes {
    DatadogAttributes.errorFingerprint: "my-custom-grouping-material",
  }
);

또는 로그 매퍼에서 핑거프린트를 추가하거나 조정할 수 있어요.

LogEvent? mapLogEvent(LogEvent event) {
  event.error?.fingerprint = "my-custom-grouping-material";
  return event;
}

final loggingConfiguration = DatadogLoggingConfiguration(
  eventMapper: mapLogEvent,
);

final configuration = DatadogConfiguration(
    // ...
    loggingConfiguration: loggingConfiguration,
);

이 섹션은 다음 기준을 충족하는 사용자에게만 적용돼요: 선택된 Context 값이 주어진 목록('iOS, Show all')에 포함되어 있어야 해요.

iOS

커스텀 그룹화를 사용하려면 Datadog iOS SDK 2.8.1 이상이 필요해요.

Datadog 모바일 SDK에서 오류를 로깅할 때 로그 호출에 미리 정의된 속성을 추가해 커스텀 오류 핑거프린트를 추가할 수 있어요.

let errorFingerprint = "my-custom-grouping-material"
logger.error(
  "My error message",
  error: error,
  attributes: [
    Logs.Attributes.errorFingerprint: errorFingerprint
  ]
)

또는 로그 매퍼에서 핑거프린트를 추가하거나 조정할 수 있어요.

let logsConfiguration = Logs.Configuration(
  eventMapper: { log in
      var log = log
      log.error?.fingerprint = "my-custom-grouping-material"
      return log
  }
)
Logs.enable(
  with: logsConfiguration
)

이 섹션은 다음 기준을 충족하는 사용자에게만 적용돼요: 선택된 Context 값이 주어진 목록('React Native, Show all')에 포함되어 있어야 해요.

React Native

커스텀 그룹화를 사용하려면 Datadog RUM SDK 2.4.2 이상이 필요해요.

Datadog 모바일 SDK에서 오류를 로깅할 때 로그 호출에 미리 정의된 속성을 추가해 커스텀 오류 핑거프린트를 추가할 수 있어요.

DdLogs.error(
  'message',
  'my-error-type',
  'my-error-message',
  'my-stack-trace',
  { my: 'context' },
  'my-custom-fingerprint'
);

또는 로그 매퍼에서 핑거프린트를 추가하거나 조정할 수 있어요.

configuration.errorEventMapper = event => {
  event.fingerprint = 'my-custom-fingerprint'
  return event;
};