Node.js 애플리케이션은 비동기 호출이 얽히면서 요청별 로깅, 트랜잭션 ID 전달, 분산 추적이 끊어지기 쉽다. AsyncLocalStorage는 비동기 호출 체인 전체에서 상태를 공유할 수 있도록 async_hooks 기반 스코프를 제공한다. 이 글에서는 AsyncLocalStorage의 동작 원리, 설치·설정 방법, 프레임워크별 통합 패턴, 운영 중 주의사항을 살펴본다.
AsyncLocalStorage는 Node.js가 제공하는 비동기 컨텍스트 저장소이다. 이벤트 루프에서 태스크가 생성될 때 내부적으로 컨텍스트 맵을 복제해 전달하므로, 콜백·Promise·async/await 체인 전반에 동일한 값을 참조할 수 있다.
await, 타이머, I/O, Worker Threads에서도 동일한 컨텍스트를 유지한다. AsyncLocalStorage는 Node.js 14에서 실험적으로 도입되었으며 16 LTS 이후 안정화되었다. 최소 Node.js 18 이상을 권장한다.
node -v컨텍스트 연동을 위해 구조화 로깅 라이브러리를 함께 사용하는 것이 좋다. 예시는 pino를 사용한다.
npm install pino컨텍스트 저장소와 로거를 초기화하는 유틸리티 파일을 만든다.
\n// context.js\nimport { AsyncLocalStorage } from \"node:async_hooks\"\nimport pino from \"pino\"\n\nexport const asyncLocalStorage = new AsyncLocalStorage()\nexport const logger = pino()\n\nexport function withRequestContext(req, res, next) {\n const trace = {\n requestId: req.headers[\"x-request-id\"] ?? crypto.randomUUID(),\n userAgent: req.headers[\"user-agent\"],\n startedAt: Date.now(),\n }\n\n asyncLocalStorage.run(trace, () => next())\n}\n\nexport function getContext() {\n return asyncLocalStorage.getStore()\n}// 나쁜 예시: 응답 로거에서 req 객체를 직접 참조해 비동기 체인 밖에서 undefined가 된다.\napp.use((req, res, next) => {\n req.context = { requestId: crypto.randomUUID() }\n next()\n})\n\nsetImmediate(() => {\n console.log(req.context.requestId) // TypeError 발생\n})\n\n// 좋은 예시: AsyncLocalStorage로 컨텍스트를 전파해 비동기 스케줄링 이후에도 안전하다.\nimport { asyncLocalStorage } from \"./context.js\"\n\napp.use((req, res, next) => {\n asyncLocalStorage.run({ requestId: crypto.randomUUID() }, () => next())\n})\n\nsetImmediate(() => {\n const store = asyncLocalStorage.getStore()\n console.log(store.requestId) // 정상 출력\n})나쁜 예시는 req 객체를 비동기 경계 밖으로 전달하면서 컨텍스트가 끊어져 TypeError가 발생한다. 좋은 예시에서는 AsyncLocalStorage가 태스크별 스토어를 복제해 setImmediate 이후에도 동일한 requestId를 조회할 수 있다.
// app.js\nimport express from \"express\"\nimport { withRequestContext, getContext, logger } from \"./context.js\"\n\nconst app = express()\napp.use(withRequestContext)\n\napp.get(\"/payments/:id\", async (req, res) => {\n const { requestId } = getContext()\n logger.info({ requestId }, \"fetching payment\")\n\n const payment = await fetchPayment(req.params.id)\n res.json({ requestId, payment })\n})// plugins/request-context.js\nimport fp from \"fastify-plugin\"\nimport { asyncLocalStorage } from \"../context.js\"\n\nexport default fp(async (fastify) => {\n fastify.addHook(\"onRequest\", (request, reply, done) => {\n asyncLocalStorage.run(\n { requestId: request.id, route: request.routerPath },\n done,\n )\n })\n\n fastify.decorateRequest(\"requestContext\", null)\n fastify.addHook(\"preHandler\", (request, reply, done) => {\n request.requestContext = asyncLocalStorage.getStore()\n done()\n })\n})Fastify에서 위 플러그인을 등록하면 서비스 레이어나 외부 연동 모듈에서 asyncLocalStorage.getStore()를 호출해 동일한 트레이스를 참고할 수 있다.
requestId를 OpenTelemetry traceId와 연결해 백엔드·프론트엔드 로그를 엮는다. asyncLocalStorage.run을 호출해 누락을 방지한다. getStore() 반환 객체를 직접 수정하면 다른 모듈에 영향을 준다. → 깊은 복사를 사용하거나 전용 setter를 제공한다. AsyncResource를 활용한다. asyncLocalStorage.disable()을 호출해 초기화한다.Q1. 기존 CLS/continuation-local-storage 라이브러리와 무엇이 다른가?
\nA: AsyncLocalStorage는 Node.js 코어가 지원해 외부 패키지보다 안정성과 성능이 높다. 기존 라이브러리는 domain API에 의존하고 이벤트 루프 개선 이후 호환성 문제가 발생한다.
Q2. 비동기 컨텍스트 내에서 비밀번호 같은 민감정보를 저장해도 안전한가?
\nA: 메모리 내에서만 유지되지만, 프로세스 덤프나 로그에 노출될 수 있으므로 민감정보는 암호화 토큰이나 참조 ID 형태로 저장하는 것이 원칙이다.
Q3. 요청 한 건이 여러 서비스로 분기되면 컨텍스트가 유지되는가?
\nA: 프로세스 내부 비동기 호출은 유지되지만, 외부 서비스 호출 후에는 컨텍스트가 전파되지 않는다. HTTP 헤더나 메시지 메타데이터로 트레이스를 전달해야 한다.
Q4. 고성능 환경에서 어떤 로거를 쓰는 것이 좋은가?
\nA: pino, winston@3, bunyan이 대표적이며, AsyncLocalStorage와 함께 쓸 때는 비동기 쓰기 구조와 구조화 JSON 출력이 가능한 로거를 선택한다.
Q5. TypeScript 프로젝트에서는 어떻게 타입을 정의해야 하는가?
\nA: 컨텍스트 스키마에 대한 인터페이스를 선언하고 ReturnType<typeof asyncLocalStorage.getStore>에 제네릭을 적용한다. 모듈 보강을 사용하면 express.Request에 context 필드를 안전하게 추가할 수 있다.