ClickStack으로 Node.js 트레이스 모니터링

요약OpenTelemetry 자동 계측을 사용해 Node.js 애플리케이션의 분산 추적을 ClickStack으로 수집합니다. 데모 데이터세트와 사전 구축된 대시보드가 포함되어 있습니다.

기존 Node.js 애플리케이션 통합

이 섹션에서는 OpenTelemetry 자동 계측을 사용해 기존 Node.js 애플리케이션에 분산 추적을 추가하는 방법을 설명합니다. 기존 환경을 직접 구성하기 전에 통합을 테스트하려면 데모 데이터세트 섹션에서 미리 구성된 환경과 샘플 데이터를 사용해 볼 수 있습니다.

사전 요구사항

OTLP 엔드포인트(포트 4317/4318)에 접근할 수 있는 실행 중인 ClickStack 인스턴스
기존 Node.js 애플리케이션(Node.js 14 이상)
npm 또는 yarn 패키지 관리자
ClickStack 호스트명 또는 IP 주소

OpenTelemetry 설치 및 구성

@hyperdx/node-opentelemetry 패키지를 설치하고 애플리케이션 시작 시 초기화합니다. 자세한 설치 단계는 Node.js SDK 가이드를 참조하십시오.

ClickStack API key 가져오기

ClickStack의 OTLP 엔드포인트로 트레이스를 전송하는 데 필요한 API Key입니다.

ClickStack URL(예: http://localhost:8080)에서 HyperDX를 엽니다
필요하면 계정을 만들거나 로그인합니다
Team Settings → API Keys로 이동합니다
수집 API key를 복사합니다

애플리케이션 실행

환경 변수를 설정한 상태로 Node.js 애플리케이션을 시작합니다:

export CLICKSTACK_API_KEY=your-api-key-here
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

트래픽 생성

애플리케이션에 요청을 보내 트레이스를 생성합니다:

# 간단한 요청
curl http://localhost:3000/
curl http://localhost:3000/api/users
curl http://localhost:3000/api/products

# 부하 시뮬레이션
for i in {1..100}; do curl -s http://localhost:3000/ > /dev/null; done

HyperDX에서 트레이스 확인

구성이 완료되면 HyperDX에 로그인하여 트레이스가 수집되고 있는지 확인합니다. 다음과 비슷한 화면이 표시됩니다. 트레이스가 보이지 않으면 시간 범위를 조정해 보십시오:아무 trace나 클릭하면 스팬, 타이밍, 속성이 포함된 상세 보기를 확인할 수 있습니다:

데모 데이터세트

프로덕션 애플리케이션에 계측을 적용하기 전에 ClickStack에서 Node.js 트레이싱을 테스트하려는 사용자를 위해, 실제 트래픽 패턴을 반영한 사전 생성 Node.js 애플리케이션 트레이스 샘플 데이터세트를 제공합니다.

샘플 데이터세트 다운로드

샘플 트레이스 파일을 다운로드하세요:

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/nodejs/nodejs-traces-sample.json

ClickStack 시작

아직 ClickStack이 실행 중이 아니라면, 다음 명령으로 시작하세요:

docker run -d --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD= \
  clickhouse/clickstack-all-in-one:latest

ClickStack API Key 가져오기

ClickStack의 OTLP 엔드포인트로 트레이스를 전송하려면 API Key가 필요합니다.

ClickStack URL에서 HyperDX를 엽니다(예: http://localhost:8080)
필요하면 계정을 생성하거나 로그인합니다
Team Settings → API Keys로 이동합니다
수집 API Key를 복사합니다

API Key를 환경 변수로 설정하세요:

export CLICKSTACK_API_KEY=your-api-key-here

ClickStack으로 트레이스 전송

curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -H "Authorization: $CLICKSTACK_API_KEY" \
  -d @nodejs-traces-sample.json

트레이스가 성공적으로 전송되었음을 나타내는 {"partialSuccess":{}}와 같은 응답이 표시됩니다.

HyperDX에서 트레이스 확인

HyperDX를 열고 계정에 로그인합니다(먼저 계정을 만들어야 할 수 있습니다)
검색 보기로 이동한 뒤 source를 Traces로 설정합니다
시간 범위를 2025-10-25 13:00:00 - 2025-10-28 13:00:00으로 설정합니다

시간대 표시HyperDX는 브라우저의 로컬 시간대로 타임스탬프를 표시합니다. 데모 데이터는 2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC) 범위에 걸쳐 있습니다. 넓은 시간 범위를 지정하면 위치와 관계없이 데모 트레이스를 확인할 수 있습니다. 트레이스가 표시되면 더 명확하게 시각화할 수 있도록 범위를 24시간으로 좁힐 수 있습니다.

대시보드 및 시각화

Node.js 애플리케이션 성능 모니터링을 시작할 수 있도록, 필수 트레이스 시각화가 포함된 사전 구축된 대시보드를 제공합니다.

대시보드 구성 다운로드

사전 구축된 대시보드 가져오기

HyperDX를 열고 Dashboards 섹션으로 이동합니다
오른쪽 상단의 대시보드 가져오기를 클릭합니다(줄임표 메뉴 아래)

nodejs-traces-dashboard.json 파일을 업로드하고 가져오기 완료를 클릭합니다

모든 시각화가 미리 구성된 상태로 대시보드가 생성됩니다

데모 데이터세트의 경우 시간 범위를 **2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC)**로 설정하십시오(로컬 시간대에 맞게 조정). 가져온 대시보드에는 기본적으로 시간 범위가 지정되지 않습니다.

문제 해결

curl로 전송한 데모 트레이스가 표시되지 않는 경우

curl로 트레이스를 전송했지만 HyperDX에 표시되지 않으면 트레이스를 한 번 더 전송해 보십시오:

curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -H "Authorization: $CLICKSTACK_API_KEY" \
  -d @nodejs-traces-sample.json

이는 curl을 통해 데모 방식을 사용할 때 발생하는 알려진 문제이며, 계측이 적용된 production 애플리케이션에는 영향을 미치지 않습니다.

HyperDX에 트레이스가 표시되지 않는 경우

환경 변수가 설정되어 있는지 확인하세요:

echo $CLICKSTACK_API_KEY
# API Key가 출력되어야 합니다

echo $OTEL_EXPORTER_OTLP_ENDPOINT
# http://localhost:4318 또는 ClickStack 호스트가 출력되어야 합니다

네트워크 연결을 확인하세요:

curl -v http://localhost:4318/v1/traces

OTLP 엔드포인트에 성공적으로 연결되어야 합니다. 애플리케이션 로그를 확인하세요: 앱이 시작될 때 OpenTelemetry 초기화 메시지가 표시되는지 확인하세요. HyperDX SDK는 초기화가 완료되었다는 확인 메시지를 출력해야 합니다.

다음 단계

중요한 메트릭(오류율, 지연 시간 임계값)에 대한 알림을 구성하세요
특정 사용 사례(API 모니터링, 보안 이벤트)용 추가 대시보드를 만드세요

프로덕션 환경으로 전환하기

이 가이드에서는 트레이스를 ClickStack의 OTLP 엔드포인트로 직접 전송하는 HyperDX SDK를 사용합니다. 이 방식은 개발, 테스트 및 소규모에서 중간 규모의 프로덕션 배포에 적합합니다. 더 큰 규모의 프로덕션 환경을 운영하거나 텔레메트리 데이터를 추가로 제어해야 하는 경우에는 자체 OpenTelemetry Collector를 에이전트로 배포하는 것을 고려하십시오. 프로덕션 배포 패턴과 collector 구성 예시는 OpenTelemetry로 수집하기를 참조하십시오.

​기존 Node.js 애플리케이션 통합

사전 요구사항

​데모 데이터세트

​대시보드 및 시각화

​문제 해결

​curl로 전송한 데모 트레이스가 표시되지 않는 경우

​HyperDX에 트레이스가 표시되지 않는 경우

​다음 단계

​프로덕션 환경으로 전환하기

기존 Node.js 애플리케이션 통합

데모 데이터세트

대시보드 및 시각화

문제 해결

curl로 전송한 데모 트레이스가 표시되지 않는 경우

HyperDX에 트레이스가 표시되지 않는 경우

다음 단계

프로덕션 환경으로 전환하기