feat: Implement deterministic ID generation for metrics with normalized tags in ClickHouse and Database adapters

Author: lohanidamodar

src/Usage/Adapter/ClickHouse.php

@@ -603,6 +603,9 @@ public function log(string $metric, int $value, string $period = Usage::PERIOD_1
         ];
         Metric::validate($data);
 
+        // Normalize tags for deterministic hashing
+        ksort($tags);
+
         // Period-aligned time so increments fall into the correct bucket
         $now = new \DateTime();
         $time = $period === Usage::PERIOD_INF
@@ -611,11 +614,8 @@ public function log(string $metric, int $value, string $period = Usage::PERIOD_1
         $timestamp = $this->formatDateTime($time);
 
         // Deterministic id so SummingMergeTree will aggregate increments for the same group
-        $idComponents = [$timestamp, $period, $metric];
-        if ($this->sharedTables) {
-            $idComponents[] = (string)$this->tenant;
-        }
-        $id = md5(implode('_', $idComponents));
+        $tenant = $this->sharedTables ? $this->tenant : null;
+        $id = $this->buildDeterministicId($metric, $period, $timestamp, $tenant);
 
         // Build insert columns dynamically from attributes
         $insertColumns = ['id'];
@@ -760,6 +760,10 @@ public function logBatch(array $metrics): bool
 
         foreach ($metrics as $metricData) {
             $period = $metricData['period'] ?? Usage::PERIOD_1H;
+            $metric = $metricData['metric'];
+            $value = $metricData['value'];
+            $tags = $metricData['tags'] ?? [];
+            ksort($tags);
 
             // Period-aligned time so increments fall into the correct bucket
             $now = new \DateTime();
@@ -768,14 +772,9 @@ public function logBatch(array $metrics): bool
                 : $now->format(Usage::PERIODS[$period]);
             $timestamp = $this->formatDateTime($time);
 
-            $idComponents = [$timestamp, $period, $metric];
-            if ($this->sharedTables) {
-                $idComponents[] = (string)$this->tenant;
-            }
-            $id = md5(implode('_', $idComponents));
-
-            $metric = $metricData['metric'];
-            $value = $metricData['value'];
+            // Deterministic id for aggregation
+            $tenant = $this->sharedTables ? $this->tenant : null;
+            $id = $this->buildDeterministicId($metric, $period, $timestamp, $tenant);
 
             $valuePlaceholders = [];
 
@@ -867,7 +866,6 @@ public function find(array $queries = []): array
         // Build LIMIT and OFFSET
         $limitClause = isset($parsed['limit']) ? ' LIMIT {limit:UInt64}' : '';
         $offsetClause = isset($parsed['offset']) ? ' OFFSET {offset:UInt64}' : '';
-
         $sql = "
             SELECT {$selectColumns}
             FROM {$escapedTable}{$whereClause}{$orderClause}{$limitClause}{$offsetClause}

src/Usage/Adapter/Database.php

@@ -68,9 +68,11 @@ public function log(string $metric, int $value, string $period = '1h', array $ta
             ? '1000-01-01 00:00:00'
             : $now->format(Usage::PERIODS[$period]);
 
-        $this->db->getAuthorization()->skip(function () use ($metric, $value, $period, $time, $tags) {
-            $id = \md5("{$time}_{$period}_{$metric}");
+        // Sort tags for consistent storage
+        ksort($tags);
+        $id = $this->buildDeterministicId($metric, $period, $time);
 
+        $this->db->getAuthorization()->skip(function () use ($metric, $value, $period, $time, $tags, $id) {
             $doc = new Document([
                 '$id' => $id,
                 '$permissions' => [],
@@ -103,7 +105,10 @@ public function logBatch(array $metrics): bool
                     ? '1000-01-01 00:00:00'
                     : $now->format(Usage::PERIODS[$period]);
 
-                $id = \md5("{$time}_{$period}_{$metric['metric']}");
+                $tags = $metric['tags'] ?? [];
+                ksort($tags);
+
+                $id = $this->buildDeterministicId($metric['metric'], $period, $time);
 
                 $documents[] = new Document([
                     '$id' => $id,
@@ -112,7 +117,7 @@ public function logBatch(array $metrics): bool
                     'value' => $metric['value'],
                     'period' => $period,
                     'time' => $time,
-                    'tags' => $metric['tags'] ?? [],
+                    'tags' => $tags,
                 ]);
             }
 

src/Usage/Adapter/SQL.php

@@ -114,4 +114,16 @@ protected function getAllColumnDefinitions(): array
 
         return $definitions;
     }
+
+    /**
+     * Build deterministic document ID based on time bucket, period, metric, and tenant (when applicable).
+     * Tags are intentionally excluded to ensure aggregation regardless of tag differences.
+     */
+    protected function buildDeterministicId(string $metric, string $period, string $timeBucket, ?int $tenant = null): string
+    {
+        $tenantPart = $tenant !== null ? ('|' . $tenant) : '';
+        $hashInput = $timeBucket . '|' . $period . '|' . $metric . $tenantPart;
+
+        return md5($hashInput);
+    }
 }