Node.js 제로 코드 계측¶

Beacon Node.js는 패키지에서 검증된 Node.js 유지 관리 버전을 지원하며 최소 버전은 Node.js 18.19입니다. Security에는 아래에 설명된 더 엄격한 런타임 요건이 적용됩니다.

연동 전에 공통 설정에 따라 DataKit OpenTelemetry 수집기를 활성화하세요. 아래 명령은 Linux/macOS 셸을 기준으로 하며 애플리케이션과 DataKit이 같은 호스트에 있다고 가정합니다. 서로 다른 호스트나 컨테이너에서는 127.0.0.1을 바꾸고 수신 주소를 조정하세요.

설치¶

npm install @beacon-observability/nodejs

시작¶

export OTEL_SERVICE_NAME=my-node-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export NODE_OPTIONS="--require @beacon-observability/nodejs/register"
node app.js

애플리케이션의 기존 node 명령을 유지하세요. NODE_OPTIONS에 이미 옵션이 있다면 기존 인수를 덮어쓰지 말고 --require를 추가하세요.

디버깅 및 진단¶

위의 NODE_OPTIONS 사전 로드 설정을 유지한 채 OpenTelemetry 진단 로그를 일시적으로 활성화하세요.

OTEL_LOG_LEVEL=debug node app.js > beacon-nodejs-debug.log 2>&1

로그는 터미널에 출력되며 위 명령은 표준 출력과 표준 오류를 함께 저장합니다. Security를 활성화할 때는 필요한 ESM --import 사전 로드를 유지하세요.

문제 해결 후 원래 시작 명령으로 복원하세요. 배포 환경에 OTEL_LOG_LEVEL=debug를 설정했다면 제거하고 애플리케이션을 재시작하세요.

Profile¶

먼저 DataKit Profile 수집기를 활성화한 뒤 아래 변수를 설정하고 위의 시작 방식을 유지하세요. Profile은 OTLP Trace 주소와 별개의 HTTP 업로드 주소를 사용합니다.

@beacon-observability/nodejs에는 Profile 기능이 포함되어 있습니다. Node.js 제로 코드 가이드의 사전 로드 설정을 유지하고 호환 pprof multipart 형식을 지원하는 HTTP 수신 주소를 설정하세요.

export NODE_OPTIONS="--require @beacon-observability/nodejs/register"
export OTEL_SERVICE_NAME=my-node-service
export OTEL_PROFILING_ENABLED=true
export OTEL_PROFILING_PPROF_UPLOAD_URL=http://127.0.0.1:9529/profiling/v1/input
node app.js

기본적으로 wall profile이 활성화됩니다. heap profile도 수집하려면 다음을 설정하세요.

export OTEL_PROFILING_MEMORY_ENABLED=true

기본 업로드 주기는 60초입니다. OTEL_PROFILING_EXPORT_INTERVAL로 초 단위 주기를 조정하고 OTEL_PROFILING_PPROF_HEADERS로 쉼표로 구분한 name:value HTTP 헤더를 설정할 수 있습니다.

파라미터 참조¶

환경 변수 이름은 대소문자를 구분합니다.

환경 변수	유형 / 허용 값	기본값	설명
`OTEL_PROFILING_ENABLED`	불리언. `true`, `1`, `yes`, `on`이면 활성화	`false`	pprof 수집을 활성화합니다.
`OTEL_PROFILING_PPROF_UPLOAD_URL`	HTTP(S) URL	설정되지 않음	Profile 활성화 시 필수. multipart pprof 업로드를 수신하는 URL.
`OTEL_PROFILING_EXPORT_INTERVAL`	양수, 초	`60`	Profile 수집 및 업로드 간격.
`OTEL_PROFILING_MEMORY_ENABLED`	불리언	`false`	기본 wall-time Profile에 heap Profile을 추가합니다.
`OTEL_PROFILING_PPROF_HEADERS`	쉼표로 구분한 `name=value` 또는 `name:value`	비어 있음	추가 HTTP 요청 헤더.

내보내기는 OTEL_SERVICE_NAME과 OTEL_RESOURCE_ATTRIBUTES의 service.version, deployment.environment.name 또는 deployment.environment, host.name을 Profile 메타데이터로 사용합니다.

Security¶

Security는 패키지에 포함되어 있으며 Node.js 22.22.3+ 또는 24.11.1+를 지원합니다. --require 대신 ESM --import 사전 로드가 필요합니다. Node.js Security 가이드를 참조하세요.

연동 확인¶

지원되는 프레임워크나 라이브러리를 거치는 요청을 애플리케이션 API에 보낸 뒤 Guance의 APM > 트레이스에서 위에 설정한 서비스 이름으로 필터링하세요. 전체 확인 절차는 공통 설정을, 데이터가 없으면 문제 해결을 참조하세요.