브라우저 로그 수집

원문 보기 위키 갱신 2026.10.05

브라우저 로그 SDK로 웹 브라우저 페이지에서 Datadog로 로그를 보내세요.

브라우저 로그 SDK를 사용하면 웹 브라우저 페이지에서 Datadog로 로그를 직접 보내고 다음 기능을 활용할 수 있어요:

SDK를 로거로 사용하세요. 모든 것이 JSON 문서로 Datadog에 전달돼요.
보내는 모든 로그에 context와 추가 사용자 정의 속성 추가.
모든 프런트엔드 오류를 자동으로 감싸 전달.
프런트엔드 오류를 전달.
실제 클라이언트 IP 주소와 user agent 기록.
자동 벌크 게시로 최적화된 네트워크 사용량.
Worker 및 Service Worker 환경에서 사용.

참고:

RUM SDK와 독립적: 브라우저 로그 SDK는 RUM SDK 없이도 사용할 수 있어요.
Worker 환경: 브라우저 로그 SDK는 동일한 설정 메서드로 Worker 및 Service Worker 환경에서 동작해요. 다만 Worker 환경에서 보낸 로그에는 세션 정보가 자동으로 포함되지 않아요.
WebAssembly 오류: 브라우저 로그에서 WASM 프레임을 기호화하려면 Browser SDK WASM 플러그인을 구성하고 모듈의 디버그 심볼을 업로드하세요.

출처: 문서

본문

설정

1단계 - 클라이언트 토큰 만들기

Datadog에서 Organization Settings > New Client Tokens로 이동하세요.

지원 환경: 브라우저 로그 SDK는 모든 최신 데스크톱·모바일 브라우저와 Worker·Service Worker 환경을 지원해요. Browser Support 표를 참고하세요.

{% alert level="info" %} 보안상의 이유로 API 키는 JavaScript 코드에서 클라이언트 측에 노출되므로 브라우저 로그 SDK를 구성하는 데 사용할 수 없어요. 웹 브라우저에서 로그를 수집하려면 클라이언트 토큰을 사용해야 해요. {% /alert %}

2단계 - Logs Browser SDK 설치

Browser SDK 설치 방법을 선택하세요.

{% tab title="NPM" %} 최신 웹 애플리케이션의 경우 Datadog는 Node Package Manager(npm)로 설치할 것을 권장해요. Browser SDK는 나머지 프런트엔드 JavaScript 코드와 함께 패키징돼요. 페이지 로드 성능에는 영향이 없어요. 다만 SDK는 초기화 전에 발생하는 오류나 콘솔 로그를 캡처하지 못할 수 있어요. Datadog는 Browser Logs SDK와 버전이 일치하는 것을 권장해요.

@datadog/browser-logs를 package.json 파일에 추가하세요. 예를 들어 npm CLI를 사용한다면: {% /tab %}

{% tab title="CDN async" %} 성능 목표가 있는 웹 애플리케이션은 CDN async로 설치해야 해요. Browser SDK는 Datadog의 CDN에서 비동기적으로 로드되므로 페이지 로드 성능에 영향을 주지 않아요. 다만 SDK는 초기화 전에 발생하는 오류나 콘솔 로그를 캡처하지 못할 수 있어요.

생성된 코드 스니펫을 애플리케이션에서 모니터링하려는 모든 HTML 페이지의 head 태그에 추가하세요.

{% callout %}

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: app.datadoghq.com

<script>
  (function(h,o,u,n,d) {
    h=h[d]=h[d]||{q:[],onReady:function(c){h.q.push(c)}}
    d=o.createElement(u);d.async=1;d.src=n;d.crossOrigin=''
    n=o.getElementsByTagName(u)[0];n.parentNode.insertBefore(d,n)
  })(window,document,'script','https://www.datadoghq-browser-agent.com/us1/v7/datadog-logs.js','DD_LOGS')
</script>

{% /callout %}

{% callout %}

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: app.datadoghq.eu

<script>
  (function(h,o,u,n,d) {
    h=h[d]=h[d]||{q:[],onReady:function(c){h.q.push(c)}}
    d=o.createElement(u);d.async=1;d.src=n;d.crossOrigin=''
    n=o.getElementsByTagName(u)[0];n.parentNode.insertBefore(d,n)
  })(window,document,'script','https://www.datadoghq-browser-agent.com/eu1/v7/datadog-logs.js','DD_LOGS')
</script>

{% /callout %}

{% callout %}

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: ap1.datadoghq.com

<script>
  (function(h,o,u,n,d) {
    h=h[d]=h[d]||{q:[],onReady:function(c){h.q.push(c)}}
    d=o.createElement(u);d.async=1;d.src=n;d.crossOrigin=''
    n=o.getElementsByTagName(u)[0];n.parentNode.insertBefore(d,n)
  })(window,document,'script','https://www.datadoghq-browser-agent.com/ap1/v7/datadog-logs.js','DD_LOGS')
</script>

{% /callout %}

{% callout %}

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: ap2.datadoghq.com

<script>
  (function(h,o,u,n,d) {
    h=h[d]=h[d]||{q:[],onReady:function(c){h.q.push(c)}}
    d=o.createElement(u);d.async=1;d.src=n;d.crossOrigin=''
    n=o.getElementsByTagName(u)[0];n.parentNode.insertBefore(d,n)
  })(window,document,'script','https://www.datadoghq-browser-agent.com/ap2/v7/datadog-logs.js','DD_LOGS')
</script>

{% /callout %}

{% callout %}

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: us3.datadoghq.com

<script>
  (function(h,o,u,n,d) {
    h=h[d]=h[d]||{q:[],onReady:function(c){h.q.push(c)}}
    d=o.createElement(u);d.async=1;d.src=n;d.crossOrigin=''
    n=o.getElementsByTagName(u)[0];n.parentNode.insertBefore(d,n)
  })(window,document,'script','https://www.datadoghq-browser-agent.com/us3/v7/datadog-logs.js','DD_LOGS')
</script>

{% /callout %}

{% callout %}

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: us5.datadoghq.com

<script>
  (function(h,o,u,n,d) {
    h=h[d]=h[d]||{q:[],onReady:function(c){h.q.push(c)}}
    d=o.createElement(u);d.async=1;d.src=n;d.crossOrigin=''
    n=o.getElementsByTagName(u)[0];n.parentNode.insertBefore(d,n)
  })(window,document,'script','https://www.datadoghq-browser-agent.com/us5/v7/datadog-logs.js','DD_LOGS')
</script>

{% /callout %}

{% callout %}

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: uk1.datadoghq.com

<script>
  (function(h,o,u,n,d) {
    h=h[d]=h[d]||{q:[],onReady:function(c){h.q.push(c)}}
    d=o.createElement(u);d.async=1;d.src=n;d.crossOrigin=''
    n=o.getElementsByTagName(u)[0];n.parentNode.insertBefore(d,n)
  })(window,document,'script','https://www.datadoghq-browser-agent.com/uk1/v7/datadog-logs.js','DD_LOGS')
</script>

{% /callout %}

{% callout %}

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: app.ddog-gov.com, us2.ddog-gov.com

<script>
  (function(h,o,u,n,d) {
    h=h[d]=h[d]||{q:[],onReady:function(c){h.q.push(c)}}
    d=o.createElement(u);d.async=1;d.src=n;d.crossOrigin=''
    n=o.getElementsByTagName(u)[0];n.parentNode.insertBefore(d,n)
  })(window,document,'script','https://www.datadoghq-browser-agent.com/datadog-logs-v7.js','DD_LOGS')
</script>

{% /callout %}

{% /tab %}

{% tab title="CDN sync" %} 모든 이벤트를 수집하려면 CDN sync로 설치해야 해요. Browser SDK는 Datadog의 CDN에서 동기적으로 로드되어 SDK가 먼저 로드되고 모든 오류, 리소스, 사용자 동작을 수집해요. 이 방법은 페이지 로드 성능에 영향을 줄 수 있어요.

생성된 코드 스니펫을 애플리케이션에서 모니터링하려는 모든 HTML 페이지의 head 태그(다른 스크립트 태그 앞)에 추가하세요. 스크립트 태그를 더 위에 배치하고 동기적으로 로드하면 Datadog RUM이 모든 성능 데이터와 오류를 수집할 수 있어요.

{% callout %}

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: app.datadoghq.com

<script
    src="https://www.datadoghq-browser-agent.com/us1/v7/datadog-logs.js"
    type="text/javascript"
    crossorigin>
</script>

{% /callout %}

{% callout %}

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: app.datadoghq.eu

<script
    src="https://www.datadoghq-browser-agent.com/eu1/v7/datadog-logs.js"
    type="text/javascript"
    crossorigin>
</script>

{% /callout %}

{% callout %}

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: ap1.datadoghq.com

<script
    src="https://www.datadoghq-browser-agent.com/ap1/v7/datadog-logs.js"
    type="text/javascript"
    crossorigin>
</script>

{% /callout %}

{% callout %}

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: ap2.datadoghq.com

<script
    src="https://www.datadoghq-browser-agent.com/ap2/v7/datadog-logs.js"
    type="text/javascript"
    crossorigin>
</script>

{% /callout %}

{% callout %}

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: us3.datadoghq.com

<script
    src="https://www.datadoghq-browser-agent.com/us3/v7/datadog-logs.js"
    type="text/javascript"
    crossorigin>
</script>

{% /callout %}

{% callout %}

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: us5.datadoghq.com

<script
    src="https://www.datadoghq-browser-agent.com/us5/v7/datadog-logs.js"
    type="text/javascript"
    crossorigin>
</script>

{% /callout %}

{% callout %}

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: uk1.datadoghq.com

<script
    src="https://www.datadoghq-browser-agent.com/uk1/v7/datadog-logs.js"
    type="text/javascript"
    crossorigin>
</script>

{% /callout %}

{% callout %}

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: app.ddog-gov.com, us2.ddog-gov.com

<script
    src="https://www.datadoghq-browser-agent.com/datadog-logs-v7.js"
    type="text/javascript"
    crossorigin>
</script>

{% /callout %}

{% /tab %}

3단계 - Logs Browser SDK 초기화

SDK는 앱 수명 주기에서 가능한 한 일찍 초기화해야 해요. 이렇게 해야 모든 로그가 올바르게 캡처돼요.

초기화 스니펫에서 클라이언트 토큰과 사이트를 설정하세요. 초기화 파라미터 전체 목록을 참고하세요.

{% tab title="NPM" %}

import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.init({
  clientToken: '<CLIENT_TOKEN>',
  // `site` refers to the Datadog site parameter of your organization
  // see https://docs.datadoghq.com/getting_started/site/
  site: '<DATADOG_SITE>',
  forwardErrorsToLogs: true,
  sessionSampleRate: 100,
});

{% /tab %}

{% tab title="CDN async" %}

<script>
  window.DD_LOGS.onReady(function() {
    window.DD_LOGS.init({
      clientToken: '<CLIENT_TOKEN>',
      // `site` refers to the Datadog site parameter of your organization
      // see https://docs.datadoghq.com/getting_started/site/
      site: '<DATADOG_SITE>',
      forwardErrorsToLogs: true,
      sessionSampleRate: 100,
    });
  })
</script>

{% /tab %}

{% tab title="CDN sync" %}

<script>
    window.DD_LOGS && window.DD_LOGS.init({
      clientToken: '<CLIENT_TOKEN>',
      // `site` refers to the Datadog site parameter of your organization
      // see https://docs.datadoghq.com/getting_started/site/
      site: '<DATADOG_SITE>',
      forwardErrorsToLogs: true,
      sessionSampleRate: 100,
    });
</script>

{% /tab %}

GDPR, CCPA 및 유사 규정에 부합하려면 RUM Browser SDK가 초기화 시 추적 동의 값을 제공하도록 하게 할 수 있어요.

Content Security Policy (CSP) 구성

사이트에서 Datadog Content Security Policy(CSP) 통합을 사용한다면 추가 설정 단계에 대해 CSP 문서를 참고하세요.

4단계 - 데이터 시각화

이제 Logs 기본 설정을 완료했으므로 애플리케이션이 브라우저 로그를 수집하고 있으며 실시간으로 문제를 모니터링·디버깅을 시작할 수 있어요.

Log Explorer에서 로그를 시각화하세요.

사용법

사용자 정의 로그

Datadog 브라우저 로그 SDK가 초기화된 후 API로 사용자 정의 로그 항목을 Datadog로 직접 보내세요:

logger.debug | info | warn | error (message: string, messageContext?: Context, error?: Error)

{% tab title="NPM" %}

import { datadogLogs } from '@datadog/browser-logs'

datadogLogs.logger.info('Button clicked', { name: 'buttonName', id: 123 })

{% /tab %}

{% tab title="CDN async" %}

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.logger.info('Button clicked', { name: 'buttonName', id: 123 })
})

참고: 이른 API 호출은 window.DD_LOGS.onReady() 콜백으로 감싸야 해요. 이렇게 해야 SDK가 제대로 로드된 후에만 코드가 실행돼요. {% /tab %}

{% tab title="CDN sync" %}

window.DD_LOGS && window.DD_LOGS.logger.info('Button clicked', { name: 'buttonName', id: 123 })

참고: window.DD_LOGS 확인은 SDK 로딩 실패가 발생할 때 문제를 방지해요. {% /tab %}

결과

NPM, CDN async, CDN sync 사용 시 결과는 동일해요:

{
  "status": "info",
  "session_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "buttonName",
  "id": 123,
  "message": "Button clicked",
  "date": 1234567890000,
  "origin": "logger",
  "http": {
    "useragent": "Mozilla/5.0 ...",
  },
  "view": {
    "url": "https://...",
    "referrer": "https://...",
  },
  "network": {
    "client": {
      "geoip": {...}
      "ip": "xxx.xxx.xxx.xxx"
    }
  }
}

Logs SDK는 기본적으로 다음 정보를 추가해요(RUM SDK가 있으면 더 많은 필드를 추가할 수 있어요):

date
view.url
view.referrer
session_id (세션을 사용할 때만)

Datadog 백엔드는 다음과 같은 필드를 더 추가해요:

http.useragent
network.client.ip

오류 추적

Datadog 브라우저 로그 SDK는 선택적 error 파라미터를 사용해 수동 오류 추적을 지원해요(가용: SDK v4.36.0+). JavaScript Error 인스턴스가 제공되면 SDK는 오류에서 관련 정보(kind, message, stack trace)를 추출해요.

logger.{debug|info|warn|error}(message: string, messageContext?: Context, error?: Error)

{% tab title="NPM" %}

import { datadogLogs } from '@datadog/browser-logs'

try {
  ...
  throw new Error('Wrong behavior')
  ...
} catch (ex) {
  datadogLogs.logger.error('Error occurred', {}, ex)
}

{% /tab %}

{% tab title="CDN async" %}

try {
  ...
  throw new Error('Wrong behavior')
  ...
} catch (ex) {
  window.DD_LOGS.onReady(function () {
    window.DD_LOGS.logger.error('Error occurred', {}, ex)
  })
}

참고: 이른 API 호출은 window.DD_LOGS.onReady() 콜백으로 감싸야 해요. 이렇게 해야 SDK가 제대로 로드된 후에만 코드가 실행돼요. {% /tab %}

{% tab title="CDN sync" %}

try {
  ...
  throw new Error('Wrong behavior')
  ...
} catch (ex) {
    window.DD_LOGS && window.DD_LOGS.logger.error('Error occurred', {}, ex)
}

참고: window.DD_LOGS 확인은 SDK 로딩 실패가 발생할 때 문제를 방지해요. {% /tab %}

결과

NPM, CDN async, CDN sync 사용 시 결과는 동일해요:

{
  "status": "error",
  "session_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "message": "Error occurred",
  "date": 1234567890000,
  "origin": "logger",
  "error" : {
    "message": "Wrong behavior",
    "kind" : "Error",
    "stack" : "Error: Wrong behavior at <anonymous> @ <anonymous>:1:1"
  },
  ...
}

WebAssembly 오류

WebAssembly(WASM) 스택 프레임을 기호화하려면 Browser SDK WASM 플러그인을 설치하세요. 플러그인과 Browser Logs SDK에 같은 버전을 사용하세요:

npm install --save-exact \
  @datadog/browser-logs@<VERSION> \
  @datadog/browser-plugin-wasm@<VERSION>

Browser Logs를 초기화할 때 플러그인을 등록하세요:

import { datadogLogs } from '@datadog/browser-logs';
import { makeWasmPlugin } from '@datadog/browser-plugin-wasm';

datadogLogs.init({
  // ...
  forwardErrorsToLogs: true,
  plugins: [makeWasmPlugin()],
});

WASM 모듈을 로드하기 전에 Browser Logs를 초기화하세요. 플러그인은 브라우저 WebAssembly API로 생성된 모듈을 관찰하고 그 URL과 빌드 ID를 WASM 스택 프레임을 포함한 오류에 추가해요.

처리되지 않은 WASM 오류를 자동으로 전달하려면 forwardErrorsToLogs를 true로 설정하세요. 처리된 WASM 오류를 로깅할 때는 오류 추적에서 보여준 대로 logger.error()의 세 번째 인자로 그 Error 객체를 전달하세요.

그런 다음 오류를 기호화하려면 WebAssembly 심볼을 업로드하세요.

일반 로거 함수

Datadog 브라우저 로그 SDK는 편의를 위해 로거에 단축 함수(.debug, .info, .warn, .error)를 추가해요. status 파라미터를 노출하는 일반 로거 함수도 사용할 수 있어요:

log(message: string, messageContext?: Context, status? = 'debug' | 'info' | 'warn' | 'error', error?: Error)

{% tab title="NPM" %}

import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.logger.log(<MESSAGE>,<JSON_ATTRIBUTES>,<STATUS>,<ERROR>);

{% /tab %}

{% tab title="CDN async" %}

window.DD_LOGS.onReady(function() {
  window.DD_LOGS.logger.log(<MESSAGE>,<JSON_ATTRIBUTES>,<STATUS>,<ERROR>);
})

참고: 이른 API 호출은 window.DD_LOGS.onReady() 콜백으로 감싸야 해요. 이렇게 해야 SDK가 제대로 로드된 후에만 코드가 실행돼요. {% /tab %}

{% tab title="CDN sync" %}

window.DD_LOGS && window.DD_LOGS.logger.log(<MESSAGE>,<JSON_ATTRIBUTES>,<STATUS>,<ERROR>);

참고: window.DD_LOGS 확인은 SDK 로딩 실패가 발생할 때 문제를 방지해요. {% /tab %}

플레이스홀더

위 예시의 플레이스홀더는 다음과 같이 설명돼요:

플레이스홀더	설명
`<MESSAGE>`	Datadog가 완전히 인덱싱하는 로그의 메시지.
`<JSON_ATTRIBUTES>`	`<MESSAGE>`에 붙는 모든 속성을 포함하는 유효한 JSON 객체.
`<STATUS>`	로그의 상태. 허용되는 상태 값은 `debug`, `info`, `warn`, `error`.
`<ERROR>`	JavaScript Error 객체의 인스턴스.

고급 사용법

브라우저 로그에서 민감한 데이터 스크러빙

브라우저 로그에 정리해야 할 민감한 정보가 있다면 Browser Log Collector를 초기화할 때 beforeSend 콜백을 사용해 민감한 시퀀스를 스크러빙하도록 Browser SDK를 구성하세요.

beforeSend 콜백 함수는 log 이벤트와 context의 두 인자로 호출될 수 있어요. 이 함수는 Datadog로 보내기 전에 Browser SDK가 수집한 각 로그에 접근할 수 있게 하고, 컨텍스트를 사용해 어떤 로그 속성이든 조정할 수 있게 해요. 컨텍스트에는 이벤트와 관련된 추가 정보가 포함되지만 이벤트에 반드시 포함되지는 않아요. 일반적으로 이 정보를 사용해 이벤트를 강화하거나 버릴 수 있어요.

function beforeSend(log, context)

가능한 context 값은 다음과 같아요:

값	데이터 유형	사용 사례
`isAborted`	Boolean	네트워크 로그 이벤트에서 이 프로퍼티는 실패한 요청이 애플리케이션에 의해 중단됐는지 알려줘요. 그 경우 이벤트가 의도적으로 중단됐을 수 있으므로 보내지 않을 수도 있어요.
`handlingStack`	String	로그 이벤트가 처리된 위치의 스택 트레이스. 로그가 어떤 마이크로프런트엔드에서 보내졌는지 식별하는 데 사용할 수 있어요.

웹 애플리케이션 URL에서 이메일 주소를 정리하려면:

{% tab title="NPM" %}

import { datadogLogs } from '@datadog/browser-logs'

datadogLogs.init({
    ...,
    beforeSend: (log) => {
        // remove email from view url
        log.view.url = log.view.url.replace(/email=[^&]*/, "email=REDACTED")
    },
    ...
});

{% /tab %}

{% tab title="CDN async" %}

window.DD_LOGS.onReady(function() {
    window.DD_LOGS.init({
        ...,
        beforeSend: (log) => {
            // remove email from view url
            log.view.url = log.view.url.replace(/email=[^&]*/, "email=REDACTED")
        },
        ...
    })
})

참고: 이른 API 호출은 window.DD_LOGS.onReady() 콜백으로 감싸야 해요. 이렇게 해야 SDK가 제대로 로드된 후에만 코드가 실행돼요. {% /tab %}

{% tab title="CDN sync" %}

window.DD_LOGS &&
    window.DD_LOGS.init({
        ...,
        beforeSend: (log) => {
            // remove email from view url
            log.view.url = log.view.url.replace(/email=[^&]*/, "email=REDACTED")
        },
        ...
    });

참고: window.DD_LOGS 확인은 SDK 로딩 실패가 발생할 때 문제를 방지해요. {% /tab %}

SDK가 자동으로 수집하며 민감한 데이터를 포함할 수 있는 프로퍼티:

속성	유형	설명
`view.url`	String	활성 웹 페이지의 URL.
`view.referrer`	String	현재 요청된 페이지로의 링크를 따라온 이전 웹 페이지의 URL.
`message`	String	로그의 내용.
`error.stack`	String	오류에 대한 스택 트레이스 또는 보충 정보.
`http.url`	String	HTTP URL.

특정 로그 버리기

beforeSend 콜백 함수를 사용하면 Datadog로 보내기 전에 로그를 버릴 수도 있어요.

네트워크 오류 상태가 404이면 버리려면:

{% tab title="NPM" %}

import { datadogLogs } from '@datadog/browser-logs'

datadogLogs.init({
    ...,
    beforeSend: (log) => {
        // discard 404 network errors
        if (log.http && log.http.status_code === 404) {
          return false
        }
    },
    ...
});

{% /tab %}

{% tab title="CDN async" %}

window.DD_LOGS.onReady(function() {
    window.DD_LOGS.init({
        ...,
        beforeSend: (log) => {
          // discard 404 network errors
          if (log.http && log.http.status_code === 404) {
            return false
          }
        },
        ...
    })
})

참고: 이른 API 호출은 window.DD_LOGS.onReady() 콜백으로 감싸야 해요. 이렇게 해야 SDK가 제대로 로드된 후에만 코드가 실행돼요. {% /tab %}

{% tab title="CDN sync" %}

window.DD_LOGS &&
    window.DD_LOGS.init({
        ...,
        beforeSend: (log) => {
          // discard 404 network errors
          if (log.http && log.http.status_code === 404) {
            return false
          }
        },
        ...
    });

참고: window.DD_LOGS 확인은 SDK 로딩 실패가 발생할 때 문제를 방지해요. {% /tab %}

여러 로거 정의

Datadog 브라우저 로그 SDK는 기본 로거를 포함하지만 다른 로거를 정의할 수도 있어요.

새 로거 만들기

Datadog 브라우저 로그 SDK가 초기화된 후 createLogger API를 사용해 새 로거를 정의하세요:

createLogger (name: string, conf?: {
    level?: 'debug' | 'info' | 'warn' | 'error',
    handler?: 'http' | 'console' | 'silent',
    context?: Context
})

참고: 이 파라미터는 setLevel, setHandler, setContext API로 설정할 수 있어요.

사용자 정의 로거 가져오기

로거를 만든 후 JavaScript 코드의 어느 곳에서든 API로 접근하세요:

getLogger(name: string)

{% tab title="NPM" %} 예를 들어 다른 모든 로거와 함께 정의된 signupLogger가 있다고 가정해요:

import { datadogLogs } from '@datadog/browser-logs'

datadogLogs.createLogger('signupLogger', {
  level: 'info',
  handler: 'http',
  context: { env: 'staging' }
})

그런 다음 코드의 다른 부분에서 다음과 같이 사용할 수 있어요:

import { datadogLogs } from '@datadog/browser-logs'

const signupLogger = datadogLogs.getLogger('signupLogger')
signupLogger.info('Test sign up completed')

{% /tab %}

{% tab title="CDN async" %} 예를 들어 다른 모든 로거와 함께 정의된 signupLogger가 있다고 가정해요:

window.DD_LOGS.onReady(function () {
  const signupLogger = window.DD_LOGS.createLogger('signupLogger', {
    level: 'info',
    handler: 'http',
    context: { env: 'staging' }
  })
})

그런 다음 코드의 다른 부분에서 다음과 같이 사용할 수 있어요:

window.DD_LOGS.onReady(function () {
  const signupLogger = window.DD_LOGS.getLogger('signupLogger')
  signupLogger.info('Test sign up completed')
})

참고: 이른 API 호출은 window.DD_LOGS.onReady() 콜백으로 감싸야 해요. 이렇게 해야 SDK가 제대로 로드된 후에만 코드가 실행돼요. {% /tab %}

{% tab title="CDN sync" %} 예를 들어 다른 모든 로거와 함께 정의된 signupLogger가 있다고 가정해요:

if (window.DD_LOGS) {
  const signupLogger = window.DD_LOGS.createLogger('signupLogger', {
    level: 'info',
    handler: 'http',
    context: { env: 'staging' }
  })
}

그런 다음 코드의 다른 부분에서 다음과 같이 사용할 수 있어요:

if (window.DD_LOGS) {
  const signupLogger = window.DD_LOGS.getLogger('signupLogger')
  signupLogger.info('Test sign up completed')
}

참고: window.DD_LOGS 확인은 SDK 로딩 실패가 발생할 때 문제를 방지해요. {% /tab %}

컨텍스트 재정의

전역 컨텍스트

Datadog 브라우저 로그 SDK가 초기화된 후 다음이 가능해요:

setGlobalContext (context: object) API로 모든 로거의 전체 컨텍스트 설정.
setGlobalContextProperty (key: string, value: any) API로 모든 로거에 컨텍스트 추가.
getGlobalContext () API로 전체 전역 컨텍스트 가져오기.
removeGlobalContextProperty (key: string) API로 컨텍스트 프로퍼티 제거.
clearGlobalContext () API로 기존 컨텍스트 프로퍼티 모두 지우기.

Log Browser SDK v4.17.0은 여러 API의 이름을 갱신했어요:

getLoggerGlobalContext 대신 getGlobalContext
setLoggerGlobalContext 대신 setGlobalContext
addLoggerGlobalContext 대신 setGlobalContextProperty
removeLoggerGlobalContext 대신 removeGlobalContextProperty

{% tab title="NPM" %} NPM의 경우 다음을 사용하세요:

import { datadogLogs } from '@datadog/browser-logs'

datadogLogs.setGlobalContext({ env: 'staging' })

datadogLogs.setGlobalContextProperty('referrer', document.referrer)

datadogLogs.getGlobalContext() // => {env: 'staging', referrer: ...}

datadogLogs.removeGlobalContextProperty('referrer')

datadogLogs.getGlobalContext() // => {env: 'staging'}

datadogLogs.clearGlobalContext()

datadogLogs.getGlobalContext() // => {}

{% /tab %}

{% tab title="CDN async" %} CDN async의 경우 다음을 사용하세요:

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.setGlobalContext({ env: 'staging' })
})

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.setGlobalContextProperty('referrer', document.referrer)
})

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.getGlobalContext() // => {env: 'staging', referrer: ...}
})

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.removeGlobalContextProperty('referrer')
})

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.getGlobalContext() // => {env: 'staging'}
})

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.clearGlobalContext()
})

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.getGlobalContext() // => {}
})

참고: 이른 API 호출은 window.DD_LOGS.onReady() 콜백으로 감싸야 해요. 이렇게 해야 SDK가 제대로 로드된 후에만 코드가 실행돼요. {% /tab %}

{% tab title="CDN sync" %} CDN sync의 경우 다음을 사용하세요:

window.DD_LOGS && window.DD_LOGS.setGlobalContext({ env: 'staging' })

window.DD_LOGS && window.DD_LOGS.setGlobalContextProperty('referrer', document.referrer)

window.DD_LOGS && window.DD_LOGS.getGlobalContext() // => {env: 'staging', referrer: ...}

window.DD_LOGS && window.DD_LOGS.removeGlobalContextProperty('referrer')

window.DD_LOGS && window.DD_LOGS.getGlobalContext() // => {env: 'staging'}

window.DD_LOGS && window.DD_LOGS.clearGlobalContext()

window.DD_LOGS && window.DD_LOGS.getGlobalContext() // => {}

참고: window.DD_LOGS 확인은 SDK 로딩 실패가 발생할 때 문제를 방지해요. {% /tab %}

사용자 컨텍스트

Datadog 로그 SDK는 User를 생성된 로그와 연결하는 편리한 함수를 제공해요.

setUser (newUser: User) API로 모든 로거의 사용자 설정.
setUserProperty (key: string, value: any) API로 모든 로거에 사용자 프로퍼티 추가 또는 수정.
getUser () API로 현재 저장된 사용자 가져오기.
removeUserProperty (key: string) API로 사용자 프로퍼티 제거.
clearUser () API로 기존 사용자 프로퍼티 모두 지우기.

참고: 사용자 컨텍스트는 전역 컨텍스트보다 먼저 적용돼요. 따라서 전역 컨텍스트에 포함된 모든 사용자 프로퍼티는 로그를 생성할 때 사용자 컨텍스트를 재정의해요.

{% tab title="NPM" %} NPM의 경우 다음을 사용하세요:

import { datadogLogs } from '@datadog/browser-logs'

datadogLogs.setUser({ id: '1234', name: 'John Doe', email: '[email protected]' })
datadogLogs.setUserProperty('type', 'customer')
datadogLogs.getUser() // => {id: '1234', name: 'John Doe', email: '[email protected]', type: 'customer'}

datadogLogs.removeUserProperty('type')
datadogLogs.getUser() // => {id: '1234', name: 'John Doe', email: '[email protected]'}

datadogLogs.clearUser()
datadogLogs.getUser() // => {}

{% /tab %}

{% tab title="CDN async" %} CDN async의 경우 다음을 사용하세요:

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.setUser({ id: '1234', name: 'John Doe', email: '[email protected]' })
})

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.setUserProperty('type', 'customer')
})

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.getUser() // => {id: '1234', name: 'John Doe', email: '[email protected]', type: 'customer'}
})

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.removeUserProperty('type')
})

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.getUser() // => {id: '1234', name: 'John Doe', email: '[email protected]'}
})

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.clearUser()
})

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.getUser() // => {}
})

참고: 이른 API 호출은 window.DD_LOGS.onReady() 콜백으로 감싸야 해요. 이렇게 해야 SDK가 제대로 로드된 후에만 코드가 실행돼요. {% /tab %}

{% tab title="CDN sync" %} CDN sync의 경우 다음을 사용하세요:

window.DD_LOGS && window.DD_LOGS.setUser({ id: '1234', name: 'John Doe', email: '[email protected]' })

window.DD_LOGS && window.DD_LOGS.setUserProperty('type', 'customer')

window.DD_LOGS && window.DD_LOGS.getUser() // => {id: '1234', name: 'John Doe', email: '[email protected]', type: 'customer'}

window.DD_LOGS && window.DD_LOGS.removeUserProperty('type')

window.DD_LOGS && window.DD_LOGS.getUser() // => {id: '1234', name: 'John Doe', email: '[email protected]'}

window.DD_LOGS && window.DD_LOGS.clearUser()

window.DD_LOGS && window.DD_LOGS.getUser() // => {}

참고: window.DD_LOGS 확인은 SDK 로딩 실패가 발생할 때 문제를 방지해요. {% /tab %}

계정 컨텍스트

Datadog 로그 SDK는 Account를 생성된 로그와 연결하는 편리한 함수를 제공해요.

setAccount (newAccount: Account) API로 모든 로거의 계정 설정.
setAccountProperty (key: string, value: any) API로 모든 로거에 계정 프로퍼티 추가 또는 수정.
getAccount () API로 현재 저장된 계정 가져오기.
removeAccountProperty (key: string) API로 계정 프로퍼티 제거.
clearAccount () API로 기존 계정 프로퍼티 모두 지우기.

참고: 계정 컨텍스트는 전역 컨텍스트보다 먼저 적용돼요. 따라서 전역 컨텍스트에 포함된 모든 계정 프로퍼티는 로그를 생성할 때 계정 컨텍스트를 재정의해요.

{% tab title="NPM" %}

import { datadogLogs } from '@datadog/browser-logs'

datadogLogs.setAccount({ id: '1234', name: 'My Company Name' })
datadogLogs.setAccountProperty('type', 'premium')
datadogLogs.getAccount() // => {id: '1234', name: 'My Company Name', type: 'premium'}

datadogLogs.removeAccountProperty('type')
datadogLogs.getAccount() // => {id: '1234', name: 'My Company Name'}

datadogLogs.clearAccount()
datadogLogs.getAccount() // => {}

{% /tab %}

{% tab title="CDN async" %}

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.setAccount({ id: '1234', name: 'My Company Name' })
})

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.setAccountProperty('type', 'premium')
})

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.getAccount() // => {id: '1234', name: 'My Company Name', type: 'premium'}
})

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.removeAccountProperty('type')
})

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.getAccount() // => {id: '1234', name: 'My Company Name'}
})

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.clearAccount()
})

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.getAccount() // => {}
})

참고: 이른 API 호출은 window.DD_LOGS.onReady() 콜백으로 감싸야 해요. 이렇게 해야 SDK가 제대로 로드된 후에만 코드가 실행돼요. {% /tab %}

{% tab title="CDN sync" %}

window.DD_LOGS && window.DD_LOGS.setAccount({ id: '1234', name: 'My Company Name' })

window.DD_LOGS && window.DD_LOGS.setAccountProperty('type', 'premium')

window.DD_LOGS && window.DD_LOGS.getAccount() // => {id: '1234', name: 'My Company Name', type: 'premium'}

window.DD_LOGS && window.DD_LOGS.removeAccountProperty('type')

window.DD_LOGS && window.DD_LOGS.getAccount() // => {id: '1234', name: 'My Company Name'}

window.DD_LOGS && window.DD_LOGS.clearAccount()

window.DD_LOGS && window.DD_LOGS.getAccount() // => {}

참고: window.DD_LOGS 확인은 SDK 로딩 실패가 발생할 때 문제를 방지해요. {% /tab %}

컨텍스트 수명 주기

기본적으로 컨텍스트는 현재 페이지 메모리에 저장되므로 다음이 아니에요:

페이지를 완전히 다시 로드한 후 유지되지 않아요.
같은 세션의 서로 다른 탭이나 창 간에 공유되지 않아요.

세션의 모든 이벤트에 추가하려면 모든 페이지에 붙여야 해요.

브라우저 SDK v4.49.0에서 storeContextsAcrossPages 구성 옵션이 도입되면서 컨텍스트를 localStorage에 저장할 수 있게 되어 다음 동작이 가능해요:

완전히 다시 로드한 후에도 컨텍스트가 보존돼요.
같은 출처에서 연 탭 간에 컨텍스트가 동기화돼요.

다만 이 기능에는 몇 가지 제한이 있어요:

localStorage에 저장된 데이터는 사용자 세션보다 오래 살아남으므로 이러한 컨텍스트에 개인 식별 정보(PII)를 설정하는 것은 권장되지 않아요.
이 기능은 trackSessionAcrossSubdomains 옵션과 호환되지 않아요(localStorage 데이터는 같은 출처에서만 공유되므로 login.site.com ≠ app.site.com).
localStorage는 출처당 5 MiB로 제한되므로 애플리케이션별 데이터, Datadog 컨텍스트 및 기타 타사 데이터가 이 제한 내에 있어야 문제가 생기지 않아요.

로거 컨텍스트

로거를 만든 후 다음이 가능해요:

setContext (context: object) API로 로거의 전체 컨텍스트 설정.
setContextProperty (key: string, value: any) API로 로거에 컨텍스트 프로퍼티 설정.

{% tab title="NPM" %}

import { datadogLogs } from '@datadog/browser-logs'

datadogLogs.setContext("{'env': 'staging'}")

datadogLogs.setContextProperty('referrer', document.referrer)

{% /tab %}

{% tab title="CDN async" %}

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.setContext("{'env': 'staging'}")
})

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.setContextProperty('referrer', document.referrer)
})

참고: 이른 API 호출은 window.DD_LOGS.onReady() 콜백으로 감싸야 해요. 이렇게 해야 SDK가 제대로 로드된 후에만 코드가 실행돼요. {% /tab %}

{% tab title="CDN sync" %}

window.DD_LOGS && window.DD_LOGS.setContext("{'env': 'staging'}")

window.DD_LOGS && window.DD_LOGS.setContextProperty('referrer', document.referrer)

참고: window.DD_LOGS 확인은 SDK 로딩 실패가 발생할 때 문제를 방지해요. {% /tab %}

상태별 필터링

Datadog 브라우저 로그 SDK가 초기화된 후 로거의 최소 로그 레벨은 API로 설정돼요:

setLevel (level?: 'debug' | 'info' | 'warn' | 'error')

지정된 레벨과 같거나 높은 상태의 로그만 보내져요.

{% tab title="NPM" %}

import { datadogLogs } from '@datadog/browser-logs'

datadogLogs.logger.setLevel('<LEVEL>')

{% /tab %}

{% tab title="CDN async" %}

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.logger.setLevel('<LEVEL>')
})

참고: 이른 API 호출은 window.DD_LOGS.onReady() 콜백으로 감싸야 해요. 이렇게 해야 SDK가 제대로 로드된 후에만 코드가 실행돼요. {% /tab %}

{% tab title="CDN sync" %}

window.DD_LOGS && window.DD_LOGS.logger.setLevel('<LEVEL>')

참고: window.DD_LOGS 확인은 SDK 로딩 실패가 발생할 때 문제를 방지해요. {% /tab %}

대상을 변경하기

기본적으로 Datadog 브라우저 로그 SDK가 만든 로거는 Datadog로 로그를 보내요. Datadog 브라우저 로그 SDK가 초기화된 후 로거를 다음으로 구성할 수 있어요:

console과 Datadog(http)로 로그를 보내기.
console에만 로그를 보내기.
로그를 전혀 보내지 않기(silent).

setHandler (handler?: 'http' | 'console' | 'silent' | Array<handler>)

{% tab title="NPM" %}

import { datadogLogs } from '@datadog/browser-logs'

datadogLogs.logger.setHandler('<HANDLER>')
datadogLogs.logger.setHandler(['<HANDLER1>', '<HANDLER2>'])

{% /tab %}

{% tab title="CDN async" %}

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.logger.setHandler('<HANDLER>')
  window.DD_LOGS.logger.setHandler(['<HANDLER1>', '<HANDLER2>'])
})

참고: 이른 API 호출은 window.DD_LOGS.onReady() 콜백으로 감싸야 해요. 이렇게 해야 SDK가 제대로 로드된 후에만 코드가 실행돼요. {% /tab %}

{% tab title="CDN sync" %} CDN sync의 경우 다음을 사용하세요:

window.DD_LOGS && window.DD_LOGS.logger.setHandler('<HANDLER>')
window.DD_LOGS && window.DD_LOGS.logger.setHandler(['<HANDLER1>', '<HANDLER2>'])

참고: window.DD_LOGS 확인은 SDK 로딩 실패가 발생할 때 문제를 방지해요. {% /tab %}

사용자 추적 동의

GDPR, CCPA 및 유사 규정에 부합하려면 Logs Browser SDK가 초기화 시 추적 동의 값을 제공하게 할 수 있어요.

trackingConsent 초기화 파라미터는 다음 값 중 하나가 될 수 있어요:

"granted": Logs Browser SDK가 데이터를 수집해 Datadog로 보내요.
"not-granted": Logs Browser SDK가 어떤 데이터도 수집하지 않아요.

Logs Browser SDK 초기화 후 추적 동의 값을 변경하려면 setTrackingConsent() API 호출을 사용하세요. Logs Browser SDK는 새 값에 따라 동작을 바꿔요:

"granted"에서 "not-granted"로 변경하면 Logs 세션이 중지되고 데이터가 더 이상 Datadog로 보내지지 않아요.
"not-granted"에서 "granted"로 변경하면 이전 세션이 활성화되어 있지 않을 때 새 Logs 세션이 만들어지고 데이터 수집이 재개돼요.

이 상태는 탭 간에 동기화되지 않고 탐색 간에도 유지되지 않아요. Logs Browser SDK 초기화 중이거나 setTrackingConsent()을 사용해 사용자 결정을 제공하는 것은 사용자의 책임이에요.

init() 전에 setTrackingConsent()을 사용하면 제공된 값이 초기화 파라미터보다 우선해요.

{% tab title="NPM" %}

import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.init({
    ...,
    trackingConsent: 'not-granted'
});

acceptCookieBannerButton.addEventListener('click', function() {
    datadogLogs.setTrackingConsent('granted');
});

{% /tab %}

{% tab title="CDN async" %}

window.DD_LOGS.onReady(function() {
    window.DD_LOGS.init({
        ...,
        trackingConsent: 'not-granted'
    });
});

acceptCookieBannerButton.addEventListener('click', () => {
    window.DD_LOGS.onReady(function() {
        window.DD_LOGS.setTrackingConsent('granted');
    });
});

{% /tab %}

{% tab title="CDN sync" %}

window.DD_LOGS && window.DD_LOGS.init({
  ...,
  trackingConsent: 'not-granted'
});

acceptCookieBannerButton.addEventListener('click', () => {
    window.DD_LOGS && window.DD_LOGS.setTrackingConsent('granted');
});

{% /tab %}

내부 컨텍스트 접근

Datadog 브라우저 로그 SDK가 초기화된 후 SDK의 내부 컨텍스트에 접근할 수 있어요. 이를 통해 session_id에 접근할 수 있어요.

getInternalContext (startTime?: 'number' | undefined)

선택적으로 startTime 파라미터로 특정 시간의 컨텍스트를 가져올 수 있어요. 파라미터를 생략하면 현재 컨텍스트가 반환돼요.

{% tab title="NPM" %}

import { datadogLogs } from '@datadog/browser-logs'

datadogLogs.getInternalContext() // { session_id: "xxxx-xxxx-xxxx-xxxx" }

{% /tab %}

{% tab title="CDN async" %}

window.DD_LOGS.onReady(function () {
  window.DD_LOGS.getInternalContext() // { session_id: "xxxx-xxxx-xxxx-xxxx" }
})

{% /tab %}

{% tab title="CDN sync" %}

window.DD_LOGS && window.DD_LOGS.getInternalContext() // { session_id: "xxxx-xxxx-xxxx-xxxx" }

{% /tab %}

브라우저 로그 수집

본문

설정

1단계 - 클라이언트 토큰 만들기

2단계 - Logs Browser SDK 설치

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: app.datadoghq.com

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: app.datadoghq.eu

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: ap1.datadoghq.com

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: ap2.datadoghq.com

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: us3.datadoghq.com

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: us5.datadoghq.com

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: uk1.datadoghq.com

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: app.ddog-gov.com, us2.ddog-gov.com

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: app.datadoghq.com

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: app.datadoghq.eu

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: ap1.datadoghq.com

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: ap2.datadoghq.com

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: us3.datadoghq.com

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: us5.datadoghq.com

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: uk1.datadoghq.com

다음 Datadog 사이트 사용자를 위한 중요 참고 사항: app.ddog-gov.com, us2.ddog-gov.com

3단계 - Logs Browser SDK 초기화

추적 동의 구성 (GDPR 준수)

Content Security Policy (CSP) 구성

4단계 - 데이터 시각화

사용법

사용자 정의 로그

결과

오류 추적

결과

WebAssembly 오류

일반 로거 함수

플레이스홀더

고급 사용법

브라우저 로그에서 민감한 데이터 스크러빙

특정 로그 버리기

여러 로거 정의

새 로거 만들기

사용자 정의 로거 가져오기

컨텍스트 재정의

전역 컨텍스트

사용자 컨텍스트

계정 컨텍스트

컨텍스트 수명 주기

로거 컨텍스트

상태별 필터링

대상을 변경하기

사용자 추적 동의

내부 컨텍스트 접근