> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-1d264819.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Chrome 확장 프로그램

> HyperDX Chrome 확장 프로그램을 사용하여 모든 웹사이트에서 ClickStack 세션 리플레이 및 RUM을 계측

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

<Info>
  **요약**

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

  소요 시간: 10-15분
</Info>

<div id="overview">
  ## 개요
</div>

[HyperDX Chrome 확장 프로그램](https://github.com/kyreddie/hyperdx-chrome-extension)은 방문하는 페이지에 [@hyperdx/browser](https://github.com/hyperdxio/hyperdx-js) SDK를 주입합니다. 이 확장 프로그램은 코드베이스를 수정하지 않고 사이트에서 세션 리플레이, RUM 또는 trace 전파를 디버깅해야 할 때 유용합니다. 예를 들어 서드파티 애플리케이션, 프로덕션 빌드 또는 엄격한 콘텐츠 보안 정책(CSP)이 적용된 로컬 개발 서버에서 활용할 수 있습니다.

SDK는 확장 프로그램 내부에 번들되어 있으므로(\~480 KB) 페이지에서 런타임에 CDN의 스크립트를 로드할 필요가 없습니다. 확장 프로그램은 먼저 외부 `chrome-extension://` 스크립트 주입을 시도하고, CSP가 확장 프로그램 출처의 스크립트를 차단하면 인라인 주입으로 대체합니다.

사용자가 제어하는 데모 애플리케이션에 계측을 추가하는 [Session Replay Demo](/ko/clickstack/example-datasets/session-replay)와 달리, 이 방식은 Chrome에서 여는 **모든** URL에서 작동합니다. 일반 사용자처럼 사이트와 상호작용하여 세션 데이터를 생성합니다.

세션 리플레이의 배경과 ClickStack에서의 역할에 대해서는 [Session Replay](/ko/clickstack/features/session-replay) 기능 페이지를 참조하십시오.

<div id="prerequisites">
  ## 사전 요구사항
</div>

* Google Chrome 또는 Chromium 기반 브라우저(Edge, Brave 등)
* ClickStack을 로컬에서 실행하는 경우 [Docker](https://docs.docker.com/get-docker/)가 설치되어 있어야 합니다
* 포트 4317, 4318, 8080을 사용할 수 있어야 합니다(로컬 ClickStack용)

<div id="running-the-demo">
  ## 데모 실행하기
</div>

<Steps>
  <Step>
    ### 확장 프로그램 리포지토리 복제

    ```shell theme={null}
    git clone https://github.com/kyreddie/hyperdx-chrome-extension
    cd hyperdx-chrome-extension
    ```
  </Step>

  <Step>
    ### 확장 프로그램 설치

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

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

  <Step>
    ### ClickStack 시작

    이미 ClickStack 또는 HyperDX 수집 엔드포인트가 있으면 [확장 프로그램 구성](#configure-extension)으로 건너뛰십시오.

    로컬 ClickStack 스택의 경우 OpenTelemetry collector를 시작합니다. `{{CLICKHOUSE_ENDPOINT}}`와 `{{CLICKHOUSE_PASSWORD}}`를 ClickHouse 연결 정보로 바꾸십시오:

    ```shell theme={null}
    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](http://localhost:8080)에서 HyperDX를 엽니다.

    ClickHouse와 HyperDX UI를 포함한 전체 로컬 배포 방법은 [ClickStack 시작하기](/ko/clickstack/getting-started/oss)를 참조하십시오.
  </Step>

  <Step>
    ### API Key 가져오기

    로컬 ClickStack의 경우 API Key가 필요하지 않을 수 있습니다 — `http://localhost:4318`의 자체 호스팅 collector로 telemetry를 보낼 때는 확장 프로그램에서 해당 필드를 비워 두십시오.

    ClickStack Cloud 또는 HyperDX Cloud로 수집하는 경우 HyperDX를 열고 **Team Settings → API Keys**로 이동한 다음 **Ingestion API Key**를 복사하십시오.
  </Step>

  <Step>
    ### 확장 프로그램 구성

    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**을 클릭한 다음 계측하려는 탭을 다시 로드합니다.

    <Image img="https://mintlify.s3.us-west-1.amazonaws.com/private-7c7dfe99-mintlify-1d264819/images/clickstack/chrome-extension/extension-config.png" alt="로컬 ClickStack 설정이 표시된 HyperDX Chrome 확장 프로그램 구성 팝업" size="sm" />

    위 스크린샷은 일반적인 로컬 설정을 보여줍니다. 모니터링이 활성화되어 있고 서비스 이름이 설정되어 있으며 collector는 `http://localhost:4318`을 가리키고, 추적 전파는 API 및 localhost URL로 제한되어 있습니다.
  </Step>

  <Step>
    ### 사이트를 둘러보고 세션 생성

    Chrome에서 웹사이트나 로컬 애플리케이션을 엽니다 — 예를 들어 프런트엔드 개발 서버라면 [http://localhost:3000](http://localhost:3000)입니다.

    페이지에서 평소처럼 상호작용합니다. 링크를 클릭하고, 양식을 제출하고, 오류를 발생시키고, 화면 간에 이동하십시오. 구성이 올바르면 확장 프로그램이 페이지를 로드할 때마다 Browser SDK를 자동으로 주입합니다.
  </Step>

  <Step>
    ### 세션 리플레이 보기

    [http://localhost:8080](http://localhost:8080)의 HyperDX로 돌아가 왼쪽 사이드바에서 **Client Sessions**로 이동합니다.

    세션이 지속 시간과 이벤트 수와 함께 목록에 표시됩니다. ▶️ 버튼을 클릭해 리플레이합니다.

    타임라인의 상세 수준을 조정하려면 **Highlighted** 모드와 **All Events** 모드 사이를 전환하십시오.
  </Step>
</Steps>

<div id="url-filtering">
  ## URL 필터링
</div>

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

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

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

<div id="verify-injection">
  ## 주입 확인
</div>

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

```text theme={null}
[HyperDX Extension] Configuration valid, injecting HyperDX
[HyperDX Extension] Injected via extension scripts
[HyperDX Extension] HyperDX initialized
```

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

<div id="troubleshooting">
  ## 문제 해결
</div>

<Accordion title="HyperDX에 세션이 표시되지 않음">
  1. 브라우저 콘솔에서 `[HyperDX Extension]` 로그 메시지나 오류를 확인하세요
  2. **Enable HyperDX Monitoring**이 켜져 있고 **Service Name**이 설정되어 있는지 확인하세요
  3. ClickStack이 실행 중이고 collector URL이 올바른지 확인하세요(예: `http://localhost:4318`)
  4. Client Sessions 보기에서 시간 범위를 조정하세요(**지난 15분** 시도)
  5. 브라우저를 하드 새로고침하세요: `Cmd+Shift+R` (Mac) 또는 `Ctrl+Shift+R` (Windows/Linux)
</Accordion>

<Accordion title="chrome-extension://invalid/ 오류">
  `chrome://extensions`에서 확장 프로그램을 다시 로드한 다음, 탭을 하드 새로고침하세요. 탭이 아직 열려 있는 상태에서 확장 프로그램이 업데이트되거나 다시 로드되면 이런 현상이 발생합니다.
</Accordion>

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

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

<div id="privacy">
  ## 개인정보 보호
</div>

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

<div id="learn-more">
  ## 더 알아보기
</div>

* [세션 리플레이](/ko/clickstack/features/session-replay) — 기능 개요, SDK 옵션, 개인정보 보호 설정
* [Browser SDK 참고](/ko/clickstack/ingesting-data/sdks/browser) — 전체 SDK 옵션과 고급 구성
* [Session Replay Demo](/ko/clickstack/example-datasets/session-replay) — 소스 코드부터 데모 애플리케이션을 계측하는 방법
* [ClickStack 시작하기](/ko/clickstack/getting-started) — ClickStack을 배포하고 첫 데이터를 수집하세요
* [GitHub의 HyperDX Chrome 확장 프로그램](https://github.com/kyreddie/hyperdx-chrome-extension) — 소스 코드와 이슈 트래커