[번역] Async Hooks (비동기 훅)

N
n-ryu

Back-End2025.12.30

Node.js v25.2.1 Documentation



Async Hooks

안정성: 1 - 실험적(Experimental). 가능하면 이 API에서 다른 API로 마이그레이션하시기 바랍니다. 우리는 createHook, AsyncHook, executionAsyncResource API를 사용하는 것을 권장하지 않습니다. 이들은 사용성 문제, 안전 위험 및 성능에 영향을 미치기 때문입니다. 비동기 컨텍스트 추적(Async context tracking) 사용 사례는 안정적인 AsyncLocalStorage API를 통해 더 잘 처리될 수 있습니다. 만약 AsyncLocalStorage로 해결되는 컨텍스트 추적 요구나 Diagnostics Channel에서 현재 제공하는 진단 데이터 이상의 createHook, AsyncHook, 또는 executionAsyncResource 사용 사례가 있다면, https://github.com/nodejs/node/issues에 사용 사례를 설명하는 이슈를 열어주시기 바랍니다. 그러면 우리는 더 목적에 집중된 API를 만들 수 있습니다.
소스 코드: lib/async_hooks.js
우리는 async_hooks API의 사용을 강력히 권장하지 않습니다. 대부분의 사용 사례를 대체할 수 있는 다른 API는 다음과 같습니다:
node:async_hooks 모듈은 비동기 리소스를 추적하기 위한 API를 제공합니다. 다음과 같이 접근할 수 있습니다:
import async_hooks from 'node:async_hooks';
const async_hooks = require('node:async_hooks');

용어 (Terminology)

비동기 리소스(Asynchronous resource)는 연관된 콜백이 있는 객체를 나타냅니다. 이 콜백은 net.createServer()'connection' 이벤트처럼 여러 번 호출될 수도 있고, fs.open()처럼 단 한 번만 호출될 수도 있습니다. 리소스는 콜백이 호출되기 전에 닫힐 수도 있습니다. AsyncHook은 이러한 서로 다른 사례를 명시적으로 구분하지 않지만, 리소스라는 추상적인 개념으로 표현합니다.
Worker가 사용되는 경우, 각 스레드는 독립적인 async_hooks 인터페이스를 가지며, 각 스레드는 새로운 비동기 ID 세트를 사용합니다.

개요 (Overview)

다음은 공개 API에 대한 간단한 개요입니다.
import async_hooks from 'node:async_hooks';

// 현재 실행 컨텍스트의 ID를 반환합니다.
const eid = async_hooks.executionAsyncId();

// 현재 실행 범위의 콜백을 트리거한 핸들의 ID를 반환합니다.
const tid = async_hooks.triggerAsyncId();

// 새로운 AsyncHook 인스턴스를 생성합니다. 이 콜백들은 모두 선택 사항입니다.
const asyncHook =
async_hooks.createHook({ init, before, after, destroy, promiseResolve });

// 이 AsyncHook 인스턴스의 콜백 호출을 허용합니다. 이는 생성자를 실행한 후
// 암시적으로 수행되는 동작이 아니며, 콜백 실행을 시작하려면 명시적으로 실행해야 합니다.
asyncHook.enable();

// 새로운 비동기 이벤트에 대한 리스닝을 중단합니다.
asyncHook.disable();

//
// 다음은 createHook()에 전달할 수 있는 콜백들입니다.
//

// init()은 객체 생성 중에 호출됩니다. 이 콜백이 실행될 때 리소스 생성이
// 완료되지 않았을 수 있습니다. 따라서 "asyncId"로 참조되는 리소스의
// 모든 필드가 채워지지 않았을 수 있습니다.
function init(asyncId, type, triggerAsyncId, resource) { }

// before()는 리소스의 콜백이 호출되기 직전에 호출됩니다. 핸들(TCPWrap 등)의 경우
// 0~N번 호출될 수 있으며, 요청(FSReqCallback 등)의 경우 정확히 1번 호출됩니다.
function before(asyncId) { }

// after()는 리소스의 콜백이 종료된 직후에 호출됩니다.
function after(asyncId) { }

// destroy()는 리소스가 파괴될 때 호출됩니다.
function destroy(asyncId) { }

// promiseResolve()는 프로미스 리소스에 대해서만 호출되며, Promise 생성자에 전달된
// resolve() 함수가 호출될 때(직접 호출되거나 다른 프로미스 해결 수단을 통해) 호출됩니다.
function promiseResolve(asyncId) { }
const async_hooks = require('node:async_hooks');

// 현재 실행 컨텍스트의 ID를 반환합니다.
const eid = async_hooks.executionAsyncId();

// 현재 실행 범위의 콜백을 트리거한 핸들의 ID를 반환합니다.
const tid = async_hooks.triggerAsyncId();

// 새로운 AsyncHook 인스턴스를 생성합니다. 이 콜백들은 모두 선택 사항입니다.
const asyncHook =
async_hooks.createHook({ init, before, after, destroy, promiseResolve });

// 이 AsyncHook 인스턴스의 콜백 호출을 허용합니다. 이는 생성자를 실행한 후
// 암시적으로 수행되는 동작이 아니며, 콜백 실행을 시작하려면 명시적으로 실행해야 합니다.
asyncHook.enable();

// 새로운 비동기 이벤트에 대한 리스닝을 중단합니다.
asyncHook.disable();

//
// 다음은 createHook()에 전달할 수 있는 콜백들입니다.
//

// init()은 객체 생성 중에 호출됩니다. 이 콜백이 실행될 때 리소스 생성이
// 완료되지 않았을 수 있습니다. 따라서 "asyncId"로 참조되는 리소스의
// 모든 필드가 채워지지 않았을 수 있습니다.
function init(asyncId, type, triggerAsyncId, resource) { }

// before()는 리소스의 콜백이 호출되기 직전에 호출됩니다. 핸들(TCPWrap 등)의 경우
// 0~N번 호출될 수 있으며, 요청(FSReqCallback 등)의 경우 정확히 1번 호출됩니다.
function before(asyncId) { }

// after()는 리소스의 콜백이 종료된 직후에 호출됩니다.
function after(asyncId) { }

// destroy()는 리소스가 파괴될 때 호출됩니다.
function destroy(asyncId) { }

// promiseResolve()는 프로미스 리소스에 대해서만 호출되며, Promise 생성자에 전달된
// resolve() 함수가 호출될 때(직접 호출되거나 다른 프로미스 해결 수단을 통해) 호출됩니다.
function promiseResolve(asyncId) { }

async_hooks.createHook(callbacks)

추가된 버전: v8.1.0
  • callbacks<Object> 등록할 훅 콜백(Hook Callbacks) init <Function> init 콜백. before <Function> before 콜백. after <Function> after 콜백. destroy <Function> destroy 콜백. promiseResolve <Function> promiseResolve 콜백. 반환값: <AsyncHook> 훅을 비활성화하거나 활성화하는 데 사용되는 인스턴스
0
2

댓글

?

아직 댓글이 없습니다.

첫 번째 댓글을 작성해보세요!

n-ryu님의 다른 글

더보기

유사한 내용의 글