المرجع
تقييم الظل
في هذه الصفحة
ما الذي يعرضه
في صفحة التغيير، تعرض لوحة الأثر في الإنتاج (تقييم الظل) لآخر 30 دقيقة، لكل خدمة وإصدار: عدد التقييمات في العيّنة، ونسبة ما سيحصل منها على قيمة مختلفة مع المسودة. مثال:
new_checkout في 12.4% من التقييمات في checkout-service (3.1.0)، و0% في غيرها. لم تطابق قاعدتان من المسودة أي تقييم.- تظهر النسب عندما يبلغ العلم 100 تقييم في العيّنة؛ وقبل ذلك تعرض اللوحة لا توجد حركة كافية بعد.
- «القواعد التي لم تطابق أي تقييم» قواعد في المسودة لم يطابقها أي تقييم في العيّنة: وكثيرًا ما يكون السبب خطأً في شرط أو سمةً لا ترسلها خدماتك.
- تبدأ المسودة الجديدة قياسًا جديدًا، وتُميَّز أرقام المسودة السابقة بذلك.
كيف يعمل
- عند طلب الموافقة (وطوال كون التغيير موافَقًا عليه دون نشر)، يوقّع NanoFlags المسودة بوصفها حزمة ظل، وتعرضها الحافة إلى جانب الحزمة الحية.
- تُوقَّع حزمة الظل بنطاق توقيع خاص بها، وتحمل علامة
shadowداخل البايتات الموقّعة. لا تطبّقها حزم SDK أبدًا بوصفها إعدادات، حتى لو عُبث بها أو قُدّمت مكان حزمة عادية: تُرفض دائمًا كل حزمة تحمل علامةshadowبوصفها إعدادات، وتُتجاهل حزمة الظل التي لا يصح توقيعها. - لعيّنة من تقييمات الأعلام التي تغيّرها المسودة (10% افتراضيًا)، تقيّم حزمة SDK المسودة أيضًا، بشكل متزامن وفي الذاكرة، وتعدّ النتائج. يحصل الكود لديك دائمًا على القيمة الحية.
- تُرسَل العدّادات مع تقرير القياس المعتاد للحزمة، مرة في الدقيقة على الأكثر. الذاكرة محدودة (100 علم على الأكثر، و10 أزواج قيم و50 عدّاد قواعد لكل علم).
- عند نشر التغيير بعد الموافقة عليه، أو إعادته إلى المسودة أو إغلاقه، أو تغيّر المسودة، ينتهي القياس وتُسحب حزمة الظل.
- تتلقى مفاتيح المتصفح والجوال عرض المتصفح من المسودة (الأعلام المكشوفة للعميل فقط)، كما تتلقاه للإعدادات المنشورة. لذا يستطيع أي شخص يملك المفتاح العام قراءة قيم المسودة لأعلامها المكشوفة للعميل أثناء قياس التغيير. أبقِ تقييم الظل متوقفًا حيث يجب أن تبقى القيم غير المنشورة سرية حتى نشرها.
تقييم الظل استشاري فقط. تعمل الموافقات واشتراطات السيناريوهات والتوقيع المشترك والنشر كما كانت تمامًا؛ لا شيء يقرأ القياس ليقرر أي أمر.
ما الذي يخرج من خدماتك
العدّادات فقط. لكل علم: عدد التقييمات في العيّنة، وعدد ما ستتغيّر قيمته، وعدد مرات ظهور كل زوج من القيم (الحية ← المسودة)، وعدد مرات مطابقة كل قاعدة في المسودة. وتُوسَم باسم الخدمة وإصدارها كما تضبطهما في حزمة SDK، وبإصدار الحزمة.
لا يُرسَل ولا يُخزَّن أبدًا: سياقات التقييم، وأسماء السمات أو قيمها، ومفاتيح المستخدمين أو معرّفاتهم، وعناوين IP. القيم في العدّادات هي القيم المضبوطة للعلم نفسه (وما يزيد على 100 حرف يُستبدل ببصمة). وعندما تُستخدم القيمة الاحتياطية التي يمرّرها تطبيقك (العلم جديد في المسودة، أو خطأ في التقييم، أو قيمة من نوع غير مطلوب) ترسل الحزمة العلامة <fallback> بدل القيمة، ويحذف الخادم أي قيمة ليست من القيم المضبوطة للعلم. ولا تُحتسب التقارير المرسلة بمفاتيح المتصفح إلا للأعلام المتاحة للمتصفح، وتُعرض منفصلة؛ ولا تستخدم رسالة Slack والمراجعة بالذكاء الاصطناعي إلا تقارير الخوادم. تُحذف العدّادات بعد 7 أيام.
صُمّمت هذه الميزة لتتوافق مع قوانين حماية البيانات مثل نظام حماية البيانات الشخصية السعودي واللائحة الأوروبية GDPR: لا تُعالَج أي بيانات شخصية لأجلها. وهي متوقفة افتراضيًا، ويشغّلها المالك أو المسؤول لكل بيئة على حدة، ويُسجَّل كل تغيير للإعداد في سجل التدقيق (environment.shadow_enabled وenvironment.shadow_disabled).
تشغيله
افتح الإعدادات ← البيئات ← الأمان، واختر البيئة (عادة الإنتاج)، ثم اختر تشغيله في قسم تقييم الظل. تُقاس التغييرات التي تنتظر الموافقة من تلك اللحظة. تلتقط حزم SDK حزمة الظل مع فحصها التالي للإعدادات: خلال دقيقة تقريبًا عند الاستطلاع الدوري، وخلال 5 دقائق عبر الاتصال الحي.
خيارات SDK
تدعم حزمة JavaScript SDK (@nanoflags/sdk، وحزم React وReact Native المبنية عليها) تقييم الظل. يحتاج إلى تشغيل القياس (events)؛ ومع events: false يتوقف هو أيضًا.
import { createClient } from "@nanoflags/sdk";
const flags = createClient({
sdkKey: process.env.NANOFLAGS_SDK_KEY!,
baseUrl: "https://edge.nanoflags.io",
service: "checkout-service",
serviceVersion: "3.1.0", // shown next to the service name
shadow: { sampleRate: 0.1 }, // default; `shadow: false` turns it off
});serviceVersion: إصدار خدمتك، ويظهر بجانب اسم الخدمة في اللوحة.shadow.sampleRate: نسبة تقييمات الأعلام المتغيّرة التي تُقيَّم بالمسودة أيضًا (0.1 افتراضيًا).shadow: false: لا تجلب هذه الخدمة حزم الظل ولا تقيّمها أبدًا.
تستمر الخدمات التي تستخدم حزم SDK أخرى في العمل دون تغيير، ولا تُبلغ فحسب.
أين يراه المعتمدون
- صفحة التغيير: لوحة الأثر في الإنتاج (تقييم الظل)، مع صف لكل خدمة وإصدار.
- Slack: تحصل رسالة الموافقة في تطبيق Slack على سطر واحد بالأثر المقيس، ويُحدَّث عندما تتوفر حركة كافية.
- مراجعة التغيير بالذكاء الاصطناعي: تذكر الفحوص التلقائية التغييرات المقيسة (متوسطة الخطورة ابتداءً من 10% من التقييمات في العيّنة)، ويأخذها الملخص بالذكاء الاصطناعي في الحسبان عندما تتوفر وقت المراجعة.
صيغة البيانات (لحزم SDK الأخرى)
لمطوّري حزم SDK. تحمل إجابة GET /v1/bundle الحديثة (200 أو 304) الترويسة X-NanoFlags-Shadow: <sessionId>.<checksum> ما دامت حزمة ظل موجودة. ويجيب GET /v1/shadow (بمفتاح SDK نفسه) بـ{sessionId, checksum, baseRevision, bundle} مع X-NanoFlags-Signature وX-NanoFlags-Key-Id وX-NanoFlags-Environment-Id، أو 404 عند عدم وجودها. التوقيع Ed25519 على
nanoflags-shadow-v1
<environment id>
<session id>
<checksum>
<sha256 hex of the bundle JSON text exactly as served>بمفاتيح /v1/keys. لا تستخدم الحزمة إلا إذا صحّ توقيعها وكان في عنصر shadow داخلها معرّف الجلسة والبصمة ومعرّف البيئة نفسها. قيّم العلم بالظل عندما تختلف إعداداته عن الحية، أو عندما يشير إلى شريحة مختلفة، مباشرة أو عبر شرائح أخرى (تختلف الشريحة إذا اختلف تعريفها، أو حذفتها المسودة، أو أشارت إلى شريحة مختلفة). وأرسل التقرير مع جسم POST /v1/events التالي، في عنصر shadow:
{
"service": "checkout-service", "sdk": "js/0.5.0", "revision": 42, "events": [],
"shadow": {
"sessionId": "6f1c2a4e-8b1d-4c3e-9f00-1234567890ab",
"checksum": "0123456789abcdef0123456789abcdef",
"version": "3.1.0",
"flags": [{
"flag": "new_checkout", "samples": 400, "flips": 50,
"pairs": [{ "live": "false", "shadow": "true", "count": 50 }],
"rules": { "0": 120, "default": 280 }
}]
}
}حدود كل تقرير: 100 علم، و10 أزواج و50 عدّاد قواعد لكل علم، والقيم نص JSON مرتّب المفاتيح لا يزيد على 100 حرف، و<fallback> للجانب الذي استُخدمت فيه القيمة الاحتياطية للتطبيق، وflips ≤ samples. قارن القيم بصيغة JSON مرتّبة المفاتيح، حتى لا يُحتسب اختلاف ترتيب المفاتيح تغييرًا. مفاتيح القواعد هي فهارس قواعد المسودة بدءًا من 0، أو default.
الخطط والحدود
| الخطة | تقييم الظل |
|---|---|
| Explore وSolo | غير متاح |
| Team وScale | متاح |
| Enterprise | متاح |
تُحفظ العدّادات 7 أيام، وينتهي القياس بعد 7 أيام على الأكثر. تسجّل الجلسة الواحدة 50 تركيبة من الخدمة والإصدار على الأكثر. راجع الخطط والحدود.