feat: add country and userAgent as event columns

- country: LowCardinality(Nullable(String)) for efficient low-cardinality storage
- userAgent: Nullable(String) with bloom filter index
- Both extracted from tags into dedicated columns like other event fields
- Added getCountry() and getUserAgent() getters on Metric

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: lohanidamodar

src/Usage/Adapter/ClickHouse.php

@@ -1202,6 +1202,11 @@ private function getColumnType(string $id, string $type = 'event'): string
             throw new Exception("Attribute {$id} not found in {$type} schema");
         }
 
+        // Country uses LowCardinality for efficient storage of low-cardinality values
+        if ($id === 'country') {
+            return 'LowCardinality(Nullable(String))';
+        }
+
         $attributeType = is_string($attribute['type'] ?? null) ? $attribute['type'] : 'string';
         $baseType = match ($attributeType) {
             'integer' => 'Int64',

src/Usage/Metric.php

@@ -40,7 +40,7 @@ class Metric extends ArrayObject
     /**
      * Event-specific column names that are extracted from tags into dedicated columns.
      */
-    public const EVENT_COLUMNS = ['path', 'method', 'status', 'resource', 'resourceId'];
+    public const EVENT_COLUMNS = ['path', 'method', 'status', 'resource', 'resourceId', 'country', 'userAgent'];
 
     /**
      * Construct a new metric object.
@@ -199,6 +199,28 @@ public function getResourceId(): ?string
         return is_string($resourceId) ? $resourceId : null;
     }
 
+    /**
+     * Get country code (event metrics only).
+     *
+     * @return string|null ISO 3166-1 alpha-2 country code, or null if not set
+     */
+    public function getCountry(): ?string
+    {
+        $country = $this->getAttribute('country', null);
+        return is_string($country) ? $country : null;
+    }
+
+    /**
+     * Get user agent (event metrics only).
+     *
+     * @return string|null The user agent string, or null if not set
+     */
+    public function getUserAgent(): ?string
+    {
+        $userAgent = $this->getAttribute('userAgent', null);
+        return is_string($userAgent) ? $userAgent : null;
+    }
+
     /**
      * Get tags.
      *
@@ -450,6 +472,24 @@ public static function getEventSchema(): array
                 'array' => false,
                 'filters' => [],
             ],
+            [
+                '$id' => 'country',
+                'type' => 'string',
+                'size' => 2,
+                'required' => false,
+                'signed' => true,
+                'array' => false,
+                'filters' => [],
+            ],
+            [
+                '$id' => 'userAgent',
+                'type' => 'string',
+                'size' => 512,
+                'required' => false,
+                'signed' => true,
+                'array' => false,
+                'filters' => [],
+            ],
             [
                 '$id' => 'tags',
                 'type' => 'string',
@@ -569,6 +609,16 @@ public static function getEventIndexes(): array
                 'type' => 'key',
                 'attributes' => ['resourceId'],
             ],
+            [
+                '$id' => 'index-country',
+                'type' => 'key',
+                'attributes' => ['country'],
+            ],
+            [
+                '$id' => 'index-userAgent',
+                'type' => 'key',
+                'attributes' => ['userAgent'],
+            ],
         ];
     }