원문 캡처 · github.com
원문 캡처 · github.com

ZoneTree.Analytics는 .NET 8·9·10 애플리케이션 안에서 이벤트를 수집하고 분석하는 임베디드 엔진이다. 별도 데이터베이스나 분석 서비스 없이 애플리케이션이 데이터를 직접 보관하고 C# API로 조회할 수 있으며, 선택적으로 ASP.NET Core 연동과 호스팅 가능한 대시보드를 사용할 수 있다.

  • 웹사이트 방문·페이지 조회, 제품 전환 퍼널, 서비스 처리 시간 등을 측정할 수 있다.
  • 코어 라이브러리는 이벤트 필터와 보존 기간을 설정할 수 있고, 원시 IP 주소와 사용자 에이전트 문자열을 저장하지 않는 기본값을 제공한다.
  • 성능 수치는 500만 건의 생성 이벤트를 대상으로 한 특정 환경의 벤치마크 결과이며, 지연 시간 보장은 아니다.

설치와 기본 사용

.NET 프로젝트에서 NuGet 패키지를 설치한다.

bash
dotnet add package ZoneTree.Analytics

아래 예제는 페이지 조회와 구매 이벤트를 기록한 뒤 최근 30일의 웹 보고서와 매출 합계를 조회한다.

csharp
using ZoneTree.Analytics;
using ZoneTree.Analytics.Web;

await using var analytics = AnalyticsEngine.Open("data/analytics");

// Track a page view and a business event for the same identified visitor.
var pageView = AnalyticsEvent.PageView("https://example.com/pricing");
pageView.VisitorId = "customer-42";
await analytics.TrackAsync(pageView);

await analytics.TrackAsync(new AnalyticsEvent("purchase")
{
 VisitorId = "customer-42",
 Dimensions = { ["plan"] = "pro" },
 Values = { ["revenue"] = 49.0 },
});

// Make the events visible before reading them in this short-lived example.
await analytics.FlushAsync();

var traffic = await analytics.Web.GetSummaryAsync(new WebReportRequest
{
 Range = DateRange.LastDays(30),
});

var sales = await analytics.QueryAsync(new AnalyticsQuery
{
 Event = "purchase",
 Range = DateRange.LastDays(30),
 Metrics = { Metric.Events, Metric.Sum("revenue") },
});

Console.WriteLine($"Page views: {traffic.Summary.PageViews}");
Console.WriteLine($"Revenue: {sales.Totals[Metric.Sum("revenue")]:F2}");

dotnet run으로 실행한다. 비어 있는 데이터셋에서는 페이지 조회 한 건과 매출 49.00을 기록하며, 금액 표시는 현재 문화권 설정을 따른다. 데이터는 data/analytics에 실행 간 보존된다.

애플리케이션 수명 동안 데이터 디렉터리마다 엔진 하나만 열어야 한다. 이벤트는 백그라운드에서 처리되고, 기본 집계 플러시 간격은 2초다. 일반적인 보고서 조회에는 명시적인 플러시가 필요하지 않지만, 위 예제는 방금 기록한 이벤트가 즉시 조회에 포함되도록 플러시한다. 종료할 때는 엔진을 비동기 폐기해 대기열을 처리하고 남은 작업을 플러시해야 한다.

ASP.NET Core와 대시보드

ASP.NET Core 프로젝트에는 통합 패키지를 설치한다.

bash
dotnet add package ZoneTree.Analytics.AspNetCore

통합 기능은 성공한 HTML 페이지 응답 추적, 브라우저 수집, 보고 API를 제공한다. 브라우저 수집은 app.MapZoneTreeAnalytics()를 연결하고 페이지에서 /_analytics/script.js를 불러와 설정한다. 같은 페이지 조회를 서버 미들웨어와 브라우저 추적 양쪽에서 수집하면 중복 집계되므로 둘 중 하나를 선택해야 한다.

보고 API는 app.MapZoneTreeAnalyticsApi()로 연결할 수 있다. 인증과 권한 부여를 구성한 호스트에서는 app.MapZoneTreeAnalyticsApi().RequireAuthorization()으로 경로 그룹을 보호한다. 여러 사이트를 운영하는 경우 사이트별 접근을 위해 AuthorizeSite도 설정해야 한다. 설정과 프록시 구성은 ASP.NET Core 안내서에서 확인할 수 있다.

포함된 대시보드에서는 트래픽, 유입 경로, 사용자, 이벤트, 퍼널, 봇 활동을 살펴보고 사용자 지정 질의를 실행하거나 보고서를 내보낼 수 있다. 저장소 루트에서 의존성을 설치한 뒤 샘플 데이터와 함께 실행한다.

bash
yarn install
yarn dashboard --Analytics:SeedDemo=true

개발 모드에서는 UI가 자동으로 시작되며, http://127.0.0.1:5088/에서 확인할 수 있다. 데모 데이터는 비어 있는 기본 데이터셋에 채워진다. 실제 데이터를 사용하려면 --Analytics:SeedDemo=true 옵션을 생략한다. 코어 라이브러리 자체에는 Node.js나 Yarn이 필요하지 않다. 배포 조건은 대시보드 안내서를 참고할 수 있다.

성능과 데이터 관리 조건

저장소의 벤치마크 보고서는 365일에 걸친 생성 이벤트 500만 건으로 전년 동기 비교를 포함한 연간 보고서를 측정했다. Intel Core Ultra 7 265KF, 메모리 64GiB, Windows x64, .NET 10.0.6 Debug 호스트에서 범위별 30회 워밍업 측정을 수행했다. 수치에는 루프백 HTTP 응답 전송과 JSON 파싱이 포함되며 차트 렌더링은 제외된다. 데이터의 그룹 카디널리티는 낮았고, 필터 보고서는 설정된 커버링 롤업 인덱스를 사용했다.

작업중앙값p95
최대 세 요청을 동시에 처리하는 전체 개요 보고서 6개84.0 ms87.0 ms
GitHub 트래픽으로 필터링한 국가별 분석13.5 ms14.0 ms

제작자는 이 결과가 해당 작업의 측정치일 뿐 지연 시간 보장은 아니라고 설명한다. 반복 보고서는 일치하는 롤업으로 처리할 수 있지만, 세그먼트·퍼널과 지원되지 않는 집계 조합은 이벤트 스캔이 필요할 수 있다. 보고서에는 설정, 질의 계획, 개별 측정값과 방법론이 담겨 있다.

기본 익명 식별은 UTC 날짜 단위로 순환 해시를 사용한다. 명시적 방문자 ID는 키가 있는 해시로 처리되며 날짜가 바뀌어도 유지된다. 원시 IP 주소와 사용자 에이전트 문자열은 식별과 데이터 보강을 위해 메모리에서 사용한 뒤 폐기하고, 페이지 URL의 쿼리 문자열은 기본적으로 제외한다. 사용자 지정 차원에는 애플리케이션이 제공한 값이 보존되므로 수집할 항목을 신중히 선택해야 한다. 차원 허용·거부 목록, 위치 정보의 정밀도, 식별 전략, 보존 기간을 설정할 수 있으며 위치 정보 보강에는 별도 제공자가 필요하다.

방문자 삭제는 해당 방문자의 보존된 원시 이벤트, 차원 인덱스 사본, 활성 세션 상태를 제거하지만 기존 집계 롤업은 다시 계산하지 않는다. 자세한 동작은 개인정보와 식별 및 보존과 삭제 문서에 설명돼 있다.

데이터 디렉터리는 프로세스 간에도 엔진 하나가 독점적으로 소유해야 하며 영구 저장소에 둬야 한다. 별도 디렉터리를 쓰는 복제본은 서로 다른 데이터셋을 갖는다. 이벤트 대기열은 크기가 제한돼 있다. 대기열이 가득 찼을 때 Track은 기본적으로 이벤트를 버리고, TrackAsync는 공간이 생길 때까지 비동기로 기다린다. 두 메서드 모두 이벤트가 수락됐는지 반환하므로 드롭 통계를 모니터링해야 한다.

집계는 성공적으로 플러시될 때까지 버퍼에 남아 있어 충돌 시 플러시되지 않은 집계를 잃을 수 있다. 지속성 레코드는 ZoneTree의 쓰기 전 로그 보장을 따르므로 정상 종료 시 플러시가 완료되도록 해야 한다. 기본 보존 기간은 원시 이벤트 90일, 시간별 롤업 400일이며 일별 롤업은 무기한 보존된다. 기본 활성 롤업 단위는 시간과 일이다. 기본 정밀도에서 고유 개수는 행당 식별자 4,096개까지 정확하고, 그 이후 표준 오차는 약 0.8%다. 질의 계획과 경고를 확인해 요청 범위를 이벤트 이력이나 집계가 충족하는지 살펴볼 수 있다.

추가 자료

MIT 라이선스로 배포되며 ZoneTree를 기반으로 한다.