Add country column to events table for geo analytics

Adds a LowCardinality(String) country column to the ClickHouse events
table, derived from GeoIP lookup on client IP. This enables geographic
breakdowns of API requests without requiring high-cardinality IP storage.

https://claude.ai/code/session_01UCN4sKD3Zkdbimn3QgTHSB

Author: claude

src/Usage/Adapter.php

@@ -8,7 +8,7 @@
  * Two main data types:
  *
  * 1. **Events** – Append-only log of API requests, executions, bandwidth, etc.
- *    Rich dimensions (path, method, status, userAgent, resource, …)
+ *    Rich dimensions (path, method, status, userAgent, country, resource, …)
  *    allow Cloudflare-style analytics with flexible filtering.
  *    ClickHouse: SummingMergeTree with hourly/daily materialized rollups.
  *
@@ -21,7 +21,7 @@ abstract class Adapter
     /** Known event dimension columns (validated in filters/groupBy) */
     public const EVENT_DIMENSIONS = [
         'metric', 'path', 'method', 'status',
-        'userAgent', 'resource', 'resourceId',
+        'userAgent', 'country', 'resource', 'resourceId',
     ];
 
     /** Known gauge dimension columns */
@@ -66,7 +66,7 @@ abstract public function healthCheck(): array;
      *   - value    (int|float) e.g. request count, bytes, ms
      *
      * Plus optional dimensions:
-     *   - path, method, status, userAgent, resource, resourceId
+     *   - path, method, status, userAgent, country, resource, resourceId
      *
      * @param array<array<string,mixed>> $events
      */

src/Usage/Adapter/ClickHouse.php

@@ -13,8 +13,8 @@
  * Stores usage data in two table families:
  *
  * 1. **events** (SummingMergeTree) – append-only API analytics & metered usage.
- *    Columns: timestamp, metric, value, path, method, status, userAgent, resource, resourceId, tenant.
- *    ORDER BY (tenant, metric, resource, resourceId, path, method, status, userAgent, timestamp) for fast range scans.
+ *    Columns: timestamp, metric, value, path, method, status, userAgent, country, resource, resourceId, tenant.
+ *    ORDER BY (tenant, metric, resource, resourceId, path, method, status, userAgent, country, timestamp) for fast range scans.
  *    Hourly and daily rollups via SummingMergeTree time-bucket grouping.
  *
  * 2. **gauges** (ReplacingMergeTree) – point-in-time resource counts.
@@ -139,8 +139,8 @@ public function setup(): void
         $eventsTable = $this->eventsTable();
         $tenantCol = $this->sharedTables ? "tenant Nullable(String),\n                " : '';
         $orderKey = $this->sharedTables
-            ? '(tenant, metric, resource, resourceId, path, method, status, userAgent, timestamp)'
-            : '(metric, resource, resourceId, path, method, status, userAgent, timestamp)';
+            ? '(tenant, metric, resource, resourceId, path, method, status, userAgent, country, timestamp)'
+            : '(metric, resource, resourceId, path, method, status, userAgent, country, timestamp)';
 
         $this->query("
             CREATE TABLE IF NOT EXISTS {$eventsTable} (
@@ -151,6 +151,7 @@ public function setup(): void
                 method LowCardinality(String) DEFAULT '',
                 status UInt16 DEFAULT 0,
                 userAgent String DEFAULT '',
+                country LowCardinality(String) DEFAULT '',
                 resource LowCardinality(String) DEFAULT '',
                 resourceId String DEFAULT '',
                 INDEX idx_metric (metric) TYPE bloom_filter GRANULARITY 1,
@@ -530,6 +531,7 @@ private function buildEventRow(array $event): array
             'method' => (string) ($event['method'] ?? ''),
             'status' => (int) ($event['status'] ?? 0),
             'userAgent' => (string) ($event['userAgent'] ?? ''),
+            'country' => (string) ($event['country'] ?? ''),
             'resource' => (string) ($event['resource'] ?? ''),
             'resourceId' => (string) ($event['resourceId'] ?? ''),
         ];

tests/Usage/UsageUnitTest.php

@@ -37,6 +37,7 @@ public function testEventDimensions(): void
         $this->assertContains('method', Adapter::EVENT_DIMENSIONS);
         $this->assertContains('status', Adapter::EVENT_DIMENSIONS);
         $this->assertContains('userAgent', Adapter::EVENT_DIMENSIONS);
+        $this->assertContains('country', Adapter::EVENT_DIMENSIONS);
         $this->assertContains('resource', Adapter::EVENT_DIMENSIONS);
         $this->assertContains('resourceId', Adapter::EVENT_DIMENSIONS);
     }