요약OpenTelemetry 자동 계측을 사용해 Node.js 애플리케이션의 분산 추적을 ClickStack으로 수집합니다. 데모 데이터세트와 사전 구축된 대시보드가 포함되어 있습니다.
사전 요구사항
- 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에 로그인하여 트레이스가 수집되는지 확인합니다. 다음과 비슷한 화면이 표시됩니다. 트레이스가 보이지 않으면 시간 범위를 조정해 보십시오:아무 트레이스나 클릭하면 스팬, 타이밍, 속성이 포함된 상세 보기를 확인할 수 있습니다:샘플 데이터세트 다운로드
샘플 트레이스 파일을 다운로드하세요: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는 브라우저의 로컬 시간대로 timestamp를 표시합니다. 데모 데이터는 2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC) 범위에 걸쳐 있습니다. 넓은 시간 범위를 지정하면 위치와 관계없이 데모 트레이스를 확인할 수 있습니다. 트레이스가 표시되면 더 명확하게 시각화할 수 있도록 범위를 24시간으로 좁힐 수 있습니다.
사전 구축된 대시보드 가져오기
- HyperDX를 열고 Dashboards 섹션으로 이동합니다
- 오른쪽 상단의 Import Dashboard를 클릭합니다(줄임표 메뉴 아래)
nodejs-traces-dashboard.json 파일을 업로드하고 Finish Import를 클릭합니다
모든 시각화가 미리 구성된 상태로 대시보드가 생성됩니다
데모 데이터세트의 경우 시간 범위를 **2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC)**로 설정하십시오(로컬 시간대에 맞게 조정). 가져온 대시보드에는 기본적으로 시간 범위가 지정되지 않습니다.
curl로 전송한 데모 트레이스가 표시되지 않는 경우
curl -X POST http://localhost:4318/v1/traces \
-H "Content-Type: application/json" \
-H "Authorization: $CLICKSTACK_API_KEY" \
-d @nodejs-traces-sample.json
HyperDX에 트레이스가 표시되지 않는 경우
echo $CLICKSTACK_API_KEY
# API Key가 출력되어야 합니다
echo $OTEL_EXPORTER_OTLP_ENDPOINT
# http://localhost:4318 또는 ClickStack 호스트가 출력되어야 합니다
curl -v http://localhost:4318/v1/traces
- 중요한 메트릭(오류율, 지연 시간 임계값)에 대한 알림을 구성하세요
- 특정 사용 사례(API 모니터링, 보안 이벤트)용 추가 대시보드를 만드세요
이 가이드는 트레이스를 ClickStack의 OTLP 엔드포인트로 직접 전송하는 HyperDX SDK를 사용합니다. 이 방식은 개발, 테스트, 그리고 소규모에서 중간 규모의 프로덕션 배포에 적합합니다.
더 큰 프로덕션 환경에서 운영하거나 텔레메트리 데이터를 더 세밀하게 제어해야 한다면, 자체 OpenTelemetry Collector를 agent로 배포하는 방안을 고려하십시오.
프로덕션 배포 패턴과 collector 구성 예시는 OpenTelemetry로 수집하기를 참조하십시오.
