FAQ¶

연동 후 데이터가 없음¶

다음 순서대로 확인하면 대부분의 설정, 샘플링 또는 네트워크 문제를 빠르게 파악할 수 있습니다.

SDK 초기화 확인: 초기화 코드는 비즈니스 이벤트 발생 전에 실행되어야 하며, 동일 페이지에서 init()는 한 번만 호출되어야 합니다.
연동 파라미터 확인: applicationId를 반드시 설정해야 합니다. 공용 네트워크 OpenWay 사용 시 site와 clientToken을, DataKit 직접 연결 시 datakitOrigin을 사용하며, 두 가지 전송 방식을 혼용하지 마세요.
세션 샘플링 확인: 최초 확인 시 sessionSampleRate를 100으로 설정하여 샘플링 누락으로 인한 오판을 방지하세요.
브라우저 콘솔 확인: 다음 초기화 오류를 중점적으로 확인하세요.

오류 메시지	처리 방법
`Application ID is not configured`	콘솔에서 생성된 `applicationId` 입력
`datakitOrigin or site is not configured`	현재 전송 방식에 맞는 주소 설정
`Allowed Tracing URLs should be an array`	`allowedTracingUrls`를 배열로 변경

네트워크 탭 확인: /v1/write/rum으로 필터링하세요. 요청이 없으면 초기화 시점, 샘플링, CSP를 확인하고, 요청이 실패하면 주소, 토큰, CORS, 프록시, DataKit 접근 가능 여부를 확인하세요.
콘솔 필터 조건 확인: 올바른 애플리케이션이 선택되었는지 확인하고, service, env, version, 시간 범위를 점검하세요.

기본적인 확인 방법은 웹 애플리케이션 연동 > 연동 확인을 참고하세요.

`allowedTracingUrls` 설정 후 비동기 요청 CORS 오류¶

APM(애플리케이션 성능 모니터링) 도구를 사용하여 프론트엔드에서 백엔드까지의 전체 트레이싱(RUM, 실제 사용자 모니터링)을 구현하려면 프론트엔드와 백엔드 모두에서 설정이 필요합니다. 주요 절차 및 주의사항은 다음과 같습니다.

프론트엔드 설정¶

RUM SDK 설치 및 설정:
웹 프론트엔드 애플리케이션에 APM 도구가 제공하는 RUM 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 도구를 성공적으로 설정하여 프론트엔드에서 백엔드까지의 전체 트레이싱을 지원하고, 웹 애플리케이션의 성능을 효과적으로 모니터링하고 최적화할 수 있습니다.

Script error 발생¶

Guance Web RUM SDK를 사용하여 웹 에러를 수집할 때 js_error에서 Script error가 자주 발생합니다. 이러한 오류 메시지에는 자세한 정보가 포함되어 있지 않습니다.

위 문제가 발생할 수 있는 이유:

사용 중인 브라우저가 오류 캡처를 지원하지 않는 경우 (확률 매우 낮음).
오류가 발생한 스크립트 파일이 페이지에 크로스 도메인으로 로드된 경우.

사용자 브라우저가 이를 지원하지 않는 경우는 처리할 수 없습니다. 여기서는 크로스 도메인 스크립트 오류를 수집할 수 없는 원인과 해결 방법을 중점적으로 설명합니다.

일반적으로 스크립트 파일은 <script> 태그를 사용하여 로드됩니다. 동일 출처 스크립트에서 오류가 발생하면 브라우저의 GlobalEventHandlers API를 사용할 때 수집된 오류 정보에 자세한 오류 정보가 포함됩니다. 그러나 다른 출처의 스크립트에서 오류가 발생하면 수집된 오류 정보에는 Script error. 텍스트만 포함됩니다. 이는 브라우저의 동일 출처 정책에 의해 제어되는 정상적인 현상입니다. 다른 출처의 스크립트의 경우 교차 출처 리소스 공유(HTTP 액세스 제어/CORS) 작업을 수행하면 됩니다.

해결 방법:

스크립트 파일이 서버에 직접 저장된 경우:

서버에서 정적 파일 출력 시 다음 헤더를 추가합니다:

Access-Control-Allow-Origin: *

다른 출처의 스크립트가 있는 Script 태그에 crossorigin="anonymous" 속성을 추가합니다:

<script type="text/javascript" src="path/to/your/script.js" crossorigin="anonymous"></script>

스크립트 파일이 CDN에 저장된 경우:

CDN 설정에 다음 헤더를 추가합니다:

Access-Control-Allow-Origin: *

다른 출처의 스크립트가 있는 Script 태그에 crossorigin="anonymous" 속성을 추가합니다:

<script type="text/javascript" src="path/to/your/script.js" crossorigin="anonymous"></script>

스크립트 파일이 타사에서 로드된 경우:

다른 출처의 스크립트가 있는 Script 태그에 crossorigin="anonymous" 속성을 추가합니다:

<script type="text/javascript" src="path/to/your/script.js" crossorigin="anonymous"></script>

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 헤더를 추가합니다:

Timing-Allow-Origin: *

2. 리소스 파일이 CDN에 저장된 경우
CDN 설정에서 리소스 파일에 다음 HTTP 헤더를 추가합니다:

Timing-Allow-Origin: *

참고 문서

Resource `resource_status` 데이터 미수집¶

일부 상황에서 resource_status 데이터가 누락될 수 있으며, 그 이유는 다음과 같습니다.

크로스 도메인 리소스 로드
리소스가 크로스 도메인 방식으로 로드되고 크로스 도메인 액세스 권한이 설정되지 않은 경우, 브라우저는 리소스 상태 정보를 가져올 수 없습니다.
브라우저 호환성
일부 브라우저가 Performance API를 지원하지 않아 관련 데이터를 수집할 수 없는 경우 (매우 드물음).

크로스 도메인 리소스로 인한 `resource_status` 데이터 누락 해결 방법¶

1. 리소스 파일이 서버에 저장된 경우
서버 설정에서 리소스 파일에 다음 HTTP 헤더를 추가합니다:

Access-Control-Allow-Origin: *

2. 리소스 파일이 CDN에 저장된 경우
CDN 설정에서 리소스 파일에 다음 HTTP 헤더를 추가합니다:

Access-Control-Allow-Origin: *

위 설정을 통해 크로스 도메인 리소스로 인한 데이터 수집 문제를 효과적으로 해결하고 브라우저가 성능 데이터를 올바르게 가져올 수 있도록 할 수 있습니다. 참고 문서.

검색 엔진 봇 식별¶

웹 페이지 활동 시 실제 사용자 활동과 검색 엔진을 구분해야 합니다. 다음 예제 스크립트를 사용하여 봇이 있는 세션을 필터링할 수 있습니다.

// 알려진 봇 인스턴스를 식별하는 정규식 패턴:
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
})