الوحدة 7 من مسار مقاييس Dynatrace Managed، وهي مخصصة لـmetric selector والتنبيهات وواجهة Metrics API v2: كتابة استعلام مقاييس، واستدعاؤه بـcurl، وإنشاء المقاييس الناقصة، ثم إطلاق تنبيه Davis عندما تنحرف.
المسار: تدريب مقاييس Dynatrace Managed · الوحدة 7/7 · المدة: نحو 75 دقيقة · المستوى: من المتوسط إلى المتقدم
الأهداف:
- قراءة وصف المقياس وتسلسل تحويلات metric selector
- كتابة تعبير حسابي بين مقياسين واستدعاء
/api/v2/metrics/queryبـcurl - إنشاء مقياس خدمة محسوب أو مقياس سجلات أو مقياس مستورد
- ضبط metric event: عتبة ثابتة أو تكيفية تلقائيًا أو خط أساس موسمي
المتطلبات: الوحدات من 2 إلى 6؛ ورمز API المميّز بنطاق metrics.read، ثم WriteConfig وmetrics.ingest وsettings.write بحسب الخطوات؛ وcurl وjq وبيئة اختبار.
أوضحت الوحدات السابقة أي مقاييس تنظر إليها. وتوضح هذه الوحدة كيف تستعلمها، ثم كيف تجعلها إشارة مناوبة. إن metric selector هو اللغة المشتركة بين Data Explorer وبلاطات لوحات المعلومات وmetric events وواجهة Metrics API v2: فالسلسلة النصية نفسها ترسم منحنى وتغذي هدف SLO وتطلق تنبيهًا.
تصلح هذه الوحدة لـDynatrace Managed (وللمقاييس الكلاسيكية في SaaS). ولا تتناول DQL ولا أمر timeseries في Grail، فهما خاصان بـDynatrace SaaS ويُعالجان في مسار مقاييس SaaS.
metric selector والتنبيهات وAPI: صياغة واحدة في كل مكان
يبدأ الـselector بمفتاح مقياس أو أكثر، تليه تحويلات تفصل بينها نقطتان رأسيتان وتُقيَّم من اليسار إلى اليمين. وكل تحويل يُطبَّق على نتيجة التحويل الذي قبله.
builtin:host.cpu.usage:sort(value(avg,descending)):limit(10)
حدّان يجب معرفتهما: يحتوي الـselector على مفتاح واحد على الأقل، ويستعلم الطلب الواحد عن 10 مقاييس كحد أقصى. ولعدة مقاييس من أصل واحد تسمح الوثائق بالصيغة المختصرة builtin:host.cpu.(usage,idle).
ونصيحة وثائق Dynatrace: ابنِ الـselectors في تبويب Code من Data Explorer (الوضع المتقدم) الذي يقدّم الإكمال التلقائي، ثم انسخها إلى API أو إلى ملف إعداد.
ابدأ بالوصف
قبل كتابة selector، اقرأ وصف المقياس بالاستدعاء GET /api/v2/metrics/{metricId}. وتهم ثلاثة حقول: aggregationTypes (التجميعات الممكنة) وdefaultAggregation (التجميع المطبّق إن لم تحدد غيره) وdimensionDefinitions (مفاتيح الأبعاد القابلة للاستخدام في splitBy وfilter).

هنا يُجمَّع builtin:host.cpu.usage افتراضيًا بالمتوسط وله بعد واحد فقط هو dt.entity.host.
التحويلات الأساسية
| التحويل | الصياغة | الأثر |
|---|---|---|
| التجميع | :max, :avg, :percentile(90)… |
تجميع عبر الزمن، لكل فاصل |
| Split by | :splitBy("dim1","dim2") |
يُبقي هذه الأبعاد ويدمج الباقي؛ و:splitBy() يدمج كل شيء |
| Filter | :filter(eq("dim","valeur")) |
تصفية على بعد أو على قيمة سلسلة |
| Fold | :fold(max) |
يختزل كل سلسلة إلى نقطة واحدة |
| Sort / Limit | :sort(value(avg,descending)):limit(10) |
أعلى N |
| Default | :default(0) |
يستبدل القيم الفارغة |
| Rate | :rate(1m) |
يحوّل عدّادًا إلى معدل |
| Rollup | :rollup(avg,15m) |
تنعيم على نافذة منزلقة |
| Time shift | :timeshift(-1d) |
يزيح الفترة (مقارنة بالأمس) |
| To unit | :toUnit(<source>,<cible>) |
يحوّل وحدة النقاط (قائمة الوحدات: GET /api/v2/units) |
التجميع في الزمن وفي المكان
دون تجميع صريح يستخدم المقياس تجميعه الافتراضي. ولرؤية ذروة المعالج في كل فاصل بدل المتوسط:
builtin:host.cpu.usage:max
وللحصول على رقم واحد هو ذروة الفترة كلها، أضف fold:
builtin:host.cpu.usage:fold(max)
أما التجميع في المكان فيتم عبر splitBy. ودون وسيط يدمج كل المضيفين في سلسلة واحدة:
builtin:host.cpu.usage:splitBy()
التصفية بحسب البعد أو الكيان أو القيمة
يقارن المرشح eq بعدًا بقيمة؛ ويقبل in محدد كيانات (entity selector)، وهذا يتيح التصفية بحسب الوسم. وتُهرَّب علامات الاقتباس الداخلية بالرمز tilde:
builtin:host.cpu.usage
:filter(
in(
"dt.entity.host",entitySelector("type(~"HOST~"),tag(~"easyTravel~")")
)
)
يصفّي الشرط series على القيمة المجمّعة لكل سلسلة: هنا لا يبقى إلا المضيفون الذين يتجاوز متوسطهم 80%.
builtin:host.cpu.usage:filter(series(avg,gt(80)))
ويمكن الجمع بين الشروط بـand وor وnot.
تتطلب rate وrollup وtimeshift تجميعًا
تفرض الوثائق تطبيق تجميع قبل rate وrollup وtoUnit. مثال على تنعيم لمدة 15 دقيقة، مفيد لرسم الاتجاه:
builtin:host.cpu.usage:avg:rollup(avg,15m)
والمقياس نفسه مزاحًا بيوم واحد، لوضعه فوق منحنى اليوم:
builtin:host.cpu.usage:timeshift(-1d)
التعبيرات الحسابية بين المقاييس
يقبل الـselector العمليات + - * / بين المقاييس والأعداد، مع الأقواس. وتُقرَن السلاسل بحسب مجموعة الأبعاد ثم تُحاذى بحسب الطابع الزمني. ويحسب مثال الوثائق معدل أخطاء الخدمة:
builtin:service.errors.total.count:value:default(0)
/
(
builtin:service.errors.total.successCount:value:default(0)
+
builtin:service.errors.total.count:value:default(0)
)
يمنع default(0) فاصلًا بلا أخطاء من إلغاء النسبة كلها. وهناك قاعدتان في الوثائق: طبّق limit على نتيجة التعبير لا على المعاملات، ولا تستخدم تعبيرًا لتحويل وحدة (فضّل toUnit).
استدعاء Metrics API v2 بـcurl
في Managed تكون نقطة النهاية https://{votre-domaine}/e/{id-environnement}/api/v2/metrics/query (أو عبر ActiveGate، والمنفذ الافتراضي 9999). وتتطلب النطاق metrics.read.

مثال مكيّف مع عنقود Managed، حيث يرمّز curl المعاملات:
export DT_ENV="https://dynatrace.example.com/e/votre-id-environnement"
curl -sS -G "$DT_ENV/api/v2/metrics/query" \
-H "Authorization: Api-Token $DT_TOKEN" \
--data-urlencode 'metricSelector=builtin:host.cpu.usage:sort(value(avg,descending)):limit(5)' \
--data-urlencode 'from=now-24h' \
--data-urlencode 'resolution=1h' \
| jq '.result[0].data[] | {host: .dimensionMap["dt.entity.host"], last: .values[-1]}'
المعاملات التي ينبغي معرفتها:
resolution: افتراضيًا 120 نقطة؛ ومدة (10mأو1h) أوInfلنقطة واحدة. وأدق دقة هي الدقيقة، وهي تتوقف أيضًا على عمر البيانات.from/to: طابع زمني أو تاريخ ISO أو قيمة نسبية (now-2hوهي القيمة الافتراضية لـfrom).entitySelector: يقصر الاستعلام على الكيانات المختارة، مثلtype("HOST"),tag("prod").mzSelector: يقصره على منطقة إدارة (management zone)، مثلmzName("Paiement").- الترويسة
Accept: text/csv; header=present: استجابة بصيغة CSV بدل JSON.
القائمة الكاملة لنقاط نهاية Managed في API في Dynatrace Managed: نقاط النهاية والمخططات، وأتمتة أعم في الوحدة 8 من مسار Managed.
إنشاء المقاييس الناقصة
تغطي المقاييس المدمجة الجزء الأكبر، لكن ليس كل شيء: زمن استجابة نقطة دفع واحدة، وعدد الطلبات المرفوضة المقروء من سجل، وعمق طابور داخلي. وتسد ثلاث آليات هذه الفجوات: المقاييس المحسوبة للخدمة (calc:service.) ومقاييس السجلات (log.) واستيعاب المقاييس.
هذه المقاييس مقاييس مخصصة: فعلى خلاف المقاييس المدمجة تستهلك وحدات بيانات Davis (DDU). أنشئها لحاجة محددة لا بدافع العادة.
إنشاء مقياس خدمة محسوب
يطبّق مقياس الخدمة المحسوب شروطًا على طلبات خدمة (وسم أو مسار URL أو سمة طلب…) ويقيس قيمة: REQUEST_COUNT أو RESPONSE_TIME أو FAILURE_RATE أو ERROR_COUNT أو CPU_TIME وغيرها. ويمكن تقسيمه بحسب بعد، مع الاقتصار على أعلى N قيمة.
تنشئه واجهة الإعداد بالاستدعاء POST /api/config/v1/calculatedMetrics/service (النطاق WriteConfig). ويحسب مثال الوثائق طلبات الخدمات الموسومة payment بحسب فئة حالة HTTP:

curl -sS -X POST "$DT_ENV/api/config/v1/calculatedMetrics/service" \
-H "Authorization: Api-Token $DT_TOKEN" \
-H "Content-Type: application/json; charset=utf-8" \
-d @requestsbycode.json
# réponse attendue (201) : {"id":"calc:service.requestsbycode","name":"Requests by code"}
نقاط تستحق الانتباه:
- يبدأ
tsmMetricKeyبالبادئةcalc:service.وجوبًا؛ وهو المفتاح الذي تستخدمه بعد ذلك في metric selector. - يحدد
dimensionDefinitionمعtopXسقف عدد قيم البعد المحتفظ بها: فالتقسيم بحسب URL كامل سيفجّر العدد الأصلي للقيم (cardinality). - ليس للمقياس سجل تاريخي: يبدأ امتلاؤه عند إنشائه.
وبعد إنشائه يُستعلم كغيره، مثل calc:service.requestsbycode:splitBy("dt.entity.service"):sum، مع تكييفه لأبعاد وصفه.
استخراج مقياس من السجلات
في Log Monitoring Classic يُنشأ مقياس السجلات من Settings > Log Monitoring > Metrics extraction بالخيار Add log metric، أو من عارض السجلات بالخيار Create metric. ويبدأ مفتاحه دائمًا بـlog.. وتختار:
- Matcher: استعلام السجل الذي يحدد الأسطر؛
- قياسًا: Occurrence of log records (عدد الأسطر) أو Attribute value (القيمة العددية لسمة)؛
- أبعادًا اختيارية، تؤخذ من سمات السجل.
مثال نموذجي: log.payment.refused الذي يعد الأسطر المحتوية على رمز رفض من مزوّد دفع، مقسّمًا بحسب المزوّد. وحدّان: لا يوجد المقياس إلا انطلاقًا من السجلات المستوعَبة بعد إنشائه، وتحدد الوثائق سقفًا قدره 1 000 000 قيمة بعد لكل مقياس. اختر أبعادًا قليلة التنوع. وتغيير المفتاح ينشئ مقياسًا جديدًا: ويبقى التاريخ تحت المفتاح القديم.
استيعاب مقاييسك الخاصة
لقياس لا يراه أي وكيل (حجم طابور أو نتيجة مهمة دفعية أو رقم تجاري) أرسل النقاط إلى POST /api/v2/metrics/ingest (النطاق metrics.ingest) بالصيغة النصية لبروتوكول الاستيعاب. سطر واحد يساوي نقطة واحدة:

curl -sS -X POST "$DT_ENV/api/v2/metrics/ingest" \
-H "Authorization: Api-Token $DT_TOKEN" \
-H "Content-Type: text/plain; charset=utf-8" \
--data-binary 'batchjob.duration,job=facturation,dt.entity.host=HOST-4587AE40F95AD90D gauge,412'
# réponse attendue (202) : "linesOk": 1, "linesInvalid": 0
قواعد البروتوكول التي ينبغي تذكرها:
- النوع gauge افتراضي؛ والصيغة
count,delta=…تنشئ مقياسًا بلاحقة.count. - حد أقصى 50 بعدًا؛ و
dt.entity.host(وبقيةdt.entity.*) يربط النقطة بكيان، ومن ثم يربط التنبيهات بهذا الكيان. - الطابع الزمني بالمللي ثانية بتوقيت UTC، ويُقبل من ساعة في الماضي إلى عشر دقائق في المستقبل.
- البادئة
dt.ممنوعة لأنها محجوزة لـDynatrace؛ وحمولة الطلب محدودة بـ1 ميغابايت. - ومن مضيف مراقَب تعرض OneAgent أيضًا نقطة نهاية محلية (
http://localhost:14499/metrics/ingestافتراضيًا) لا تتطلب رمزًا مميّزًا.
metric selector والتنبيهات: metric events
يحوّل metric event أي مقياس، مدمجًا كان أو مخصصًا، إلى حدث Davis، ومن ثم إلى مشكلة وإشعار. ويُضبط في Settings > Anomaly detection > Metric events، أو عبر Settings API بالمخطط builtin:anomaly-detection.metric-events.
- نوع الاستعلام:
METRIC_KEY(مفتاح واحد، عتبة ثابتة فقط) أوMETRIC_SELECTOR(selector كامل بما فيه التعبيرات). - النموذج:
STATIC_THRESHOLDأوAUTO_ADAPTIVE_THRESHOLDأوSEASONAL_BASELINE؛ والأخيران يتطلبان metric selector. - النافذة المنزلقة:
samplesعينات مدة كل منها دقيقة، يجب أن تخالف منهاviolatingSamplesالعتبة لفتح الحدث، وأن تعودdealertingSamplesإلى الوضع الطبيعي لإغلاقه. - البيانات المفقودة:
alertOnNoData؛ وتنصح الوثائق بتعطيله للسلاسل المتقطعة.
مثال: التنبيه عندما يتجاوز معدل فشل خدمة موسومة payment نسبة 5% خلال 3 دقائق من 5. يتبع المتن حقول المخطط؛ تحقق منها في إصدارك بالاستدعاء GET /api/v2/settings/schemas/builtin:anomaly-detection.metric-events.
[{
"schemaId": "builtin:anomaly-detection.metric-events",
"scope": "environment",
"value": {
"enabled": true,
"summary": "Taux d'échec paiement > 5 %",
"queryDefinition": {
"type": "METRIC_SELECTOR",
"metricSelector": "builtin:service.errors.total.rate:filter(in(\"dt.entity.service\",entitySelector(\"type(~\"SERVICE~\"),tag(~\"payment~\")\"))):splitBy(\"dt.entity.service\"):avg"
},
"modelProperties": {
"type": "STATIC_THRESHOLD",
"threshold": 5,
"alertCondition": "ABOVE",
"alertOnNoData": false,
"samples": 5,
"violatingSamples": 3,
"dealertingSamples": 5
},
"eventTemplate": {
"title": "Taux d'échec paiement élevé",
"description": "Le taux d'échec dépasse 5 %.",
"eventType": "ERROR",
"davisMerge": true
}
}
}]
أرسله بالاستدعاء POST /api/v2/settings/objects (النطاق settings.write). أما توجيه الإشعارات التالية فيعود إلى ملفات التنبيه: راجع التنبيه وملفاته وتكاملاته في Managed، ولتفادي سيل التنبيهات راجع تقليل ضجيج تنبيهات Davis.
تمرين عملي
الخطوة 1 — قراءة وصف
curl -sS "$DT_ENV/api/v2/metrics/builtin:host.disk.avail" \
-H "Authorization: Api-Token $DT_TOKEN" | jq '.dimensionDefinitions[].key'
النتيجة المتوقعة: dt.entity.host وdt.entity.disk.
الخطوة 2 — بناء قائمة أعلى 5 في Data Explorer
في تبويب Code اكتب selector يعرض المضيفين الخمسة ذوي أعلى متوسط معالج خلال 24 ساعة، ثم أضف استعلامًا ثانيًا بـ:timeshift(-1d). النتيجة المتوقعة: منحنيان متراكبان على الفترة نفسها.
الخطوة 3 — استيعاب مقياس والعثور عليه
أرسل خمس نقاط من batchjob.duration بفاصل دقيقة بأمر الاستيعاب أعلاه، ثم اكتب batchjob.duration:splitBy("job"):max في Data Explorer. النتيجة المتوقعة: "linesOk": 1 عند كل إرسال، ثم سلسلة facturation بقيمك الخمس.
الخطوة 4 — metric event تجريبي
أنشئ metric event بعتبة ثابتة على هذا المقياس، بعتبة أدنى من قيمك. النتيجة المتوقعة: مشكلة مفتوحة على المضيف المشار إليه بـdt.entity.host.
الخطوة 5 — كيف تتحقق من أن الأمر يعمل
يجب أن تحتوي استجابة /api/v2/metrics/query على "totalCount" ومصفوفة result؛ ويدل الرمز 403 على نطاق ناقص، والرمز 400 على خطأ في الصياغة تصفه الرسالة. ثم افتح المشكلة: يحمل الحدث عنوان eventTemplate الذي كتبته. وفي Settings > Anomaly detection > Metric events تشير النظرة العامة أيضًا إلى الإعدادات الفاشلة (QUERY_FAILED وTHROTTLED) خلال آخر 24 ساعة. وأخيرًا احذف الحدث التجريبي.
أفضل الممارسات
- اصنع النموذج الأولي في Data Explorer، ثم انسخ الـselector إلى السكربت أو لوحة المعلومات أو metric event.
- صفِّ مبكرًا واستخدم
sortقبلlimitدائمًا: سلاسل أقل تُقرأ، وقائمة أعلى N لها معنى. - مقياس مخصص واحد لكل سؤال، لا لمجرد الفضول: كل مقياس يستهلك DDU.
- ضبط تنوع القيم:
topXللمقاييس المحسوبة، وأبعاد محدودة القيم للسجلات والاستيعاب. - عدة عينات مخالفة بدل عينة واحدة، وتنبيه على العَرَض (معدل الفشل وزمن الاستجابة): إنذارات كاذبة أقل وإرهاق مناوبة أقل.
- أدِر إصدارات الـselectors مع لوحات المعلومات والتنبيهات: فهي مؤشرات مستوى الخدمة (SLI) لديك.
اختبار قصير
- ماذا يعيد
builtin:host.cpu.usage:fold(max)؟ أ) سلسلة لكل دقيقة ب) نقطة لكل سلسلة: القيمة القصوى للفترة ج) متوسط كل المضيفين د) خطأ - ماذا يفعل
:splitBy()دون وسيط؟ أ) لا شيء ب) يدمج كل الأبعاد في سلسلة واحدة ج) يقسّم بحسب كل الأبعاد د) يحذف القيم الفارغة - أي نطاق يلزم لـ
/api/v2/metrics/query؟ أ)ReadConfigب)metrics.ingestج)metrics.readد)entities.read - بأي بادئة يبدأ مقياس الخدمة المحسوب؟ أ)
builtin:ب)calc:service.ج)log.د)ext: - أي بادئة ممنوعة في الاستيعاب؟ أ)
custom.ب)app.ج)dt.د) لا شيء - ماذا يعني
violatingSamples: 3معsamples: 5؟ أ) 3 تنبيهات خلال 5 أيام ب) 3 دقائق مخالفة ضمن نافذة من 5 دقائق تفتح الحدث ج) تسامح بنسبة 3% د) 5 إعادات تنبيه
الإجابات
- ب) يختزل
foldالسلسلة إلى نقطة واحدة بالتجميع المطلوب. - ب) تُدمج كل السلاسل.
- ج)
metrics.read. - ب)
calc:service.. - ج) البادئة
dt.محجوزة لـDynatrace. - ب) مدة العينة دقيقة واحدة.
للمزيد
- لوحة معلومات Dynatrace Managed: البلاطات وData Explorer وJSON
- أهداف SLO في Dynatrace Managed: الإعداد وAPI، حيث تكون مؤشرات SLI عبارة عن metric selectors
- Davis والمشكلات والتنبيه في Managed
- Metric selector (وثائق Dynatrace Managed)
- Metric ingestion protocol (وثائق Dynatrace Managed)
→ الوحدة 6: السحابة والإضافات · فهرس المسار · نهاية المسار
الأسئلة الشائعة
لماذا يعيد استعلامي نقاطًا أقل مما طلبت؟
الدقة (resolution) قيمة مرجعية: تعدّلها Dynatrace بحسب الفترة وعمر البيانات. فالبيانات القديمة لم تعد متاحة بدقة الدقيقة.
هل يسترجع المقياس المحسوب السجل التاريخي؟
لا. يمتلئ ابتداءً من لحظة إنشائه. وإن احتجت إلى الماضي فحلّل التتبعات الموجودة في التحليل متعدد الأبعاد للخدمة، ثم أنشئ المقياس للمستقبل.
metric event أم الكشف التلقائي عن الشذوذ في Davis؟
يكمل أحدهما الآخر. فDavis يراقب أصلًا الخدمات والتطبيقات والبنية التحتية بخطوط أساسه التلقائية. ويفيد metric event للمقاييس التي لا يراقبها Davis وحده: المقاييس المحسوبة أو مقاييس السجلات أو المستوردة، أو عتبة تعاقدية محددة.
لقد أنهيت المسار: صرت تعرف قراءة مفتاح مقياس، واختيار المفتاح المناسب لمضيف أو خدمة أو تطبيق أو عملية أو مورد سحابي، واستعلامه بـselector وعبر API، وإنشاء مقاييسك الخاصة ومراقبتها. أبقِ الفهرس في متناولك كمذكرة.
span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. لا يغني هذا المسار عن التدريبات والشهادات الرسمية في Dynatrace University. تحقق دائمًا من مفاتيح المقاييس والميزات في الوثائق الرسمية الخاصة بإصدارك.