الوحدة 7 — metric selector والتنبيهات وMetrics API v2 في Dynatrace Managed

تعلّم metric selector في Dynatrace Managed: التحويلات والتعبيرات الحسابية واستدعاء Metrics API v2 بـcurl والمقاييس المحسوبة وmetric events.
Module 7 — Requêter et alerter : metric selector, alertes, API Metrics v2 et métriques calculées

الوحدة 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 كما تعرضه وثائق Dynatrace Managed: التجميعات auto وavg وmax وmin، والتجميع الافتراضي avg، والبعد dt.entity.host

هنا يُجمَّع 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.

مثال curl من وثائق Dynatrace Managed للاستدعاء GET metric data points: المحدد metricSelector بالقيمة builtin:host.cpu.(usage,idle):fold، وentitySelector على مضيفين، وfrom=now-5m

مثال مكيّف مع عنقود 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:

متن الطلب في مثال وثائق Dynatrace Managed لإنشاء المقياس المحسوب calc:service.requestsbycode: المقياس REQUEST_COUNT، وشرط على الوسم payment، والبعد HTTP Status class المقتصر على أول 10 قيم
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) بالصيغة النصية لبروتوكول الاستيعاب. سطر واحد يساوي نقطة واحدة:

أمثلة على أسطر بروتوكول استيعاب المقاييس من وثائق Dynatrace Managed: gauge بسيط، وgauge ملخّص بـmin وmax وsum وcount، وربط بمضيف عبر dt.entity.host، وطابع زمني
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) لديك.

اختبار قصير

  1. ماذا يعيد builtin:host.cpu.usage:fold(max)؟ أ) سلسلة لكل دقيقة ب) نقطة لكل سلسلة: القيمة القصوى للفترة ج) متوسط كل المضيفين د) خطأ
  2. ماذا يفعل :splitBy() دون وسيط؟ أ) لا شيء ب) يدمج كل الأبعاد في سلسلة واحدة ج) يقسّم بحسب كل الأبعاد د) يحذف القيم الفارغة
  3. أي نطاق يلزم لـ/api/v2/metrics/query؟ أ) ReadConfig ب) metrics.ingest ج) metrics.read د) entities.read
  4. بأي بادئة يبدأ مقياس الخدمة المحسوب؟ أ) builtin: ب) calc:service. ج) log. د) ext:
  5. أي بادئة ممنوعة في الاستيعاب؟ أ) custom. ب) app. ج) dt. د) لا شيء
  6. ماذا يعني violatingSamples: 3 مع samples: 5؟ أ) 3 تنبيهات خلال 5 أيام ب) 3 دقائق مخالفة ضمن نافذة من 5 دقائق تفتح الحدث ج) تسامح بنسبة 3% د) 5 إعادات تنبيه

الإجابات

  1. ب) يختزل fold السلسلة إلى نقطة واحدة بالتجميع المطلوب.
  2. ب) تُدمج كل السلاسل.
  3. ج) metrics.read.
  4. ب) calc:service..
  5. ج) البادئة dt. محجوزة لـDynatrace.
  6. ب) مدة العينة دقيقة واحدة.

للمزيد

→ الوحدة 6: السحابة والإضافات · فهرس المسار · نهاية المسار

الأسئلة الشائعة

لماذا يعيد استعلامي نقاطًا أقل مما طلبت؟

الدقة (resolution) قيمة مرجعية: تعدّلها Dynatrace بحسب الفترة وعمر البيانات. فالبيانات القديمة لم تعد متاحة بدقة الدقيقة.

هل يسترجع المقياس المحسوب السجل التاريخي؟

لا. يمتلئ ابتداءً من لحظة إنشائه. وإن احتجت إلى الماضي فحلّل التتبعات الموجودة في التحليل متعدد الأبعاد للخدمة، ثم أنشئ المقياس للمستقبل.

metric event أم الكشف التلقائي عن الشذوذ في Davis؟

يكمل أحدهما الآخر. فDavis يراقب أصلًا الخدمات والتطبيقات والبنية التحتية بخطوط أساسه التلقائية. ويفيد metric event للمقاييس التي لا يراقبها Davis وحده: المقاييس المحسوبة أو مقاييس السجلات أو المستوردة، أو عتبة تعاقدية محددة.

لقد أنهيت المسار: صرت تعرف قراءة مفتاح مقياس، واختيار المفتاح المناسب لمضيف أو خدمة أو تطبيق أو عملية أو مورد سحابي، واستعلامه بـselector وعبر API، وإنشاء مقاييسك الخاصة ومراقبتها. أبقِ الفهرس في متناولك كمذكرة.

span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. لا يغني هذا المسار عن التدريبات والشهادات الرسمية في Dynatrace University. تحقق دائمًا من مفاتيح المقاييس والميزات في الوثائق الرسمية الخاصة بإصدارك.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Module 6 — Cloud et extensions : les métriques cloud Managed, VMware, AWS, Azure

الوحدة 6 — مقاييس السحابة في Dynatrace Managed: VMware وAWS وAzure والإضافات

Next Post
Module 4 — Métriques RUM Grail : frontends et synthétique dt.frontend.* et dt.synthetic.*

الوحدة 4 — مقاييس RUM في Grail: الواجهات الأمامية والمراقبة الاصطناعية dt.frontend.* وdt.synthetic.*

Related Posts