APM 트러블슈팅 (APM Troubleshooting)

원문 보기 위키 갱신 2026.10.05

Datadog APM을 사용하면서 예기치 않은 동작이 발생한다면 이 페이지의 정보를 읽고 문제를 해결해 보세요. Datadog는 사용 중인 Datadog SDK를 정기적으로 최신 버전으로 업데이트할 것을 권장해요. 각 릴리스에는 개선 사항과 수정 사항이 포함되어 있거든요. 계속 문제가 발생한다면 Datadog 지원에 문의해요.

출처: 문서

본문

다음 구성 요소가 APM 데이터를 Datadog로 보내는 데 관여해요:

자세한 내용은 Additional support를 참고해요.

trace 보존 (Trace retention)

이 섹션은 Datadog 전반의 trace 데이터 보존 및 필터링과 관련된 문제를 다뤄요.

Trace Explorer에 모니터 페이지보다 더 많은 스팬이 있어요

custom retention filters를 설정하지 않았다면 이는 예상된 동작이에요. 이유는 다음과 같아요:

Trace Explorer 페이지에서는 어떤 태그로든 수집되거나 인덱스된 모든 스팬을 검색할 수 있어요. 여기서 어떤 trace든 쿼리할 수 있어요.

기본적으로 스팬이 수집된 후에는 Datadog 지능형 필터가 이를 보존해요. Datadog는 서비스, 엔드포인트, 오류, 고레이턴시 trace에 대한 가시성을 제공하기 위해 기본적으로 활성화된 다른 보존 필터도 가지고 있어요.

그러나 모니터에서 이런 trace를 사용하려면 custom retention filters를 설정해야 해요.

Custom retention filter를 사용하면 태그 기반으로 추가 필터를 만들고, 수정하고, 비활성화하여 어떤 스팬을 인덱스하고 보존할지 결정할 수 있어요. 또한 각 필터와 일치하는 스팬의 보존 비율을 설정할 수 있어요. 이렇게 인덱스된 trace는 모니터에서 사용할 수 있어요.

제품	스팬 소스
Monitors	커스텀 보존 필터의 스팬
기타 제품(Dashboard, Notebook 등)	커스텀 보존 필터 + Datadog 지능형 필터의 스팬

trace 메트릭 (Trace metrics)

이 섹션은 trace 메트릭의 불일치와 불일치 문제를 다뤄요.

trace 메트릭과 커스텀 스팬 기반 메트릭의 값이 달라요

trace 메트릭과 커스텀 스팬 기반 메트릭은 서로 다른 데이터셋을 기반으로 계산되기 때문에 값이 다를 수 있어요:

trace 메트릭은 trace 수집 샘플링 구성과 관계없이 애플리케이션 트래픽의 100%를 기준으로 계산돼요. trace 메트릭 네임스페이스는 trace.<SPAN_NAME>.<METRIC_SUFFIX> 형식을 따라요.
커스텀 스팬 기반 메트릭은 수집된 스팬을 기반으로 생성되며, 이것은 trace 수집 샘플링에 따라 달라져요. 예를 들어 trace의 50%만 수집하고 있다면 커스텀 스팬 기반 메트릭은 수집된 50% 스팬을 기반으로 해요.

trace 메트릭과 커스텀 스팬 기반 메트릭의 값이 같도록 하려면 애플리케이션 또는 서비스에 대해 100% 수집 비율을 구성해요.

💡 메트릭 이름은 메트릭 명명 규칙을 따라야 해요. trace.*로 시작하는 메트릭 이름은 허용되지 않으며 저장되지 않아요.

서비스 (Services)

이 섹션은 서비스 관련 문제를 트러블슈팅하는 전략을 다뤄요.

하나의 서비스가 Datadog에서 여러 서비스로 표시돼요

이런 현상은 서비스 이름이 모든 스팬에서 일관되지 않을 때 발생할 수 있어요.

예를 들어 service:test 같은 단일 서비스가 Datadog에 여러 서비스로 표시될 수 있어요:

service:test
service:test-mongodb
service:test-postgresdb

Inferred Service dependencies (Preview)를 사용할 수 있어요. Inferred 외부 API는 기본 명명 스킴 net.peer.name을 사용해요. 예: api.stripe.com, api.twilio.com, us6.api.mailchimp.com. Inferred 데이터베이스는 기본 명명 scheme db.instance를 사용해요.

또는 언어에 따라 DD_SERVICE_MAPPING 또는 DD_TRACE_SERVICE_MAPPING 같은 환경 변수로 서비스 이름을 병합할 수 있어요.

자세한 내용은 Configure the Datadog SDK를 참고하거나 여기서 언어를 선택해요:

Java — dd.service.mapping 환경 변수: DD_SERVICE_MAPPING 기본값: null 예시: mysql:my-mysql-service-name-db, postgresql:my-postgres-service-name-db 구성으로 서비스를 동적으로 이름 바꿔요. 서로 다른 서비스 간에 데이터베이스의 이름을 구분 짓는 데 유용해요.

Python — DD_SERVICE_MAPPING trace에서 서비스 이름을 바꿀 수 있도록 서비스 이름 매핑을 정의해요. 예: postgres:postgresql,defaultdb:postgresql. 버전 0.47+에서 사용할 수 있어요.

Go — DD_SERVICE_MAPPING 기본값: null 구성으로 서비스를 동적으로 이름 바꿔요. 서비스는 쉼표 또는 공백으로 구분할 수 있어요. 예: mysql:mysql-service-name,postgres:postgres-service-name, mysql:mysql-service-name postgres:postgres-service-name.

Node.js — DD_SERVICE_MAPPING 구성: serviceMapping 기본값: N/A 예시: mysql:my-mysql-service-name-db,pg:my-pg-service-name-db 각 플러그인에 서비스 이름을 제공해요. 쉼표로 구분된 plugin:service-name 쌍을 공백 유무와 관계없이 허용해요.

.NET — DD_TRACE_SERVICE_MAPPING 구성으로 서비스를 이름 바꿔요. 이름을 바꿀 서비스 이름 키-값 쌍의 쉼표로 구분된 목록과 대신 사용할 이름을 [from-key]:[to-name] 형식으로 허용해요. 예시: mysql:main-mysql-db, mongodb:offsite-mongodb-service from-key 값은 통합 유형에 따라 다르며 애플리케이션 이름 접두사를 제외해야 해요. 예를 들어 my-application-sql-server를 main-db로 바꾸려면 sql-server:main-db을 사용해요. 버전 1.23.0에서 추가됨.

PHP — DD_SERVICE_MAPPING INI: datadog.service_mapping 기본값: null APM 통합의 기본 이름을 변경해요. 한 번에 하나 이상의 통합 이름을 바꿔요. 예: DD_SERVICE_MAPPING=pdo:payments-db,mysqli:orders-db (Integration names 참고).

Ruby — Ruby는 DD_SERVICE_MAPPING 또는 DD_TRACE_SERVICE_MAPPING을 지원하지 않아요. 서비스 이름을 변경하는 코드 옵션은 Additional Ruby configuration을 참고해요.

Plan and Usage 페이지에서 수집/인덱스 스팬이 예기치 않게 증가했어요

데이터 수집과 인덱싱의 급증은 다양한 요인으로 발생할 수 있어요. 증가 원인을 조사하려면 APM Traces Estimated Usage 메트릭을 사용해요:

사용 유형	메트릭	설명
APM Indexed Spans	`datadog.estimated_usage.apm.indexed_spans`	태그 기반 보존 필터로 인덱스된 총 스팬 수.
APM Ingested Spans	`datadog.estimated_usage.apm.ingested_spans`	총 수집된 스팬 수.

APM Traces Usage 대시보드에는 상위 수준 KPI와 추가 사용 정보를 표시하는 여러 위젯 그룹이 있어요.

오류 메시지와 스택 트레이스가 누락됐어요

오류 상태의 일부 trace에서 Errors 탭에 예외 세부 정보 대신 Missing error message and stack trace가 표시돼요.

스팬이 이 메시지를 표시할 수 있는 이유는 두 가지예요:

스팬에 처리되지 않은 예외가 포함되어 있어요.
스팬 내 HTTP 응답이 400~599 사이의 HTTP 상태 코드를 반환했어요.

예외가 try/catch 블록에서 처리되면 error.message, error.type, error.stack 스팬 태그가 채워지지 않아요. 상세 오류 스팬 태그를 채우려면 Custom Instrumentation 코드를 사용해요.

데이터 볼륨 가이드라인 (Data volume guidelines)

다음 문제 중 하나라도 발생한다면 Datadog의 볼륨 가이드라인을 초과하고 있을 수 있어요:

trace 메트릭이 Datadog 플랫폼에서 예상대로 보고되지 않아요.
Datadog 플랫폼에 보일 것으로 기대했던 일부 리소스가 없어요.
서비스의 trace는 보이는데 Catalog 페이지에서 이 서비스를 찾을 수 없어요.

데이터 볼륨 가이드라인 — 계측된 애플리케이션은 현재 시간으로부터 최대 18시간 이전과 2시간 이후의 타임스탬프를 가진 스팬을 제출할 수 있어요.

Datadog는 주어진 40분 간격에 대해 다음 조합을 허용해요:

5000개의 고유 environments 및 service 조합
추가 기본 태그별 100개의 고유 primary tag values
환경·서비스별 100개의 고유 operation names
환경, 서비스, 운영 이름별 1000개의 고유 resources
환경·서비스별 30개의 고유 versions

더 큰 볼륨을 수용해야 한다면 사용 사례와 함께 Datadog 지원에 문의해요.

Datadog는 다음 문자열이 표시된 문자 수를 초과하면 잘라요:

이름	문자
service	100
operation	100
type	100
resource	5000
tag key	200
tag value	25000

또한 어떤 스팬에든 존재하는 스팬 태그 수는 1024를 초과할 수 없어요.

서비스 수가 데이터 볼륨 가이드라인에 지정된 것보다 많아요

서비스 수가 데이터 볼륨 가이드라인에 지정된 것보다 많으면 서비스 명명 규칙의 다음 모범 사례를 따라 보세요.

서비스 이름에서 환경 태그 값 제외하기 — 기본적으로 환경(env)은 Datadog APM의 기본 태그예요.

서비스는 일반적으로 prod, staging, dev 같은 여러 환경에 배포돼요. 요청 수, 레이턴시, 오류율 같은 성능 메트릭은 다양한 환경에서 다르게 나타나요. Catalog의 환경 드롭다운을 사용하면 Performance 탭의 데이터를 특정 환경으로 범위를 좁힐 수 있어요.

지나치게 많은 서비스 수로 문제를 일으키는 흔한 패턴 중 하나는 서비스 이름에 환경 값을 포함하는 것이에요. 예를 들어 두 개의 별도 환경에서 운영되기 때문에 하나 대신 두 개의 고유 서비스가 있을 수 있어요: prod-web-store와 dev-web-store.

Datadog는 서비스 이름을 바꿔 계측을 조정할 것을 권장해요.

Trace 메트릭은 샘플링되지 않으므로 계측된 애플리케이션이 하위 섹션이 아닌 모든 데이터를 보여줘요. 볼륨 가이드라인도 적용돼요.

메트릭 파티션이나 그룹화 변수를 서비스 이름에 넣는 대신 추가 기본 태그 사용하기 — 추가 기본 태그를 사용해 trace 메트릭을 그룹화·집계할 수 있어요. 드롭다운을 사용해 성능 데이터를 특정 클러스터 이름이나 데이터 센터 값으로 범위를 좁혀요.

추가 기본 태그를 적용하는 대신 서비스 이름에 메트릭 파티션이나 그룹화 변수를 포함하면 계정의 고유 서비스 수가 과도하게 늘어나고 지연이나 데이터 손실이 발생할 수 있어요.

예를 들어 web-store 서비스 대신 서비스의 다른 인스턴스에 web-store-us-1, web-store-eu-1, web-store-eu-2라고 이름을 지어 이 파티션들의 성능 메트릭을 나란히 보려 할 수 있어요. Datadog는 지역 값(us-1, eu-1, eu-2)을 기본 태그로 구현할 것을 권장해요.

연결 오류 (Connection errors)

이 섹션은 애플리케이션과 Datadog Agent 사이의 연결 및 통신 문제를 진단·해결하는 지침을 제공해요.

계측된 애플리케이션이 Datadog Agent와 통신하지 않아요 — 이러한 문제를 찾고 해결하는 방법은 Connection Errors에서 읽어보세요.

리소스 사용량 (Resource usage)

이 섹션은 리소스 활용과 관련된 성능 문제를 트러블슈팅하는 정보를 담고 있어요.

OOM(메모리 부족) 오류 — Agent Resource Usage에서 trace 수집 CPU 사용량을 감지하고 Agent의 적절한 리소스 한도를 계산하는 방법을 읽어보세요.

속도 제한 또는 최대 이벤트 오류 메시지 — Datadog Agent 로그에서 속도 제한 또는 초당 최대 이벤트에 대한 오류 메시지가 보이면 이 지침을 따라 한도를 변경할 수 있어요. 변경 전에 질문이 있으면 Datadog 지원 팀과 상의해요.

보안 (Security)

이 섹션은 민감 데이터 보호와 트래픽 관리 포함, APM의 보안 문제 해결 접근 방식을 다뤄요.

스팬 수정, 폐기 또는 난독화 — 민감 데이터를 스크럽하거나 헬스 체크나 기타 원치 않는 트래픽에 해당하는 trace를 폐기하는 데 사용할 수 있는 여러 구성 옵션이 있어요. Datadog Agent 내에서 또는 일부 언어에서는 tracing client에서 구성할 수 있어요. 사용 가능한 옵션에 대한 자세한 내용은 Security and Agent Customization을 참고해요. 대표적인 예시를 제공하지만, 이러한 옵션을 환경에 적용하는 데 도움이 필요하다면 Datadog Support에 문의해요.

디버깅과 로깅 (Debugging and logging)

이 섹션은 Datadog SDK의 문제를 식별·해결하기 위해 디버그 및 시작 로그를 사용하는 방법을 설명해요.

디버그 로그 — Datadog SDK에 대한 전체 세부 정보를 캡처하려면 DD_TRACE_DEBUG 환경 변수를 사용해 SDK에서 디버그 모드를 활성화해요.

이 로그는 계측 오류나 통합별 오류를 표면화할 수 있어요. 이러한 디버그 로그를 활성화·캡처하는 방법은 debug mode troubleshooting page를 참고해요.

시작 로그 — 시작하는 동안 Datadog SDK는 JSON 객체로 적용된 구성과 발생한 오류를 반영하는 로그를 내보내요. 가능한 언어에서는 Agent에 도달할 수 있는지도 포함돼요. 일부 언어는 환경 변수 DD_TRACE_STARTUP_LOGS=true로 시작 로그를 활성화해야 해요. 자세한 내용은 Startup logs를 참고해요.

SDK 구성 — 구성 값은 SDK가 자동으로 보고하며 UI에서 볼 수 있어요. 이는 잘못된 구성으로 인한 계측 문제를 트러블슈팅하는 데 사용할 수 있어요. 자세한 내용은 SDK configurations page를 참고해요.

추가 지원 (Additional support)

여전히 추가 지원이 필요하다면 Datadog Support로 티켓을 열어요.

Datadog Support 티켓 열기 — 지원 티켓을 열면 Datadog 지원 팀이 다음 유형의 정보를 요청할 수 있어요:

trace 링크 또는 문제 스크린샷: 문제를 재현해 트러블슈팅하는 데 도움이 돼요.
SDK 시작 로그: 시작 로그는 트레이서 잘못된 구성 또는 SDK와 Datadog Agent 사이의 통신 문제를 식별하는 데 도움이 돼요. SDK의 구성과 애플리케이션 또는 컨테이너 설정을 비교해 지원 팀은 잘못 적용된 설정을 정확히 찾아낼 수 있어요.
SDK 디버그 로그: SDK 디버그 로그는 시작 로그보다 더 깊은 인사이트를 제공해 다음을 보여줘요:
- 애플리케이션 트래픽 흐름 중 올바른 통합 계측
- SDK가 만든 스팬의 내용
- 스팬을 Agent로 보낼 때의 연결 오류
Datadog Agent flare: Datadog Agent flares를 사용하면 trace가 거부되거나 잘못된 형식인 경우처럼 Datadog Agent 안에서 무슨 일이 벌어지고 있는지 볼 수 있어요. trace가 Datadog Agent에 도달하지 못할 때는 도움이 되지 않지만, 문제의 원인이나 메트릭 불일치를 식별하는 데는 도움이 돼요.
환경 설명: 애플리케이션의 배포 구성을 이해하면 지원 팀이 잠재적인 tracer-Agent 통신 문제를 식별하고 잘못된 구성을 찾아내는 데 도움이 돼요. 복잡한 문제의 경우 지원 팀이 Kubernetes 매니페스트, ECS 태스크 정의 또는 유사한 배포 구성 파일을 요청할 수 있어요.
커스텀 추적 코드: 커스텀 계측, 구성, 스팬 태그 추가는 Datadog의 trace 시각화에 큰 영향을 줄 수 있어요.
버전 정보: 사용 중인 언어, 프레임워크, Datadog Agent, Datadog SDK 버전을 알면 지원 팀이 Compatibility Requirements를 확인하고, 알려진 문제를 확인하며, 버전 업그레이드를 권장할 수 있어요. 예: