User manual

사용자 매뉴얼

관리자 화면은 웹 페이지를 불러올 때 사용한 에너지를 측정하고, 측정 조건을 조정하며, 단일 URL 또는 여러 URL의 측정 작업을 실행하는 도구입니다. 결과 에너지는 줄(J) 단위로 제공되며, 측정 레코드와 API를 통해 후속 분석에 사용할 수 있습니다.

1. Measurement settings

측정 설정 화면

Measurement Settings에서는 측정의 반복 횟수, 페이지 로드 대기 시간, 시스템 안정화 시간, 실패 재시도 정책을 설정합니다. Save를 누르면 이후에 시작하는 측정에 적용됩니다.

입력 항목

자동 표시 항목과 버튼

2. URL analysis

URL 분석 화면

URL Analysis에서는 한 개의 URL을 바로 측정하거나, URL 목록 파일을 올려 여러 페이지를 순차적으로 측정할 수 있습니다.

단일 URL 측정

파일 기반 배치 측정

URL 파일 작성 예시

TXT와 CSV 모두 URL을 한 줄에 하나씩 작성합니다. CSV는 헤더 없이 첫 번째 열에 URL만 넣으세요. 설명이나 주석 행은 넣지 않습니다.

https://www.example.com/
https://www.example.com/products
https://www.example.org/about

Client API reference

클라이언트 API

URL에서 모델 입력값을 생성한 뒤 해당 입력값으로 페이지의 예상 에너지 사용량을 조회할 수 있습니다. 모든 요청은 Content-Type: application/json을 사용합니다.

URL 입력값 생성 API

POST /page-features/collect는 전달받은 URL을 별도의 Chrome/CDP 브라우저에서 로드하고 네트워크, Resource Timing, DOM, JavaScript/CSS Coverage 정보를 수집해 모델 입력값을 생성합니다. URL은 http:// 또는 https://로 시작해야 합니다.

{
  "url": "https://www.example.com"
}

응답에는 요청한 url, 모델 입력 계약을 나타내는 featureSetId, 정확히 25개의 camelCase 정수 값이 담긴 features가 포함됩니다. Coverage 수집 상태는 jsCoverageStatus와 cssCoverageStatus로 확인하며, 부분 실패나 참고 사항은 coverageErrorCode와 warnings에 표시됩니다.

에너지 예측 API

POST /page-energy/predictions는 /page-features/collect가 반환한 featureSetId와 features에 labelScope: "PACKAGE_PLUS_DRAM"을 더한 요청을 받아 페이지의 예상 에너지 사용량을 반환합니다. 응답의 predictedEnergyJ가 클라이언트가 사용할 예측 결과이며 단위는 줄(J)입니다.

Canonical record schema

Schema

아래 필드는 정규 레코드 및 학습 데이터셋에서 사용하는 핵심 컬럼입니다. 기본 예측 대상(label)은 energy_package_dram_j입니다.

Input and output

INPUT JSON 형식

예측 API는 camelCase의 정확히 25개 정수 feature를 요구합니다. 모든 값은 0 이상 64-bit 정수여야 합니다.

{
  "labelScope": "PACKAGE_PLUS_DRAM",
  "featureSetId": "kepler-page-energy-b-v1",
  "features": {
    "requestCount": 120, "thirdPartyRequestCount": 12, "distinctDomainCount": 8,
    "transferSizeDocument": 12000, "transferSizeScript": 840000, "transferSizeCss": 120000,
    "transferSizeImage": 240000, "transferSizeFont": 0, "transferSizeMedia": 0,
    "transferSizeXhrFetch": 32000, "transferSizeOther": 0,
    "decodedBodySizeDocument": 25000, "decodedBodySizeScript": 2300000, "decodedBodySizeCss": 410000,
    "decodedBodySizeImage": 610000, "decodedBodySizeFont": 0, "decodedBodySizeMedia": 0,
    "decodedBodySizeXhrFetch": 80000, "decodedBodySizeOther": 0,
    "domNodeCount": 1800, "domDepth": 18,
    "jsTotalBytesTotal": 2400000, "jsUnusedBytesTotal": 630000,
    "cssTotalBytesTotal": 410000, "cssUnusedBytesTotal": 150000
  }
}

OUTPUT JSON 형식

{
  "status": "READY",
  "labelScope": "PACKAGE_PLUS_DRAM",
  "target": "energy_package_dram_j",
  "predictedEnergyJ": 18.42,
  "fallbackUsed": false,
  "fallbackReason": null,
  "modelKey": "page-energy-model-b",
  "modelRunId": "00000000-0000-0000-0000-000000000000"
}