FAQ¶
연동 후 데이터 없음¶
다음 순서로 점검하면 일반적으로 구성, 샘플링 또는 네트워크 문제를 빠르게 파악할 수 있습니다:
- SDK 초기화 확인: 초기화 코드는 비즈니스 이벤트가 발생하기 전에 실행되어야 하며, 동일 페이지에서
init()을 한 번만 호출해야 합니다. Browser SDK3.3.25이상에서는onInitSuccess로 준비 완료를 확인하거나onInitError의code에 따라 실패 원인을 점검할 수 있습니다. 원격 구성을 활성화한 경우fallback은 로컬 구성으로 시작했음을 의미합니다. 자세한 내용은 초기화 결과를 참조하세요. - 연동 파라미터 완전성 확인:
applicationId는 반드시 구성해야 합니다. 퍼블릭 OpenWay는site와clientToken을 사용하고, DataKit 직접 연결은datakitOrigin을 사용하며, 두 가지 전송 방식을 혼용하지 마세요. - Session 샘플링 적중 확인: 최초 점검 시
sessionSampleRate를100으로 설정하여 샘플링 미적중으로 인한 오판을 피하세요. - 브라우저 Console 확인: 다음 초기화 오류를 중점적으로 확인하세요.
| 오류 메시지 | 처리 방법 |
|---|---|
Application ID is not configured |
콘솔에서 생성된 applicationId를 추가하세요 |
datakitOrigin or site is not configured |
현재 전송 방식에 해당하는 주소를 구성하세요 |
Allowed Tracing URLs should be an array |
allowedTracingUrls를 배열로 변경하세요 |
- Network 확인:
/v1/write/rum을 필터링합니다. 요청이 없을 때는 초기화 시점, 샘플링 및 CSP를 확인하고, 요청이 실패할 때는 주소, Token, CORS, 프록시 및 DataKit 접근 가능성을 확인하세요. - 콘솔 필터 조건 확인: 올바른 애플리케이션을 선택했는지 확인하고
service,env,version및 시간 범위를 확인하세요.
기본 점검 방법은 Web 애플리케이션 연동 > 연동 검증을 참고할 수도 있습니다.
allowedTracingUrls 구성 후 비동기 요청의 교차 출처¶
애플리케이션 성능 모니터링(APM) 도구를 사용할 때 프런트엔드에서 백엔드까지의 전체 추적(일반적으로 실제 사용자 모니터링(RUM)이라고 함)을 구현하려면 프런트엔드와 백엔드에서 해당 구성을 수행해야 합니다. 다음은 주요 단계와 유의 사항입니다:
프런트엔드 구성¶
-
RUM SDK 설치 및 구성:
-
Web 프런트엔드 애플리케이션에 APM 도구에서 제공하는 RUM SDK를 설치합니다.
-
SDK를 구성합니다. 여기에는
allowedTracingUrls(Trace Header 주입을 허용할 요청 URL 일치 목록)와traceType(분산 추적 유형) 설정이 포함됩니다. NPM + TypeScript 연동에서는TraceType열거형을 사용합니다(예:TraceType.DDTRACE). 해당 런타임 값은ddtrace입니다. -
추적 정보 전송:
- RUM SDK는
traceType에 따라 해당 요청 헤더를 자동으로 추가합니다. DDTrace를 예로 들면x-datadog-parent-id,x-datadog-origin,x-datadog-sampling-priority,x-datadog-trace-id등이 포함됩니다.
백엔드 구성¶
-
CORS 정책 설정:
-
백엔드 서버에서 CORS(교차 출처 리소스 공유) 정책을 구성하여 프런트엔드 도메인에서 오는 요청을 허용하고, 특히
Access-Control-Allow-Headers에 필요한 모든 추적 정보 헤더를 포함하도록 지정합니다. - 예를 들어 백엔드에서 Node.js와 Express 프레임워크를 사용한다면 CORS 미들웨어를 추가하고
allowedHeaders속성에 이러한 추적 정보 헤더를 포함하도록 설정할 수 있습니다.
const cors = require('cors')
app.use(
cors({
origin: 'https://your-frontend-domain.com', // 프런트엔드 애플리케이션 도메인으로 교체하세요
allowedHeaders: [
'x-datadog-parent-id',
'x-datadog-origin',
'x-datadog-sampling-priority',
'x-datadog-trace-id',
// 기타 필요한 헤더가 있을 수 있습니다
],
})
)
- 요청 처리:
- 백엔드 서비스가 이러한 추적 정보 헤더를 수신하고 올바르게 처리할 수 있도록 보장합니다. 이 정보는 일반적으로 백엔드 서비스에서 요청을 연결하고 추적하는 데 사용됩니다.
검증 및 테스트¶
-
구성 테스트:
-
프런트엔드에서 백엔드로 요청을 보내고 네트워크 요청의 HTTP 헤더를 확인하여 추적 정보가 올바르게 전송되는지 검사합니다.
-
백엔드 서버 로그를 확인하여 추적 정보가 올바르게 처리되는지 확인합니다.
-
디버깅 및 수정:
- 문제(CORS 오류, 헤더 미전송 등)가 발생하면 프런트엔드와 백엔드 구성을 확인하고 필요에 따라 조정하세요.
유의 사항¶
- 보안:
allowedTracingUrls가 신뢰할 수 있는 요청 URL에만 일치하도록 하여 예기치 않은 대상에 Trace Header가 주입되지 않도록 하세요. - 성능: 추적 정보가 성능 모니터링에 매우 중요하지만, 애플리케이션 성능에 부정적인 영향을 주지 않도록 하세요.
위 단계를 통해 APM 도구가 프런트엔드에서 백엔드까지의 전체 추적을 지원하도록 성공적으로 구성할 수 있으며, 이를 통해 Web 애플리케이션의 성능을 보다 효과적으로 모니터링하고 최적화할 수 있습니다.
Script error 발생¶
Guance Web RUM SDK로 Web 오류를 수집할 때 js_error에서 Script error를 자주 보게 됩니다. 이러한 오류 메시지에는 상세 정보가 포함되어 있지 않습니다.
위 문제가 발생할 수 있는 원인:
- 사용자가 사용하는 브라우저가 오류 캡처를 지원하지 않는 경우(확률이 매우 낮음).
- 오류가 발생한 스크립트 파일이 교차 출처로 페이지에 로드된 경우.
사용자 브라우저가 지원하지 않는 경우는 처리할 수 없습니다. 여기서는 주로 교차 출처 스크립트 오류를 수집할 수 없는 원인과 해결 방법을 다룹니다.
일반적으로 스크립트 파일은 <script> 태그로 로드됩니다. 동일 출처 스크립트에서 오류가 발생하면 브라우저의 GlobalEventHandlers API를 사용할 때 수집되는 오류 정보에 상세 오류 정보가 포함됩니다. 교차 출처 스크립트에서 오류가 발생하면 수집되는 오류 정보에는 Script error. 텍스트만 포함되며, 이는 브라우저의 동일 출처 정책에 의해 제어되는 정상적인 상황입니다. 교차 출처 스크립트의 경우 교차 출처 리소스 공유(HTTP 액세스 제어 / CORS라고도 함) 작업만 수행하면 됩니다.
해결 방법:
스크립트 파일을 서버에 직접 저장하는 경우:
서버에서 정적 파일을 출력할 때 헤더를 추가합니다:
교차 출처 스크립트가 있는 Script 태그에 crossorigin="anonymous" 속성을 추가합니다:
스크립트 파일이 CDN에 저장된 경우:
CDN 설정에 헤더를 추가합니다:
교차 출처 스크립트가 있는 Script 태그에 crossorigin="anonymous" 속성을 추가합니다:
스크립트 파일을 타사에서 로드하는 경우:
교차 출처 스크립트가 있는 Script 태그에 crossorigin="anonymous" 속성을 추가합니다:
Resource 데이터 수집 불완전¶
다음 현상은 리소스 데이터가 완전히 수집되지 않은 것으로 간주될 수 있습니다:
-
리소스 크기 관련 데이터가 0인 경우
resource_transfer_size,resource_decode_size,resource_encode_size,resource_size등의 필드를 포함합니다. -
시간 관련 데이터가 수집되지 않은 경우
resource_dns,resource_tcp,resource_ssl,resource_ttfb,resource_trans,resource_first_byte,resource_dns_time,resource_download_time,resource_first_byte_time,resource_connect_time등의 필드를 포함합니다.
가능한 원인¶
-
연결 재사용(Keep-Alive)
리소스 요청이keep-alive방식으로 연결을 유지하면 DNS 조회와 TCP 연결 과정은 최초 요청에서만 발생하고, 후속 요청은 동일한 연결을 재사용하므로 관련 데이터가 기록되지 않거나 0일 수 있습니다. -
교차 출처 리소스 로드
리소스가 교차 출처 방식으로 로드되고 관련 헤더 정보가 구성되지 않으면 브라우저가 전체 성능 데이터를 수집할 수 없습니다. 이는 데이터 누락의 주요 원인입니다. -
브라우저 호환성
매우 드물게 일부 브라우저가Performance API를 지원하지 않아 리소스 관련 성능 데이터를 가져올 수 없을 수 있습니다.
교차 출처 리소스로 인한 데이터 누락 해결 방법¶
1. 리소스 파일이 서버에 저장된 경우
서버에서 리소스 파일에 다음 HTTP 헤더를 추가합니다:
2. 리소스 파일이 CDN에 저장된 경우
CDN 구성에서 리소스 파일에 다음 HTTP 헤더를 추가합니다:
Resource resource_status 데이터 미수집¶
경우에 따라 resource_status 데이터가 누락될 수 있으며, 원인은 다음과 같습니다:
-
교차 출처 리소스 로드
리소스가 교차 출처 방식으로 로드되고 교차 출처 액세스 권한이 설정되지 않으면 브라우저는 리소스 상태 정보를 가져올 수 없습니다. -
브라우저 호환성
일부 브라우저가Performance API를 지원하지 않아 관련 데이터를 수집할 수 없을 수 있습니다(매우 드물게 발생).
교차 출처 리소스로 인한 resource_status 데이터 누락 해결 방법¶
1. 리소스 파일이 서버에 저장된 경우
서버 구성에서 리소스 파일에 다음 HTTP 헤더를 추가합니다:
2. 리소스 파일이 CDN에 저장된 경우
CDN 구성에서 리소스 파일에 다음 HTTP 헤더를 추가합니다:
위 구성을 통해 교차 출처 리소스로 인한 데이터 수집 문제를 효과적으로 해결하고 브라우저가 성능 데이터를 올바르게 가져오도록 보장할 수 있습니다. 참고 문서.
검색 엔진 봇 식별¶
웹 활동을 분석할 때 실제 사용자 활동과 검색 엔진을 구분해야 합니다. 다음 예시 스크립트를 사용하여 봇이 있는 세션을 필터링할 수 있습니다:
// 알려진 봇 인스턴스를 식별하기 위한 정규식 패턴:
let botPattern = "(googlebot\/|bot|Googlebot-Mobile|Googlebot-Image|Google favicon|Mediapartners-Google|bingbot|slurp|java|wget|curl|Commons-HttpClient|Python-urllib|libwww|httpunit|nutch|phpcrawl|msnbot|jyxobot|FAST-WebCrawler|FAST Enterprise Crawler|biglotron|teoma|convera|seekbot|gigablast|exabot|ngbot|ia_archiver|GingerCrawler|webmon |httrack|webcrawler|grub.org|UsineNouvelleCrawler|antibot|netresearchserver|speedy|fluffy|bibnum.bnf|findlink|msrbot|panscient|yacybot|AISearchBot|IOI|ips-agent|tagoobot|MJ12bot|dotbot|woriobot|yanga|buzzbot|mlbot|yandexbot|purebot|Linguee Bot|Voyager|CyberPatrol|voilabot|baiduspider|citeseerxbot|spbot|twengabot|postrank|turnitinbot|scribdbot|page2rss|sitebot|linkdex|Adidxbot|blekkobot|ezooms|dotbot|Mail.RU_Bot|discobot|heritrix|findthatfile|europarchive.org|NerdByNature.Bot|sistrix crawler|ahrefsbot|Aboundex|domaincrawler|wbsearchbot|summify|ccbot|edisterbot|seznambot|ec2linkfinder|gslfbot|aihitbot|intelium_bot|facebookexternalhit|yeti|RetrevoPageAnalyzer|lb-spider|sogou|lssbot|careerbot|wotbox|wocbot|ichiro|DuckDuckBot|lssrocketcrawler|drupact|webcompanycrawler|acoonbot|openindexspider|gnam gnam spider|web-archive-net.com.bot|backlinkcrawler|coccoc|integromedb|content crawler spider|toplistbot|seokicks-robot|it2media-domain-crawler|ip-web-crawler.com|siteexplorer.info|elisabot|proximic|changedetection|blexbot|arabot|WeSEE:Search|niki-bot|CrystalSemanticsBot|rogerbot|360Spider|psbot|InterfaxScanBot|Lipperhey SEO Service|CC Metadata Scaper|g00g1e.net|GrapeshotCrawler|urlappendbot|brainobot|fr-crawler|binlar|SimpleCrawler|Livelapbot|Twitterbot|cXensebot|smtbot|bnf.fr_bot|A6-Indexer|ADmantX|Facebot|Twitterbot|OrangeBot|memorybot|AdvBot|MegaIndex|SemanticScholarBot|ltx71|nerdybot|xovibot|BUbiNG|Qwantify|archive.org_bot|Applebot|TweetmemeBot|crawler4j|findxbot|SemrushBot|yoozBot|lipperhey|y!j-asr|Domain Re-Animator Bot|AddThis)";
let regex = new RegExp(botPattern, 'i');
// 사용자 에이전트가 봇 패턴과 일치하면 추적 헤더 주입을 비활성화합니다
const allowedTracingUrls = regex.test(navigator.userAgent)
? []
: ['https://api.example.com']
window.DATAFLUX_RUM.init({
// ... 구성 옵션
allowedTracingUrls
})