검사기

[Stable: 2 - Stable]

node:inspector 모듈은 V8 검사기와 상호 작용하기 위한 API를 제공합니다.

다음을 사용하여 액세스할 수 있습니다.

ESMCJS

import * as inspector from 'node:inspector/promises'

const inspector = require('node:inspector/promises')

또는

ESMCJS

import * as inspector from 'node:inspector'

const inspector = require('node:inspector')

Promises API

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Experimental

추가됨: v19.0.0

클래스: `inspector.Session`

상속: <EventEmitter>

inspector.Session은 V8 검사기 백엔드로 메시지를 디스패치하고 메시지 응답 및 알림을 수신하는 데 사용됩니다.

`new inspector.Session()`

추가됨: v8.0.0

inspector.Session 클래스의 새 인스턴스를 만듭니다. 검사기 세션은 메시지를 검사기 백엔드로 디스패치하기 전에 session.connect()를 통해 연결되어야 합니다.

Session을 사용할 때, Runtime.DiscardConsoleEntries 명령을 수동으로 실행하지 않는 한 콘솔 API에서 출력되는 객체는 해제되지 않습니다.

이벤트: `'inspectorNotification'`

추가됨: v8.0.0

<Object> 알림 메시지 객체

V8 검사기에서 알림이 수신될 때 발생합니다.

session.on('inspectorNotification', message => console.log(message.method))
// Debugger.paused
// Debugger.resumed

특정 메서드를 가진 알림만 구독하는 것도 가능합니다.

이벤트: `<inspector-protocol-method>`; {#event-<inspector-protocol-method>;}

추가됨: v8.0.0

<Object> 알림 메시지 객체

<inspector-protocol-method> 값으로 메서드 필드가 설정된 검사기 알림을 수신할 때 발생합니다.

다음 코드 스니펫은 'Debugger.paused' 이벤트에 리스너를 설치하고, 프로그램 실행이 중단될 때마다(예: 중단점을 통해) 프로그램 중단 사유를 출력합니다.

session.on('Debugger.paused', ({ params }) => {
  console.log(params.hitBreakpoints)
})
// [ '/the/file/that/has/the/breakpoint.js:11:0' ]

`session.connect()`

추가됨: v8.0.0

세션을 검사기 백엔드에 연결합니다.

`session.connectToMainThread()`

추가됨: v12.11.0

세션을 메인 스레드 검사기 백엔드에 연결합니다. 이 API가 Worker 스레드에서 호출되지 않은 경우 예외가 발생합니다.

`session.disconnect()`

추가됨: v8.0.0

세션을 즉시 닫습니다. 모든 보류 중인 메시지 콜백은 오류와 함께 호출됩니다. 메시지를 다시 보내려면 session.connect()를 호출해야 합니다. 다시 연결된 세션은 활성화된 에이전트 또는 구성된 중단점과 같은 모든 검사기 상태를 잃습니다.

`session.post(method[, params])`

추가됨: v19.0.0

method <string>
params <Object>
반환값: <Promise>

검사기 백엔드에 메시지를 게시합니다.

import { Session } from 'node:inspector/promises'
try {
  const session = new Session()
  session.connect()
  const result = await session.post('Runtime.evaluate', { expression: '2 + 2' })
  console.log(result)
} catch (error) {
  console.error(error)
}
// 출력: { result: { type: 'number', value: 4, description: '4' } }

최신 버전의 V8 검사기 프로토콜은 Chrome DevTools Protocol Viewer에 게시되어 있습니다.

Node.js 검사기는 V8에서 선언한 모든 Chrome DevTools Protocol 도메인을 지원합니다. Chrome DevTools Protocol 도메인은 애플리케이션 상태를 검사하고 런타임 이벤트를 수신하는 데 사용되는 런타임 에이전트 중 하나와 상호 작용하기 위한 인터페이스를 제공합니다.

예시 사용법

디버거 외에도 DevTools 프로토콜을 통해 다양한 V8 프로파일러를 사용할 수 있습니다.

CPU 프로파일러

다음은 CPU 프로파일러 사용 방법을 보여주는 예시입니다.

import { Session } from 'node:inspector/promises'
import fs from 'node:fs'
const session = new Session()
session.connect()

await session.post('Profiler.enable')
await session.post('Profiler.start')
// 여기에 측정 대상 비즈니스 로직 호출...

// 얼마 후...
const { profile } = await session.post('Profiler.stop')

// 프로필을 디스크에 쓰거나, 업로드 등을 합니다.
fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile))

힙 프로파일러

다음은 힙 프로파일러 사용 방법을 보여주는 예시입니다.

import { Session } from 'node:inspector/promises'
import fs from 'node:fs'
const session = new Session()

const fd = fs.openSync('profile.heapsnapshot', 'w')

session.connect()

session.on('HeapProfiler.addHeapSnapshotChunk', m => {
  fs.writeSync(fd, m.params.chunk)
})

const result = await session.post('HeapProfiler.takeHeapSnapshot', null)
console.log('HeapProfiler.takeHeapSnapshot done:', result)
session.disconnect()
fs.closeSync(fd)

콜백 API

클래스: `inspector.Session`

상속: <EventEmitter>

inspector.Session은 V8 검사기 백엔드로 메시지를 전송하고 메시지 응답 및 알림을 수신하는 데 사용됩니다.

`new inspector.Session()`

추가됨: v8.0.0

inspector.Session 클래스의 새 인스턴스를 만듭니다. 검사기 세션은 메시지를 검사기 백엔드로 전송하기 전에 session.connect()를 통해 연결해야 합니다.

Session을 사용할 때, 콘솔 API에서 출력되는 객체는 Runtime.DiscardConsoleEntries 명령을 수동으로 실행하지 않는 한 해제되지 않습니다.

이벤트: `'inspectorNotification'`

추가됨: v8.0.0

<Object> 알림 메시지 객체

V8 Inspector에서 알림이 수신될 때 발생합니다.

session.on('inspectorNotification', message => console.log(message.method))
// Debugger.paused
// Debugger.resumed

특정 메서드를 사용하는 알림만 구독하는 것도 가능합니다.

이벤트: `<inspector-protocol-method>`; {#event-<inspector-protocol-method>;_1}

추가됨: v8.0.0

<Object> 알림 메시지 객체

메서드 필드가 \<inspector-protocol-method\> 값으로 설정된 Inspector 알림이 수신될 때 발생합니다.

session.on('Debugger.paused', ({ params }) => {
  console.log(params.hitBreakpoints)
})
// [ '/the/file/that/has/the/breakpoint.js:11:0' ]

`session.connect()`

추가됨: v8.0.0

세션을 Inspector 백엔드에 연결합니다.

`session.connectToMainThread()`

추가됨: v12.11.0

세션을 메인 스레드 Inspector 백엔드에 연결합니다. 이 API가 Worker 스레드에서 호출되지 않은 경우 예외가 throw됩니다.

`session.disconnect()`

추가됨: v8.0.0

세션을 즉시 닫습니다. 모든 보류 중인 메시지 콜백이 오류와 함께 호출됩니다. 메시지를 다시 보내려면 session.connect()를 호출해야 합니다. 다시 연결된 세션은 활성화된 에이전트나 구성된 중단점과 같은 모든 Inspector 상태를 잃게 됩니다.

`session.post(method[, params][, callback])`

[히스토리]

버전	변경 사항
v18.0.0	`callback` 인수에 잘못된 콜백을 전달하면 이제 `ERR_INVALID_CALLBACK` 대신 `ERR_INVALID_ARG_TYPE`를 throw합니다.
v8.0.0	추가됨: v8.0.0

method <string>
params <Object>
callback <Function>

메시지를 Inspector 백엔드에 게시합니다. 응답을 수신하면 callback이 알림을 받습니다. callback은 두 개의 선택적 인수(오류 및 메시지 관련 결과)를 허용하는 함수입니다.

session.post('Runtime.evaluate', { expression: '2 + 2' }, (error, { result }) => console.log(result))
// 출력: { type: 'number', value: 4, description: '4' }

V8 Inspector 프로토콜의 최신 버전은 Chrome DevTools Protocol Viewer에 게시됩니다.

Node.js Inspector는 V8에서 선언된 모든 Chrome DevTools Protocol 도메인을 지원합니다. Chrome DevTools Protocol 도메인은 애플리케이션 상태를 검사하고 런타임 이벤트를 수신하는 데 사용되는 런타임 에이전트 중 하나와 상호 작용하기 위한 인터페이스를 제공합니다.

HeapProfiler.takeHeapSnapshot 또는 HeapProfiler.stopTrackingHeapObjects 명령을 V8에 보낼 때 reportProgress를 true로 설정할 수 없습니다.

예시 사용법

디버거 외에도 DevTools 프로토콜을 통해 다양한 V8 프로파일러를 사용할 수 있습니다.

CPU 프로파일러

다음은 CPU 프로파일러를 사용하는 방법을 보여주는 예시입니다.

const inspector = require('node:inspector')
const fs = require('node:fs')
const session = new inspector.Session()
session.connect()

session.post('Profiler.enable', () => {
  session.post('Profiler.start', () => {
    // 여기에 측정 대상 비즈니스 로직 호출...

    // 얼마 후...
    session.post('Profiler.stop', (err, { profile }) => {
      // 프로필을 디스크에 쓰거나, 업로드 등을 합니다.
      if (!err) {
        fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile))
      }
    })
  })
})

힙 프로파일러

다음은 힙 프로파일러를 사용하는 방법을 보여주는 예시입니다.

const inspector = require('node:inspector')
const fs = require('node:fs')
const session = new inspector.Session()

const fd = fs.openSync('profile.heapsnapshot', 'w')

session.connect()

session.on('HeapProfiler.addHeapSnapshotChunk', m => {
  fs.writeSync(fd, m.params.chunk)
})

session.post('HeapProfiler.takeHeapSnapshot', null, (err, r) => {
  console.log('HeapProfiler.takeHeapSnapshot done:', err, r)
  session.disconnect()
  fs.closeSync(fd)
})

일반 객체

`inspector.close()`

[히스토리]

버전	변경 사항
v18.10.0	API가 워커 스레드에서 노출됩니다.
v9.0.0	추가됨: v9.0.0

모든 남은 연결을 닫으려고 시도하고, 모든 연결이 닫힐 때까지 이벤트 루프를 차단합니다. 모든 연결이 닫히면 검사기를 비활성화합니다.

`inspector.console`

<객체> 원격 검사기 콘솔로 메시지를 보내는 객체입니다.

require('node:inspector').console.log('a message')

검사기 콘솔은 Node.js 콘솔과 API 호환성이 없습니다.

`inspector.open([port[, host[, wait]]])`

[이력]

버전	변경 사항
v20.6.0	`inspector.open()`은 이제 `Disposable` 객체를 반환합니다.

port <number> 인스펙터 연결을 수신할 포트입니다. 선택 사항입니다. 기본값: CLI에서 지정된 값입니다.
host <string> 인스펙터 연결을 수신할 호스트입니다. 선택 사항입니다. 기본값: CLI에서 지정된 값입니다.
wait <boolean> 클라이언트가 연결될 때까지 차단합니다. 선택 사항입니다. 기본값: false.
반환값: <Disposable> inspector.close()를 호출하는 Disposable입니다.

호스트 및 포트에서 인스펙터를 활성화합니다. node --inspect=[[host:]port]와 동일하지만 Node.js가 시작된 후 프로그램 방식으로 수행할 수 있습니다.

wait가 true이면 클라이언트가 검사 포트에 연결되고 흐름 제어가 디버거 클라이언트로 전달될 때까지 차단합니다.

host 매개변수 사용에 대한 보안 경고를 참조하십시오.

`inspector.url()`

반환값: <string> | <undefined>

활성 인스펙터의 URL을 반환하거나, 인스펙터가 없으면 undefined를 반환합니다.

bash

$ node --inspect -p 'inspector.url()'
Debugger listening on ws://127.0.0.1:9229/166e272e-7a30-4d09-97ce-f1c012b43c34
For help, see: https://nodejs.org/en/docs/inspector
ws://127.0.0.1:9229/166e272e-7a30-4d09-97ce-f1c012b43c34

$ node --inspect=localhost:3000 -p 'inspector.url()'
Debugger listening on ws://localhost:3000/51cf8d0e-3c36-4c59-8efd-54519839e56a
For help, see: https://nodejs.org/en/docs/inspector
ws://localhost:3000/51cf8d0e-3c36-4c59-8efd-54519839e56a

$ node -p 'inspector.url()'
undefined

`inspector.waitForDebugger()`

추가됨: v12.7.0

클라이언트(기존 또는 나중에 연결됨)가 Runtime.runIfWaitingForDebugger 명령을 보낼 때까지 차단합니다.

활성화된 검사기가 없으면 예외가 발생합니다.

DevTools와의 통합

node:inspector 모듈은 Chrome DevTools Protocol을 지원하는 Devtools와 통합하기 위한 API를 제공합니다. 실행 중인 Node.js 인스턴스에 연결된 DevTools 프런트엔드는 인스턴스에서 방출되는 프로토콜 이벤트를 캡처하고 디버깅을 용이하게 하도록 이에 따라 표시할 수 있습니다. 다음 메서드는 연결된 모든 프런트엔드에 프로토콜 이벤트를 브로드캐스트합니다. 메서드에 전달되는 params는 프로토콜에 따라 선택적일 수 있습니다.

// `Network.requestWillBeSent` 이벤트가 발생합니다.
inspector.Network.requestWillBeSent({
  requestId: 'request-id-1',
  timestamp: Date.now() / 1000,
  wallTime: Date.now(),
  request: {
    url: 'https://nodejs.org/en',
    method: 'GET',
  },
})

`inspector.Network.requestWillBeSent([params])`

추가됨: v22.6.0, v20.18.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Experimental

params <Object>

이 기능은 --experimental-network-inspection 플래그를 활성화한 경우에만 사용할 수 있습니다.

연결된 프런트엔드에 Network.requestWillBeSent 이벤트를 브로드캐스트합니다. 이 이벤트는 애플리케이션이 HTTP 요청을 보내려고 함을 나타냅니다.

`inspector.Network.responseReceived([params])`

추가됨: v22.6.0, v20.18.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Experimental

params <Object>

이 기능은 --experimental-network-inspection 플래그를 활성화한 경우에만 사용할 수 있습니다.

연결된 프런트엔드에 Network.responseReceived 이벤트를 브로드캐스트합니다. 이 이벤트는 HTTP 응답을 사용할 수 있음을 나타냅니다.

`inspector.Network.loadingFinished([params])`

추가됨: v22.6.0, v20.18.0

[안정성: 1 - 실험적]

안정성: 1 안정성: 1 - 실험적

params <Object>

이 기능은 --experimental-network-inspection 플래그가 활성화된 경우에만 사용할 수 있습니다.

연결된 프런트엔드에 Network.loadingFinished 이벤트를 브로드캐스트합니다. 이 이벤트는 HTTP 요청이 로딩을 완료했음을 나타냅니다.

`inspector.Network.loadingFailed([params])`

추가됨: v22.7.0, v20.18.0

[안정성: 1 - 실험적]

안정성: 1 안정성: 1 - 실험적

params <Object>

이 기능은 --experimental-network-inspection 플래그가 활성화된 경우에만 사용할 수 있습니다.

연결된 프런트엔드에 Network.loadingFailed 이벤트를 브로드캐스트합니다. 이 이벤트는 HTTP 요청이 로딩에 실패했음을 나타냅니다.

중단점 지원

Chrome DevTools Protocol Debugger 도메인을 사용하면 inspector.Session이 프로그램에 연결되어 코드를 단계별로 실행하기 위한 중단점을 설정할 수 있습니다.

하지만 session.connect()를 통해 연결된 동일 스레드 inspector.Session으로 중단점을 설정하는 것은 피해야 합니다. 연결되어 일시 중지되는 프로그램이 디버거 자체이기 때문입니다. 대신 session.connectToMainThread()를 사용하여 메인 스레드에 연결하고 작업자 스레드에서 중단점을 설정하거나, WebSocket 연결을 통해 Debugger 프로그램과 연결하십시오.

검사기 ​

Promises API ​

클래스: inspector.Session ​

new inspector.Session() ​

이벤트: 'inspectorNotification' ​

이벤트: <inspector-protocol-method>; {#event-<inspector-protocol-method>;} ​

session.connect() ​

session.connectToMainThread() ​

session.disconnect() ​

session.post(method[, params]) ​

예시 사용법 ​

CPU 프로파일러 ​

힙 프로파일러 ​

콜백 API ​

클래스: inspector.Session ​

new inspector.Session() ​

이벤트: 'inspectorNotification' ​

이벤트: &lt;inspector-protocol-method&gt;; {#event-<inspector-protocol-method>;_1} ​

session.connect() ​

session.connectToMainThread() ​

session.disconnect() ​

session.post(method[, params][, callback]) ​

예시 사용법 ​

CPU 프로파일러 ​

힙 프로파일러 ​

일반 객체 ​

inspector.close() ​

inspector.console ​

inspector.open([port[, host[, wait]]]) ​

inspector.url() ​

inspector.waitForDebugger() ​

DevTools와의 통합 ​

inspector.Network.requestWillBeSent([params]) ​

inspector.Network.responseReceived([params]) ​

inspector.Network.loadingFinished([params]) ​

inspector.Network.loadingFailed([params]) ​

중단점 지원 ​

검사기

Promises API

클래스: `inspector.Session`

`new inspector.Session()`

이벤트: `'inspectorNotification'`

이벤트: `<inspector-protocol-method>`; {#event-<inspector-protocol-method>;}

`session.connect()`

`session.connectToMainThread()`

`session.disconnect()`

`session.post(method[, params])`

예시 사용법

CPU 프로파일러

힙 프로파일러

콜백 API

클래스: `inspector.Session`

`new inspector.Session()`

이벤트: `'inspectorNotification'`

이벤트: `<inspector-protocol-method>`; {#event-<inspector-protocol-method>;_1}

`session.connect()`

`session.connectToMainThread()`

`session.disconnect()`

`session.post(method[, params][, callback])`

예시 사용법

CPU 프로파일러

힙 프로파일러

일반 객체

`inspector.close()`

`inspector.console`

`inspector.open([port[, host[, wait]]])`

`inspector.url()`

`inspector.waitForDebugger()`

DevTools와의 통합

`inspector.Network.requestWillBeSent([params])`

`inspector.Network.responseReceived([params])`

`inspector.Network.loadingFinished([params])`

`inspector.Network.loadingFailed([params])`

중단점 지원