콘텐츠로 이동

브라우저 점검

Version-2.1.0

브라우저 점검은 inputs.dialtesting 수집기의 BROWSER 작업 유형으로, Lightpanda 브라우저 엔진을 통해 페이지 접근, 상호작용, 검증을 시뮬레이션하고 페이지 성능, 단계 결과, 실패 원인을 보고합니다. Lightpanda 엔진은 현재 스크린샷을 지원하지 않습니다.

기본 점검 노드 설정은 네트워크 점검을 참고하세요. 이 문서는 브라우저 점검과 관련된 추가 설정, 배포, 문제 해결 방법만 설명합니다.

사용 요구사항

브라우저 점검은 Linux 점검 노드에서 기본적으로 활성화됩니다. Linux가 아닌 환경에서는 DataKit 서비스 모드가 BROWSER 작업을 실행하지 않으며, 로컬 debug 검증 모드는 예외입니다.

노드 런타임은 Lightpanda 브라우저 엔진에 접근할 수 있어야 합니다. DataKit는 BROWSER 작업을 실행할 때 Lightpanda를 강제로 사용하며, 작업의 advance_options.engine은 노드 설정으로 덮어써집니다.

DataKit는 다음 순서로 Lightpanda를 찾습니다.

  1. [inputs.dialtesting.browser].engine_path
  2. LIGHTPANDA_EXECUTABLE_PATH
  3. PATH의 lightpanda
  4. ~/.cache/lightpanda-node/lightpanda

브라우저 점검을 명시적으로 끄려면 dialtesting.conf에 다음을 설정하세요.

[[inputs.dialtesting]]
  [inputs.dialtesting.browser]
    enabled = false

max_concurrency로 동시에 실행되는 브라우저 작업 수를 제한할 수 있습니다. 0은 제한 없음이며, 리소스가 제한된 노드에서는 1로 설정하는 것이 좋습니다.

Kubernetes 배포

Kubernetes에서는 DataKit 이미지를 직접 사용하는 것을 권장합니다.

pubrepo.guance.com/datakit/datakit:<version>

DataKit 이미지에는 Lightpanda가 내장되어 있어 BROWSER 작업을 바로 실행할 수 있습니다. 사용자 정의 Lightpanda 바이너리를 사용하려면 실행 파일을 마운트로 제공하고 engine_path를 설정하세요.

[[inputs.dialtesting]]
  [inputs.dialtesting.browser]
    enabled = true
    engine = "lightpanda"
    engine_path = "/opt/datakit-browser/bin/lightpanda"
    max_concurrency = 10

호스트 배포

호스트 배포에서는 먼저 Lightpanda를 설치해야 합니다. 아래 예시는 Linux 호스트를 기준으로 합니다.

Lightpanda 설치

Lightpanda 설치 방법은 공식 설치 문서를 참고하세요. Linux 호스트에서는 공식 설치 스크립트를 사용할 수 있습니다.

curl -fsSL https://pkg.lightpanda.io/install.sh | bash

버전을 지정할 수도 있습니다. 예를 들면 다음과 같습니다.

curl -fsSL https://pkg.lightpanda.io/install.sh | bash -s "0.3.1"

고정된 버전의 바이너리를 수동으로 설치하려면 x86_64 Linux 예시는 다음과 같습니다.

curl -L -o lightpanda \
  https://github.com/lightpanda-io/browser/releases/download/0.3.1/lightpanda-x86_64-linux
chmod a+x ./lightpanda
sudo install -m 0755 lightpanda /usr/local/bin/lightpanda

arm64/aarch64 Linux에서는 다음을 사용할 수 있습니다.

curl -L -o lightpanda \
  https://github.com/lightpanda-io/browser/releases/download/0.3.1/lightpanda-aarch64-linux
chmod a+x ./lightpanda
sudo install -m 0755 lightpanda /usr/local/bin/lightpanda

설치가 끝나면 버전을 확인하세요.

lightpanda version
lightpanda serve --help

DataKit 설정

점검 수집기 설정을 복사하세요.

cd /usr/local/datakit/conf.d/samples
sudo cp dialtesting.conf.sample ../dialtesting.conf

/usr/local/datakit/conf.d/dialtesting.conf를 편집하고, 브라우저 엔진과 경로를 명시적으로 지정하는 것이 좋습니다.

[[inputs.dialtesting]]
  server = "https://dflux-dial.guance.com"
  region_id = "<your-private-node-id>"
  ak = "<your-ak>"
  sk = "<your-sk>"
  pull_interval = "1m"
  time_out = "30s"

  [inputs.dialtesting.browser]
    engine = "lightpanda"
    engine_path = "/usr/local/bin/lightpanda"
    max_concurrency = 10

  [inputs.dialtesting.tags]
    region = "<your-region>"

환경 변수로 지정할 수도 있습니다.

export LIGHTPANDA_EXECUTABLE_PATH=/usr/local/bin/lightpanda

DataKit가 systemd 서비스로 실행 중이라면, 현재 셸의 export는 보통 DataKit 서비스 프로세스에 전달되지 않습니다. 호스트 배포에서는 dialtesting.conf에 engine_path를 설정하는 것이 더 권장됩니다.

설정을 수정한 뒤 DataKit를 재시작하세요.

sudo datakit service -R

로컬 검증

아직 페이지를 통해 BROWSER 작업이 내려오지 않았다면, 로컬 JSON 작업으로 브라우저 실행 경로를 검증할 수 있습니다. browser_config는 YAML 문자열입니다.

브라우저 스크립트 예시는 다음과 같습니다.

name: browser-homepage
target: https://example.com
timeout_ms: 60000
viewport:
  width: 1280
  height: 720
steps:
  - name: open page
    action: goto
    url: https://example.com
  - name: assert title
    action: assert_title
    contains: Example

/tmp/dialtesting-browser-task.json를 생성하세요. JSON을 작성할 때는 위 YAML을 문자열로 browser_config에 넣고, 줄바꿈은 \n으로 표시해야 합니다.

{
  "BROWSER": [
    {
      "name": "browser-homepage",
      "url": "https://example.com",
      "status": "OK",
      "frequency": "1m",
      "post_url": "https://openway.guance.com?token=<your-token>",
      "browser_config": "name: browser-homepage\ntarget: https://example.com\ntimeout_ms: 60000\nviewport:\n  width: 1280\n  height: 720\nsteps:\n  - name: open page\n    action: goto\n    url: https://example.com\n  - name: assert title\n    action: assert_title\n    contains: Example\n"
    }
  ]
}

dialtesting.conf의 server를 임시로 로컬 파일 주소로 바꾸세요.

[[inputs.dialtesting]]
  server = "file:///tmp/dialtesting-browser-task.json"
  pull_interval = "10s"

  [inputs.dialtesting.browser]
    engine = "lightpanda"
    engine_path = "/usr/local/bin/lightpanda"
    max_concurrency = 10

debug로 실행합니다.

datakit debug --input-conf /usr/local/datakit/conf.d/dialtesting.conf

정상이라면 메트릭에서 BROWSER 작업을 볼 수 있어야 합니다.

curl -s http://127.0.0.1:9529/metrics | grep datakit_dialtesting

검증이 끝나면 server, region_id, ak, sk 등의 설정을 실제 점검 노드 설정으로 복원하세요.

BROWSER 작업 예시

BROWSER 작업은 browser_config로 브라우저 스크립트를 정의합니다. browser_config는 YAML 문자열이며, 자주 쓰는 필드는 다음과 같습니다.

브라우저 점검 설정 YAML은 페이지 녹화로 생성할 수 있으며, 자세한 방법은 브라우저 점검 녹화 안내를 참고하세요.

필드 타입 필수 여부 설명
name string N 스크립트 이름
target string N 기본 대상 주소, goto 단계에 URL이 없을 때 사용
timeout_ms int N 스크립트 전체 타임아웃, 밀리초 단위
viewport.width int N 브라우저 뷰포트 너비
viewport.height int N 브라우저 뷰포트 높이
tags object N 사용자 정의 태그
steps array Y 브라우저 실행 단계

steps에서는 goto, click, input, wait_for_selector, assert_title, assert_url, assert_text 등의 동작과 검증을 사용할 수 있습니다. 전체 작업 JSON에서 browser_config는 BROWSER 작업 객체 안에 있습니다.

{
  "BROWSER": [
    {
      "name": "browser-homepage",
      "url": "https://example.com",
      "status": "OK",
      "frequency": "1m",
      "post_url": "https://openway.guance.com?token=<your-token>",
      "browser_config": "<browser_config YAML string>"
    }
  ]
}

스크린샷 지원

Lightpanda 엔진은 현재 스크린샷을 지원하지 않습니다. 작업에서 advance_options.screenshot_on_failure = true를 켜더라도 steps[].screenshot은 생성되지 않습니다.

문제 해결

DataKit 메트릭으로 작업과 전송 상태를 확인하세요.

curl -s http://127.0.0.1:9529/metrics | grep datakit_dialtesting

브라우저 엔진 환경은 다음 명령으로 확인할 수 있습니다.

echo $LIGHTPANDA_EXECUTABLE_PATH
$LIGHTPANDA_EXECUTABLE_PATH version
command -v lightpanda

자주 발생하는 문제는 다음과 같습니다.

  • 작업을 가져오지 못함: server, region_id, ak, sk 설정이 올바른지 확인하고, datakit_dialtesting_task_number{protocol="BROWSER"}가 0보다 큰지 확인하세요.
  • 페이지에 BROWSER 작업은 내려왔지만 노드가 실행하지 않음: [inputs.dialtesting.browser].enabled = false를 명시적으로 설정하지 않았는지 확인하고, DataKit 로그에 browser.enabled is false or unsupported가 있는지 확인하세요.
  • 작업이 보고되지 않음: 작업 post_url에 접근할 수 있는지 확인하고, 전송 실패, 캐시, 폐기 관련 메트릭이 계속 증가하는지 확인하세요.
  • 브라우저가 시작되지 않음: engine_path, LIGHTPANDA_EXECUTABLE_PATH 또는 PATH의 lightpanda를 DataKit 프로세스가 접근할 수 있는지 확인하세요.
  • 브라우저 의존성이 누락됨: Kubernetes에서는 datakit:<version> 이미지를 직접 사용하는 것을 권장합니다. 호스트 배포에서는 Lightpanda가 올바르게 설치되었는지 확인하세요.
  • 스크린샷이 업로드되지 않음: Lightpanda 엔진은 현재 스크린샷을 생성하지 않습니다.

문서 평가

이 페이지가 도움이 되었나요?