عن المشروع

Counterscale هو متتبع ولوحة تحكم لتحليلات الويب مفتوحة المصدر يقوم المستخدمون باستضافتها ذاتياً على Cloudflare. تم إصداره بموجب رخصة MIT وهو مصمم ليكون سهل النشر والصيانة، حيث يشير ملف README إلى أن تكلفة تشغيله يجب أن تكون قريبة من الصفر حتى عند مستويات حركة مرور عالية. يعتمد بشكل أساسي على Cloudflare Workers وWorkers Analytics Engine. واعتباراً من فبراير 2025، يمتلك Workers Analytics Engine فترة احتفاظ قصوى تبلغ 90 يوماً، لذا يمكن للوحة التحكم عرض آخر 90 يوماً فقط من البيانات المسجلة. كما يوفر Counterscale تخزيناً طويل الأمد للبيانات في R2 bucket باستخدام ملفات Apache Arrow، ويكون هذا التخزين طويل الأمد مفعلاً بشكل افتراضي ويمكن تعطيله عبر CLI. يتطلب التثبيت نظام macOS أو Linux، وإصدار Node v20 أو أعلى، وحساب Cloudflare نشط. قبل النشر، يحتاج المستخدمون إلى نطاق فرعي لـ Cloudflare Workers، وتفعيل Analytics Engine beta على الحساب، ورمز Cloudflare API token بصلاحيات Account.Account Analytics على الأقل. يبدأ النشر بـ npx wrangler login، يليه npx @counterscale/cli@latest install. يطلب برنامج التثبيت رمز API ويسأل عما إذا كان يجب حماية لوحة التحكم بكلمة مرور؛ ويُنصح باختيار "نعم" للنشر العام، بينما يترك اختيار "لا" لوحة التحكم متاحة للعامة. بعد التثبيت، يتم نشر تطبيق الخادم على نطاق فرعي workers.dev. لتسجيل حركة مرور الموقع، يقدم Counterscale عدة طرق للتكامل. يجعل محمل السكربت tracker.js متاحاً في عنوان URL المنشور، حيث يمكن للمستخدمين إضافة وسم script بمعرف counterscale-script، وسمة data-site-id، ومصدر tracker.js. كما يتم نشر المتتبع كحزمة npm باسم @counterscale/tracker، ويمكن تهيئته باستخدام معرف الموقع (site ID) وعنوان URL للمبلغ (reporter URL). توفر وحدة العميل (client module) طرقاً مثل init وisInitialized وgetInitializedClient وtrackPageview وcleanup. وتدعم وحدة خادم منفصلة، @counterscale/tracker/server، تتبع التحليلات من جهة الخلفية (backend)، حيث تستخدم fetch API بدلاً من XMLHttpRequest، ولا تحتوي على ميزات تعتمد على DOM، وتتطلب معاملات صريحة لـ URL واسم المضيف، وهي من نوع "أطلق وانسَ" (fire-and-forget) بحيث لا تؤدي أخطاء التتبع إلى إلقاء استثناءات. يتضمن Counterscale خيارات متقدمة؛ حيث يمكن تعطيل التتبع التلقائي لمشاهدات الصفحة عن طريق تعيين autoTrackPageviews إلى false، وبعد ذلك يمكن استدعاء trackPageview يدوياً. كما يمكن وضع عنوان URL للنشر خلف نطاق مخصص. يوفر CLI أوامر للتثبيت والمصادقة وإدارة التخزين. يدعم أمر install الوضع المتقدم لتخصيص اسم worker ومجموعة بيانات التحليلات، بالإضافة إلى التسجيل التفصيلي (verbose logging). تشمل الأوامر الفرعية للمصادقة enable وdisable وroll، بينما تشمل الأوامر الفرعية للتخزين enable وdisable. تعني الترقية عموماً إعادة تشغيل مثبت CLI، وقد تتطلب الإصدارات الرئيسية خطوات إضافية موصوفة في ملاحظات الإصدار. بالنسبة للتطوير المحلي، يمتلك Counterscale قاعدة بيانات واحدة فقط: مجموعة بيانات Cloudflare Analytics Engine، والتي يتم التواصل معها عبر HTTP باستخدام API الخاص بـ Cloudflare. لا توجد قاعدة بيانات اختبار محلية، لذا فإن عمليات الكتابة المحلية لا تؤدي أي وظيفة (no-op) وتأتي عمليات القراءة من مجموعة بيانات Analytics Engine في بيئة الإنتاج. يستخدم Cloudflare Analytics Engine أخذ العينات (sampling) لجعل استيعاب البيانات والاستعلام عنها بكميات كبيرة ميسور التكلفة على نطاق واسع، على غرار أدوات التحليلات الأخرى.