Analytics Events, Dimensions و Metric Regimes

1. مسئله واقعی: نمودار سالم، معنای شکسته

یک داشبورد شش‌ماهه Conversion را بدون وقفه نشان می‌دهد، اما در میانه دوره نام یک Event Parameter عوض شده، Denominator از Session به Active User تغییر کرده و یک Campaign Dimension پرکاردینال اضافه شده است. Chart هنوز خط پیوسته دارد، ولی Measurement Contract دیگر یکی نیست. این درس قبل از هر تفسیر، مرز Regimeها را ثبت می‌کند.

2. مرز این درس

مالک این درس Analytics Event & Metric-Regime Registry v1 است. Experiment Model درس قبل و Performance Lens/Provenance Result درس بعد را جذب نمی‌کنیم. اینجا نه علت تغییر KPI را ثابت می‌کنیم و نه تصمیم Production می‌دهیم؛ فقط مشخص می‌کنیم Event/Dimension/Metric semantics در چه بازه‌ای معتبر و با چه Regimeهایی قابل مقایسه‌اند.

3. Event Contract فقط Event Name نیست

event_name همراه event_schema_version و Parameterهای مؤثر معنا پیدا می‌کند. Google Analytics Event Parameter را دادهٔ زمینه‌ای برای Interaction می‌داند که می‌تواند به Dimension یا Metric خوراک بدهد. اگر Parameter rename یا type/meaning آن عوض شود، صرف ثابت ماندن Event Name continuity را ثابت نمی‌کند.

4. Parameter → Dimension/Metric را صریح ثبت کن

هر Parameter باید معلوم کند به کدام Dimension یا Metric می‌رسد و Scope آن چیست. Dimension یک Attribute برای گروه‌بندی/فیلتر است؛ Metric مقدار کمی است. اگر Parameter جمع‌آوری شود ولی Mapping آن به Report semantic روشن نباشد، Regime قابل ممیزی نیست و State نباید با حدس به success ارتقا پیدا کند.

5. Metric Label با Metric Contract فرق دارد

Label مثل conversion_rate کافی نیست. Registry باید metric_type، unit، numerator، denominator و aggregation را ثبت کند. نرخ Conversion بر Session با همان نرخ بر Active User دو Metric Regime متفاوت است—even اگر عنوان Chart عوض نشده باشد.

6. Unit تغییر کند، Regime را بررسی کن

تغییر ms به s ممکن است فقط تبدیل واحد باشد یا همراه با تغییر Instrument/aggregation رخ دهد. برای continuity باید Conversion Rule صریح، reversible و testable باشد. اگر فقط Label واحد عوض شود ولی Mapping مشخص نباشد، مقایسه مستقیم NOT_COMPARABLE یا REBASE_REQUIRED می‌شود.

7. Dimension Scope و Cardinality

اضافه‌کردن Dimension جدید می‌تواند Grain داده را عوض کند. Raw URL و Route Template یک Scope یکسان نیستند؛ Campaign ID پرکاردینال هم ممکن است aggregation و cost را تغییر دهد. dimension_scope و cardinality باید بخشی از Regime باشند، نه metadata تزئینی.

8. Filter Set بخشی از Measurement Regime است

دو Query با Metric یکسان اما Filter متفاوت یک Series واحد نیستند مگر Bridge صریح داشته باشند. حذف Bot Traffic، اضافه‌کردن Country Filter یا تغییر Include/Exclude Rule باید version boundary یا bridge rule ایجاد کند. Filter پنهان یعنی continuity پنهان و غیرقابل دفاع.

9. API Compatibility را با Semantic Compatibility اشتباه نگیر

Google Analytics Data API متادیتای Dimension/Metric و checkCompatibility دارد. این ابزار می‌گوید چه Fieldهایی می‌توانند در یک Report Request کنار هم قرار بگیرند؛ اما ثابت نمی‌کند تعریف Metric امروز با تعریف همان Label در ماه قبل یکی است. Queryable بودن ≠ comparable بودن.

10. OpenTelemetry و ابهام معنایی

OpenTelemetry توصیه می‌کند نام‌ها و Attributeها سازگار باشند، aggregation معنادار باشد، unit صریح و semantic ambiguity کم شود. این یک Reference خوب برای Measurement Discipline است، نه Policy محصول MAKNOW. Registry ما باید معنای محلی Product Metric را مستقل و versioned نگه دارد.

11. Effective Interval و Provenance

هر metric_regime_id باید effective_from و در صورت پایان effective_to داشته باشد. provenance_ref نشان می‌دهد تعریف از کدام Spec/Change Request/Instrument Config آمده است. اگر provenance حذف شود یا Metadata قدیمی باشد، Regime نمی‌تواند silently current فرض شود؛ State به UNKNOWN یا STALE_EVIDENCE می‌رود.

12. Compatibility Gate

COMPARABLE فقط وقتی صادر می‌شود که Event schema، Dimension scope، Metric type، Unit/ratio semantics، Aggregation، Filter set و Provenance هم‌ارز باشند. تفاوت شناخته‌شده با Mapping صریح → BRIDGED. Semantic break بدون Bridge → NOT_COMPARABLE. تغییر عمده‌ای که continuity را می‌شکند و baseline جدید می‌خواهد → REBASE_REQUIRED.

13. مثال کارشده: Conversion Trend

Regime R1 از purchase_complete با denominator=sessions استفاده می‌کند. R2 همان Chart label را دارد اما denominator=active_users و Dimension=campaign_id را اضافه کرده است. Data API ممکن است هر دو Field set را قابل Query بداند، ولی Registry continuity را رد می‌کند: denominator و grain عوض شده‌اند. Decision=DO_NOT_COMPARE و سری جدید باید Rebase شود.

14. Negative Caseها

چهار Shortcut باید شکست بخورند: Parameter rename بدون mapping؛ denominator change با label ثابت؛ high-cardinality dimension بدون version boundary؛ و checkCompatibility=OK در حالی که Metric semantics عوض شده است. همچنین Metadata قدیمی یا provenance مفقود نباید با best guess به COMPARABLE تبدیل شود.

15. Transfer: API Latency از ms به s

در Transfer، latency unit از millisecond به second تبدیل می‌شود و route از raw URL به route-template تفکیک می‌شود. اگر conversion factor دقیق (ms × 0.001 = s) و dimension mapping رسمی/آزمون‌پذیر باشد، Registry می‌تواند BRIDGED صادر کند. بدون این bridge، baseline decision قابل کپی نیست و continuity باید شکسته شود.