TypeScript SDK: 서드파티 인테그레이션 가이드

서드파티 라이브러리를 Weave TypeScript SDK에 통합하는 방법

이 가이드는 서드파티 라이브러리(예: OpenAI)를 Weave TypeScript SDK에 통합하는 방법을 설명합니다. Weave는 자동 계측을 지원하므로 설정이 더 간편해지고 수동 설정의 필요도 줄어듭니다.

무엇이 바뀌었나요? PR #4554부터 OpenAI와 같은 지원 라이브러리는 Weave가 로드될 때 자동으로 패치됩니다. 이제는 이전처럼 직접 래핑할 필요가 없습니다.

weave.wrapOpenAI(new OpenAI());

일반적으로는 Weave가 이를 자동으로 처리합니다. 다만 예외적인 경우가 있을 수 있습니다.

​

TypeScript 프로젝트에서 Weave 인테그레이션 사용하기

TypeScript 프로젝트에서는 CommonJS 또는 ESM 모듈 시스템을 사용할 수 있습니다.

​

어떤 유형의 프로젝트인지 잘 모르겠다면

다음과 같은 도구로 TypeScript 파일을 직접 실행한다면:

npx tsx test.ts

모듈 시스템은 환경에 따라 암묵적으로 결정될 수 있습니다. 일관된 동작을 위해 package.json 및 tsconfig.json 파일을 명시적으로 지정하는 것이 좋습니다.

프로젝트에서 CommonJS를 사용하는지 ESM을 사용하는지 확인하려면 package.json의 type 필드를 확인하세요:

"type": "module"

• type이 "module"이면 프로젝트는 ESM을 사용합니다.
• type 필드가 없거나 "commonjs"로 설정되어 있으면 프로젝트는 기본적으로 CommonJS를 사용합니다.

​

CommonJS 프로젝트 설정

CommonJS 프로젝트에서는 추가 설정 없이 자동 계측이 작동합니다.

프로젝트를 CommonJS에 맞게 설정하려면 다음 단계를 따르세요.

1. package.json을 생성하거나 업데이트합니다:

   {
     "type": "commonjs"
   }
   

2. CommonJS와 호환되는 설정으로 tsconfig.json을 생성합니다:

   {
     "compilerOptions": {
       "module": "CommonJS",
       "target": "es2022",
       "rootDir": ".",
       "outDir": "dist"
     }
   }
   

   이 설정은 TypeScript가 CommonJS용으로 컴파일되도록 설정합니다:

   • module: "CommonJS" — 모듈을 CommonJS 형식(require/module.exports)으로 컴파일합니다. 이 컴파일러 옵션에 대한 자세한 내용은 TypeScript - Module을 참조하세요.

   • target: "es2022" (권장) — 최신 Node.js 버전과 호환되는 최신 JavaScript를 출력합니다. 이 컴파일러 옵션에 대한 자세한 내용은 TypeScript - Target을 참조하세요.

   • rootDir: "." — tsconfig.json이 포함된 디렉터리를 입력 파일의 루트로 간주합니다. TypeScript는 이를 outDir과 함께 사용해 출력에서 소스 폴더 레이아웃을 그대로 반영합니다. 이 컴파일러 옵션에 대한 자세한 내용은 TypeScript - Root Dir을 참조하세요.

   • outDir: "dist" — 생성된 JavaScript(및 기타 컴파일러 출력)를 dist 폴더에 씁니다. 이 컴파일러 옵션에 대한 자세한 내용은 TypeScript - Out Dir을 참조하세요.

3. Weave와 필요한 다른 라이브러리를 설치합니다:

   npm install weave
   

4. TypeScript 파일을 컴파일합니다.

   예제 파일이 test.ts인 경우:

   npx tsc
   

   그러면 파일이 dist/test.js로 컴파일됩니다.

5. 컴파일된 파일을 Node.js로 실행합니다:

   node dist/test.js
   

CommonJS는 Node.js의 require 모듈 로더를 사용하므로, Weave는 ESM 프로젝트에서 사용하는 --import 플래그 없이도 지원되는 라이브러리를 자동으로 계측할 수 있습니다.

​

ESM 프로젝트 설정

ESM TypeScript 프로젝트에서 Weave를 사용하려면 프로젝트를 Node.js ESM에 맞게 구성하고, 코드를 컴파일한 다음, 다른 모듈이 로드되기 전에 Weave가 계측을 등록할 수 있도록 --import 플래그와 함께 Node.js를 시작하세요.

프로젝트를 ESM용으로 구성하려면 다음을 수행하세요.

1. package.json을 생성하거나 업데이트합니다:

   {
     "type": "module"
   }
   

2. Node.js와 호환되는 ESM 설정으로 tsconfig.json을 생성합니다:

   {
     "compilerOptions": {
       "module": "nodenext",
       "moduleResolution": "nodenext",
       "target": "es2022",
       "rootDir": ".",
       "outDir": "dist"
     }
   }
   

   이 설정은 TypeScript가 최신 Node.js ESM 환경에 맞게 컴파일되도록 구성합니다:

   • module: "nodenext" — Node.js ESM 방식에 따라 모듈을 컴파일합니다. 이 컴파일러 옵션에 대한 자세한 내용은 TypeScript - Module을 참조하세요.

   • moduleResolution: "nodenext" — 모듈 해석이 Node.js ESM 규칙을 따르도록 합니다. 이 컴파일러 옵션에 대한 자세한 내용은 TypeScript - Module Resolution을 참조하세요.

   • target: "es2022" (권장) — 최신 Node.js 버전과 호환되는 최신 JavaScript를 출력합니다. 이 컴파일러 옵션에 대한 자세한 내용은 TypeScript - Target을 참조하세요.

   • rootDir: "." — tsconfig.json이 있는 디렉터리를 입력 파일의 루트로 간주합니다. TypeScript는 이 설정을 outDir와 함께 사용해 출력 시 소스 폴더 레이아웃을 그대로 반영합니다. 이 컴파일러 옵션에 대한 자세한 내용은 TypeScript - Root Dir을 참조하세요.

   • outDir: "dist" — 생성된 JavaScript(및 기타 컴파일러 출력)를 dist 폴더에 씁니다. 이 컴파일러 옵션에 대한 자세한 내용은 TypeScript - Out Dir을 참조하세요.

3. Weave와 필요한 다른 라이브러리를 설치합니다:

   npm install weave
   

4. TypeScript 파일을 컴파일합니다.

   예제 파일 test.ts의 경우:

   npx tsc
   

   그러면 파일이 dist/test.js로 컴파일됩니다.

5. Node.js로 컴파일된 파일을 실행하고 Weave 계측을 미리 로드합니다:

   node --import=weave/instrument dist/test.js
   

--import 플래그를 사용하면 weave/instrument 모듈이 다른 모듈보다 먼저 로드되므로, Weave가 지원되는 라이브러리와 인테그레이션을 자동으로 계측할 수 있습니다.

Weave는 실행할 프로젝트에 로컬로 설치되어 있어야 합니다.

​

고급 활용 및 문제 해결

이 섹션에서는 TypeScript SDK의 자동 패치가 예상대로 작동하지 않을 때 발생하는 예외적인 상황과 우회 방법을 다룹니다. 예를 들어 ESM 전용 환경, Next.js와 같은 번들러 설정, 또는 제약이 있는 런타임 환경에서는 예상치 못한 문제가 생길 수 있습니다. 트레이스가 누락되거나 인테그레이션 관련 문제가 발생한다면, 이 섹션부터 확인하세요.

​

NODE_OPTIONS 사용하기(ESM 전용)

NODE_OPTIONS는 환경 내의 모든 Node.js 프로세스에 영향을 줄 수 있고 부작용을 일으킬 수 있으므로, 주의해서 사용하세요.

ESM 프로젝트를 사용 중인데 CLI 플래그를 전달할 수 없는 경우(예: CLI 도구나 프레임워크의 제약 때문)에는 NODE_OPTIONS 환경 변수를 설정하세요:

export NODE_OPTIONS="--import=weave/instrument"

​

번들러 호환성

Next.js와 같은 일부 프레임워크와 번들러는 Node.js가 런타임에 패치할 수 없도록 서드파티 라이브러리를 번들링할 수 있습니다.

현재 설정이 이에 해당한다면, 다음 step을 사용해 보세요:

1. 번들러 설정에서 LLM 라이브러리를 external로 지정합니다. 이렇게 하면 해당 라이브러리가 번들링되지 않으므로 Weave가 런타임에 올바르게 패치할 수 있습니다.

   다음 예시는 next.config.js 설정에서 openai 패키지를 external로 지정하는 방법을 보여 줍니다. 이렇게 하면 해당 패키지가 번들링되지 않습니다. 모듈은 런타임에 로드되므로 Weave가 이를 자동으로 패치하고 추적할 수 있습니다. Next.js와 같은 프레임워크를 사용할 때 자동 계측을 활성화하려면 이 설정을 사용하세요.

   externals: {
   'openai': 'commonjs openai'
   }
   

2. 패치가 계속 실패하면 수동 계측으로 전환하세요.

​

수동 패치(대체 옵션)

수동 패치는 레거시 방식입니다. 자동 패치가 작동하지 않을 때만 사용하세요.

경우에 따라서는 여전히 수동 계측을 사용해야 할 수 있습니다:

import { wrapOpenAI } from 'weave';
const client = wrapOpenAI(new OpenAI());