진단 채널

[히스토리]

버전	변경 사항
v19.2.0, v18.13.0	diagnostics_channel이 이제 Stable입니다.
v15.1.0, v14.17.0	추가됨: v15.1.0, v14.17.0

[Stable: 2 - Stable]

Stable: 2 Stability: 2 - Stable

소스 코드: lib/diagnostics_channel.js

node:diagnostics_channel 모듈은 진단 목적으로 임의의 메시지 데이터를 보고하는 명명된 채널을 생성하는 API를 제공합니다.

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

CJS

const diagnostics_channel = require('node:diagnostics_channel')

진단 메시지를 보고하려는 모듈 작성자는 메시지를 통해 보고할 하나 이상의 최상위 채널을 생성하는 것이 좋습니다. 채널은 런타임에 획득할 수도 있지만 추가적인 오버헤드로 인해 권장하지 않습니다. 채널은 편의를 위해 내보낼 수 있지만 이름만 알고 있으면 어디서든 획득할 수 있습니다.

모듈이 다른 사람이 사용할 진단 데이터를 생성하려는 경우 사용되는 명명된 채널과 메시지 데이터의 형태에 대한 설명서를 포함하는 것이 좋습니다. 채널 이름에는 일반적으로 다른 모듈의 데이터와의 충돌을 방지하기 위해 모듈 이름이 포함되어야 합니다.

공개 API

개요

다음은 공개 API의 간략한 개요입니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

// 재사용 가능한 채널 객체 가져오기
const channel = diagnostics_channel.channel('my-channel')

function onMessage(message, name) {
  // 수신된 데이터
}

// 채널 구독
diagnostics_channel.subscribe('my-channel', onMessage)

// 채널에 활성 구독자가 있는지 확인
if (channel.hasSubscribers) {
  // 채널에 데이터 게시
  channel.publish({
    some: 'data',
  })
}

// 채널 구독 취소
diagnostics_channel.unsubscribe('my-channel', onMessage)

CJS

const diagnostics_channel = require('node:diagnostics_channel')

// 재사용 가능한 채널 객체 가져오기
const channel = diagnostics_channel.channel('my-channel')

function onMessage(message, name) {
  // 수신된 데이터
}

// 채널 구독
diagnostics_channel.subscribe('my-channel', onMessage)

// 채널에 활성 구독자가 있는지 확인
if (channel.hasSubscribers) {
  // 채널에 데이터 게시
  channel.publish({
    some: 'data',
  })
}

// 채널 구독 취소
diagnostics_channel.unsubscribe('my-channel', onMessage)

diagnostics_channel.hasSubscribers(name)

추가됨: v15.1.0, v14.17.0

• name <string> | <symbol> 채널 이름
• 반환값: <boolean> 활성 구독자가 있는 경우

지정된 채널에 활성 구독자가 있는지 확인합니다. 이는 전송하려는 메시지를 준비하는 데 많은 비용이 들 수 있는 경우에 유용합니다.

이 API는 선택 사항이지만 성능에 매우 민감한 코드에서 메시지를 게시하려고 할 때 유용합니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // 구독자가 있습니다. 메시지를 준비하고 게시합니다.
}

CJS

const diagnostics_channel = require('node:diagnostics_channel')

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // 구독자가 있습니다. 메시지를 준비하고 게시합니다.
}

diagnostics_channel.channel(name)

추가됨: v15.1.0, v14.17.0

• name <string> | <symbol> 채널 이름
• 반환값: <Channel> 지정된 채널 객체

이는 지정된 채널에 게시하려는 모든 사용자를 위한 기본 진입점입니다. 게시 시 오버헤드를 최대한 줄이도록 최적화된 채널 객체를 생성합니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channel = diagnostics_channel.channel('my-channel')

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channel = diagnostics_channel.channel('my-channel')

diagnostics_channel.subscribe(name, onMessage)

추가됨: v18.7.0, v16.17.0

• name <string> | <symbol> 채널 이름
• onMessage <Function> 채널 메시지를 수신할 핸들러
  • message <any> 메시지 데이터
  • name <string> | <symbol> 채널 이름

이 채널을 구독할 메시지 핸들러를 등록합니다. 이 메시지 핸들러는 메시지가 채널에 게시될 때마다 동기적으로 실행됩니다. 메시지 핸들러에서 발생하는 모든 오류는 'uncaughtException'을 트리거합니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // 수신된 데이터
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // 수신된 데이터
})

diagnostics_channel.unsubscribe(name, onMessage)

추가됨: v18.7.0, v16.17.0

• name <string> | <symbol> 채널 이름
• onMessage <Function> 제거할 이전 구독 처리기
• 반환값: <boolean> 처리기가 발견되면 true, 그렇지 않으면 false.

diagnostics_channel.subscribe(name, onMessage)를 사용하여 이 채널에 이전에 등록된 메시지 처리기를 제거합니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

function onMessage(message, name) {
  // 수신된 데이터
}

diagnostics_channel.subscribe('my-channel', onMessage)

diagnostics_channel.unsubscribe('my-channel', onMessage)

CJS

const diagnostics_channel = require('node:diagnostics_channel')

function onMessage(message, name) {
  // 수신된 데이터
}

diagnostics_channel.subscribe('my-channel', onMessage)

diagnostics_channel.unsubscribe('my-channel', onMessage)

diagnostics_channel.tracingChannel(nameOrChannels)

추가됨: v19.9.0, v18.19.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - 실험적

• nameOrChannels <string> | <TracingChannel> 채널 이름 또는 모든 TracingChannel 채널을 포함하는 객체
• 반환값: <TracingChannel> 추적할 채널 컬렉션

주어진 TracingChannel 채널에 대한 TracingChannel 래퍼를 생성합니다. 이름이 지정되면 tracing:${name}:${eventType} 형식으로 해당 추적 채널이 생성됩니다. 여기서 eventType는 TracingChannel 채널의 유형에 해당합니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channelsByName = diagnostics_channel.tracingChannel('my-channel')

// 또는...

const channelsByCollection = diagnostics_channel.tracingChannel({
  start: diagnostics_channel.channel('tracing:my-channel:start'),
  end: diagnostics_channel.channel('tracing:my-channel:end'),
  asyncStart: diagnostics_channel.channel('tracing:my-channel:asyncStart'),
  asyncEnd: diagnostics_channel.channel('tracing:my-channel:asyncEnd'),
  error: diagnostics_channel.channel('tracing:my-channel:error'),
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channelsByName = diagnostics_channel.tracingChannel('my-channel')

// 또는...

const channelsByCollection = diagnostics_channel.tracingChannel({
  start: diagnostics_channel.channel('tracing:my-channel:start'),
  end: diagnostics_channel.channel('tracing:my-channel:end'),
  asyncStart: diagnostics_channel.channel('tracing:my-channel:asyncStart'),
  asyncEnd: diagnostics_channel.channel('tracing:my-channel:asyncEnd'),
  error: diagnostics_channel.channel('tracing:my-channel:error'),
})

클래스: Channel

추가됨: v15.1.0, v14.17.0

Channel 클래스는 데이터 파이프라인 내의 개별 명명된 채널을 나타냅니다. 구독자를 추적하고 구독자가 있는 경우 메시지를 게시하는 데 사용됩니다. 게시 시 채널 조회를 피하기 위해 별도의 객체로 존재하므로 매우 빠른 게시 속도를 가능하게 하고 최소한의 비용으로 많은 사용을 허용합니다. 채널은 diagnostics_channel.channel(name)으로 생성되며, new Channel(name)으로 채널을 직접 생성하는 것은 지원되지 않습니다.

channel.hasSubscribers

추가됨: v15.1.0, v14.17.0

• 반환값: <boolean> 활성 구독자가 있는 경우

이 채널에 활성 구독자가 있는지 확인합니다. 보낼 메시지를 준비하는 데 비용이 많이 들 수 있는 경우 유용합니다.

이 API는 선택 사항이지만 성능에 매우 민감한 코드에서 메시지를 게시하려고 할 때 유용합니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channel = diagnostics_channel.channel('my-channel')

if (channel.hasSubscribers) {
  // 구독자가 있습니다. 메시지를 준비하고 게시합니다.
}

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channel = diagnostics_channel.channel('my-channel')

if (channel.hasSubscribers) {
  // 구독자가 있습니다. 메시지를 준비하고 게시합니다.
}

channel.publish(message)

추가됨: v15.1.0, v14.17.0

• message <any> 채널 구독자에게 보낼 메시지

채널 구독자에게 메시지를 게시합니다. 이렇게 하면 메시지 처리기가 동기적으로 트리거되므로 동일한 컨텍스트 내에서 실행됩니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channel = diagnostics_channel.channel('my-channel')

channel.publish({
  some: 'message',
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channel = diagnostics_channel.channel('my-channel')

channel.publish({
  some: 'message',
})

channel.subscribe(onMessage)

추가된 버전: v15.1.0, v14.17.0

더 이상 사용되지 않는 버전: v18.7.0, v16.17.0

[안정성: 0 - 더 이상 사용되지 않음]

안정성: 0 안정성: 0 - 더 이상 사용되지 않음: diagnostics_channel.subscribe(name, onMessage) 사용

• onMessage <Function> 채널 메시지를 수신할 핸들러
  • message <any> 메시지 데이터
  • name <string> | <symbol> 채널 이름

이 채널을 구독할 메시지 핸들러를 등록합니다. 이 메시지 핸들러는 채널에 메시지가 게시될 때마다 동기적으로 실행됩니다. 메시지 핸들러에서 발생하는 모든 오류는 'uncaughtException'을 트리거합니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channel = diagnostics_channel.channel('my-channel')

channel.subscribe((message, name) => {
  // 수신된 데이터
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channel = diagnostics_channel.channel('my-channel')

channel.subscribe((message, name) => {
  // 수신된 데이터
})

channel.unsubscribe(onMessage)

[이력]

버전	변경 사항
v18.7.0, v16.17.0	더 이상 사용되지 않는 버전: v18.7.0, v16.17.0
v17.1.0, v16.14.0, v14.19.0	반환 값 추가. 구독자가 없는 채널에 추가
v15.1.0, v14.17.0	추가된 버전: v15.1.0, v14.17.0

[안정성: 0 - 더 이상 사용되지 않음]

안정성: 0 안정성: 0 - 더 이상 사용되지 않음: diagnostics_channel.unsubscribe(name, onMessage) 사용

• onMessage <Function> 제거할 이전 구독 핸들러
• 반환 값: <boolean> 핸들러가 발견되면 true, 그렇지 않으면 false.

channel.subscribe(onMessage)을 사용하여 이 채널에 이전에 등록된 메시지 핸들러를 제거합니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channel = diagnostics_channel.channel('my-channel')

function onMessage(message, name) {
  // 수신된 데이터
}

channel.subscribe(onMessage)

channel.unsubscribe(onMessage)

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channel = diagnostics_channel.channel('my-channel')

function onMessage(message, name) {
  // 수신된 데이터
}

channel.subscribe(onMessage)

channel.unsubscribe(onMessage)

channel.bindStore(store[, transform])

추가됨: v19.9.0, v18.19.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Experimental

• store <AsyncLocalStorage> 컨텍스트 데이터를 바인딩할 저장소
• transform <Function> 저장소 컨텍스트를 설정하기 전에 컨텍스트 데이터를 변환하는 함수

channel.runStores(context, ...)가 호출되면, 주어진 컨텍스트 데이터는 채널에 바인딩된 모든 저장소에 적용됩니다. 저장소가 이미 바인딩된 경우 이전 transform 함수는 새 함수로 대체됩니다. 주어진 컨텍스트 데이터를 직접 컨텍스트로 설정하려면 transform 함수를 생략할 수 있습니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'
import { AsyncLocalStorage } from 'node:async_hooks'

const store = new AsyncLocalStorage()

const channel = diagnostics_channel.channel('my-channel')

channel.bindStore(store, data => {
  return { data }
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')
const { AsyncLocalStorage } = require('node:async_hooks')

const store = new AsyncLocalStorage()

const channel = diagnostics_channel.channel('my-channel')

channel.bindStore(store, data => {
  return { data }
})

channel.unbindStore(store)

추가됨: v19.9.0, v18.19.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Experimental

• store <AsyncLocalStorage> 채널에서 언바인딩할 저장소
• 반환값: <boolean> 저장소가 발견되면 true, 그렇지 않으면 false를 반환합니다.

channel.bindStore(store)를 사용하여 이전에 이 채널에 등록된 메시지 핸들러를 제거합니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'
import { AsyncLocalStorage } from 'node:async_hooks'

const store = new AsyncLocalStorage()

const channel = diagnostics_channel.channel('my-channel')

channel.bindStore(store)
channel.unbindStore(store)

CJS

const diagnostics_channel = require('node:diagnostics_channel')
const { AsyncLocalStorage } = require('node:async_hooks')

const store = new AsyncLocalStorage()

const channel = diagnostics_channel.channel('my-channel')

channel.bindStore(store)
channel.unbindStore(store)

channel.runStores(context, fn[, thisArg[, ...args]])

추가됨: v19.9.0, v18.19.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Experimental

• context <any> 구독자에게 보내고 저장소에 바인딩할 메시지
• fn <Function> 입력된 저장소 컨텍스트 내에서 실행할 핸들러
• thisArg <any> 함수 호출에 사용할 수신기
• ...args <any> 함수에 전달할 선택적 인수

주어진 함수의 지속 시간 동안 채널에 바인딩된 모든 AsyncLocalStorage 인스턴스에 주어진 데이터를 적용한 다음, 해당 데이터의 범위 내에서 채널에 게시합니다.

channel.bindStore(store)에 변환 함수가 제공된 경우, 저장소에 대한 컨텍스트 값이 되기 전에 메시지 데이터를 변환하는 데 사용됩니다. 컨텍스트 연결이 필요한 경우 변환 함수 내에서 이전 저장소 컨텍스트에 액세스할 수 있습니다.

저장소에 적용된 컨텍스트는 주어진 함수 중에 시작된 실행에서 계속되는 모든 비동기 코드에서 액세스할 수 있지만, 컨텍스트 손실이 발생할 수 있는 몇 가지 상황이 있습니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'
import { AsyncLocalStorage } from 'node:async_hooks'

const store = new AsyncLocalStorage()

const channel = diagnostics_channel.channel('my-channel')

channel.bindStore(store, message => {
  const parent = store.getStore()
  return new Span(message, parent)
})
channel.runStores({ some: 'message' }, () => {
  store.getStore() // Span({ some: 'message' })
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')
const { AsyncLocalStorage } = require('node:async_hooks')

const store = new AsyncLocalStorage()

const channel = diagnostics_channel.channel('my-channel')

channel.bindStore(store, message => {
  const parent = store.getStore()
  return new Span(message, parent)
})
channel.runStores({ some: 'message' }, () => {
  store.getStore() // Span({ some: 'message' })
})

클래스: TracingChannel

추가됨: v19.9.0, v18.19.0

[안정성: 1 - 실험적]

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

TracingChannel 클래스는 단일 추적 가능한 작업을 함께 표현하는 TracingChannel 채널의 컬렉션입니다. 애플리케이션 흐름 추적을 위한 이벤트 생성 프로세스를 공식화하고 단순화하는 데 사용됩니다. diagnostics_channel.tracingChannel()은 TracingChannel을 생성하는 데 사용됩니다. Channel과 마찬가지로 동적으로 생성하는 대신 파일의 최상위 레벨에서 단일 TracingChannel을 생성하고 재사용하는 것이 좋습니다.

tracingChannel.subscribe(subscribers)

추가됨: v19.9.0, v18.19.0

[안정성: 1 - 실험적]

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

• subscribers <객체> TracingChannel 채널 구독자 집합
  • start <함수> start 이벤트 구독자
  • end <함수> end 이벤트 구독자
  • asyncStart <함수> asyncStart 이벤트 구독자
  • asyncEnd <함수> asyncEnd 이벤트 구독자
  • error <함수> error 이벤트 구독자

각 채널에 대해 개별적으로 channel.subscribe(onMessage)를 호출하는 것과 동일하게, 함수 컬렉션을 해당 채널에 구독하는 데 도움이 됩니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.subscribe({
  start(message) {
    // 시작 메시지 처리
  },
  end(message) {
    // 종료 메시지 처리
  },
  asyncStart(message) {
    // asyncStart 메시지 처리
  },
  asyncEnd(message) {
    // asyncEnd 메시지 처리
  },
  error(message) {
    // 오류 메시지 처리
  },
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.subscribe({
  start(message) {
    // 시작 메시지 처리
  },
  end(message) {
    // 종료 메시지 처리
  },
  asyncStart(message) {
    // asyncStart 메시지 처리
  },
  asyncEnd(message) {
    // asyncEnd 메시지 처리
  },
  error(message) {
    // 오류 메시지 처리
  },
})

tracingChannel.unsubscribe(subscribers)

추가됨: v19.9.0, v18.19.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Experimental

• subscribers <Object> TracingChannel 채널 구독자 집합

  • start <Function> start 이벤트 구독자
  • end <Function> end 이벤트 구독자
  • asyncStart <Function> asyncStart 이벤트 구독자
  • asyncEnd <Function> asyncEnd 이벤트 구독자
  • error <Function> error 이벤트 구독자

• 반환값: <boolean> 모든 핸들러의 구독이 성공적으로 해제된 경우 true, 그렇지 않으면 false를 반환합니다.

대응하는 채널에서 함수 집합의 구독을 해제하는 데 사용하는 도우미 함수입니다. 각 채널에서 개별적으로 channel.unsubscribe(onMessage)를 호출하는 것과 같습니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.unsubscribe({
  start(message) {
    // start 메시지 처리
  },
  end(message) {
    // end 메시지 처리
  },
  asyncStart(message) {
    // asyncStart 메시지 처리
  },
  asyncEnd(message) {
    // asyncEnd 메시지 처리
  },
  error(message) {
    // error 메시지 처리
  },
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.unsubscribe({
  start(message) {
    // start 메시지 처리
  },
  end(message) {
    // end 메시지 처리
  },
  asyncStart(message) {
    // asyncStart 메시지 처리
  },
  asyncEnd(message) {
    // asyncEnd 메시지 처리
  },
  error(message) {
    // error 메시지 처리
  },
})

tracingChannel.traceSync(fn[, context[, thisArg[, ...args]]])

추가됨: v19.9.0, v18.19.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Experimental

• fn <Function> 추적을 감싸는 함수
• context <Object> 이벤트를 상호 연관시키는 데 사용되는 공유 객체
• thisArg <any> 함수 호출에 사용될 수신기
• ...args <any> 함수에 전달할 선택적 인수
• 반환값: <any> 지정된 함수의 반환값

동기 함수 호출을 추적합니다. 이는 실행 주변에 항상 start 이벤트와 end 이벤트를 생성하며, 지정된 함수가 오류를 throw하는 경우 error 이벤트를 생성할 수 있습니다. 이는 start 채널에서 channel.runStores(context, ...)를 사용하여 지정된 함수를 실행하며, 이를 통해 모든 이벤트에 바인딩된 저장소가 이 추적 컨텍스트와 일치하도록 설정되어야 함을 보장합니다.

올바른 추적 그래프만 형성되도록 하기 위해, 이벤트는 추적을 시작하기 전에 구독자가 있는 경우에만 게시됩니다. 추적이 시작된 후에 추가된 구독은 해당 추적의 이후 이벤트를 수신하지 않으며, 오직 이후 추적만 볼 수 있습니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.traceSync(
  () => {
    // 작업 수행
  },
  {
    some: 'thing',
  }
)

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.traceSync(
  () => {
    // 작업 수행
  },
  {
    some: 'thing',
  }
)

tracingChannel.tracePromise(fn[, context[, thisArg[, ...args]]])

추가됨: v19.9.0, v18.19.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Experimental

• fn <Function> 추적을 감싸는 Promise 반환 함수
• context <Object> 추적 이벤트를 상호 연관시키는 공유 객체
• thisArg <any> 함수 호출에 사용할 수신기
• ...args <any> 함수에 전달할 선택적 인수
• 반환값: <Promise> 지정된 함수에서 반환된 Promise에서 체이닝됨

Promise 반환 함수 호출을 추적합니다. 이는 항상 함수 실행의 동기 부분 주위에 start 이벤트와 end 이벤트를 생성하고, Promise 연속이 도달하면 asyncStart 이벤트와 asyncEnd 이벤트를 생성합니다. 지정된 함수가 오류를 throw하거나 반환된 Promise가 거부되면 error 이벤트를 생성할 수도 있습니다. 이는 모든 이벤트에 바인딩된 저장소가 이 추적 컨텍스트와 일치하도록 설정되도록 보장하는 start 채널에서 channel.runStores(context, ...)를 사용하여 지정된 함수를 실행합니다.

올바른 추적 그래프만 형성되도록 하기 위해, 이벤트는 추적 시작 전에 구독자가 있는 경우에만 게시됩니다. 추적이 시작된 후에 추가된 구독은 해당 추적의 향후 이벤트를 수신하지 않으며, 향후 추적만 볼 수 있습니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.tracePromise(
  async () => {
    // 작업 수행
  },
  {
    some: 'thing',
  }
)

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.tracePromise(
  async () => {
    // 작업 수행
  },
  {
    some: 'thing',
  }
)

tracingChannel.traceCallback(fn[, position[, context[, thisArg[, ...args]]]])

추가됨: v19.9.0, v18.19.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Experimental

• fn <Function> 추적을 래핑하는 데 사용하는 함수를 이용한 콜백
• position <number> 예상되는 콜백의 0부터 시작하는 인덱스 위치 ( undefined 가 전달되면 마지막 인수로 기본 설정)
• context <Object> 추적 이벤트를 상호 연관시키는 공유 객체 ( undefined 가 전달되면 {} 로 기본 설정)
• thisArg <any> 함수 호출에 사용할 수신기
• ...args <any> 함수에 전달할 인수 (콜백을 포함해야 함)
• 반환 값: <any> 지정된 함수의 반환 값

콜백을 수신하는 함수 호출을 추적합니다. 콜백은 일반적으로 사용되는 오류를 첫 번째 인수로 사용하는 규칙을 따라야 합니다. 이렇게 하면 함수 실행의 동기 부분을 항상 감싸는 start 이벤트와 end 이벤트가 생성되고, 콜백 실행을 감싸는 asyncStart 이벤트와 asyncEnd 이벤트가 생성됩니다. 지정된 함수가 예외를 throw하거나 콜백에 전달된 첫 번째 인수가 설정된 경우 error 이벤트가 생성될 수도 있습니다. 이는 start 채널에서 channel.runStores(context, ...)를 사용하여 지정된 함수를 실행하며, 이를 통해 모든 이벤트에 바인딩된 저장소가 이 추적 컨텍스트와 일치하도록 설정되어야 합니다.

올바른 추적 그래프만 형성되도록 하기 위해, 이벤트는 추적을 시작하기 전에 구독자가 있을 경우에만 게시됩니다. 추적이 시작된 후에 추가된 구독은 해당 추적의 향후 이벤트를 수신하지 않고, 향후 추적만 볼 수 있습니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.traceCallback(
  (arg1, callback) => {
    // 작업 수행
    callback(null, 'result')
  },
  1,
  {
    some: 'thing',
  },
  thisArg,
  arg1,
  callback
)

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.traceCallback(
  (arg1, callback) => {
    // 작업 수행
    callback(null, 'result')
  },
  1,
  {
    some: 'thing',
  },
  thisArg,
  arg1,
  callback
)

콜백은 channel.runStores(context, ...)를 사용하여 실행되며, 이를 통해 특정 경우에 컨텍스트 손실 복구가 가능합니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'
import { AsyncLocalStorage } from 'node:async_hooks'

const channels = diagnostics_channel.tracingChannel('my-channel')
const myStore = new AsyncLocalStorage()

// start 채널은 초기 저장소 데이터를 설정하고
// 해당 저장소 데이터 값을 추적 컨텍스트 객체에 저장합니다.
channels.start.bindStore(myStore, data => {
  const span = new Span(data)
  data.span = span
  return span
})

// 그러면 asyncStart는 이전에 저장된 데이터에서 복원할 수 있습니다.
channels.asyncStart.bindStore(myStore, data => {
  return data.span
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')
const { AsyncLocalStorage } = require('node:async_hooks')

const channels = diagnostics_channel.tracingChannel('my-channel')
const myStore = new AsyncLocalStorage()

// start 채널은 초기 저장소 데이터를 설정하고
// 해당 저장소 데이터 값을 추적 컨텍스트 객체에 저장합니다.
channels.start.bindStore(myStore, data => {
  const span = new Span(data)
  data.span = span
  return span
})

// 그러면 asyncStart는 이전에 저장된 데이터에서 복원할 수 있습니다.
channels.asyncStart.bindStore(myStore, data => {
  return data.span
})

tracingChannel.hasSubscribers

추가됨: v22.0.0, v20.13.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Experimental

• 반환값: <boolean> 개별 채널 중 하나라도 구독자가 있으면 true, 없으면 false를 반환합니다.

TracingChannel 인스턴스에서 사용할 수 있는 이 도우미 메서드는 TracingChannel 채널 중 어느 하나라도 구독자가 있는지 확인합니다. 하나라도 구독자가 하나 이상 있으면 true를, 그렇지 않으면 false를 반환합니다.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channels = diagnostics_channel.tracingChannel('my-channel')

if (channels.hasSubscribers) {
  // 작업 수행
}

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channels = diagnostics_channel.tracingChannel('my-channel')

if (channels.hasSubscribers) {
  // 작업 수행
}

TracingChannel 채널

TracingChannel은 단일 추적 가능한 작업의 실행 수명 주기의 특정 지점을 나타내는 여러 diagnostics_channel의 집합입니다. 동작은 start, end, asyncStart, asyncEnd 및 error로 구성된 5개의 diagnostics_channel로 분할됩니다. 단일 추적 가능한 작업은 모든 이벤트 간에 동일한 이벤트 객체를 공유하며, 이는 weakmap을 통한 상관 관계 관리에 유용할 수 있습니다.

이러한 이벤트 객체는 작업이 "완료"될 때 result 또는 error 값으로 확장됩니다. 동기 작업의 경우 result는 반환 값이고 error는 함수에서 throw된 모든 것입니다. 콜백 기반 비동기 함수의 경우 result는 콜백의 두 번째 인수이고 error는 end 이벤트에서 볼 수 있는 throw된 오류 또는 asyncStart 또는 asyncEnd 이벤트 중 하나의 첫 번째 콜백 인수입니다.

올바른 추적 그래프만 형성되도록 하려면 구독자가 추적을 시작하기 전에 존재하는 경우에만 이벤트를 게시해야 합니다. 추적이 시작된 후 추가된 구독은 해당 추적의 향후 이벤트를 수신하지 않으며, 향후 추적만 볼 수 있습니다.

Tracing 채널은 다음과 같은 명명 패턴을 따라야 합니다.

• tracing:module.class.method:start 또는 tracing:module.function:start
• tracing:module.class.method:end 또는 tracing:module.function:end
• tracing:module.class.method:asyncStart 또는 tracing:module.function:asyncStart
• tracing:module.class.method:asyncEnd 또는 tracing:module.function:asyncEnd
• tracing:module.class.method:error 또는 tracing:module.function:error

start(event)

• Name: tracing:${name}:start

start 이벤트는 함수가 호출되는 시점을 나타냅니다. 이 시점에서 이벤트 데이터에는 함수 인수 또는 함수 실행의 시작 시점에서 사용 가능한 기타 모든 정보가 포함될 수 있습니다.

end(event)

• Name: tracing:${name}:end

end 이벤트는 함수 호출이 값을 반환하는 시점을 나타냅니다. 비동기 함수의 경우, 함수 자체가 내부적으로 return 문을 실행하는 시점이 아니라 반환된 Promise가 완료되는 시점입니다. 추적된 함수가 동기 함수인 경우 이 시점에서 result 필드는 함수의 반환값으로 설정됩니다. 또는, 발생한 오류를 나타내는 error 필드가 있을 수 있습니다.

추적 가능한 작업에서 여러 오류가 발생할 수 있으므로 오류를 추적하려면 error 이벤트를 구체적으로 수신하는 것이 좋습니다. 예를 들어, 실패하는 비동기 작업은 작업의 동기 부분이 오류를 throw하기 전에 내부적으로 시작될 수 있습니다.

asyncStart(event)

• Name: tracing:${name}:asyncStart

asyncStart 이벤트는 추적 가능한 함수의 콜백 또는 연속이 도달하는 시점을 나타냅니다. 이 시점에서 콜백 인수 또는 작업의 "결과"를 나타내는 기타 정보를 사용할 수 있습니다.

콜백 기반 함수의 경우, 콜백의 첫 번째 인수는 undefined 또는 null이 아닌 경우 error 필드에 할당되고, 두 번째 인수는 result 필드에 할당됩니다.

Promise의 경우, resolve 경로의 인수는 result에 할당되고, reject 경로의 인수는 error에 할당됩니다.

추적 가능한 작업에서 여러 오류가 발생할 수 있으므로 오류를 추적하려면 error 이벤트를 구체적으로 수신하는 것이 좋습니다. 예를 들어, 실패하는 비동기 작업은 작업의 동기 부분이 오류를 throw하기 전에 내부적으로 시작될 수 있습니다.

asyncEnd(event)

• Name: tracing:${name}:asyncEnd

asyncEnd 이벤트는 비동기 함수의 콜백이 반환되는 시점을 나타냅니다. asyncStart 이벤트 이후에 이벤트 데이터가 변경될 가능성은 낮지만, 콜백이 완료되는 시점을 확인하는 데 유용할 수 있습니다.

error(event)

• 이름: tracing:${name}:error

error 이벤트는 추적 가능한 함수에서 동기적으로 또는 비동기적으로 생성된 모든 오류를 나타냅니다. 추적된 함수의 동기 부분에서 오류가 발생하면 오류가 이벤트의 error 필드에 할당되고 error 이벤트가 트리거됩니다. 콜백이나 Promise 거부를 통해 비동기적으로 오류가 수신되면 이벤트의 error 필드에 할당되고 error 이벤트가 트리거됩니다.

단일 추적 가능한 함수 호출에서 여러 번 오류가 발생할 수 있으므로 이 이벤트를 사용할 때 이 점을 고려해야 합니다. 예를 들어, 내부적으로 실패하는 다른 비동기 작업이 트리거되고 함수의 동기 부분에서 오류가 발생하면 동기 오류에 대한 하나의 error 이벤트와 비동기 오류에 대한 하나의 error 이벤트가 두 개 방출됩니다.

기본 제공 채널

[안정적: 1 - 실험적]

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

diagnostics_channel API는 이제 안정적인 것으로 간주되지만, 현재 사용 가능한 기본 제공 채널은 그렇지 않습니다. 각 채널은 개별적으로 안정적인 것으로 선언되어야 합니다.

HTTP

http.client.request.created

• request <http.ClientRequest>

클라이언트가 요청 객체를 생성할 때 방출됩니다. http.client.request.start와 달리 이 이벤트는 요청이 전송되기 전에 방출됩니다.

http.client.request.start

• request <http.ClientRequest>

클라이언트가 요청을 시작할 때 방출됩니다.

http.client.request.error

• request <http.ClientRequest>
• error <Error>

클라이언트 요청 중에 오류가 발생하면 방출됩니다.

http.client.response.finish

• request <http.ClientRequest>
• response <http.IncomingMessage>

클라이언트가 응답을 수신하면 방출됩니다.

http.server.request.start

• request <http.IncomingMessage>
• response <http.ServerResponse>
• socket <net.Socket>
• server <http.Server>

서버가 요청을 수신하면 방출됩니다.

http.server.response.created

• request <http.IncomingMessage>
• response <http.ServerResponse>

서버가 응답을 생성할 때 방출됩니다. 이 이벤트는 응답이 전송되기 전에 방출됩니다.

http.server.response.finish

• request <http.IncomingMessage>
• response <http.ServerResponse>
• socket <net.Socket>
• server <http.Server>

서버가 응답을 전송할 때 방출됩니다.

모듈

module.require.start

• event <Object> 다음 속성을 포함하는 객체
  • id - require()에 전달된 인수. 모듈 이름.
  • parentFilename - require(id)를 호출하려고 시도한 모듈의 이름.

require()가 실행될 때 발생합니다. start 이벤트를 참조하십시오.

module.require.end

• event <Object> 다음 속성을 포함하는 객체
  • id - require()에 전달된 인수. 모듈 이름.
  • parentFilename - require(id)를 호출하려고 시도한 모듈의 이름.

require() 호출이 반환될 때 발생합니다. end 이벤트를 참조하십시오.

module.require.error

• event <Object> 다음 속성을 포함하는 객체

  • id - require()에 전달된 인수. 모듈 이름.
  • parentFilename - require(id)를 호출하려고 시도한 모듈의 이름.

• error <Error>

require()에서 오류가 발생할 때 발생합니다. error 이벤트를 참조하십시오.

module.import.asyncStart

• event <Object> 다음 속성을 포함하는 객체
  • id - import()에 전달된 인수. 모듈 이름.
  • parentURL - import(id)를 호출하려고 시도한 모듈의 URL 객체.

import()가 호출될 때 발생합니다. asyncStart 이벤트를 참조하십시오.

module.import.asyncEnd

• event <Object> 다음 속성을 포함하는 객체
  • id - import()에 전달된 인수. 모듈 이름.
  • parentURL - import(id)를 호출하려고 시도한 모듈의 URL 객체.

import()가 완료될 때 발생합니다. asyncEnd 이벤트를 참조하십시오.

module.import.error

• event <Object> 다음 속성을 포함하는 객체

  • id - import()에 전달된 인수. 모듈 이름.
  • parentURL - import(id)를 호출하려고 시도한 모듈의 URL 객체.

• error <Error>

import()에서 오류가 발생할 때 발생합니다. error 이벤트를 참조하십시오.

NET

net.client.socket

• socket <net.Socket>

새로운 TCP 또는 파이프 클라이언트 소켓이 생성될 때 발생합니다.

net.server.socket

• socket <net.Socket>

새로운 TCP 또는 파이프 연결이 수신될 때 발생합니다.

tracing:net.server.listen:asyncStart

• server <net.Server>
• options <Object>

포트 또는 파이프가 실제로 설정되기 전에 net.Server.listen()이 호출될 때 발생합니다.

tracing:net.server.listen:asyncEnd

• server <net.Server>

net.Server.listen()이 완료되고 서버가 연결을 수락할 준비가 되었을 때 발생합니다.

tracing:net.server.listen:error

• server <net.Server>
• error <Error>

net.Server.listen()이 오류를 반환할 때 발생합니다.

UDP

udp.socket

• socket <dgram.Socket>

새로운 UDP 소켓이 생성될 때 발생합니다.

프로세스

추가됨: v16.18.0

child_process

• process <ChildProcess>

새로운 프로세스가 생성될 때 발생합니다.

워커 스레드

추가됨: v16.18.0

worker_threads

• worker Worker

새로운 스레드가 생성될 때 발생합니다.