ورشة عمل أساسية 2 — Grafana: مصدر واحد وجزء واحد ولوحة واحدة

المدة

20 دقيقة

الوحدة

1/7

المتطلبات الأساسية

المختبر يعمل منذ دقيقتين على الأقل (etat يعرض 8/8 cibles up)، وGrafana مفتوح على http://localhost:3000 بـ admin / aiopsatlas2026، والورشة 1 منجزة (تعرف ما يعيده count(up))

ستبني

لوحة معلومات من لوح واحد، تُنشأ يدوياً في الواجهة، وتُحفظ، وتُقرأ مجدداً بصيغة JSON، ثم تُحذف

المخرج المطلوب

كتلة JSON للوح كما حفظها Grafana (الخطوة 9)، مع ثلاث كلمات محاطة بدائرة : نوع التصور، والاستعلام، ومصدر البيانات

كيف تقرأ هذه الصفحة. عشر خطوات، حركة واحدة في كل مرة. لكل منها : أين تنقر، وما يعرضه Grafana كلمة بكلمة، وما يجب النظر إليه. تسميات الواجهة بالإنجليزية في Grafana 13.2.2 (إصدار الحقيبة) ؛ وهي مقتبسة كما هي، بخط عريض. ستكون الأرقام مختلفة عندك ؛ الأشكال (عدد السلاسل، وقيمة اللوح، والرسائل) يجب أن تكون نفسها. كتل « لفهم أعمق » اختيارية. إذا لم يكن المختبر قد بدأ، عد إلى التمرين الموجه : يعطي القسم باختصار الأوامر، بما فيها الحقيبة (https://github.com/hrhouma2/aiopsatlas-observabilite-labo-fr). كل ما تنشئه هنا يُدمَّر في الخطوة 10 : لوحات المعلومات الثلاث المرفقة بالحقيبة لا تُمَس.

الهدف

في التمرين الموجه، كتبت ثمانية استعلامات في Explore ونظرت إلى ثلاث لوحات معلومات جاهزة. إذن تعرف قراءة Grafana. لكن إذا طُلب منك إضافة رقم على لوحة، هل تعرف من أين تبدأ ؟ هنا، تنطلق من الصفر وتجمّع بنفسك كائنات Grafana الثلاثة، من الأصغر إلى الأكبر : مصدر بيانات (لا يخزن Grafana شيئاً، بل يستعلم Prometheus)، ولوح (استعلام بالإضافة إلى طريقة لرسمه)، ولوحة معلومات (ألواح مرتبة على شبكة، باسم وعنوان). خطوة واحدة هي فخ متعمد : تكسر استعلاماً لترى كيف يعبر خطأ Prometheus عبر Grafana. في النهاية، تقرأ JSON الذي كتبه Grafana لك وتجد فيه الكائنات الثلاثة، ثم تحذف كل شيء.

المصطلحات في صورة واحدة

Grafana هو إطار صور رقمي. لا يلتقط أي صورة : يذهب لجلبها من مصوّر (مصدر البيانات : Prometheus وLoki) ويعرضها. كل صورة لوح : سؤال مطروح على المصوّر (الاستعلام) وتنسيق عرض (رقم، أو منحنى، أو مقياس). الإطار نفسه، بصوره الموزعة على شبكة، هو لوحة المعلومات : لها اسم، وعنوان، وتُحفظ في قاعدة Grafana على شكل مستند JSON.

أين تنقر، وكيف تقرأ استجابة

افتح http://localhost:3000. القائمة الرئيسية هي أيقونة الخطوط الثلاثة في أعلى اليسار : تتيح الوصول إلى Dashboards وExplore وConnections. يقول مسار التنقل في الأعلى (مثلاً Dashboards › New dashboard) دائماً أين أنت. عندما ينجح إجراء، يعرض Grafana لبضع ثوانٍ شريطاً في أسفل اليمين (toast) : Dashboard saved وDashboard deleted. عندما يفشل استعلام، يعرض مربعاً أحمر تحت حقل الاستعلام، مع رسالة Prometheus منسوخة كما هي.

بعد حفظ اللوحة، ستعيد قراءتها بصيغة JSON عبر واجهة برمجة Grafana. في PowerShell أو في طرفية Linux، الأمر نفسه :

curl -s -u admin:aiopsatlas2026 http://localhost:3000/api/dashboards/uid/<uid>

<uid> هو المعرّف الذي أعطاه Grafana للوحتك ؛ ستقرأه في عنوان الصفحة في الخطوة 8.

الخطوة 1 — التحقق من مصدر البيانات

القائمة الرئيسية → Connections → Data sources. ثلاثة مصادر مدرجة : Alertmanager وLoki وPrometheus (معلَّم default). انقر Prometheus. تُفتح صفحة Settings، مع Prometheus server URL ممتلئاً : http://prometheus:9090. لا تغيّر شيئاً. انزل إلى الأسفل تماماً وانقر Save & test.

Successfully queried the Prometheus API.
Next, you can start to visualize data by building a dashboard from scratch or by querying data in the Explore view.

ما يجب النظر إليه : الشريط الأخضر. أرسل Grafana للتو استعلاماً إلى Prometheus وأجاب Prometheus. هذا هو الكائن الأول : مصدر البيانات هو عنوان ونوع. العنوان http://prometheus:9090 وليس http://localhost:9090 : يعمل Grafana في حاوية، ومن هذه الحاوية، يُسمى Prometheus باسم prometheus. أما متصفحك، فيصل إليه عبر localhost:9090. اسمان للآلة نفسها، حسب من يتحدث.

الخطوة 2 — الاستعلام من المصدر في Explore

القائمة الرئيسية → Explore. في الأعلى، يعرض محدد المصدر Prometheus. على يمين الحقل، انتقل إلى Code (وليس Builder). اكتب :

up

ثم Run query (أو Shift+Enter).

up{instance="alertmanager:9093", job="alertmanager"}
up{instance="alloy:12345", job="alloy"}
up{instance="api:8000", job="api", service="api"}
up{instance="cadvisor:8080", job="cadvisor"}
up{instance="grafana:3000", job="grafana"}
up{instance="localhost:9090", job="prometheus"}
up{instance="loki:3100", job="loki"}
up{instance="node-exporter:9100", job="node-exporter"}

ما يجب النظر إليه : ثمانية أسطر في وسيلة الإيضاح تحت الرسم البياني، السلاسل الثماني من الخطوة 2 في الورشة 1، بالترتيب الأبجدي لـ instance. الاستعلام هو بالضبط ما كتبته في Prometheus ؛ نقله Grafana ورسم الاستجابة. Explore مسودة : لا يُحفظ فيه شيء، هناك يُضبط الاستعلام قبل وضعه على لوح.

الخطوة 3 — الفخ : قوس ناقص

دائماً في Explore، استبدل الاستعلام بنسخة خاطئة، عمداً :

count(up

Run query :

bad_data: invalid parameter "query": 1:9: parse error: unclosed left parenthesis

ما يجب النظر إليه : مربع أحمر تحت الحقل، وNo data في الرسم البياني. الرسالة ليست من Grafana : parse error والموضع 1:9 هما من Prometheus، وقد تعلمت قراءتهما في الورشة 1. يضيف Grafana فقط البادئة bad_data:، فئة الخطأ التي تعيدها واجهة برمجة Prometheus. قاعدة : عندما يعرض لوح Grafana خطأ PromQL، صحّحه في Prometheus أولاً (http://localhost:9090)، ثم انسخه إلى Grafana. أغلق القوس، Run query : سطر واحد في وسيلة الإيضاح، يسميه Grafana count(up) لغياب التسميات (أما Prometheus، فكان يكتب {})، عند 8. هذا هو الاستعلام الذي ستضعه على لوحك.

الخطوة 4 — إنشاء لوحة معلومات فارغة

القائمة الرئيسية → Dashboards. تدرج الصفحة مجلداً واحداً، Labo observabilite، يحتوي على لوحات الحقيبة الثلاث. في أعلى اليمين، New → New dashboard.

New dashboard
Add a panel to visualize your data

ما يجب النظر إليه : يقول مسار التنقل Dashboards › New dashboard، الصفحة فارغة، والزر Save موجود مسبقاً في أعلى اليمين. لم يُحفظ شيء بعد : إذا أغلقت علامة التبويب الآن، لن يبقى شيء. لا توجد لوحة المعلومات إلا من لحظة حفظها (الخطوة 8). على اليمين، يقترح لوح جانبي Add الخيار Panel (« Drag or click to add a panel »).

الخطوة 5 — إضافة لوح بلا استعلام

في اللوح الجانبي Add، انقر Panel. يظهر إطار على الشبكة، بعنوان New panel، مع النص No visualization configured. على اليمين، يحتوي حقل Title على New panel : استبدله بـ :

Cibles surveillées

ما يجب النظر إليه : يتغير عنوان الإطار مباشرة. لديك لوح، لكنه فارغ : لا استعلام، ولا تصور. هذا هو الكائن الثاني، مختصراً إلى حده الأدنى : موقع على الشبكة واسم. انقر Edit visualization في اللوح الجانبي : تُفتح صفحة Edit panel، مع علامة التبويب Queries 1 في الأسفل، وعلى اليمين، Suggestions / All visualizations.

الخطوة 6 — وضع الاستعلام

في Queries، السطر A مرتبط مسبقاً بـ Data source : Prometheus (المصدر الافتراضي). انتقل إلى Code، واكتب في الحقل Enter a PromQL query… :

count(up)

ثم Run queries (أو Shift+Enter).

Suggestions
Time series · Stat · Gauge · Bar gauge · Table · State timeline · Heatmap · Histogram

ما يجب النظر إليه : يتغير الجزء الأيمن : تحت Suggestions، يقترح Grafana حوالي عشرة تصورات، وتعرض كل صورة مصغرة بياناتك مسبقاً : count(up) و8. أما اللوح العلوي، فلا يزال يقول « Run a query to visualize it here or go to all visualizations » : لديه الاستعلام، ولم يختر بعد كيف يرسمه. الاستعلام والتصور إعدادان منفصلان للوح واحد.

الخطوة 7 — اختيار التصور

في Suggestions، انقر الصورة المصغرة Stat.

Stat
Value options
  Calculate | All values
  Calculation: Last *
Thresholds
  80  (rouge)
  Base  (vert)

ما يجب النظر إليه : يعرض اللوح العلوي الآن رقماً 8 أخضر كبيراً، مع منحنى الخلفية الصغير. يدرج الجزء الأيمن خيارات Stat، ومنها خياران يجب معرفتهما : تحت Value options، Calculate محدد وCalculation يساوي Last * (يعرض اللوح آخر قيمة في السلسلة، وليس متوسطاً) ؛ تحت Thresholds، عتبتان، Base بالأخضر و80 بالأحمر : ستتحول القيمة إلى الأحمر بدءاً من 80. هذه العتبات هي ما يضعه Grafana افتراضياً على كل لوح جديد ؛ لا معنى لها لعدد أهداف (سترى الأحمر عند 80 هدفاً)، وستقرأها وتغيّرها في لوحة حقيقية. هنا، اتركها : ما يهم هو التعرف عليها في JSON.

الخطوة 8 — الحفظ : اسم، وعنوان

في أعلى اليمين، Save. يُفتح مربع الحوار Save dashboard، بعلامتي تبويب، Details وChanges 3، وثلاثة حقول : Title (New dashboard) وDescription وFolder (Dashboards).

ما يجب النظر إليه أولاً : امسح العنوان وانقر Save : تظهر كلمة Required بالأحمر تحت Title ويصبح الزر Save رمادياً. للوحة المعلومات اسم إلزامي. اكتب :

Atelier M1 - Cibles Prometheus

يُعاد تفعيل الزر. انقر Save.

Dashboard saved

ما يجب النظر إليه بعد ذلك : الشريط Dashboard saved، ثم عنوان الصفحة :

http://localhost:3000/d/adc947c/atelier-m1-cibles-prometheus?orgId=1&from=now-6h&to=now&timezone=browser

ثلاثة أشياء في هذا العنوان. adc947c هو uid، اختاره Grafana عشوائياً : إنه هوية اللوحة، دوّنه. atelier-m1-cibles-prometheus هو العنوان بصيغة عنوان ويب ؛ لا يفيد إلا في المقروئية. from=now-6h&to=now هي الفترة المعروضة، Last 6 hours افتراضياً للوحة جديدة. حلّ القلم في أعلى اليمين (Edit) محل Save : أنت في وضع القراءة. القائمة الرئيسية → Dashboards : لوحتك في القائمة، في الجذر، بجانب المجلد Labo observabilite.

الخطوة 9 — إعادة قراءة JSON : الكائنات الثلاثة موجودة فيه

في طرفية، مع uid الخاص بك بدلاً من adc947c :

curl -s -u admin:aiopsatlas2026 http://localhost:3000/api/dashboards/uid/adc947c

الاستجابة مستند JSON. جزؤه meta :

"meta": {
  "slug": "atelier-m1-cibles-prometheus",
  "url": "/d/adc947c/atelier-m1-cibles-prometheus",
  "created": "2026-09-15T21:21:02Z",
  "version": 1,
  "folderTitle": "General"
}

وفي dashboard، تحتوي المصفوفة panels على عنصر واحد، لوحك (مختصراً إلى الحقول المهمة) :

{
  "type": "stat",
  "title": "Cibles surveillées",
  "datasource": { "type": "prometheus", "uid": "prometheus" },
  "targets": [
    {
      "datasource": { "type": "prometheus", "uid": "prometheus" },
      "editorMode": "code",
      "expr": "count(up)",
      "legendFormat": "__auto",
      "range": true,
      "refId": "A"
    }
  ],
  "fieldConfig": {
    "defaults": {
      "color": { "mode": "thresholds" },
      "thresholds": {
        "mode": "absolute",
        "steps": [
          { "color": "green", "value": 0 },
          { "color": "red", "value": 80 }
        ]
      }
    }
  },
  "options": {
    "colorMode": "value",
    "graphMode": "area",
    "reduceOptions": { "calcs": ["lastNotNull"], "fields": "", "values": false }
  },
  "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 },
  "id": 1,
  "pluginVersion": "13.2.2"
}

ما يجب النظر إليه : كائنات الورشة الثلاثة، مكتوبة بوضوح. المصدر : "datasource": { "type": "prometheus", "uid": "prometheus" }، وهو uid ملف التزويد من الخطوة 1. الاستعلام : "expr": "count(up)"، في targets، مع "refId": "A" (حرف السطر في Queries) و"editorMode": "code". التصور : "type": "stat"، وإعداداته من الخطوة 7 : "calcs": ["lastNotNull"] هو Last * على الشاشة، وsteps هي Thresholds الاثنتان، green في القاعدة وred عند 80. يقول gridPos أين الإطار على الشبكة : في أعلى اليسار، 12 عموداً عرضاً من 24، و8 صفوف ارتفاعاً. لوحة معلومات Grafana ليست سوى هذا : هذا المستند، محفوظاً تحت uid. هذا مخرجك المطلوب : هذه الكتلة، مع stat وcount(up) وprometheus محاطة بدائرة.

الخطوة 10 — حذف كل شيء، وإثبات ذلك

على صفحة اللوحة، Edit → Options → View all settings. تُفتح صفحة Settings (علامات التبويب General وAnnotations وVariables وLinks وVersions وPermissions وJSON Model). في الأسفل تماماً، الزر الأحمر Delete dashboard.

Delete
Do you want to delete this dashboard?
Atelier M1 - Cibles Prometheus
Type "Delete" to confirm

ما يجب النظر إليه : يبقى زر Delete في مربع الحوار رمادياً ما لم تكتب كلمة Delete في الحقل. اكتبها، وانقر Delete.

Dashboard deleted
View deleted dashboards

يعيدك Grafana إلى الصفحة الرئيسية. الإثبات عبر واجهة برمجة التطبيقات، مع uid الخاص بك :

curl -s -u admin:aiopsatlas2026 http://localhost:3000/api/dashboards/uid/adc947c

{"message":"Dashboard not found"}

والقائمة الكاملة للوحات المعلومات :

curl -s -u admin:aiopsatlas2026 "http://localhost:3000/api/search?type=dash-db"

ثلاثة مدخلات، الثلاث في الحقيبة، كلها في المجلد Labo observabilite : api-catalogue (« API catalogue — signaux dorés »، API الكتالوج — الإشارات الذهبية)، وhote-conteneurs (« Hôte et conteneurs »، المضيف والحاويات)، وjournaux-api (« Journaux de l'API »، سجلات API). لوحتك لم تعد هناك. كان مربع حوار الحذف يقول ذلك : يحتفظ Grafana باللوحات المحذوفة في سجل تاريخي حتى اثني عشر شهراً (Recently deleted على صفحة Dashboards)، ومنه يمكن استعادتها ؛ فيما تفعله في هذه الدورة، محذوف يعني محذوفاً.

التحقق النهائي

أعد الحركات العشر من الذاكرة، بالترتيب، وضع علامة :

• Connections → Data sources → Prometheus → Save & test يعيد Successfully queried the Prometheus API.
• في Explore، يعيد up في وضع Code 8 سلاسل.
• count(up يعيد مربعاً أحمر bad_data: … parse error: unclosed left parenthesis ؛ count(up) يعيد {} و8.
• Dashboards → New → New dashboard يفتح صفحة New dashboard فارغة، مع Save ظاهر مسبقاً.
• Add → Panel ينشئ New panel ؛ يعيد حقل Title تسمية الإطار مباشرة.
• count(up) ثم Run queries يملأ Suggestions بالقيمة 8 على كل صورة مصغرة.
• تعرض الصورة المصغرة Stat رقماً 8 كبيراً ؛ Calculation يساوي Last * ؛ Thresholds : Base أخضر، و80 أحمر.
• عنوان فارغ : Required وSave رمادي ؛ العنوان Atelier M1 - Cibles Prometheus : شريط Dashboard saved وuid في العنوان.
• curl … /api/dashboards/uid/<uid> يحتوي على "type": "stat" و"expr": "count(up)" و"uid": "prometheus".
• بعد Delete dashboard، يعيد curl نفسه {"message":"Dashboard not found"} ويدرج /api/search?type=dash-db ثلاث لوحات بالضبط.

من جهة المختبر، لم يتحرك شيء : لا يزال etat يعرض 10/10 services و8/8 cibles up و0 alertes actives. كتب Grafana ثم مسح سطراً في قاعدته الخاصة ؛ ولم يرَ Prometheus شيئاً يمرّ.

إذا حدثت مشكلة