TypeScript 지원은 주장하기 쉽습니다. npm 패키지를 게시하고, 몇 가지 타입 선언(type declarations)을 추가하면 트레이싱 제품은 통합 목록에 “JavaScript 및 TypeScript”를 올릴 수 있습니다.

네이티브 지원(Native support)은 더 높은 기준을 요구합니다.

TypeScript 생태계의 AI 애플리케이션은 동시 실행되는 Node.js 서버, 서버리스 함수(serverless functions), 에지 런타임(edge runtimes), 백그라운드 워커(background workers), 테스트 러너(test runners), 그리고 스트리밍 웹 프레임워크 내에서 실행됩니다. 이들은 프로미스 체인(promise chains), 콜백(callbacks), 도구 어댑터(tool adapters), 비동기 반복자(async iterators), 그리고 패키지 경계를 가로지릅니다. 유용한 트레이싱 도구는 타입을 깨뜨리거나 단절된 스팬(spans)을 생성하지 않고 이러한 실행 모델에 부합해야 합니다.

따라서 질문은 단지 **“이 도구에 TypeScript SDK가 있는가?”**가 아닙니다. 질문은 **“이 도구가 TypeScript 에이전트가 실제로 실행되는 방식을 보존하는가?”**가 되어야 합니다.

런타임은 제품의 일부입니다

작은 에이전트를 예로 들어보겠습니다:

async function supportAgent(question: string) {
  const category = await classifyQuestion(question);
  const documents = await retrieveDocuments(question, category);
...

소스 코드는 순차적으로 보이지만, 프로덕션 서버는 수백 개의 이러한 함수를 동시에 실행할 수 있습니다. 평면적인 이벤트 스트림(flat event stream)만으로는 어떤 검색(retrieval)이나 모델 호출이 어떤 요청에 속하는지 알 수 없습니다.

request A: classify -> retrieve -> generate
request B: classify -> retrieve -> generate

트레이서(tracer)에는 요청 수준의 트레이스 ID(trace ID)와 각 중첩된 작업에 대한 부모 스팬(parent span)이 필요합니다. 더 중요한 것은, 이러한 식별자들이 모든 비동기 핸드오프(asynchronous handoff) 이후에도 계속 사용 가능해야 한다는 점입니다.

동시성 환경에서 비동기 컨텍스트(Async Context)가 정확해야 합니다

Node.js에서 AsyncLocalStorage는 요청 범위 컨텍스트(request-scoped context)를 위한 일반적인 기반입니다. 이는 일반적인 프로미스 체인과 많은 비동기 리소스를 통해 상태를 전파하며, 이는 현재의 트레이스 ID를 모듈 수준의 변수에 저장하는 것보다 훨씬 안전합니다.

import { AsyncLocalStorage } from 'node:async_hooks';

type TraceContext = {
...

AsyncLocalStorage를 올바르게 사용한다면 await 자체만으로는 컨텍스트 손실(context loss)이 발생하지 않습니다. 문제는 보통 계측(instrumentation)이 전역 가변 상태(global mutable state)에 의존하거나, 활성 컨텍스트(active context) 외부에서 작업을 등록하거나, 지원되지 않는 런타임 경계(runtime boundary)를 넘나들거나, 자체적인 스케줄링을 관리하는 라이브러리와 통합될 때 발생합니다.

TypeScript 트레이싱 라이브러리는 최소한 다음과 같은 케이스들을 테스트해야 합니다:

• 동시에 실행되는 여러 에이전트 실행 (Multiple agent runs)
• 중첩된 도구(tools) 및 모델 호출
• 타이머(timers), 이벤트 에미터(event emitters), 그리고 큐에 쌓인 콜백(queued callbacks)
• 분리된 백그라운드 작업 (Detached background work)
• 새로운 비동기 분기를 시작하는 재시도 (Retries)
• 병렬 워커(parallel workers)에서 실행되는 테스트

수용 기준(acceptance criterion)은 간단합니다: 모든 스팬(span)은 정확히 하나의 트레이스(trace)에 속해야 하며, 예상된 부모(parent)를 가져야 합니다.

스트리밍은 스팬의 생명주기를 변화시킨다

많은 AI 라우트(routes)는 생성이 완료되기 전에 스트림(stream)을 반환합니다. 프레임워크 관점에서는 HTTP 핸들러가 완료되었을지라도, 토큰(tokens), 도구 호출(tool calls), 그리고 사용량 데이터(usage data)는 여전히 전송 중(in flight)일 수 있습니다.

따라서 모델 스팬(model span)은 단순히 라우트가 Response를 반환했다고 해서 종료되어서는 안 됩니다. 스트림이 완료되거나, 실패하거나, 또는 취소될 때 종료되어야 합니다.

type StreamHooks<T> = {
  onStart(): Promise<void> | void;
  onChunk(chunk: T): Promise<void> | void;
...

실제 통합 과정에서는 에러와 취소가 거의 동시에 발생할 때 스팬이 이중으로 종료(double-finalizing)되는 상황도 피해야 합니다. 또한 기본적으로 모든 청크(chunk)를 저장하지 않으면서도, 첫 번째 청크까지의 시간(time to first chunk), 완료 상태, 도구 활동, 그리고 최종 토큰 사용량을 기록해야 합니다.

스트리밍 지원은 단순한 미적 기능(cosmetic feature)이 아닙니다. 스트리밍 지원이 없다면 지연 시간(latency)이 잘못 측정되고, 취소(cancellations) 정보가 사라지며, 부분적인 응답이 성공적인 완료처럼 보이게 됩니다.

런타임 호환성은 매트릭스 구조다

“TypeScript 런타임”은 여러 가지 서로 다른 환경을 의미할 수 있습니다:

메인 엔트리 포인트(main entry point)에서 node:async_hooks 또는 node:fs를 임포트하는 라이브러리는, 해당 기능이 실제로 호출되지 않더라도 에지 런타임 (edge runtime)용으로 번들링될 때 실패할 수 있습니다. 런타임 특정 코드 (Runtime-specific code)는 번들러가 이를 제외할 수 있도록 명시적인 익스포트 (explicit exports) 뒤에 위치해야 합니다.

{
  "exports": {
    ".": "./dist/core.js",
...

핵심 이벤트 모델 (core event model)은 이식 가능할 수 있습니다. 컨텍스트 전파 (Context propagation), 지속성 (persistence), 그리고 플러시 동작 (flush behavior)은 런타임별 구현이 필요할 수 있습니다.

프레임워크 훅 (Framework Hooks)은 실제 라이프사이클을 따라야 한다

프레임워크 통합 (Framework integrations)은 프라이빗 내부 구현 (private internals)을 패치하는 대신 안정적인 라이프사이클 훅 (lifecycle hooks)에 연결될 때 가치가 있습니다. AI 라우트 (AI route)의 경우, 유용한 경계 (boundaries)는 다음과 같습니다:

• 요청 수락 및 검증됨 (Request accepted and validated)
• 에이전트 실행 시작됨 (Agent run started)
• 검색 시작 및 완료됨 (Retrieval started and completed)
• 도구 호출 요청됨, 실행됨, 재시도됨 또는 거부됨 (Tool call requested, executed, retried, or rejected)
• 모델 스트림이 열리고, 첫 번째 청크를 생성하고, 완료됨 (Model stream opened, produced its first chunk, and completed)
• 클라이언트 연결 해제 또는 취소됨 (Client disconnected or cancelled)
• 최종 사용량(Final usage) 사용 가능해짐
• 트레이스 플러시(Trace flush) 성공 또는 시간 초과

프레임워크마다 이러한 경계를 노출하는 방식이 다릅니다. TypeScript 네이티브 트레이서 (TypeScript-native tracer)는 수동 API를 일급 객체 (first-class)로 만들어야 하며, 그 다음 Vercel AI SDK, LangChain.js 또는 OpenAI Agents SDK와 같은 프레임워크를 위한 얇은 어댑터 (thin adapters)를 추가해야 합니다. 어댑터는 코어 (core)가 모든 프레임워크에 의존하도록 강제하는 대신, 프레임워크 이벤트를 하나의 내부 트레이스 모델 (internal trace model)로 변환해야 합니다.

타입 보존 (Type Preservation)은 개발자 경험 (Developer Experience)의 일부다

계측 (Instrumentation)은 자신이 감싸는 함수의 시그니처 (function signature)를 지워서는 안 됩니다. 제네릭 래퍼 (generic wrapper)는 인자(argument)와 반환 타입(return types)을 보존할 수 있습니다:

type AsyncFunction<Args extends unknown[], Result> = (
  ...args: Args
) => Promise<Result>;
...

오버로드된 함수 (Overloaded functions), this에 의존하는 메서드, 그리고 스트리밍 반환 타입 (streaming return types)은 더 세심한 어댑터가 필요합니다. 라이브러리는 any로 회귀하는 대신 이러한 경계들을 문서화해야 합니다.

강력한 타입(Strong types)은 트레이스 품질도 향상시킵니다. 도구 이름, 스팬 종류(span kinds), 메타데이터 필드, 그리고 완료 상태(completion states)를 제어된 유니온(controlled unions)으로 설정하면, 런타임 이전에 계측(instrumentation) 실수를 잡아낼 수 있습니다.

ESM, CommonJS, 그리고 번들러(Bundlers)는 여전히 중요합니다

현대의 TypeScript 패키지는 ESM, CommonJS, 트랜스파일러(transpilers), 모노레포(monorepo) 빌드 시스템, 그리고 프레임워크 번들러를 통해 소비됩니다. 트레이싱 라이브러리는 초기화가 일찍 이루어지고 패키지 경계를 가로질러 통합되는 경우가 많기 때문에 특히 민감합니다.

프로덕션 환경에 적합한 패키지는 다음과 같은 동작들을 명확히 해야 합니다:

• 어떤 모듈 형식(module formats)이 배포되고 테스트되었는지
• 초기화(initialization)가 부작용(side effects)을 일으키는지 여부
• 중복된 패키지 복사본이 전역 등록(global registration)에 어떤 영향을 미치는지
• Node 전용 모듈을 웹 및 엣지(edge) 번들에서 제외할 수 있는지 여부
• 소스 맵(source maps)이 스택 및 코드 위치 메타데이터에 어떤 영향을 미치는지
• 번들링 전후로 계측(instrumentation)이 제대로 작동하는지 여부

자동 몽키 패칭(monkey-patching)은 편리할 수 있지만, 모듈 시스템 전반에 걸쳐 추론하기에는 명시적인 래퍼(wrappers)와 어댑터(adapters)가 더 쉽습니다. 자동 계측(automatic instrumentation)이 제공된다면, 이는 선택 사항이어야 하며 관찰 가능(observable)해야 합니다.

벤더 중립적인 이벤트(Vendor-Neutral Events)는 코어의 유연성을 유지합니다

TypeScript-native라고 해서 반드시 백엔드 전용일 필요는 없습니다. 계측 계층(instrumentation layer)은 작은 내부 이벤트 모델을 방출(emit)하고, 싱크(sinks)가 해당 이벤트들을 로컬 파일, OpenTelemetry, 또는 호스팅된 플랫폼으로 변환할 수 있습니다.

type TraceSink = {
  write(event: TraceEvent): Promise<void>;
  flush(options?: { timeoutMs?: number }): Promise<void>;
...

이러한 분리를 통해 팀은 모든 어댑터를 다시 작성하지 않고도 개발 시에는 로컬 트레이스를, CI에서는 수명이 짧은 아티팩트(artifacts)를, 프로덕션에서는 중앙 집중식 관측성(observability)을 사용할 수 있습니다.

또한 이는 개인정보 보호 정책을 강제할 수 있는 단일 지점을 만들어 줍니다. 프레임워크 통합(framework integrations)은 승인된 메타데이터를 코어로 방출해야 하며, 목적지(destinations)가 어떤 민감한 페이로드(payloads)를 수집할지 결정해서는 안 됩니다.

TypeScript 트레이싱 도구를 평가하는 방법

단일한 hello-world 스크립트보다는 대표성 있는 테스트를 사용하세요.

TypeScript-Native에 대한 더 나은 정의

TypeScript-native 트레이싱 도구는 다음과 같아야 합니다:

• 비동기 인지 (Async-aware): 동시 실행 및 중첩 실행 환경에서도 정확해야 함.
• 스트림 인지 (Stream-aware): 완료, 실패 및 취소 과정 전반에서 정확해야 함.
• 런타임 인지 (Runtime-aware): Node, serverless, edge, browser 및 worker 지원 여부를 명확히 해야 함.
• 프레임워크 적응성 (Framework-adaptable): 안정적인 라이프사이클 훅 (lifecycle hooks)을 통해 통합되어야 함.
• 타입 보존 (Type-preserving): 불필요한 any 없이 안전한 래퍼 (wrapper)를 제공해야 함.
• 모듈 의식 (Module-conscious): ESM, CommonJS 및 번들러 (bundler) 전반에서 예측 가능해야 함.
• 개인정보 보호 의식 (Privacy-conscious): 명시적인 페이로드 (payload) 캡처와 함께 메타데이터를 우선시해야 함.
• 백엔드 유연성 (Backend-flexible): 하나의 이벤트 모델을 여러 싱크 (sink)로 보낼 수 있어야 함.

npm 패키지는 단지 전달 메커니즘일 뿐입니다. 네이티브 지원이란 이러한 런타임 및 개발자 경험 (developer-experience) 결정들이 축적된 품질을 의미합니다.

마치며

TypeScript 에이전트는 비동기적이고, 스트리밍 방식이며, 종종 하나 이상의 런타임에 걸쳐 배포됩니다. 이들의 관찰성 도구는 이러한 제약 사항들을 일급 설계 입력값 (first-class design inputs)으로 이해해야 합니다.

트레이서 (tracer)를 평가할 때, 귀하의 애플리케이션이 실제로 사용하는 조건 하에서 실행 컨텍스트 (execution context), 라이프사이클 (lifecycle), 타입 (types) 및 개인정보 보호를 보존하는지 질문하십시오. 그것이 단순히 컴파일되는 SDK와 신뢰할 수 있는 계측 (instrumentation) 사이의 차이입니다.

다음 기사에서는 핵심 메커니즘을 직접 구축해 보겠습니다: AsyncLocalStorage를 사용하는 TypeScript 실행 트리, 부모-자식 스팬 (parent-child spans), 안전한 완료 처리, 그리고 플러그인 방식의 트레이스 싱크 (trace sinks)를 다룹니다.