DQL Smartscape هو مجموعة الأوامر التي تستعلم عن الطوبولوجيا (topology) المخزّنة في Grail: الأمر smartscapeNodes للكيانات، والأمر smartscapeEdges للعلاقات، والأمر traverse للانتقال من عقدة إلى جاراتها. أثناء الحادثة تجيب هذه الأوامر باستعلام واحد عن أسئلة كانت تتطلب عدة شاشات: على أي مضيفات تعمل هذه العملية، وأي خدمات تتبع هذه المساحة (namespace)، وأي وحدات تخزين مرتبطة بهذه النسخ؟
يعرض هذا الدليل النموذج (العقد والحواف ومدة الحياة)، ثم الصياغة الدقيقة للأوامر الثلاثة ودوال الإثراء، ثم استعلامات للتشغيل. كل الصياغات المذكورة مأخوذة من صفحتي «DQL Smartscape commands» و«Smartscape on Grail» في الوثائق الرسمية، التي اطُّلع عليها في أكتوبر 2026.
ميزة Smartscape on Grail خاصة بـ Dynatrace SaaS. أما Dynatrace Managed فلا يملك Grail ولا DQL؛ وتُستعرض الطوبولوجيا فيه عبر Smartscape الكلاسيكي ومحدد الكيانات في واجهة API. وإن كانت DQL جديدة عليك، فابدأ بـ شرح أوامر DQL.
نموذج DQL Smartscape: العقد والحواف ومدة الحياة
- العقد (nodes): لكل كيان حقل
typeبأحرف كبيرة (HOSTوK8S_NAMESPACEوAWS_EC2_INSTANCE…) ومعرّف Smartscape بصيغةENTITY_TYPE-000000000000007B، ويمكن مقارنته بسلسلة نصية. - الحواف (edges): تحمل العلاقة نوعًا (
runs_onوcallsوbelongs_to…) وتربط بين عقدتين. الحواف الثابتة الناتجة عن الإعدادات ترث مدة حياة العقدة؛ أما الحواف الديناميكية الناتجة عن الإشارات (خدمة تستدعي أخرى بحسب التتبعات) فتُسجَّل في لحظة محددة. - مدة الحياة (lifetime): ليس للعقدة طابع زمني واحد بل حقلان هما
lifetime.startوlifetime.end. ولا يرى الاستعلام إلا العقد التي تتقاطع مدة حياتها مع فترته.
ثلاث نقاط من الوثائق تستحق التذكر: الفترة التي تبدأ قبل أقل من 15 دقيقة تُمدَّد تلقائيًا إلى 15 دقيقة؛ ومدة الاحتفاظ (retention) 35 يومًا؛ وبيانات Smartscape مشمولة في ترخيص DPS دون تكلفة استعلام إضافية. والصلاحية المطلوبة هي storage:smartscape:read، وهي تغطي smartscapeNodes وsmartscapeEdges وgetNodeName() وgetNodeField().
خطوة بخطوة: استعلام الطوبولوجيا
الخطوة 1: اعرض أنواع العقد الموجودة
smartscapeNodes "*"
| fields type
| dedup type
يقبل المعامل type نوعًا محددًا بلا علامات اقتباس (HOST)، أو قائمة بين أقواس معقوفة ({ HOST, PROCESS })، أو نمطًا بين علامتي اقتباس مع * ("*EC2*"). يقبل النمط 64 حرف بدل كحد أقصى، ولا يُدعم حرفا بدل متتاليان (**). أما المعاملات الاختيارية from وto وtimeframe فتحدد الفترة.
الخطوة 2: صفِّ العقد
smartscapeNodes HOST
| fields id, type
| limit 10
لكل عقدة حقل tags. وتُخزَّن وسوم السحابة وKubernetes فيه بطريقة تختلف عن السجلات: تذكر الوثائق مثلًا أن aws.tags.team يصبح tags:aws[team]، وأن تسميات (labels) الـ pod أو الـ workload تصبح tags:k8s.labels[*].
الخطوة 3: استعلم عن الحواف
smartscapeEdges "*"
| filter source_type == "K8S_POD"
| summarize by:{type, target_type}, edges = count()
تعرض كل حافة الحقول type وsource_id وsource_type وtarget_id وtarget_type. يحصي هذا الاستعلام المأخوذ من الوثائق العلاقات الصادرة من الـ pods؛ ولصياغة التجميع راجع DQL group by.
الخطوة 4: تنقّل في الطوبولوجيا بالأمر traverse
الصياغة الموثقة:
traverse edgeType, …, targetType, … [, direction] [, fieldsKeep: field, …] [, nodeId]
تأخذ direction القيمة forward (الافتراضية) أو backward. يأتي traverse بعد الأمر smartscapeNodes ويقرأ معرّف العقدة المصدر من الحقل id، ما لم يحدد nodeId حقلًا آخر. ويعيد العقد الهدف مع الحقل dt.traverse.history: مصفوفة من السجلات، سجل لكل عملية تنقل، تحتوي افتراضيًا على id وedge_type وdirection، إضافة إلى الحقول المذكورة في fieldsKeep.

الاتجاه مهم. العملية تعمل على مضيف: نبدأ من العملية ونتبع runs_on إلى الأمام. ولسرد خدمات مساحة (namespace) نبدأ من المساحة ونصعد عبر belongs_to إلى الخلف:
smartscapeNodes K8S_NAMESPACE
| filter tags[`example.com/annotation`] == "my-annotation"
| traverse belongs_to, K8S_SERVICE, direction: backward
يمكن الجمع بين عدة أنواع من الحواف والأهداف بين أقواس معقوفة، كما في هذا المثال الرسمي:
smartscapeNodes CONTAINER
| filter k8s.workload.kind == "daemonset"
| traverse {runs_on, belongs_to}, {HOST, K8S_CLUSTER}, fieldsKeep:name
| fields container_name = dt.traverse.history[0][name], node_name = name, node_type = type
الخطوة 5: أثرِ السجلات والـ spans والمقاييس
تحمل الإشارات المرتبطة بعقدة حقولًا بالصيغة dt.smartscape.<type>. وتستخرج دالتان معلومات العقدة:
fetch bizevents
| fieldsAdd getNodeName(dt.smartscape.host)
timeseries avg(dt.host.cpu.idle), by:{ dt.smartscape.host }
| fieldsAdd getNodeField(dt.smartscape.host, "tags")
توصي الوثائق باستخدام getNodeField بدل entityAttr. ويلخص الجدول أدناه التقابل مع نموذج الكيانات الكلاسيكي.

تختلف أنواع العقد أحيانًا عن النموذج الكلاسيكي: فالنوع CLOUD_APPLICATION_INSTANCE يسمّى K8S_POD في Smartscape on Grail. ويعطي الحقل id_classic المعرّف الكلاسيكي المقابل عند وجوده (كيانات Kubernetes والكيانات الأساسية والخدمات).
استعلامات مفيدة في التشغيل
- نطاق التأثير: ابدأ من مضيف متعطل واصعد عبر
runs_onبالاتجاهbackwardلسرد ما يعمل عليه. - جرد حسب الفريق: صفِّ العقد بوسم المالك، ثم تنقّل نحو الموارد المرتبطة، كالمثال الرسمي لوحدات EC2 المرفقة بنسخ فريق معين.
- العدّ لكل مضيف: يستخدم
smartscapeNodes CONTAINER | summarize by:references[runs_on.host], count()الحقل المخفيreferencesالذي يعرض الحواف الثابتة انطلاقًا من العقدة المصدر.
تقلل هذه الاستعلامات زمن الحل (MTTR): فسؤال «ما الذي يعتمد على هذا المكوّن؟» ينال جوابًا قابلًا للتحقق ومشاركًا في Notebook، بدل إعادة بناء من الذاكرة.
كيف تتحقق من صحة الاستعلام
- شغّل
smartscapeNodes "*" | fields type | dedup type: يجب أن تظهر الأنواع المتوقعة. وإلا فتحقق من الصلاحيةstorage:smartscape:read. - قبل
traverseاسرد الحواف الفعلية:smartscapeEdges "*" | filter source_type == "PROCESS" | summarize by:{type, target_type}, edges = count(). النتيجة الفارغة بعدtraverseتأتي غالبًا من اتجاه معكوس. - وسّع الفترة إذا غابت عقدة: العقدة التي يسبق
lifetime.endفيها الفترة لا تظهر.
أفضل الممارسات
- ابدأ دائمًا من العقدة الأكثر تصفية ثم تنقّل: عقد أقل في المدخل ونتيجة أوضح.
- احتفظ باسم العقدة المصدر عبر
fieldsKeepحتى لا تفقد السياق. - فضّل الأنواع المحددة على الأنماط
"*"في استعلامات لوحات المعلومات (dashboards). - احمِ الحقول الحساسة (مثل
k8s.object) بمجموعة حقول (fieldset) على الجدولsmartscape، كما تصف الوثائق. - وللاستراتيجية العامة، اربط هذه الاستعلامات بـ استعلامات DQL للتشغيل.
الأسئلة الشائعة
ما الفرق بين fetch dt.entity.host وsmartscapeNodes HOST؟
يقرأ fetch dt.entity.host نموذج الكيانات الكلاسيكي، بينما يقرأ smartscapeNodes HOST نموذج Smartscape on Grail. وهذا الأخير وحده يتيح استعلام كل الأنواع دفعة واحدة ("*") وكل العلاقات، والتنقل في الطوبولوجيا بالأمر traverse.
هل يمكن استخدام محدد كيانات في Smartscape on Grail؟
لا: تذكر الوثائق أن classicEntitySelector غير مدعوم هناك. ويتم التنقل بالأمر traverse. وللتصفية على قائمة معرّفات، راجع الدالة in() في DQL.
كم تُحفظ الطوبولوجيا؟
35 يومًا. تُحذف العقد التي يتجاوز lifetime.end فيها هذه المدة مع حوافها الثابتة، وتُنظَّف الحواف الديناميكية عند الأجل نفسه.
الخلاصة
يتلخص DQL Smartscape في ثلاثة أوامر: smartscapeNodes للعثور، وsmartscapeEdges لجرد العلاقات، وtraverse لتتبع الاعتماديات. ومع getNodeName وgetNodeField لإثراء الإشارات، تصبح الطوبولوجيا بيانات تُستعلم وتُتحقق وتُشارك، بدل مخطط يُنظر إليه. ولوضع هذه الاستعلامات في نهج أوسع، راجع قابلية الملاحظة مقابل المراقبة.
span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. العلامات التجارية المذكورة ملك لأصحابها. صياغة DQL تتطور: تحقق منها في الوثائق الرسمية قبل استخدامها في الإنتاج.