counterscale

Counterscale은 사용자가 Cloudflare에 직접 호스팅하는 오픈 소스 웹 분석 트래커 및 대시보드입니다. MIT 라이선스로 출시되었으며 배포와 유지 관리가 쉽도록 설계되었으며, README에 따르면 트래픽이 높은 수준에서도 운영 비용이 거의 제로에 가깝습니다. 이 서비스는 주로 Cloudflare Workers와 Workers Analytics Engine을 기반으로 작동합니다. 2025년 2월 기준으로 Workers Analytics Engine의 최대 보관 기간은 90일이므로, 대시보드에서는 최근 90일 동안의 기록된 데이터만 표시할 수 있습니다. Counterscale은 또한 Apache Arrow 파일을 사용하여 R2 버킷에 데이터를 장기 저장하는 기능을 제공합니다. 이 장기 저장 기능은 기본적으로 활성화되어 있으며 CLI를 통해 비활성화할 수 있습니다. 설치하려면 macOS 또는 Linux, Node v20 이상, 그리고 활성화된 Cloudflare 계정이 필요합니다. 배포 전 사용자는 Cloudflare Workers 서브도메인, 계정의 Analytics Engine 베타 활성화, 그리고 최소 Account.Account Analytics 권한이 있는 Cloudflare API 토큰이 필요합니다. 배포는 npx wrangler login으로 시작하여 npx @counterscale/cli@latest install을 실행합니다. 설치 프로그램은 API 토큰을 요청하고 대시보드를 비밀번호로 보호할지 묻습니다. 공개 배포의 경우 '예'를 선택하는 것이 권장되며, '아니오'를 선택하면 대시보드에 누구나 접근할 수 있게 됩니다. 설치 후 서버 애플리케이션은 workers.dev 서브도메인에 배포됩니다. 웹사이트 트래픽을 기록하기 위해 Counterscale은 여러 통합 방법을 제공합니다. 스크립트 로더를 통해 배포된 URL에서 tracker.js를 사용할 수 있습니다. 사용자는 id가 counterscale-script이고 data-site-id 속성과 tracker.js 소스가 포함된 스크립트 태그를 추가할 수 있습니다. 트래커는 npm 패키지인 @counterscale/tracker로도 제공됩니다. 이는 사이트 ID와 리포터 URL로 초기화할 수 있습니다. 클라이언트 모듈은 init, isInitialized, getInitializedClient, trackPageview, cleanup과 같은 메서드를 제공합니다. 별도의 서버 모듈인 @counterscale/tracker/server는 백엔드 분석 트래킹을 지원합니다. 이는 XMLHttpRequest 대신 fetch API를 사용하며, DOM 의존적 기능이 없고, 명시적인 URL 및 호스트네임 파라미터가 필요하며, 'fire-and-forget' 방식이어서 트래킹 오류가 발생해도 예외를 던지지 않습니다. Counterscale에는 고급 옵션이 포함되어 있습니다. autoTrackPageviews를 false로 설정하여 자동 페이지뷰 트래킹을 비활성화할 수 있으며, 이후 trackPageview를 수동으로 호출할 수 있습니다. 배포 URL은 커스텀 도메인 뒤에 배치할 수도 있습니다. CLI는 설치, 인증 및 저장소 관리를 위한 명령어를 제공합니다. install 명령어는 워커 이름과 분석 데이터셋을 사용자 정의할 수 있는 고급 모드와 상세 로그 기록을 지원합니다. 인증 하위 명령어에는 enable, disable, roll이 포함됩니다. 저장소 하위 명령어에는 enable과 disable이 있습니다. 업그레이드는 일반적으로 CLI 설치 프로그램을 다시 실행하는 것을 의미하며, 주요 버전의 경우 릴리스 노트에 설명된 추가 단계가 있을 수 있습니다. 로컬 개발의 경우, Counterscale은 Cloudflare API를 통해 HTTP로 통신하는 Cloudflare Analytics Engine 데이터셋이라는 단 하나의 데이터베이스만 가집니다. 로컬 테스트 데이터베이스가 없으므로 로컬 쓰기는 아무런 동작을 하지 않으며(no-op), 읽기는 프로덕션 Analytics Engine 데이터셋에서 가져옵니다. Cloudflare Analytics Engine은 다른 분석 도구와 마찬가지로 대규모의 고용량 수집 및 쿼리를 저렴하게 처리하기 위해 샘플링을 사용합니다.