ClickHouse usage analytics: events/gauges tables with daily MV

[lohanidamodar]

Summary

Complete rewrite of the usage analytics library with a two-table architecture optimized for both real-time analytics and billing.

Architecture

• Events table (MergeTree) — raw request events with dedicated columns for path, method, status, resource, resourceId, country (LowCardinality), userAgent
• Gauges table (MergeTree) — simple resource snapshots (metric, value, time, tags)
• Daily MV (SummingMergeTree) — pre-aggregates events by metric + tenant + day for fast billing
• No periods — query-time aggregation via toStartOfHour/toStartOfDay instead of write-time fan-out
• Single write path — collect(metric, value, type, tags) routes to correct table; event columns auto-extracted from tags

Key Changes

• Two separate tables instead of one — events have 7 extra columns gauges don't need
• Plain MergeTree for both tables — raw appends, query-time aggregation
• Daily MV with minimal schema (metric, value, time, tenant)
• LowCardinality(String) for country column
• Bloom filter indexes on all filterable columns
• String tenant — setTenant(?string)
• Utopia Query for all read operations — parameterized queries, no SQL injection risk

API

Write

• collect(metric, value, type, tags) — buffer with auto-flush
• addBatch(metrics, type) — direct batch insert
• flush() — write buffered metrics

Read

• find(queries, type) / count(queries, type) / sum(queries, attr, type)
• getTotal(metric, queries, type) — SUM for events, argMax for gauges
• getTotalBatch(metrics, queries, type) — batch totals
• getTimeSeries(metrics, interval, start, end, queries, zeroFill, type)

Billing (Daily MV)

• findDaily(queries) / sumDaily(queries) / sumDailyBatch(metrics, queries)

Test Plan

• Unit tests for Metric schema, getters, validation
• Integration tests for ClickHouse and Database adapters
• PHPStan level max passing
• Linter passing
• Security audit — no SQL injection vulnerabilities
• CI green (CodeQL, Tests, Linter)

[greptile-apps]

getTotal() sums semantically incompatible aggregations

The inline comment says "return whichever is nonzero" but the code actually returns $eventTotal + $gaugeTotal. These two values are computed with fundamentally different aggregation semantics — SUM(value) for events and argMax(value, time) for gauges — so adding them together produces a number with no valid meaning.

In the common case where a metric name only exists in one table this is harmless (one of the two is 0). But if a metric name were ever present in both tables (e.g. during a data migration or a misconfigured adapter), callers would silently receive a corrupted total without any warning.

Consider throwing (or at least returning the dominant value) instead:

if ($eventTotal > 0 && $gaugeTotal > 0) {
    // Metric exists in both tables — this is unexpected; callers should specify $type.
    throw new \RuntimeException(
        "Metric '{$metric}' found in both events and gauges tables. Specify \$type explicitly."
    );
}

Or, if silent fallback is preferred, at least fix the comment to match what the code does.

[greptile-apps]

getTimeSeriesFromTable() truncates float bucket values to int

$value = (int) ($row['agg_value'] ?? 0) will silently truncate any fractional part returned by ClickHouse. For gauge metrics the aggregation expression is argMax(value, time), and for event metrics it is SUM(value). Large event sums can exceed the range of a PHP int on 32-bit hosts, and gauge values can legitimately be fractional (e.g. storage in fractional GB) if the schema ever changes to Float64.

The declared return type in the docblock is array{total: int, data: array<array{value: int, date: string}>}, which locks in int — but the abstract Adapter interface at the getTimeSeries() level does not restrict callers to integer-only metrics. Consider casting to (float) internally and widening the return type, or at minimum documenting the truncation explicitly so future schema changes surface the discrepancy immediately.

[greptile-apps]

Event-specific column filters silently break findDaily/sumDaily/sumDailyBatch

parseQueries($queries, Usage::TYPE_EVENT) validates query attributes against the full event schema (which includes path, method, status, resource, resourceId, userAgent), so no exception is thrown client-side. However the daily table only contains metric, value, time, and optionally tenant. A caller passing Query::equal('path', '/v1/...') produces WHERE \path` = {param_0:String}` against the daily table, causing a ClickHouse "No such column 'path'" server error at runtime.

The same issue affects sumDaily() (line 1761) and sumDailyBatch() (line 1802). A lightweight fix is to validate the attribute name against the daily table's actual column set before building the clause:

private const DAILY_TABLE_COLUMNS = ['metric', 'value', 'time', 'tenant'];

// in findDaily/sumDaily/sumDailyBatch, before parseQueries:
foreach ($queries as $query) {
    $attr = $query->getAttribute();
    if ($attr !== '' && !in_array($attr, self::DAILY_TABLE_COLUMNS, true)) {
        throw new \InvalidArgumentException(
            "Column '{$attr}' does not exist in the daily table. Allowed: "
            . implode(', ', self::DAILY_TABLE_COLUMNS)
        );
    }
}

[greptile-apps]

collect() silently drops event tags on repeated same-metric calls, corrupting path/method attribution

The buffer key is $metric . ':' . $type. When two events for the same metric name arrive with different tags — e.g. collect('bandwidth', 100, 'event', ['path' => '/v1/files']) followed by collect('bandwidth', 200, 'event', ['path' => '/v1/functions']) — only the value is summed; the second call's tags are silently discarded. The single ClickHouse row written at flush time carries path='/v1/files' and value=300, misattributing 200 bytes to the wrong endpoint.

Given that the system has dedicated path, method, status, resource, and resourceId columns specifically for per-path analytics, this aggregation strategy loses the metadata granularity that the schema was designed to preserve. Either:

• Use addBatch() directly (bypassing the buffer) when per-event tag fidelity matters, or
• Change the buffer key to include a hash of the tags so that events with distinct contexts remain separate entries.