요약이 가이드에서는 HyperDX Chrome 확장 프로그램을 사용해 임의의 웹사이트에 ClickStack Browser SDK를 주입하는 방법을 설명합니다. 대상 애플리케이션의 소스 코드를 변경할 필요는 없습니다 — 확장 프로그램을 한 번만 구성한 뒤 사이트를 둘러보고 ClickStack에서 세션 리플레이를 확인하십시오.소요 시간: 10-15분
개요
chrome-extension:// 스크립트 주입을 시도하고, CSP가 확장 프로그램 출처의 스크립트를 차단하면 인라인 주입으로 대체합니다.
사용자가 제어하는 데모 애플리케이션에 계측을 추가하는 Session Replay Demo와 달리, 이 방식은 Chrome에서 여는 모든 URL에서 작동합니다. 일반 사용자처럼 사이트와 상호작용하여 세션 데이터를 생성합니다.
세션 리플레이의 배경과 ClickStack에서의 역할에 대해서는 Session Replay 기능 페이지를 참조하십시오.
사전 요구사항
- Google Chrome 또는 Chromium 기반 브라우저(Edge, Brave 등)
- ClickStack을 로컬에서 실행하는 경우 Docker가 설치되어 있어야 합니다
- 포트 4317, 4318, 8080을 사용할 수 있어야 합니다(로컬 ClickStack용)
데모 실행하기
확장 프로그램 리포지토리 복제
확장 프로그램 설치
- Chrome을 열고
chrome://extensions로 이동합니다. - 개발자 모드를 활성화합니다(오른쪽 상단).
- 압축해제된 확장 프로그램을 로드를 클릭합니다.
- 복제한
hyperdx-chrome-extension디렉터리를 선택합니다.
ClickStack 시작
이미 ClickStack 또는 HyperDX 수집 엔드포인트가 있으면 확장 프로그램 구성으로 건너뛰십시오.로컬 ClickStack 스택의 경우 OpenTelemetry collector를 시작합니다.{{CLICKHOUSE_ENDPOINT}}와 {{CLICKHOUSE_PASSWORD}}를 ClickHouse 연결 정보로 바꾸십시오:API Key 가져오기
로컬 ClickStack의 경우 API Key가 필요하지 않을 수 있습니다 —http://localhost:4318의 자체 호스팅 collector로 telemetry를 보낼 때는 확장 프로그램에서 해당 필드를 비워 두십시오.ClickStack Cloud 또는 HyperDX Cloud로 수집하는 경우 HyperDX를 열고 Team Settings → API Keys로 이동한 다음 Ingestion API Key를 복사하십시오.확장 프로그램 구성
Chrome 도구 모음에서 HyperDX Browser Extension 아이콘을 클릭하고 설정을 입력합니다:| Field | Local ClickStack example | Notes |
|---|---|---|
| Enable HyperDX Monitoring | On | 주입을 위한 기본 토글 |
| Service Name | my-frontend-app | 필수 — ClickStack에서 서비스를 식별합니다 |
| API Key | (empty) | Cloud 수집에는 필수이며, 일부 자체 호스팅 구성에서는 선택 사항입니다 |
| Collector URL | http://localhost:4318 | OTLP HTTP 엔드포인트입니다. Cloud 기본값은 https://in-otel.hyperdx.io입니다 |
| Environment | development | 선택 사항 — deployment.environment 리소스 속성을 설정합니다 |
| Trace Propagation Targets | /api\.myapp\.domain/i, /localhost/i | 선택 사항 — 추적 header 전파를 위한 쉼표로 구분된 JavaScript 정규식 패턴입니다 |
| 일치하는 URL에만 삽입 | Off | 계측할 사이트를 제한하려면 활성화합니다 |
| Capture console logs | Off | 브라우저 콘솔 출력을 전달하려면 활성화합니다 |
| Advanced network capture | Off | 상세한 네트워크 요청 캡처를 위해 활성화합니다 |
http://localhost:4318을 가리키고, 추적 전파는 API 및 localhost URL로 제한되어 있습니다.사이트를 둘러보고 세션 생성
Chrome에서 웹사이트나 로컬 애플리케이션을 엽니다 — 예를 들어 프런트엔드 개발 서버라면 http://localhost:3000입니다.페이지에서 평소처럼 상호작용합니다. 링크를 클릭하고, 양식을 제출하고, 오류를 발생시키고, 화면 간에 이동하십시오. 구성이 올바르면 확장 프로그램이 페이지를 로드할 때마다 Browser SDK를 자동으로 주입합니다.세션 리플레이 보기
http://localhost:8080의 HyperDX로 돌아가 왼쪽 사이드바에서 Client Sessions로 이동합니다.세션이 지속 시간과 이벤트 수와 함께 목록에 표시됩니다. ▶️ 버튼을 클릭해 리플레이합니다.타임라인의 상세 수준을 조정하려면 Highlighted 모드와 All Events 모드 사이를 전환하십시오.URL 필터링
| 패턴 | 일치 항목 |
|---|---|
http://homedepot.com/* | homedepot.com의 HTTP만 |
*://homedepot.com/* | homedepot.com의 HTTP 및 HTTPS |
*://*.homedepot.com/* | www.homedepot.com과 같은 하위 도메인 |
https://localhost:3000/* | 포트 3000의 로컬 개발 서버 |
주입 확인
문제 해결
HyperDX에 세션이 표시되지 않음
HyperDX에 세션이 표시되지 않음
- 브라우저 콘솔에서
[HyperDX Extension]로그 메시지나 오류를 확인하세요 - Enable HyperDX Monitoring이 켜져 있고 Service Name이 설정되어 있는지 확인하세요
- ClickStack이 실행 중이고 collector URL이 올바른지 확인하세요(예:
http://localhost:4318) - Client Sessions 보기에서 시간 범위를 조정하세요(지난 15분 시도)
- 브라우저를 하드 새로고침하세요:
Cmd+Shift+R(Mac) 또는Ctrl+Shift+R(Windows/Linux)
chrome-extension://invalid/ 오류
chrome-extension://invalid/ 오류
chrome://extensions에서 확장 프로그램을 다시 로드한 다음, 탭을 하드 새로고침하세요. 탭이 아직 열려 있는 상태에서 확장 프로그램이 업데이트되거나 다시 로드되면 이런 현상이 발생합니다.사이트에 삽입되지 않음
사이트에 삽입되지 않음
- 모니터링이 활성화되어 있고 서비스 이름이 설정되어 있는지 확인하세요
- 일치하는 URL에만 삽입이 켜져 있다면, 현재 페이지 URL이 패턴 중 하나와 일치하는지 확인하세요
- 일부 사이트는 CSP를 통해 확장 프로그램 출처와 인라인 스크립트 삽입을 모두 차단하므로 해당 페이지에서는 삽입이 불가능할 수 있습니다
HyperDX: 콘솔에 apiKey가 없음
HyperDX: 콘솔에 apiKey가 없음
API key 필드가 비어 있으면 정상입니다. 클라우드 엔드포인트를 사용하는 경우 HyperDX에서 수집 API key를 추가하거나, 자체 호스팅 collector가 인증되지 않은 로컬 트래픽을 허용하는 경우에는 무시하세요.
개인정보 보호
더 알아보기
- 세션 리플레이 — 기능 개요, SDK 옵션, 개인정보 보호 설정
- Browser SDK 참고 — 전체 SDK 옵션과 고급 구성
- Session Replay Demo — 소스 코드부터 데모 애플리케이션을 계측하는 방법
- ClickStack 시작하기 — ClickStack을 배포하고 첫 데이터를 수집하세요
- GitHub의 HyperDX Chrome 확장 프로그램 — 소스 코드와 이슈 트래커