Give unnamed perk events a perk.quantity

Sources/CodexBarCore/BarTelemetry.swift

@@ -104,10 +104,11 @@ enum BarEvents {
         return usageDidReset(from: before.utilization, to: limit.utilization)
     }
 
-    static func perkAttributes(id: String?, expiresAt: TimeInterval?) -> [OTLPTelemetryEncoder.Attribute] {
+    static func perkAttributes(id: String?, expiresAt: TimeInterval?, quantity: Int? = nil) -> [OTLPTelemetryEncoder.Attribute] {
         var attributes: [OTLPTelemetryEncoder.Attribute] = [.init("perk.kind", "reset_credit")]
         if let id { attributes.append(.init("perk.id", id)) }
         if let expiresAt, expiresAt.isFinite { attributes.append(.init("perk.expires_at", Int(expiresAt))) }
+        if let quantity { attributes.append(.init("perk.quantity", quantity)) }
         return attributes
     }
 
@@ -146,8 +147,9 @@ enum BarEvents {
             kept[id] = nil
             goneBudget -= 1
         }
+        // Credits that went without a row to name them are one event for the whole count.
         if goneBudget > 0 {
-            events.append(.init(name: "bar.perk.gone", attributes: perkAttributes(id: nil, expiresAt: nil)))
+            events.append(.init(name: "bar.perk.gone", attributes: perkAttributes(id: nil, expiresAt: nil, quantity: goneBudget)))
         }
 
         // Only a rise in the count is a new perk. A capped list can rotate which credits it
@@ -162,7 +164,7 @@ enum BarEvents {
             kept.updateValue(expiresAt, forKey: id)
         }
         if appearBudget > 0 {
-            events.append(.init(name: "bar.perk.available", attributes: perkAttributes(id: nil, expiresAt: nil)))
+            events.append(.init(name: "bar.perk.available", attributes: perkAttributes(id: nil, expiresAt: nil, quantity: appearBudget)))
         }
         // An expiry reported late, or moved, must be the one a later disappearance is judged by.
         for (id, expiresAt) in availableNow {

Tests/CodexBarCoreTests/BarTelemetryTests.swift

@@ -244,6 +244,13 @@ final class BarTelemetryTests: XCTestCase {
 
         let countOnly = BarEvents.perkEvents(previous: ObservedPerks(count: 1, available: [:]), summary: summary(3, nil), now: now)
         XCTAssertEqual(countOnly.events.map(\.name), ["bar.perk.available"])
+        // An unnamed event stands for every credit the count moved by; a named one is one credit.
+        XCTAssertTrue(countOnly.events[0].attributes.contains { $0.key == "perk.quantity" && $0.value.intValue == "2" })
+        XCTAssertFalse(first.events.contains { $0.attributes.contains { $0.key == "perk.quantity" } })
+        let countDrop = BarEvents.perkEvents(previous: ObservedPerks(count: 3, available: ["a": 2_000]), summary: summary(0, nil), now: now)
+        XCTAssertEqual(countDrop.events.map(\.name), ["bar.perk.gone", "bar.perk.gone"])
+        XCTAssertFalse(countDrop.events[0].attributes.contains { $0.key == "perk.quantity" })
+        XCTAssertTrue(countDrop.events[1].attributes.contains { $0.key == "perk.quantity" && $0.value.intValue == "2" })
     }
 
     func testPerkGaugeCountsAvailableCreditsWithEarliestExpiry() throws {

docs/telemetry.md

@@ -54,6 +54,7 @@ Codex reset credits are `perk.kind=reset_credit`.
 - A credit that Codex reports as redeemed or redeeming produces `bar.perk.gone` with `perk.gone.reason=used`.
 - When the count drops for any other reason, CodexBar reports the missing credit as gone. The reason is `expired` if its expiry has passed, and left out otherwise.
 - A credit missing from a list while the count holds is not treated as gone, because Codex can return a capped list.
+- If the count moves by more credits than CodexBar can name from the list, the rest go into one `bar.perk.available` or `bar.perk.gone` event with no `perk.id`. Its `perk.quantity` is how many credits it covers. Events for a named credit leave `perk.quantity` out, which means 1.
 
 ## Extra `codex.*` records