ZoneTree.Analytics 1.0.0

ZoneTree.Analytics

Understand your traffic. Measure your product. Own your data.

Web analytics, custom events, and telemetry inside your .NET application.

ZoneTree.Analytics is an embedded analytics engine built on ZoneTree. Record events, keep the dataset on your infrastructure, and query it directly from C#. The engine runs in your process and requires no external database or separate analytics service.

Packages

Both packages target .NET 8, 9, and 10.

What you can build

• One query model. Combine metrics, filters, dimensions, formulas, time buckets, and period comparisons through a typed C# API.
• Pre-aggregation for recurring reports. Matching rollups and optional indexes answer recurring reports; queries they cannot answer fall back to retained event history. Query plans expose coverage and warnings.
• Privacy-conscious defaults. Cookie-free collection, daily anonymous identity rotation, and no stored raw IP addresses or user-agent strings.
• Application-owned storage. Background ingestion, configurable retention, and persistent ZoneTree stores.
• Room to customize. Plug in event filters, enrichers, bot detectors, a user-agent parser, or a geolocation provider. Bot traffic can be excluded or reported separately.

Quick start

In a .NET console project, install the engine:

dotnet add package ZoneTree.Analytics

Replace Program.cs with this complete example:

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}");

Run it with dotnet run. On an empty dataset, it records one page view and revenue of 49.00. The data remains in data/analytics between runs.

Keep one engine per data directory open for the application's lifetime. Events are processed in the background, with an aggregate flush interval of two seconds by default. Normal reporting does not need an explicit flush; this example uses one so its immediate read includes the events it just tracked. Await disposal at shutdown to drain the queue and flush remaining work.

Add it to ASP.NET Core

Install the integration package in an ASP.NET Core project:

dotnet add package ZoneTree.Analytics.AspNetCore

This minimal Program.cs registers the engine and tracks successful HTML page responses:

using ZoneTree.Analytics.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddZoneTreeAnalytics(
    options => options.DataDirectory = "data/analytics");

var app = builder.Build();
app.UseZoneTreeAnalytics();

app.MapGet("/", () => Results.Content(
    "<!doctype html><html><body><h1>Hello analytics</h1></body></html>",
    "text/html"));

await app.RunAsync();

Dependency injection owns the shared engine and disposes it at host shutdown. Inject IAnalyticsTracker to record custom actions, or AnalyticsEngine to query reports.

• Browser collection: map app.MapZoneTreeAnalytics() and load /_analytics/script.js on your pages. Choose either server middleware or browser tracking for each page view to avoid double counting.
• Reporting API: map app.MapZoneTreeAnalyticsApi(), and protect it with app.MapZoneTreeAnalyticsApi().RequireAuthorization() in a host with authentication and authorization configured. Multi-site applications should also configure AuthorizeSite for site-level access.

The ASP.NET Core guide covers collection choices, proxy configuration, and reporting access.

Ask more of your events

The general query API supports totals, grouped reports, time series, and formulas. After tracking purchases with a plan dimension and a revenue value:

var revenue = Metric.Sum("revenue");
var averageOrder = revenue / Metric.Events;

var report = await analytics.QueryAsync(new AnalyticsQuery
{
    Event = "purchase",
    Range = DateRange.ThisMonth,
    Interval = TimeInterval.Day,
    GroupBy = { "plan" },
    Metrics = { Metric.Events, revenue, averageOrder },
    Compare = ComparisonPeriod.PreviousPeriod,
});

foreach (var row in report.Rows)
    Console.WriteLine($"{row.Bucket:yyyy-MM-dd} | {row["plan"]}: {row[revenue]:F2} revenue");

Console.WriteLine($"Average order: {report.Totals[averageOrder]:F2}");

Totals evaluate formulas over the range's totals. Here, the overall average order value is total revenue divided by the number of purchases.

Explore querying, segments and funnels, and the query reference for supported combinations and metric semantics.

A dashboard you can host

Explore traffic, acquisition, audience, events, funnels, and bot activity, run custom queries, and export reports. The dashboard is a .NET server with a static UI, built on these packages. It ships as source in the GitHub repository, not as a NuGet package.

The dashboard guide covers running it with sample data, release builds, and deployment.

Performance

A documented benchmark measures annual reports with previous-period comparisons over 5 million generated events spanning 365 days, including configuration, query plans, individual timings, and methodology.

Matching rollups answer recurring reports from aggregates. Segments, funnels, and unsupported aggregate combinations can require event scans. The benchmarking guide explains how to measure your own workload.

Privacy and data ownership

The default identity strategy recognizes anonymous visitors within a UTC day using a rotating hash. Explicit visitor IDs are keyed hashes and remain stable across days. Raw IP addresses and user-agent strings are used in memory for identity and enrichment, then discarded. Page query strings are excluded by default.

Custom dimensions retain the values your application supplies, so choose what to collect. Configure dimension allow and deny lists, geography precision, identity strategy, and retention to fit your use case. Geography enrichment requires a geolocation provider.

Visitor erasure removes an explicit visitor's retained raw events, dimension-index copies, and active session state. Existing aggregate rollups are not recomputed. Read privacy and identity and retention and erasure for the full behavior.

Operating the engine

Use analytics.GetStatistics() and host logging to monitor the engine. See deployment and lifecycle for scaling and backups, and time and accuracy for identity, count, and reporting semantics.

Documentation

Feedback

Bug reports and focused pull requests are welcome on GitHub. For a reproducible report, include the package version, runtime, relevant options, and a small example in a GitHub issue.

License

Released under the MIT license. Built on ZoneTree.