أدوات Active Support في ريلز

Active Support هو جزء من نواة ريلز التي توفر ملحقات للغة روبي والأدوات المساعدة وغيرها من الأشياء. أحد الأشياء التي يتضمنها هو واجهة برمجية لأدوات قياس (instrumentation API) يمكن استخدامها داخل تطبيق لقياس إجراءات معينة تحدث داخل شيفرة روبي، مثل تلك الموجودة داخل تطبيق ريلز أو إطار العمل نفسه، إذ لا يقتصر ذلك على ريلز فقط. يمكن استخدامها بشكل مستقل في شيفرات روبي البرمجية الأخرى إذا كان ذلك مطلوبًا.

في هذا الدليل، ستتعلم كيفية استخدام الواجهة البرمجية لأدوات القياس (instrumentation API) داخل Active Support لقياس الأحداث داخل ريلز وغيرها من شيفرات روبي.

بعد قراءة هذا الدليل، ستتعلم:

ما هي الأدوات المتوافرة.
الخطافات داخل إطار ريلز لأدوات القياس.
إضافة مُشترِك (subscriber) إلى خطاف.
بناء تنفيذ مخصص لأداة قياس.

مقدمة إلى الأدوات

تسمح الواجهة البرمجية لأدوات القياس التي يوفرها Active Support لمطوري البرامج بتوفير خطافات يمكن لمطوري البرامج الآخرين استعمالها. هناك العديد منها في إطار ريلز. باستخدام واجهة برمجة التطبيقات هذه، يمكن للمطورين اختيار كيفية تنبيههم عند وقوع أحداث معينة داخل التطبيق أو في جزء آخر من شيفرة روبي.

على سبيل المثال، هناك خطاف يتوفر ضمن Active Record يستدعى في كل مرة يستخدم Active Record استعلام SQL في قاعدة بيانات. يمكن الاشتراك في هذا الخطاف واستخدامه لتتبع عدد طلبات البحث أثناء تنفيذ إجراء معين. هناك خطاف آخر حول معالجة إجراء وحدة التحكم. يمكن استخدام هذا، على سبيل المثال، لتتبع مدة تنفيذ إجراء معين.

يمكنك حتى إنشاء أحداثك الخاصة داخل تطبيقك والتي يمكنك الاشتراك فيها لاحقًا.

خطافات إطار ريلز

ضمن إطار ريلز، هناك عدد من الخطافات المتوافرة للأحداث الشائعة سنتظرق إليها في الأقسام الآتية.

وحدة التحكم

`write_fragment.action_controller`

المفتاح	القيمة
‎`:key`	المفتاح الكامل.

{
 key: 'posts/1-dashboard-view'
}

`read_fragment.action_controller`

المفتاح	القيمة
‎`:key`	المفتاح الكامل.

{
 key: 'posts/1-dashboard-view'
}

`expire_fragment.action_controller`

المفتاح	القيمة
‎`:key`	المفتاح الكامل.

{
 key: 'posts/1-dashboard-view'
}

`exist_fragment?.action_controller`

المفتاح	القيمة
‎`:key`	المفتاح الكامل.

{
 key: 'posts/1-dashboard-view'
}

`write_page.action_controller`

المفتاح	القيمة
‎`:key`	المفتاح الكامل.

{
 path: '/users/1'
}

`expire_page.action_controller`

المفتاح	القيمة
‎`:path`	المسار الكامل.

{
 path: '/users/1'
}

`start_processing.action_controller`

المفتاح	القيمة
‎`:controller`	اسم وحدة التحكم
‎`:action`	الإجراء
‎`:params`	جدول Hash من معاملات الطلب دون أي معامل مرشح
‎`:headers`	ترويسات طلب
‎`:format`	html/js/json/xml ...إلخ.
‎`:method`	فعل طلب HTTP
‎`:path`	طلب المسار

{
  controller: "PostsController",
  action: "new",
  params: { "action" => "new", "controller" => "posts" },
  headers: #<ActionDispatch::Http::Headers:0x0055a67a519b88>,
  format: :html,
  method: "GET",
  path: "/posts/new"
}

`process_action.action_controller`

المفتاح	القيمة
‎`:controller`	اسم وحدة التحكم
‎`:action`	الإجراء
‎`:params`	جدول Hash لمعاملات الطلب من غير أي معامل مرشح
‎`:headers`	ترويسات الطلب
‎`:format`	html/js/json/xml ...إلخ.
‎`:method`	فعل طلب HTTP
‎`:path`	طلب المسار
‎`:status`	رمز حالة HTTP
‎`:view_runtime`	الكمية المستغرقة في واجهة العرض بالمللي ثانية.
‎`:db_runtime`	الكمية المستغرقة لتنفيذ استعلامات قاعدة البيانات بالميللي ثانية.

{
  controller: "PostsController",
  action: "index",
  params: {"action" => "index", "controller" => "posts"},
  headers: #<ActionDispatch::Http::Headers:0x0055a67a519b88>,
  format: :html,
  method: "GET",
  path: "/posts",
  status: 200,
  view_runtime: 46.848,
  db_runtime: 0.157
}

`send_file.action_controller`

المفتاح	القيمة
‎`:path`	المسار الكامل.

ملاحظة: يمكن إضافة مفاتيح إضافية من قبل المتصل.

`send_data.action_controller`

ليس لدى المتحكم ActionController أي معلومات محددة للحمولة (payload). تُمرر جميع الخيارات إلى الحمولة (payload).

`redirect_to.action_controller`

المفتاح	القيمة
‎`:status`	رمز استجابة HTTP
‎`:location`	عنوان URL لإعادة التوجيه إليه

{
  status: 302,
  location: "http://localhost:3000/posts/new"
}

`halted_callback.action_controller`

القيمة	المفتاح
‎`:filter`	المرشح الذي أوقف الإجراء.

{
 filter: ":halting_filter"
}

`unpermitted_parameters.action_controller`

المفتاح	القيمة
‎`:keys`	المفاتيح غير مسموح بها.

Action View

`render_template.action_view`

المفتاح	القيمة
‎`:identifier`	المسار الكامل للقالب.
‎`:layout`	تخطيط قابل للتطبيق.

{
  identifier: "/Users/adam/projects/notifications/app/views/posts/index.html.erb",
  layout: "layouts/application"
}

`render_partial.action_view`

المفتاح	القيمة
‎`:identifier`	المسار الكامل للقالب.

{
  identifier: "/Users/adam/projects/notifications/app/views/posts/_form.html.erb"
}

`render_collection.action_view`

المفتاح	القيمة
`‎:identifier`	المسار الكامل للقالب.
`‎:count`	حجم المجموعة.
`‎:cache_hits`	عدد الجزيئات التي جُلبت من ذاكرة التخزين المؤقت.

المفتاح cache_hits: يُضمَّن فقط إذا صُيِّرت المجموعة مع cached: true.

{
  identifier: "/Users/adam/projects/notifications/app/views/posts/_post.html.erb",
  count: 3,
  cache_hits: 0
}

Active Record

`sql.active_record`

المفتاح	القيمة
‎`:sql`	تعليمة SQL.
‎`:name`	اسم العملية.
‎`:connection_id`	`self.object_id`
‎`:binds`	معاملات الربط.
‎`:cached`	تضاف `true` عند استخدام الاستعلامات المخبأة.

ملاحظة: ستضيف المحولات البيانات الخاصة بها أيضًا.

{
  sql: "SELECT \"posts\".* FROM \"posts\" ",
  name: "Post Load",
  connection_id: 70307250813140,
  binds: []
}

`instantiation.active_record`

المفتاح	القيمة
‎`:record_count`	عدد السجلات التي أُنشئت نسخ لها.
‎`:class_name`	صنف السجل.

{
  record_count: 1,
  class_name: "User"
}

Action Mailer

`receive.action_mailer`

المفتاح	القيمة
‎`:mailer`	اسم صنف المرسل.
‎`:message_id`	معرف الرسالة، التي أُنشئت بواسطة الجوهرة Mail.
‎`:subject`	موضوع البريد.
‎`:to`	عنوان (عناوين) المُرسَل إليه.
‎`:from`	عنوان المُرسِل.
‎`:bcc`	عناوين الأشخاص المراد إرسال نسخة مخفية (BCC) من البريد إليهم.
‎`:cc`	عناوين الأشخاص المراد إرسال نسخة (CC) من البريد إليهم.
‎`:date`	تاريخ البريد.
‎`:mail`	شكل مشفر للبريد.

{
  mailer: "Notification",
  message_id: "4f5b5491f1774_181b23fc3d4434d38138e5@mba.local.mail",
  subject: "Rails Guides",
  to: ["users@rails.com", "dhh@rails.com"],
  from: ["me@rails.com"],
  date: Sat, 10 Mar 2012 14:18:09 +0100,
  mail: "..." # omitted for brevity
}

`deliver.action_mailer`

المفتاح	القيمة
‎`:mailer`	اسم صنف المرسل.
‎`:message_id`	معرف الرسالة، التي أُنشئت بواسطة الجوهرة Mail.
‎`:subject`	موضوع البريد.
‎`:to`	عنوان (عناوين) المُرسَل إليه.
‎`:from`	عنوان المُرسِل.
‎`:bcc`	عناوين الأشخاص المراد إرسال نسخة مخفية (BCC) من البريد إليهم.
‎`:cc`	عناوين الأشخاص المراد إرسال نسخة (CC) من البريد إليهم.
‎`:date`	تاريخ البريد.
‎`:mail`	شكل مشفر للبريد.

{
  mailer: "Notification",
  message_id: "4f5b5491f1774_181b23fc3d4434d38138e5@mba.local.mail",
  subject: "Rails Guides",
  to: ["users@rails.com", "dhh@rails.com"],
  from: ["me@rails.com"],
  date: Sat, 10 Mar 2012 14:18:09 +0100,
  mail: "..." # omitted for brevity
}

`process.action_mailer`

المفتاح	القيمة
‎`:mailer`	اسم صنف الارسال.
‎`:action`	الإجراء.
‎`:args`	الوسائط.

{
  mailer: "Notification",
  action: "welcome_email",
  args: []
}

Active Support

`cache_read.active_support`

المفتاح	القيمة
`‎:key`	المفتاح المستخدم في المخزن.
`‎:hit`	إذا كانت هذه القراءة (read) هي النتيجة.
`‎:super_operation`	يضاف ‎`:fetch` عند استخدام `read` مع ‎`.fetch`.

`cache_generate.active_support`

يستخدم هذا الحدث فقط عندما تستدعى ‎.fetch مع كتلة.

المفتاح	القيمة
‎`:key`	المفتاح المستخدم في المخزن.

ملاحظة: تدمج الخيارات التي مُررت لجلب البيانات مع الحمولة عند الكتابة إلى المخزن.

{
  key: 'name-of-complicated-computation'
}

`cache_fetch_hit.active_support`

يستخدم هذا الحدث فقط عندما تستدعى ‎.fetch مع كتلة.

المفتاح	القيمة
‎`:key`	المفتاح المستخدم في المخزن.

ملاحظة: تدمج الخيارات التي مُررت لجلب البيانات مع الحمولة.

{
  key: 'name-of-complicated-computation'
}

`cache_write.active_support`

المفتاح	القيمة
‎`:key`	المفتاح المستخدم في المخزن.

ملاحظة: قد تضيف مخازن ذاكرة التخزين المؤقت مفاتيحها الخاصة.

{
  key: 'name-of-complicated-computation'
}

`cache_delete.active_support`

المفتاح	القيمة
‎`:key`	المفتاح المستخدم في المخزن.

{
  key: 'name-of-complicated-computation'
}

`cache_exist?.active_support`

المفتاح	القيمة
‎`:key`	المفتاح المستخدم في المخزن.

{
  key: 'name-of-complicated-computation'
}

Active Job

`enqueue_at.active_job`

المفتاح	القيمة
‎`:adapter`	كائن `QueueAdapter` يعالج الوظيفة.
‎`:job`	كائن الوظيفة.

`enqueue.active_job`

المفتاح	القيمة
‎`:adapter`	كائن `QueueAdapter` يعالج الوظيفة.
‎`:job`	كائن الوظيفة.

`perform_start.active_job`

المفتاح	القيمة
‎`:adapter`	كائن `QueueAdapter` يعالج الوظيفة.
‎`:job`	كائن الوظيفة.

`perform.active_job`

المفتاح	القيمة
‎`:adapter`	كائن `QueueAdapter` يعالج الوظيفة.
‎`:job`	كائن الوظيفة.

Action Cable

`perform_action.action_cable`

المفتاح	القيمة
‎`:channel_class`	اسم صنف القناة.
‎`:action`	الإجراء.
‎`:data`	جدول Hash من البيانات.

`transmit.action_cable`

المفتاح	القيمة
‎`:channel_class`	اسم صنف القناة.
‎`:data`	جدول Hash من البيانات.
‎`:via`	النقل عبر (via).

`transmit_subscription_confirmation.action_cable`

المفتاح	القيمة
‎`:channel_class`	اسم صنف القناة.

`transmit_subscription_rejection.action_cable`

المفتاح	القيمة
‎`:channel_class`	اسم صنف القناة.

`broadcast.action_cable`

المفتاح	القيمة
‎`:broadcasting`	بث مسمى.
‎`:message`	جدول Hash للرسالة.
‎`:coder`	المرمز (coder).

Active Storage

`service_upload.active_storage`

المفتاح	القيمة
‎`:key`	رمز آمن.
‎`:service`	اسم الخدمة.
‎`:checksum`	تدقيق لضمان السلامة.

`service_streaming_download.active_storage`

المفتاح	القيمة
‎`:key`	رمز آمن.
‎`:service`	اسم الخدمة.

`service_download.active_storage`

المفتاح	القيمة
‎`:key`	رمز آمن.
‎`:service`	اسم الخدمة.

`service_delete.active_storage`

المفتاح	القيمة
‎`:key`	رمز آمن.
‎`:service`	اسم الخدمة.

`service_delete_prefixed.active_storage`

المفتاح	القيمة
‎`:prefix`	بادئة المفتاح.
‎`:service`	اسم الخدمة.

`service_exist.active_storage`

المفتاح	القيمة
‎`:key`	رمز آمن.
‎`:service`	اسم الخدمة.
‎`:exist`	ملف أو كائن بيانات ثنائية موجود أم لا.

`service_url.active_storage`

المفتاح	القيمة
‎`:key`	رمز آمن.
‎`:service`	اسم الخدمة.
‎`:url`	عنوان URL المولد.

Railties

`load_config_initializer.railties`

المفتاح	القيمة
‎`:initializer`	مسار تحميل مُهيئ من config/initializers.

Rails

`deprecation.rails`

المفتاح	القيمة
‎`:message`	تحذير الإهمال.
‎`:callstack`	من أين جاء تحذير الإهمال.

الاشتراك في الحدث

الاشتراك في حدث أمر سهل. استخدم ActiveSupport::Notifications.subscribe مع كتلة للاستماع إلى أي إخطار.

تتلقى الكتلة الوسائط التالية:

اسم الحدث.
وقت بدء الحدث.
وقت انتهاء الحدث.
معرف فريد لهذا الحدث.

الحمولة (الموضحة في الأقسام السابقة).

ActiveSupport::Notifications.subscribe "process_action.action_controller" do |name, started, finished, unique_id, data|
  # your own custom stuff
  Rails.logger.info "#{name} Received!"
end

تعريف كل وسائط الكتلة هذه في كل مرة يمكن أن تكون مملة. يمكنك بسهولة إنشاء ActiveSupport::Notifications::Event من وسائط كتلة مثل هذا:

ActiveSupport::Notifications.subscribe "process_action.action_controller" do |*args|
  event = ActiveSupport::Notifications::Event.new *args
 
  event.name      # => "process_action.action_controller"
  event.duration  # => 10 (in milliseconds)
  event.payload   # => {:extra=>information}
 
  Rails.logger.info "#{event} Received!"
end

في معظم الأحيان، لا تهتم إلا بالبيانات نفسها. هنا هو اختصار للحصول على البيانات فقط.

ActiveSupport::Notifications.subscribe "process_action.action_controller" do |*args|
  data = args.extract_options!
  data # { extra: :information }
end

يمكنك أيضًا الاشتراك في الأحداث التي تتطابق مع تعبير نمطي. يتيح لك هذا الاشتراك في أحداث متعددة في وقت واحد. هنا يمكنك الاشتراك في كل شيء من ActionController.

ActiveSupport::Notifications.subscribe /action_controller/ do |*args|
  # ActionController تفحُّص جميع أحداث
end

إنشاء أحداث مخصصة

إضافة الأحداث الخاصة بك من السهل أيضًا. ActiveSupport::Notifications سيعتني بكل شيء من أجلك. استدعي instrument ببساطة مع الاسم والحمولة والكتلة. سيرسل الإخطار بعد إرجاع الكتلة. ينشئ ActiveSupport أوقات البدء والانتهاء بالإضافة إلى معرف فريد. جميع البيانات التي مُررت إلى الاستدعاء instrument تجعلها في الحمولة.

إليك مثال على ذلك:

ActiveSupport::Notifications.instrument "my.custom.event", this: :data do
  # do your custom stuff here
end

الآن يمكنك الاستماع إلى هذا الحدث مع:

ActiveSupport::Notifications.subscribe "my.custom.event" do |name, started, finished, unique_id, data|
  puts data.inspect # {:this=>:data}
end

يجب عليك اتباع معايير ريلز عند تحديد الأحداث الخاصة بك. التنسيق هو: event.library. إذا كان تطبيقك يرسل التغريدات، فيجب إنشاء حدث باسم tweet.twitter.

مصادر

صفحة Active Support Instrumentation في توثيق Ruby On Rails الرسمي.