عرض مصدر Rails/active support instrumentation

<noinclude>{{DISPLAYTITLE:أدوات الدعم الفعال في ريلز}}</noinclude>
الدعم الفعال هو جزء من Rails الأساسية التي توفر امتدادات لغة روبي والأدوات المساعدة وغيرها من الأشياء. أحد الأشياء التي تتضمنها هو واجهة برمجة تطبيقات للأجهزة يمكن استخدامها داخل تطبيق لقياس إجراءات معينة تحدث داخل شفرة روبي، مثل تلك الموجودة داخل تطبيق Rails أو إطار العمل نفسه. لا يقتصر على Rails، ولكن. يمكن استخدامه بشكل مستقل في نصوص Ruby الأخرى إذا كان ذلك مطلوبًا.

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

بعد قراءة هذا الدليل، ستعرف:
* ما الأدوات يمكن أن توفر.
* الخطافات داخل إطار Rails للأجهزة.
* إضافة مشترك إلى الخطاف.
* بناء تطبيق الأجهزة المخصصة.

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

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

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

== خطافات اطار Rails ==
ضمن إطار Ruby on Rails، هناك عدد من الخطافات المقدمة للأحداث الشائعة. هذه مفصلة أدناه.

== وحدة التحكم ==

=== Write_fragment.action_controller ===
{| class="wikitable"
|المفتاح
|القيمة
|-
|المفتاح الكامل
|  :key	
|}
<syntaxhighlight lang="rails">
{

 key: 'posts/1-dashboard-view'

}
</syntaxhighlight>

=== Read_fragment.action_controller ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|المفتاح الكامل
|:key
|}
<syntaxhighlight lang="rails">
{

 key: 'posts/1-dashboard-view'

}
</syntaxhighlight>

=== Expire_fragment.action_controller ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|المفتاح الكامل
|:key	
|}
<syntaxhighlight lang="rails">
{

 key: 'posts/1-dashboard-view'

}
</syntaxhighlight>

=== Exist_fragment?.action_controller ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|المفتاح الكامل
|:key	
|}
<syntaxhighlight lang="rails">
{

 key: 'posts/1-dashboard-view'

}
</syntaxhighlight>

=== Write_page.action_controller ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|المسار الكامل
| :path	
|}
<syntaxhighlight lang="rails">
{

 path: '/users/1'

}
</syntaxhighlight>

=== Expire_page.action_controller ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|المسار الكامل
| :path	
|}
<syntaxhighlight lang="rails">
{

 path: '/users/1'

}
</syntaxhighlight>

=== Start_processing.action_controller ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|اسم وحدة التحكم.
|:controller
|-
|الإجراء.
|:action	
|-
|تجزئة معاملات الطلب دون أي معامل مرشح.
|    :params	
|-
|طلب رأس الصفحة.
|   :headers	
|-
|html/js/json/xml etc
|    :format	
|-
|فعل طلب HTTP
|    :method	
|-
|طلب المسار
|:path	
|}
<syntaxhighlight lang="rails">
{

 controller: "PostsController",

 action: "new",

 params: { "action" => "new", "controller" => "posts" },

 headers: #<ActionDispatch::Http::Headers:0x0055a67a519b88>,

 format: :html,

 method: "GET",

 path: "/posts/new"

}
</syntaxhighlight>

=== Process_action.action_controller ===
{| class="wikitable"
|
|
|-
|اسم وحدة التحكم.
|:controller
|-
|الإجراء.
|:action	
|-
|تجزئة معاملات الطلب من غير اي معامل مرشح.
|:params
|-
|طلب رأس الصفحة.
|:headers
|-
|html/js/json/xml etc
|:format	
|-
|فعل طلب HTTP.
|:method
|-
|طلب المسار.
|:path	
|-
|رمز حالة HTTP.
|:status	
|-
|الكمية المستغرقة في الواجهة بالمللي ثانية.
|:view_runtime
|-
|الكمية المستغرقة لتنفيذ استعلامات قاعدة البيانات في مللي ثانية.
|:db_runtime
|}
<syntaxhighlight lang="rails">
{

 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

}
</syntaxhighlight>

=== Send_file.action_controller ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|المسار الكامل للملف.
|:path	
|}
ملاحظة: يمكن إضافة مفاتيح إضافية من قبل المتصل.

=== Send_data.action_controller ===
ليس لدى ActionController أي معلومات محددة للحمولة. تُمرر جميع الخيارات إلى الحمولة.

=== Redirect_to.action_controller ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|رمز استجابة HTTP
|:status	
|-
|عنوان URL لإعادة التوجيه إلى
|     :location	
|}
<syntaxhighlight lang="rails">
{

 status: 302,

 location: "<nowiki>http://localhost:3000/posts/new</nowiki>"

}
</syntaxhighlight>

=== Halted_callback.action_controller ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|المرشح الذي أوقف الإجراء.
| :filter	
|}
<syntaxhighlight lang="rails">
{

 filter: ":halting_filter"

}
</syntaxhighlight>

=== Unpermitted_parameters.action_controller ===
{| class="wikitable"
|المفتاح
|القيمة
|-
| :keys	
|المفاتيح غير مسموح لها.
|}

== واجهة الإجراء ==

=== Render_template.action_view ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|المسار الكامل للقالب.
|:identifier
|-
|تخطيط قابل للتطبيق.
|:layout	
|}
<syntaxhighlight lang="rails">
{

 identifier: "/Users/adam/projects/notifications/app/views/posts/index.html.erb",

 layout: "layouts/application"

}
</syntaxhighlight>

=== Render_partial.action_view ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|المسار الكامل للقالب.
|:identifier
|}
<syntaxhighlight lang="rails">
{

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

}
</syntaxhighlight>

=== Render_collection.action_view ===
{| class="wikitable"
|المفتاح
|القيمة
|-
|   :identifier	
|المسار الكامل للقالب.
|-
|    :count	
|حجم المجموعة.
|-
| :cache_hits	
|عدد الجزيئات التي جُلبت من ذاكرة التخزين المؤقت.
|}
Cache_hits: يُضمن فقط إذا كانت المجموعة مقدمة مع cached: true.

<syntaxhighlight lang="rails">
{

 identifier: "/Users/adam/projects/notifications/app/views/posts/_post.html.erb",

 count: 3,

 cache_hits: 0

}
</syntaxhighlight>

== السجل النشط ==

=== Sql.active_record ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|جملة SQL.
|:sql	
|-
|اسم العملية.
|:name	
|-
|self.object_id
|:connection_id	
|-
|معاملات الربط.
|:binds	
|-
|تضاف true عند استخدام الاستعلامات المخبأة
|    :cached	
|}
ملاحظة: ستضيف المحولات البيانات الخاصة بها أيضًا.

<syntaxhighlight lang="rails">
{

 sql: "SELECT \"posts\".* FROM \"posts\" ",

 name: "Post Load",

 connection_id: 70307250813140,

 binds: []

}
</syntaxhighlight>

=== Instantiation.active_record ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|عدد السجلات التي أُنشئت نسخ لها.
|:record_count	
|-
|سجل الفئة.
|:class_name	
|}
<syntaxhighlight lang="rails">
{

 record_count: 1,

 class_name: "User"

}
</syntaxhighlight>

== إجراء الإرسال ==

=== Receive.action_mailer ===
{| class="wikitable"
|المفتاح
|القيمة
|-
|:mailer	
|اسم فئة الارسال.
|-
|:message_id	
|معرف الرسالة، التي أُنشئت بواسطة جوهرة البريد.
|-
|:subject	
|موضوع البريد.
|-
|:to	
|لمعالجة (عناوين) البريد.
|-
|:from	
|من عنوان البريد.
|-
|:bcc	
|عناوين BCC للبريد.
|-
|:cc	
|عناوين CC للبريد.
|-
|:date	
|تاريخ البريد.
|-
|:mail	
|شكل مشفر للبريد.
|}
<syntaxhighlight lang="rails">
{

 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

}
</syntaxhighlight>

=== Deliver.action_mailer ===
{| class="wikitable"
|المفتاح
|القيمة
|-
|:mailer	
|اسم فئة الارسال.
|-
|:message_id	
|معرف الرسالة، التي أُنشئت بواسطة جوهرة البريد.
|-
|:subject	
|موضوع البريد.
|-
|:to	
|لمعالجة (عناوين) البريد.
|-
|:from	
|من عنوان البريد.
|-
|:bcc	
|عناوين BCC للبريد.
|-
|:cc	
|عناوين CC للبريد.
|-
|:date	
|تاريخ البريد.
|-
|:mail
|شكل مشفر للبريد.
|}
<syntaxhighlight lang="rails">
{

 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

}
</syntaxhighlight>

=== Process.action_mailer ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|اسم فئة الارسال.
|:mailer	
|-
|الإجراء.
|:action	
|-
|الحجج.
|:args	
|}
<syntaxhighlight lang="rails">
{

 mailer: "Notification",

 action: "welcome_email",

 args: []

}
</syntaxhighlight>

== الدعم الفعال ==

=== Cache_read.active_support ===
{| class="wikitable"
|المفتاح
|القيمة
|-
|:key	
|المفتاح المستخدم في المخزن.
|-
|:hit	
|إذا كانت هذه القراءة هي النتيجة.
|-
|:super_operation
|#fetch  عند إضافة قراءة مع :fetch   
|}

=== Cache_generate.active_support ===
يستخدم هذا الحدث فقط عندما تستدعى #fetch بعلامة.
{| class="wikitable"
|القيمة
|المفتاح
|-
|المفتاح المستخدم في المخزن.
|:key	
|}
ملاحظة: تدمج الخيارات التي مُررت لجلب البيانات مع الحمولة عند الكتابة إلى المخزن.

<syntaxhighlight lang="rails">
{

 key: 'name-of-complicated-computation'

}
</syntaxhighlight>

=== Cache_fetch_hit.active_support ===
يستخدم هذا الحدث فقط عندما تستدعى #fetch بعلامة.
{| class="wikitable"
|القيمة
|المفتاح
|-
|المفتاح المستخدم في المخزن.
|:key	
|}
ملاحظة: ملاحظة: تدمج الخيارات التي مُررت لجلب البيانات مع الحمولة.

<syntaxhighlight lang="rails">
{

 key: 'name-of-complicated-computation'

}
</syntaxhighlight>

=== Cache_write.active_support ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|المفتاح المستخدم في المخزن.
|:key	
|}
ملاحظة: قد تضيف مخازن ذاكرة التخزين المؤقت مفاتيحها الخاصة.

<syntaxhighlight lang="rails">
{

 key: 'name-of-complicated-computation'

}
</syntaxhighlight>

=== Cache_delete.active_support ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|المفتاح المستخدم في المخزن.
|:key	
|}
<syntaxhighlight lang="rails">
{

 key: 'name-of-complicated-computation'

}
</syntaxhighlight>

=== Cache_exist?.active_support ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|المفتاح المستخدم في المخزن.
|:key	
|}
<syntaxhighlight lang="rails">
{

 key: 'name-of-complicated-computation'

}
</syntaxhighlight>

== الوظيفة النشطة ==

=== Enqueue_at.active_job ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|كائن QueueAdapter يعالج الوظيفة.
|:adapter	
|-
|كائن الوظيفة.
|:job	
|}

=== Enqueue.active_job ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|كائن QueueAdapter يعالج الوظيفة.
|:adapter	
|-
|كائن الوظيفة.
|:job	
|}

=== Perform_start.active_job ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|كائن QueueAdapter يعالج الوظيفة.
|:adapter	
|-
|كائن الوظيفة.
|:job	
|}

=== Perform.active_job ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|كائن QueueAdapter يعالج الوظيفة.
|:adapter	
|-
|كائن الوظيفة.
|:job	
|}

== كابل العمل ==

=== Perform_action.action_cable ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|اسم فئة القناة.
|:channel_class
|-
|الإجراء.
|:action	
|-
|تجزئة البيانات.
|:data	
|}

=== Transmit.action_cable ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|اسم فئة القناة.
|:channel_class
|-
|تجزئة البيانات.
|:data	
|-
|عبر.
|:via	
|}

=== Transmit_subscription_confirmation.action_cable ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|اسم فئة القناة.
|:channel_class
|}

=== Transmit_subscription_rejection.action_cable ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|اسم فئة القناة.
|:channel_class
|}

=== Broadcast.action_cable ===
{| class="wikitable"
|المفتاح
|القيمة
|-
|:broadcasting	
|بث مسمى.
|-
|:message	
|تجزئة للرسالة.
|-
|:coder	
|المبرمج.
|}

== التخزين النشط ==

=== Service_upload.active_storage ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|رمز آمن.
|:key	
|-
|اسم الخدمة.
|:service	
|-
|تدقيق لضمان السلامة.
|:checksum	
|}

=== Service_streaming_download.active_storage ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|رمز آمن.
|:key	
|-
|اسم الخدمة.
|:service	
|}

=== Service_download.active_storage ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|رمز آمن.
|:key	
|-
|اسم الخدمة.
|:service	
|}

=== Service_delete.active_storage ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|رمز آمن.
|:key	
|-
|اسم الخدمة.
|:service	
|}

=== Service_delete_prefixed.active_storage ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|بادئة المفتاح.
|:prefix	
|-
|اسم الخدمة.
|:service	
|}

=== Service_exist.active_storage ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|رمز آمن.
|:key	
|-
|اسم الخدمة.
|:service	
|-
|الملف أو السقوط موجود أم لا.
|:exist	
|}

=== Service_url.active_storage ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|رمز آمن.
|:key	
|-
|اسم الخدمة.
|:service	
|-
|عنوان URL أُنشأ.
|:url
|}

== Railties ==

=== Load_config_initializer.railties ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|المسار لتحميل مُهيئ من config / initializers.
|:initializer
|}

== Rails ==

=== Deprecation.rails ===
{| class="wikitable"
|القيمة
|المفتاح
|-
|تحذير الانتقاص.
|:message	
|-
|من اين جاء الانتقاص.
|:callstack	
|}

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

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

- اسم الحدث.

- الوقت عند البدء.

- الوقت عند الانتهاء.

- معرف فريد لهذا الحدث.

- الحمولة (الموضحة في الأقسام السابقة).
<syntaxhighlight lang="rails">

ActiveSupport::Notifications.subscribe "process_action.action_controller" do |name, started, finished, unique_id, data|

 # your own custom stuff

 Rails.logger.info "#{name} Received!"

End
</syntaxhighlight>

تعريف كل وسيطات الكتلة هذه في كل مرة يمكن أن تكون مملة. يمكنك بسهولة إنشاء ActiveSupport :: Notifications :: Event من وسيطات حظر مثل هذا:
<syntaxhighlight lang="rails">

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
</syntaxhighlight>

في معظم الأحيان، لا تهتم إلا بالبيانات نفسها. هنا هو اختصار للحصول على البيانات فقط.
<syntaxhighlight lang="rails">

ActiveSupport::Notifications.subscribe "process_action.action_controller" do |*args|

 data = args.extract_options!

 data # { extra: :information }

End
</syntaxhighlight>

يمكنك أيضًا الاشتراك في الأحداث التي تتطابق مع تعبير عادي. يتيح لك هذا الاشتراك في أحداث متعددة في وقت واحد. هنا يمكنك الاشتراك في كل شيء من ActionController.
<syntaxhighlight lang="rails">

ActiveSupport::Notifications.subscribe /action_controller/ do |*args|

 # inspect all ActionController events

End
</syntaxhighlight>

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

إليك مثال على ذلك:
<syntaxhighlight lang="rails">

ActiveSupport::Notifications.instrument "my.custom.event", this: :data do

 # do your custom stuff here

End
</syntaxhighlight>

الآن يمكنك الاستماع إلى هذا الحدث مع:
<syntaxhighlight lang="rails">

ActiveSupport::Notifications.subscribe "my.custom.event" do |name, started, finished, unique_id, data|

 puts data.inspect # {:this=>:data}

End
</syntaxhighlight>

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

== مصادر ==
* [https://guides.rubyonrails.org/active_support_instrumentation.html صفحة Active Support Instrumentation في توثيق Ruby On Rails الرسمي.]