Node.js 호환성 요구사항 (Node.js Compatibility Requirements)

원문 보기 위키 갱신 2026.10.05

Datadog Node.js SDK의 호환성 요구사항을 안내해요.

출처: 문서

본문

릴리스 (Releases)

버전 정책 (Versioning)

Datadog Node.js SDK의 버전 관리는 semver를 따르고 있어요. 새로운 메이저 버전이 릴리스되면 주요 릴리스 라인이 되어 모든 새 기능, 버그 수정, 보안 패치가 이 라인에 모여요. 각 semver 변경 유형이 무엇을 의미하는지 다음 표에 정리했어요:

메이저	마이너	패치
이전 버전과 호환되지 않는 변경.	이전 버전과 호환되는 항목 추가(기존 항목을 깨지 않음).	보안 수정
이전 버전과 호환되지 않는 API 변경.	API 추가	버그 수정
이전 버전과 호환되지 않는 기능 변경.	기능 추가
Node.js 버전, 지원 라이브러리, 기타 기능에 대한 지원 중단.	Node.js 버전, 지원 라이브러리, 기타 기능에 대한 테스트된 지원 추가.

여러 semver 범주에 해당하는 변경이 있는 릴리스라면 가장 높은 범주가 선택돼요. 릴리스 노트는 각 GitHub 릴리스와 함께 게시돼요.

유지보수 (Maintenance)

유지보수 모드는 가능할 때마다 릴리스가 보안·버그 수정만 받고, 경우에 따라 새 기능은 받지 않는 기간이에요. dd-trace의 메이저 버전은 후속 메이저 버전이 릴리스되면 유지보수 모드로 들어가요. 유지보수 모드 기간은 후속 버전의 릴리스 날짜로부터 1년 동안 지속돼요.

예를 들어 dd-trace 5.0.0이 2023년 5월 4일에 릴리스되면 4.x.x 릴리스 라인은 2024년 5월 4일까지 유지보수 모드 기준으로 지원돼요. 이 유지보수 모드 기간 동안 Datadog는 가능할 때마다 보안·버그 패치를 적용해요.

특정 dd-trace-js 버전에 대한 Datadog의 지원에 대해 궁금한 점이나 우려가 있으면 지원팀에 문의해 논의하세요.

Node.js 버전 지원 (Node.js Version Support)

Node.js 프로젝트가 LTS 메이저 릴리스 라인 지원을 중단하면(즉 EOL이 되면), 해당 지원은 dd-trace의 다음 메이저 버전에서 중단돼요. dd-trace 라이브러리의 마지막 메이저 지원 릴리스 라인은 해당 EOL 버전의 Node.js를 유지보수 모드 기준으로 최소 1년 더 지원해요.

일부 문제는 dd-trace에서 해결할 수 없고 Node.js에서 해결해야 해요. 이 경우 해당 Node.js 릴리스가 EOL이라면 다른 비-EOL 릴리스로 옮기지 않고는 문제를 해결할 수 없어요. Datadog는 비-LTS Node.js 메이저 릴리스 라인(홀수 버전)에 특정 지원을 제공하기 위한 dd-trace 새 릴리스를 만들지 않아요.

최고 수준의 지원을 받으려면 항상 Node.js의 최신 LTS 릴리스와 dd-trace의 최신 메이저 버전을 실행하세요. 어떤 Node.js 릴리스 라인을 사용하든 그 라인의 최신 Node.js 버전도 함께 사용해 최신 보안 수정을 확보하세요.

Node.js 릴리스에 대한 자세한 내용은 공식 Node.js 문서를 참고하세요.

운영체제 지원 (Operating system support)

다음 운영체제가 dd-trace의 정식 지원 대상이에요. 나열되지 않은 운영체제도 동작할 가능성은 있지만, 예를 들어 AAP, 프로파일링, 런타임 메트릭 같은 일부 기능이 빠질 수 있어요. 일반적으로 메이저 버전 초기 릴리스 시점에 활발히 유지보수되는 운영체제를 지원해요.

dd-trace 버전	운영체제	아키텍처	최소 버전
6.x	Linux (glibc)	arm, arm64, x64	Debian 10, RHEL 8, Ubuntu 20.04
	Linux (musl)	arm, arm64, x64	Alpine 3.19
	macOS	arm64, x64	Big Sur (11.0)
	Windows	ia32, x64	Windows 10, Windows Server 2016
5.x	Linux (glibc)	arm, arm64, x64	CentOS 7, Debian 10, RHEL 8, Ubuntu 20.04
	Linux (musl)	arm, arm64, x64	Alpine 3.15
	macOS	arm64, x64	Catalina (10.15)
	Windows	ia32, x64	Windows 10, Windows Server 2016
3.x, 4.x	Linux (glibc)	arm, arm64, x64	CentOS 7, Debian 9, RHEL 7, Ubuntu 14.04
	Linux (musl)	arm, arm64, x64	Alpine 3.13
	macOS	arm64, x64	Catalina (10.15)
	Windows	ia32, x64	Windows 8.1, Windows Server 2012
2.x	Linux (glibc)	arm, arm64, ia32, x64	CentOS 7, Debian 9, RHEL 7, Ubuntu 14.04
	Linux (musl)	arm, arm64, ia32, x64	Alpine 3.10
	macOS	arm64, x64	Yosemite (10.10)
	Windows	ia32, x64	Windows 8.1, Windows Server 2012

지원되는 통합 (Supported integrations)

APM은 플러그인 시스템을 사용해 많은 인기 프레임워크와 라이브러리에 대한 즉시 사용 가능한 계측을 제공해요. 나열되지 않은 모듈에 대한 지원을 요청하려면 훌륭한 지원팀에 문의하세요.

플러그인을 켜고 구성하는 방법에 대한 자세한 내용은 API 문서를 확인하세요.

네이티브 모듈 호환성 (Native module compatibility)

모듈	지원 유형	참고
child_process	완전 지원
dns	완전 지원
http	완전 지원	내장 `fetch` 함수를 포함해요.
https	완전 지원
http2	부분 지원	HTTP2 클라이언트만 지원하고 서버는 지원하지 않아요.
net	완전 지원

프로토콜 호환성 (Protocol compatibility)

모듈	버전	지원 유형	참고
@apollo/gateway	`>=2.3.0`	완전 지원
@apollo/server	`>=4`	완전 지원
apollo-server-core	`>=3`	완전 지원	Apollo Server v2와 v3에 사용돼요.
avsc	`>=5`	완전 지원
gRPC	`>=1.13`	완전 지원
graphql-yoga	`>=3.6.0`	완전 지원	graphql-yoga v3 executor를 지원해요.
graphql	`>=0.10`	완전 지원	Apollo Server와 express-graphql을 지원해요.
ldapjs	`>=2`	완전 지원
ws	`>=8`	완전 지원	자세한 내용은 WebSocket 관측성을 참고하세요.

웹 프레임워크 호환성 (Web framework compatibility)

모듈	버전	지원 유형	참고
connect	`>=2`	완전 지원
express	`>=4`	완전 지원	Express 위에 구축된 Sails, Loopback 및 기타 프레임워크를 지원해요.
fastify	`>=1`	완전 지원
hapi	`>=2`	완전 지원	[@hapi/hapi] 버전 `>=17.9`를 지원해요.
hono	`>=4`	완전 지원
koa	`>=2`	완전 지원
microgateway-core	`>=2.1`	완전 지원	Apigee Edge용 핵심 라이브러리예요. edgemicro CLI 지원에는 @datadog/cli를 사용한 정적 패치가 필요해요.
moleculer	`>=0.14`	완전 지원
next	`>=10.2`	완전 지원	복잡한 프레임워크 사용 참고를 보세요. SDK는 다음 Next.js 기능을 지원해요:

Standalone (output: 'standalone')
App Router
Middleware: 추적되지 않음. 최상의 경험을 위해 트레이서 버전 4.18.0, 3.39.0 이상을 사용하세요. 참고: Next.js는 활발히 개발 중이며, 패치 릴리스가 dd-trace와의 호환성을 깨는 경우가 드물지 않아요. 테스트 자동화가 이런 문제를 Datadog에 알리지만, 최신 Next.js 릴리스와의 호환성 수정에는 며칠이 걸리기도 해요. | | paperplane | >=2.3 | 완전 지원 | serverless-mode에서는 지원되지 않아요. | | restify | >=3 | 완전 지원 | |

복잡한 프레임워크 사용 (Complex framework usage)

Next.js, Nest.js 같은 일부 현대적 복합 Node.js 프레임워크는 애플리케이션에 자체 진입점을 제공해요. 예를 들어 node app.js를 실행하는 대신 next start를 실행해야 할 수 있어요. 이 경우 진입점은 로컬 애플리케이션 파일(app.js)이 아니라 프레임워크 패키지에 포함된 파일이에요.

애플리케이션 코드 초기에 Datadog SDK를 로드하는 것은 효과적이지 않아요. 프레임워크가 계측되어야 할 모듈을 이미 로드했을 수 있기 때문이에요.

프레임워크보다 먼저 SDK를 로드하려면 다음 방법 중 하나를 사용하세요:

실행하는 모든 명령 앞에 환경 변수를 붙이세요:

NODE_OPTIONS='--require dd-trace/init' npm start

또는 일반적으로 npm 또는 yarn run 스크립트로 애플리케이션을 시작한다면 package.json 파일을 수정하세요:

    // 기존 명령
    "start": "next start",

    // 제안하는 명령
    "start": "node --require dd-trace/init ./node_modules/.bin/next start",
    "start": "NODE_OPTIONS='--require dd-trace/init' ./node_modules/.bin/next start",

참고: 앞의 예시는 Next.js를 사용하지만, 사용자 지정 진입점이 있는 다른 프레임워크(예: Nest.js)에도 동일한 접근 방식이 적용돼요. 특정 프레임워크와 구성에 맞게 명령을 조정하세요. 두 명령 모두 동작해야 하지만, NODE_OPTIONS를 사용하면 하위 Node.js 프로세스에도 적용돼요.

데이터 저장소 호환성 (Data store compatibility)

모듈	버전	지원 유형	참고
aerospike	`>=4`	완전 지원
cassandra-driver	`>=3`	완전 지원
couchbase	`^2.6.12`	완전 지원
elasticsearch	`>=10`	완전 지원	`@elastic/elasticsearch` 버전 `>=5`를 지원해요.
ioredis	`>=2`	완전 지원
iovalkey	`>=0.0.1`	완전 지원
knex	`>=0.8`	완전 지원	이 통합은 컨텍스트 전파 전용이에요.
mariadb	`>=2`	완전 지원
memcached	`>=2.2`	완전 지원
mongodb-core	`>=2`	완전 지원	Mongoose를 지원해요.
mongoose	`>=4.6.4`	완전 지원
mysql	`>=2`	완전 지원
mysql2	`>=1`	완전 지원
opensearch	`>=1`	완전 지원
oracledb	`>=5`	완전 지원
pg	`>=4`	완전 지원	`pg`와 함께 사용할 때 `pg-native`를 지원해요.
prisma	`>=6.1.0`	부분 지원	DBM을 지원하지 않아요.
redis	`>=0.12`	완전 지원
sequelize	`>=4`	완전 지원
sharedb	`>=1`	완전 지원
tedious	`>=1`	완전 지원	`mssql`과 `sequelize`용 SQL Server 드라이버예요.

참고: Redis 6.0+는 HELLO, MIGRATE, ACL SETUSER 같은 명령에서 인라인 인증을 지원해요.

Datadog Trace Agent: 인증 매개변수가 트레이스 메타데이터에서 자동으로 난독화되도록 보장하는 최소 권장 버전은 7.76.1이에요.
Datadog Lambda Extension(서버리스 환경): 최소 필요 버전은 v28.0.0이에요.

워커 호환성 (Worker compatibility)

모듈	버전	지원 유형	참고
@azure/event-hubs	`>=6.0.0`	완전 지원
@azure/functions	`>=4`	완전 지원	기본적으로 비활성화돼요. `DD_TRACE_AZURE_FUNCTIONS_ENABLED=true`로 활성화하세요.
@azure/service-bus	`>=7.9.2`	완전 지원
@confluentinc/kafka-javascript	`>=1`	완전 지원
@google-cloud/pubsub	`>=1.2`	완전 지원
amqp10	`>=3`	완전 지원	AMQP 1.0 브로커(ActiveMQ, Apache Qpid 등)를 지원해요.
amqplib	`>=0.5`	완전 지원	AMQP 0.9 브로커(RabbitMQ, Apache Qpid 등)를 지원해요.
bullmq	`>=5.66.0`	완전 지원
generic-pool	`>=2`	완전 지원
kafkajs	`>=1.4`	완전 지원
rhea	`>=1`	완전 지원

SDK 호환성 (SDK compatibility)

모듈	버전	지원 유형	참고
aws-sdk	`>=2.1.35`	완전 지원	CloudWatch, DynamoDB, Kinesis, Redshift, S3, SNS, SQS 및 일반 요청.

Promise 라이브러리 호환성 (Promise library compatibility)

모듈	버전	지원 유형
bluebird	`>=2`	완전 지원
promise	`>=7`	완전 지원
promise-js	`>=0.0.3`	완전 지원
q	`>=1`	완전 지원
when	`>=3`	완전 지원

로거 호환성 (Logger compatibility)

모듈	버전	지원 유형
bunyan	`>=1`	완전 지원
pino	`>=2`	완전 지원
winston	`>=1`	완전 지원

AI/LLM 호환성 (AI/LLM compatibility)

Agent Observability 자동 계측 페이지에 계측된 LLM 패키지 목록(Amazon Bedrock, Anthropic, LangChain, OpenAI, Azure OpenAI, Vercel AI SDK, VertexAI, Google GenAI 포함)이 있어요.

테스트 프레임워크 호환성 (Testing framework compatibility)

JavaScript 및 TypeScript 테스트 페이지에 계측된 테스트 프레임워크 패키지 목록(Jest, Mocha, Cucumber, Cypress, Playwright, Vitest 포함)이 있어요.

알려진 전이 의존성 호환성 (Known transitive package compatibility)

Datadog SDK는 여기에 나열된 모듈을 직접 지원하지 않지만, SDK가 계측하는 모듈에 의존하므로 동작하는 것으로 알려져 있어요.

모듈	참고
axios	Axios는 내부 `http` 모듈에 의존해요.

지원되지 않는 라이브러리 (Unsupported libraries)

Fibers

fibers는 dd-trace-js가 비동기 컨텍스트를 추적해 정확한 트레이싱을 보장하는 데 사용하는 Node.js 모듈인 async_hooks와 호환되지 않아요. fibers와 async_hooks 사이의 상호작용은 예방할 수 없는 충돌과 정의되지 않은 동작을 초래할 수 있어요. 따라서 Meteor 같은 프레임워크를 통해 직접든 간접든 fibers를 호출하는 애플리케이션에서 dd-trace-js를 사용하면 불안정성(충돌)이나 잘못된 트레이싱이 발생할 수 있어요.

추가 정보는 이 GitHub 이슈에 댓글을 남기거나 지원팀에 문의해 더 논의하세요.

더 알아보기 (Learn more)

애플리케이션 계측 (Instrument Your Application)