Chrome 확장 프로그램 - ClickHouse Documentation

요약이 가이드에서는 HyperDX Chrome 확장 프로그램을 사용해 임의의 웹사이트에 ClickStack Browser SDK를 주입하는 방법을 설명합니다. 대상 애플리케이션의 소스 코드를 변경할 필요는 없습니다 — 확장 프로그램을 한 번만 구성한 뒤 사이트를 둘러보고 ClickStack에서 세션 리플레이를 확인하십시오.소요 시간: 10-15분

개요

HyperDX Chrome 확장 프로그램은 방문하는 페이지에 @hyperdx/browser SDK를 주입합니다. 이 확장 프로그램은 코드베이스를 수정하지 않고 사이트에서 세션 리플레이, RUM 또는 trace 전파를 디버깅해야 할 때 유용합니다. 예를 들어 서드파티 애플리케이션, 프로덕션 빌드 또는 엄격한 콘텐츠 보안 정책(CSP)이 적용된 로컬 개발 서버에서 활용할 수 있습니다. SDK는 확장 프로그램 내부에 번들되어 있으므로(~480 KB) 페이지에서 런타임에 CDN의 스크립트를 로드할 필요가 없습니다. 확장 프로그램은 먼저 외부 chrome-extension:// 스크립트 주입을 시도하고, CSP가 확장 프로그램 출처의 스크립트를 차단하면 인라인 주입으로 대체합니다. 사용자가 제어하는 데모 애플리케이션에 계측을 추가하는 Session Replay Demo와 달리, 이 방식은 Chrome에서 여는 모든 URL에서 작동합니다. 일반 사용자처럼 사이트와 상호작용하여 세션 데이터를 생성합니다. 세션 리플레이의 배경과 ClickStack에서의 역할에 대해서는 Session Replay 기능 페이지를 참조하십시오.

사전 요구사항

Google Chrome 또는 Chromium 기반 브라우저(Edge, Brave 등)
ClickStack을 로컬에서 실행하는 경우 Docker가 설치되어 있어야 합니다
포트 4317, 4318, 8080을 사용할 수 있어야 합니다(로컬 ClickStack용)

데모 실행하기

확장 프로그램 리포지토리 복제

git clone https://github.com/kyreddie/hyperdx-chrome-extension
cd hyperdx-chrome-extension

확장 프로그램 설치

Chrome을 열고 chrome://extensions로 이동합니다.
개발자 모드를 활성화합니다(오른쪽 상단).
압축해제된 확장 프로그램을 로드를 클릭합니다.
복제한 hyperdx-chrome-extension 디렉터리를 선택합니다.

확장 프로그램은 도구 모음에 HyperDX Browser Extension으로 표시됩니다.

ClickStack 시작

이미 ClickStack 또는 HyperDX 수집 엔드포인트가 있으면 확장 프로그램 구성으로 건너뛰십시오.로컬 ClickStack 스택의 경우 OpenTelemetry collector를 시작합니다. {{CLICKHOUSE_ENDPOINT}}와 {{CLICKHOUSE_PASSWORD}}를 ClickHouse 연결 정보로 바꾸십시오:

export CLICKHOUSE_ENDPOINT={{CLICKHOUSE_ENDPOINT}}
export CLICKHOUSE_PASSWORD={{CLICKHOUSE_PASSWORD}}

docker run \
  -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} \
  -p 8080:8080 \
  -p 4317:4317 \
  -p 4318:4318 \
  clickhouse/clickstack-otel-collector:latest

UI가 실행 중인지 확인하려면 http://localhost:8080에서 HyperDX를 엽니다.ClickHouse와 HyperDX UI를 포함한 전체 로컬 배포 방법은 ClickStack 시작하기를 참조하십시오.

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	상세한 네트워크 요청 캡처를 위해 활성화합니다

Save Configuration을 클릭한 다음 계측하려는 탭을 다시 로드합니다.위 스크린샷은 일반적인 로컬 설정을 보여줍니다. 모니터링이 활성화되어 있고 서비스 이름이 설정되어 있으며 collector는 http://localhost:4318을 가리키고, 추적 전파는 API 및 localhost URL로 제한되어 있습니다.

사이트를 둘러보고 세션 생성

Chrome에서 웹사이트나 로컬 애플리케이션을 엽니다 — 예를 들어 프런트엔드 개발 서버라면 http://localhost:3000입니다.페이지에서 평소처럼 상호작용합니다. 링크를 클릭하고, 양식을 제출하고, 오류를 발생시키고, 화면 간에 이동하십시오. 구성이 올바르면 확장 프로그램이 페이지를 로드할 때마다 Browser SDK를 자동으로 주입합니다.

세션 리플레이 보기

http://localhost:8080의 HyperDX로 돌아가 왼쪽 사이드바에서 Client Sessions로 이동합니다.세션이 지속 시간과 이벤트 수와 함께 목록에 표시됩니다. ▶️ 버튼을 클릭해 리플레이합니다.타임라인의 상세 수준을 조정하려면 Highlighted 모드와 All Events 모드 사이를 전환하십시오.

URL 필터링

기본적으로 모니터링이 활성화되어 있으면 확장 기능이 방문하는 모든 페이지에 SDK를 삽입합니다. 삽입 대상을 특정 사이트로 제한하려면 일치하는 URL에만 삽입을 켜고 패턴을 한 줄에 하나씩 추가하거나 쉼표로 구분해 추가하십시오.

패턴	일치 항목
`http://homedepot.com/*`	`homedepot.com`의 HTTP만
`://homedepot.com/`	`homedepot.com`의 HTTP 및 HTTPS
`://.homedepot.com/*`	`www.homedepot.com`과 같은 하위 도메인
`https://localhost:3000/*`	포트 3000의 로컬 개발 서버

URL 패턴을 저장한 후 탭을 새로고침하십시오.

주입 확인

모니터링 중인 페이지에서 DevTools를 열고(Console 탭), 페이지를 새로고침한 뒤 다음 항목을 확인합니다:

[HyperDX Extension] Configuration valid, injecting HyperDX
[HyperDX Extension] Injected via extension scripts
[HyperDX Extension] HyperDX initialized

확장 프로그램에서 제공되는 스크립트가 CSP에 의해 차단되면, 확장 프로그램은 폴백 메시지를 로그에 남기고 인라인 삽입 방식으로 다시 시도합니다.

문제 해결

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://extensions에서 확장 프로그램을 다시 로드한 다음, 탭을 하드 새로고침하세요. 탭이 아직 열려 있는 상태에서 확장 프로그램이 업데이트되거나 다시 로드되면 이런 현상이 발생합니다.

사이트에 삽입되지 않음

모니터링이 활성화되어 있고 서비스 이름이 설정되어 있는지 확인하세요
일치하는 URL에만 삽입이 켜져 있다면, 현재 페이지 URL이 패턴 중 하나와 일치하는지 확인하세요
일부 사이트는 CSP를 통해 확장 프로그램 출처와 인라인 스크립트 삽입을 모두 차단하므로 해당 페이지에서는 삽입이 불가능할 수 있습니다

HyperDX: 콘솔에 apiKey가 없음

API key 필드가 비어 있으면 정상입니다. 클라우드 엔드포인트를 사용하는 경우 HyperDX에서 수집 API key를 추가하거나, 자체 호스팅 collector가 인증되지 않은 로컬 트래픽을 허용하는 경우에는 무시하세요.

개인정보 보호

이 확장 프로그램은 방문하는 웹페이지에 관측성 코드를 삽입합니다. 디버깅이 허용된 사이트에서만 사용하십시오. API Key를 다른 사람과 공유하거나 버전 관리 시스템에 커밋하지 마십시오.

더 알아보기

세션 리플레이 — 기능 개요, SDK 옵션, 개인정보 보호 설정
Browser SDK 참고 — 전체 SDK 옵션과 고급 구성
Session Replay Demo — 소스 코드부터 데모 애플리케이션을 계측하는 방법
ClickStack 시작하기 — ClickStack을 배포하고 첫 데이터를 수집하세요
GitHub의 HyperDX Chrome 확장 프로그램 — 소스 코드와 이슈 트래커

​개요

​사전 요구사항

​데모 실행하기

​확장 프로그램 리포지토리 복제

​확장 프로그램 설치

​ClickStack 시작

​API Key 가져오기

​확장 프로그램 구성

​사이트를 둘러보고 세션 생성

​세션 리플레이 보기

​URL 필터링

​주입 확인

​문제 해결

​개인정보 보호

​더 알아보기

개요

사전 요구사항

데모 실행하기

확장 프로그램 리포지토리 복제

확장 프로그램 설치

ClickStack 시작

API Key 가져오기

확장 프로그램 구성

사이트를 둘러보고 세션 생성

세션 리플레이 보기

URL 필터링

주입 확인

문제 해결

개인정보 보호

더 알아보기