이 가이드는 서드파티 라이브러리(예: OpenAI)를 Weave TypeScript SDK에 통합하는 방법을 설명합니다. Weave는 자동 계측을 지원하므로 설정이 더 간편해지고 수동 설정의 필요도 줄어듭니다.
무엇이 바뀌었나요?
PR #4554부터 OpenAI와 같은 지원 라이브러리는 Weave가 로드될 때 자동으로 패치됩니다. 이제는 이전처럼 직접 래핑할 필요가 없습니다.weave.wrapOpenAI(new OpenAI());
TypeScript 프로젝트에서 Weave 인테그레이션 사용하기
package.json 및 tsconfig.json 파일을 명시적으로 지정하는 것이 좋습니다.
프로젝트에서 CommonJS를 사용하는지 ESM을 사용하는지 확인하려면 package.json의 type 필드를 확인하세요:
type이 "module"이면 프로젝트는 ESM을 사용합니다.type 필드가 없거나 "commonjs"로 설정되어 있으면 프로젝트는 기본적으로 CommonJS를 사용합니다.
CommonJS 프로젝트에서는 추가 설정 없이 자동 계측이 작동합니다.
프로젝트를 CommonJS에 맞게 설정하려면 다음 단계를 따르세요.
-
package.json을 생성하거나 업데이트합니다:
-
CommonJS와 호환되는 설정으로
tsconfig.json을 생성합니다:
{
"compilerOptions": {
"module": "CommonJS",
"target": "es2022",
"rootDir": ".",
"outDir": "dist"
}
}
-
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을 참조하세요.
-
Weave와 필요한 다른 라이브러리를 설치합니다:
-
TypeScript 파일을 컴파일합니다.
예제 파일이
test.ts인 경우:
그러면 파일이 dist/test.js로 컴파일됩니다.
-
컴파일된 파일을 Node.js로 실행합니다:
CommonJS는 Node.js의 require 모듈 로더를 사용하므로, Weave는 ESM 프로젝트에서 사용하는 --import 플래그 없이도 지원되는 라이브러리를 자동으로 계측할 수 있습니다.
ESM TypeScript 프로젝트에서 Weave를 사용하려면 프로젝트를 Node.js ESM에 맞게 구성하고, 코드를 컴파일한 다음, 다른 모듈이 로드되기 전에 Weave가 계측을 등록할 수 있도록 --import 플래그와 함께 Node.js를 시작하세요.
프로젝트를 ESM용으로 구성하려면 다음을 수행하세요.
-
package.json을 생성하거나 업데이트합니다:
-
Node.js와 호환되는 ESM 설정으로
tsconfig.json을 생성합니다:
{
"compilerOptions": {
"module": "nodenext",
"moduleResolution": "nodenext",
"target": "es2022",
"rootDir": ".",
"outDir": "dist"
}
}
-
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을 참조하세요.
-
Weave와 필요한 다른 라이브러리를 설치합니다:
-
TypeScript 파일을 컴파일합니다.
예제 파일
test.ts의 경우:
그러면 파일이 dist/test.js로 컴파일됩니다.
-
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 프로세스에 영향을 줄 수 있고 부작용을 일으킬 수 있으므로, 주의해서 사용하세요.
NODE_OPTIONS 환경 변수를 설정하세요:
export NODE_OPTIONS="--import=weave/instrument"
-
번들러 설정에서 LLM 라이브러리를 external로 지정합니다. 이렇게 하면 해당 라이브러리가 번들링되지 않으므로 Weave가 런타임에 올바르게 패치할 수 있습니다.
다음 예시는
next.config.js 설정에서 openai 패키지를 external로 지정하는 방법을 보여 줍니다. 이렇게 하면 해당 패키지가 번들링되지 않습니다. 모듈은 런타임에 로드되므로 Weave가 이를 자동으로 패치하고 추적할 수 있습니다. Next.js와 같은 프레임워크를 사용할 때 자동 계측을 활성화하려면 이 설정을 사용하세요.
externals: {
'openai': 'commonjs openai'
}
-
패치가 계속 실패하면 수동 계측으로 전환하세요.
수동 패치는 레거시 방식입니다. 자동 패치가 작동하지 않을 때만 사용하세요.
import { wrapOpenAI } from 'weave';
const client = wrapOpenAI(new OpenAI());
