Rails/active support instrumentation

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

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

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

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

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

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

على سبيل المثال، هناك خطاف يتوفر ضمن السجل الفعال يستدعى في كل مرة يستخدم السجل الفعال استعلام 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	المفاتيح غير مسموح بها.

إجراء العرض

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
}

السجل الفعال

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"
}

إجراء مرسل البريد (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: []
}

الدعم الفعال

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'
}

الوظيفة الفعالة

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	كائن الوظيفة.

إجراء الربط

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).

التخزين الفعال

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 الرسمي.