بوابة الدفع

بوابة بروميثيوس

توجد بوابة Prometheus Pushgateway للسماح للمهام المؤقتة والدفعية بكشف مقاييسها إلى Prometheus. نظرًا لأن هذه الأنواع من الوظائف قد لا تكون موجودة لفترة كافية ليتم التخلص منها، فيمكنها بدلاً من ذلك دفع مقاييسها إلى Pushgateway. يقوم Pushgateway بعد ذلك بكشف هذه المقاييس لبروميثيوس.

غير الأهداف

بادئ ذي بدء، فإن Pushgateway غير قادر على تحويل Prometheus إلى نظام مراقبة قائم على الدفع. للحصول على وصف عام لحالات استخدام Pushgateway، يرجى قراءة متى يجب استخدام Pushgateway.

من الواضح أن Pushgateway ليس مجمعًا أو عدادًا موزعًا ولكنه عبارة عن ذاكرة تخزين مؤقت للمقاييس. ليس لديها دلالات تشبه الإحصائيات. المقاييس التي تم دفعها هي نفسها تمامًا التي تقدمها للتجريد في برنامج يعمل بشكل دائم. إذا كنت بحاجة إلى العد الموزع، فيمكنك إما استخدام الإحصائيات الفعلية مع مُصدر Prometheus statsd، أو إلقاء نظرة على بوابة تجميع الحفلة الراقصة. مع اكتساب المزيد من الخبرة، قد يتمكن مشروع بروميثيوس يومًا ما من توفير حل أصلي، منفصل عن Pushgateway أو ربما حتى كجزء منه.

بالنسبة للمقاييس على مستوى الجهاز، عادةً ما يكون مُجمع الملفات النصية لمصدر العقدة أكثر ملاءمة. تم تصميم Pushgateway لمقاييس مستوى الخدمة.

إن Pushgateway ليس متجرًا للأحداث . على الرغم من أنه يمكنك استخدام Prometheus كمصدر بيانات لتعليقات Grafana، إلا أن تتبع شيء مثل أحداث الإصدار يجب أن يحدث باستخدام بعض إطارات تسجيل الأحداث.

منذ فترة، قررنا عدم تنفيذ "مهلة" أو TTL للمقاييس المدفوعة لأنه تبين أن جميع حالات الاستخدام المقترحة تقريبًا هي أنماط مضادة لا نشجعها بشدة. يمكنك متابعة مناقشة أحدث على القائمة البريدية لمطوري بروميثيوس.

تشغيله

قم بتنزيل الإصدارات الثنائية لمنصتك من صفحة الإصدار وقم بفك حزمة القطران.

إذا كنت تريد تجميع نفسك من المصادر، فأنت بحاجة إلى إعداد Go فعال. ثم استخدم ملف Makefile المقدم (اكتب make ).

بالنسبة للإعداد الأساسي، ما عليك سوى بدء الملف الثنائي. لتغيير العنوان الذي سيتم الاستماع إليه، استخدم علامة --web.listen-address (على سبيل المثال "0.0.0.0:9091" أو ":9091"). افتراضيًا، لا يحتفظ Pushgateway بالمقاييس. ومع ذلك، تسمح لك علامة --persistence.file بتحديد ملف ستستمر فيه المقاييس المدفوعة (حتى تتمكن من البقاء على قيد الحياة عند إعادة تشغيل Pushgateway).

باستخدام عامل الميناء

يمكنك نشر Pushgateway باستخدام صورة prom/pushgateway Docker.

على سبيل المثال:

docker pull prom/pushgateway

docker run -d -p 9091:9091 prom/pushgateway

استخدمه

قم بتكوين Pushgateway كهدف للكشط

يجب تكوين Pushgateway كهدف ليتخلص منه بروميثيوس باستخدام إحدى الطرق المعتادة. ومع ذلك، يجب عليك دائمًا تعيين honor_labels: true في تكوين Scrape (انظر أدناه للحصول على شرح مفصل).

المكتبات

يجب أن تحتوي مكتبات عملاء Prometheus على ميزة لدفع المقاييس المسجلة إلى Pushgateway. عادة، يقدم عميل Prometheus بشكل سلبي مقياسًا للاستخراج بواسطة خادم Prometheus. تحتوي مكتبة العميل التي تدعم الدفع على وظيفة دفع، والتي يجب استدعاؤها بواسطة رمز العميل. سيقوم بعد ذلك بدفع المقاييس بشكل فعال إلى Pushgateway، باستخدام واجهة برمجة التطبيقات الموضحة أدناه.

سطر الأوامر

باستخدام بروتوكول النص Prometheus، يعد دفع المقاييس أمرًا سهلاً للغاية بحيث لا يتم توفير واجهة سطر أوامر (CLI) منفصلة. ما عليك سوى استخدام أداة HTTP لسطر الأوامر مثل curl . من المرجح أن تحتوي لغة البرمجة النصية المفضلة لديك على بعض إمكانيات HTTP المضمنة التي يمكنك الاستفادة منها هنا أيضًا.

لاحظ أنه في بروتوكول النص، يجب أن ينتهي كل سطر بحرف تغذية الأسطر (المعروف أيضًا باسم "LF" أو "n"). سيؤدي إنهاء الخط بطرق أخرى، على سبيل المثال باستخدام 'CR' المعروف أيضًا باسم 'r'، أو 'CRLF' المعروف أيضًا باسم 'rn'، أو مجرد نهاية الحزمة، إلى حدوث خطأ في البروتوكول.

تتم إدارة المقاييس المدفوعة في مجموعات، يتم تحديدها بواسطة مفتاح تجميع لأي عدد من التصنيفات، والتي يجب أن يكون أولها هو تصنيف job . من السهل فحص المجموعات عبر واجهة الويب.

للتعرف على تأثيرات الأحرف الخاصة في قيم التصنيف، راجع قسم عنوان URL أدناه.

أمثلة:

• ادفع عينة واحدة إلى المجموعة التي تم تحديدها بواسطة {job="some_job"} :

    echo "some_metric 3.14" | curl --data-binary @- http://pushgateway.example.org:9091/metrics/job/some_job
  

  نظرًا لعدم توفير معلومات النوع، سيكون some_metric من النوع untyped .

• ادفع شيئًا أكثر تعقيدًا إلى المجموعة المحددة بواسطة {job="some_job",instance="some_instance"} :

    cat <

  لاحظ كيفية توفير معلومات النوع وسلاسل المساعدة. هذه الخطوط اختيارية، ولكن يُنصح بها بشدة لأي شيء أكثر تعقيدًا.

• احذف جميع المقاييس الموجودة في المجموعة المحددة بواسطة {job="some_job",instance="some_instance"} :

    curl -X DELETE http://pushgateway.example.org:9091/metrics/job/some_job/instance/some_instance
  

• احذف جميع المقاييس في المجموعة المحددة بواسطة {job="some_job"} (لاحظ أن هذا لا يتضمن المقاييس الموجودة في المجموعة {job="some_job",instance="some_instance"} من المثال السابق، حتى إذا كانت تلك المقاييس تحتوي على نفس التسمية الوظيفية):

    curl -X DELETE http://pushgateway.example.org:9091/metrics/job/some_job
  

• حذف جميع المقاييس في جميع المجموعات (يتطلب تمكين واجهة برمجة تطبيقات المشرف عبر علامة سطر الأوامر --web.enable-admin-api ):

    curl -X PUT http://pushgateway.example.org:9091/api/v1/admin/wipe
  

حول تسميات الوظيفة والمثيلات

سيقوم خادم Prometheus بإرفاق تسمية job وتسمية instance لكل مقياس مسروق. تأتي قيمة تسمية job من تكوين الكشط. عندما تقوم بتكوين Pushgateway كهدف كشط لخادم Prometheus الخاص بك، فمن المحتمل أن تختار اسم وظيفة مثل pushgateway . يتم تعيين قيمة تسمية instance تلقائيًا على المضيف ومنفذ الهدف الذي تم مسحه. ومن ثم، فإن جميع المقاييس المستخرجة من Pushgateway ستحتوي على مضيف ومنفذ Pushgateway كتسمية instance وتسمية job مثل pushgateway . يتم حل التعارض مع تسميات job instance التي قد تكون أرفقتها بالمقاييس التي تم دفعها إلى Pushgateway عن طريق إعادة تسمية تلك التسميات إلى exported_job و exported_instance .

ومع ذلك، عادةً ما يكون هذا السلوك غير مرغوب فيه عند تجريف Pushgateway. بشكل عام، ترغب في الاحتفاظ بتسميات job instance الخاصة بالمقاييس التي تم دفعها إلى Pushgateway. لهذا السبب يتعين عليك تعيين honor_labels: true في تكوين الكشط لـ Pushgateway. أنها تمكن السلوك المطلوب. راجع الوثائق للحصول على التفاصيل.

وهذا يتركنا في الحالة التي لا تحتوي فيها المقاييس التي تم دفعها إلى Pushgateway على تسمية instance . هذه الحالة شائعة جدًا نظرًا لأن المقاييس المدفوعة غالبًا ما تكون على مستوى الخدمة وبالتالي لا تتعلق بمثيل معين. حتى مع honor_labels: true ، سيُرفق خادم Prometheus تسمية instance إذا لم يتم تعيين تسمية instance في المقام الأول. لذلك، إذا تم دفع مقياس إلى Pushgateway بدون تسمية مثيل (وبدون تسمية مثيل في مفتاح التجميع، انظر أدناه)، فسوف يقوم Pushgateway بتصديره مع تسمية مثيل فارغة ( {instance=""} )، وهو ما يعادل لعدم وجود تسمية instance على الإطلاق ولكن يمنع الخادم من إرفاق واحدة.

حول التناقضات المترية

يعرض Pushgateway كافة المقاييس المدفوعة مع المقاييس الخاصة به عبر نقطة النهاية /metrics نفسها. (راجع القسم الخاص بالمقاييس المكشوفة للحصول على التفاصيل.) لذلك، يجب أن تكون جميع المقاييس متسقة مع بعضها البعض: يجب أن تكون المقاييس التي تحمل الاسم نفسه من نفس النوع، حتى إذا تم دفعها إلى مجموعات مختلفة، ويجب ألا يكون هناك تكرارات ، أي المقاييس التي لها نفس الاسم وأزواج التسميات نفسها تمامًا. يتم رفض الدفعات التي قد تؤدي إلى عدم الاتساق مع رمز الحالة 400.

ومع ذلك، يتم التسامح مع سلاسل المساعدة غير المتناسقة. سوف يختار Pushgateway سلسلة تعليمات فائزة ويسجلها على مستوى المعلومات.

ملاحظة قديمة: لقد تغيرت سلسلة المساعدة الخاصة بمقياس push_time_seconds الخاص بـ Pushgateway في الإصدار 0.10.0. باستخدام ملف الثبات، يمكن للمقاييس التي تم دفعها إلى Pushgateway لإصدار سابق أن تتحول إلى Pushgateway للإصدار v0.10.0 أو أحدث. في هذه الحالة، ستظهر رسالة السجل المذكورة أعلاه. بمجرد حذف كل مجموعة تم دفعها مسبقًا أو تلقي دفعة جديدة، ستختفي رسالة السجل.

إن فحص الاتساق الذي يتم إجراؤه أثناء الدفع هو نفسه الذي يحدث على أي حال أثناء الكشط. في حالات الاستخدام الشائع، تحدث الخدوش أكثر من عمليات الدفع. ولذلك، فإن تكلفة أداء فحص وقت الدفع ليست ذات صلة. ومع ذلك، إذا تم دمج كمية كبيرة من المقاييس الموجودة على Pushgateway مع عمليات الدفع المتكررة، فقد تصبح مدة الدفع طويلة جدًا. في هذه الحالة، قد تفكر في استخدام علامة سطر الأوامر --push.disable-consistency-check ، والتي توفر تكلفة فحص الاتساق أثناء الدفع ولكنها تسمح بدفع المقاييس غير المتسقة. سيستمر إجراء الفحص أثناء عملية المسح، وبالتالي فشل جميع عمليات المسح طالما تم تخزين المقاييس غير المتناسقة على Pushgateway. وبالتالي فإن تعيين العلامة يعرضك لخطر تعطيل Pushgateway بدفعة واحدة غير متناسقة.

حول الطوابع الزمنية

إذا دفعت المقاييس في الوقت t 1 ، فقد تميل إلى الاعتقاد بأن بروميثيوس سوف يتخلص منها بنفس الطابع الزمني t 1 . بدلاً من ذلك، ما يعلقه بروميثيوس كطابع زمني هو الوقت الذي يقوم فيه بإلغاء Pushgateway. لماذا ذلك؟

في النظرة العالمية لبروميثيوس، يمكن إلغاء المقياس في أي وقت. المقياس الذي لا يمكن كشطه لم يعد موجودًا بشكل أساسي. إن بروميثيوس متسامح إلى حد ما، ولكن إذا لم يتمكن من الحصول على أي عينات لمقياس ما في 5 دقائق، فسوف يتصرف كما لو أن هذا المقياس لم يعد موجودًا. يعد منع ذلك في الواقع أحد أسباب استخدام Pushgateway. ستجعل Pushgateway مقاييس وظيفتك المؤقتة قابلة للإلغاء في أي وقت. إن إرفاق وقت الدفع كطابع زمني من شأنه أن يبطل هذا الغرض لأنه بعد 5 دقائق من الدفعة الأخيرة، سيبدو مقياسك قديمًا بالنسبة إلى Prometheus كما لو أنه لم يعد من الممكن كشطه على الإطلاق. (يعرف بروميثيوس طابعًا زمنيًا واحدًا فقط لكل عينة، ولا توجد طريقة للتمييز بين "وقت الدفع" و"وقت الكشط".)

نظرًا لعدم وجود أي حالات استخدام يكون فيها من المنطقي إرفاق طابع زمني مختلف، ويحاول العديد من المستخدمين القيام بذلك بشكل غير صحيح (على الرغم من عدم وجود مكتبة عملاء تدعم ذلك)، فإن Pushgateway يرفض أي دفعات ذات طوابع زمنية.

إذا كنت تعتقد أنك بحاجة إلى دفع الطابع الزمني، فيرجى الاطلاع على متى يجب استخدام Pushgateway.

لتسهيل التنبيه على أدوات الدفع الفاشلة أو تلك التي لم يتم تشغيلها مؤخرًا، ستضيف بوابة Pushgate المقاييس push_time_seconds و push_failure_time_seconds مع الطابع الزمني لنظام Unix لآخر POST / PUT ناجحة وفاشلة لكل مجموعة. سيؤدي هذا إلى تجاوز أي مقياس مدفوع بهذا الاسم. تشير القيمة صفر لأي من المقياسين إلى أن المجموعة لم تشهد أبدًا POST / PUT ناجحة أو فاشلة.

واجهة برمجة التطبيقات

تتم جميع عمليات الدفع عبر HTTP. الواجهة تشبه REST بشكل غامض.

عنوان URL

المنفذ الافتراضي الذي يستمع إليه Pushgateway هو 9091. يبدو المسار

 /metrics/job/{//}

يتم استخدام كقيمة لتسمية job ، متبوعة بأي عدد من أزواج التسميات الأخرى (والتي قد تتضمن أو لا تتضمن تسمية instance ). يتم استخدام مجموعة التصنيفات المحددة بواسطة مسار URL كمفتاح تجميع. أي من هذه التصنيفات التي تم تعيينها بالفعل في نص الطلب (كتسميات عادية، على سبيل المثال name{job="foo"} 42 ) ستتم الكتابة فوقها لمطابقة التصنيفات المحددة بواسطة مسار URL!

إذا تمت إضافة اسم job أو أي تسمية بـ @base64 ، فسيتم تفسير اسم الوظيفة أو قيمة التسمية التالية على أنها سلسلة مشفرة base64 وفقًا لـ RFC 4648، باستخدام عنوان URL والأبجدية الآمنة لاسم الملف. (الحشو اختياري، ولكن = واحد مطلوب لترميز قيمة تسمية فارغة.) هذه هي الطريقة الوحيدة للتعامل مع الحالات التالية:

• اسم مهمة أو قيمة تسمية تحتوي على / ، لأن / سيتم تفسير عادي (أو حتى مشفر URI) / على أنه فاصل مسار.
• قيمة تسمية فارغة، لأن // أو اللاحقة / الناتجة ستختفي عندما يتم تنظيف المسار بواسطة رمز جهاز التوجيه HTTP. لاحظ أن اسم job الفارغة غير صالح. قيم التسمية الفارغة صالحة ولكنها نادرًا ما تكون مفيدة. لتشفيرها باستخدام base64، يجب عليك استخدام حرف = الحشو لتجنب // أو زائدة / .

بالنسبة للأحرف الخاصة الأخرى، يعمل تشفير مكون URI المعتاد أيضًا، ولكن قد يكون base64 أكثر ملاءمة.

من الناحية المثالية، تعتني مكتبات العملاء باللاحقة والتشفير.

أمثلة:

• لاستخدام مفتاح التجميع job="directory_cleaner",path="/var/tmp" ، لن يعمل المسار التالي:

   /metrics/job/directory_cleaner/path//var/tmp
  

  بدلاً من ذلك، استخدم التشفير الآمن لعنوان URL base64 لقيمة التصنيف وقم بوضع علامة عليه عن طريق إضافة اسم التصنيف بـ @base64 :

   /metrics/job/directory_cleaner/path@base64/L3Zhci90bXA
  

  إذا كنت لا تستخدم مكتبة عميل تتعامل مع التشفير نيابةً عنك، فيمكنك استخدام أدوات التشفير. على سبيل المثال، هناك أداة سطر الأوامر base64url (حزمة دبيان basez )، والتي يمكنك دمجها مع curl للدفع من سطر الأوامر بالطريقة التالية:

   echo 'some_metric{foo="bar"} 3.14' | curl --data-binary @- http://pushgateway.example.org:9091/metrics/job/directory_cleaner/path@base64/$(echo -n '/var/tmp' | base64url)
  

• لاستخدام مفتاح تجميع يحتوي على قيمة تسمية فارغة مثل job="example",first_label="",second_label="foobar" ، لن يعمل المسار التالي:

   /metrics/job/example/first_label//second_label/foobar
  

  بدلاً من ذلك، استخدم المسار التالي بما في ذلك حرف الحشو = :

   /metrics/job/example/first_label@base64/=/second_label/foobar
  

• يمكن تمثيل job="titan",name="Προμηθεύς" بشكل تقليدي" باستخدام تشفير URI:

   /metrics/job/titan/name/%CE%A0%CF%81%CE%BF%CE%BC%CE%B7%CE%B8%CE%B5%CF%8D%CF%82
  

  أو يمكنك استخدام ترميز base64 الأكثر إحكاما:

   /metrics/job/titan/name@base64/zqDPgc6_zrzOt864zrXPjc-C
  

دعم UTF-8 لأسماء القياسات والتسميات

تدعم الإصدارات الأحدث من تنسيقات عرض Prometheus (النص والبروتوبوف) مجموعة أحرف UTF-8 الكاملة في أسماء القياسات والتسميات. يقبل Pushgateway فقط الأحرف الخاصة في الأسماء إذا تم تعيين علامة سطر الأوامر --push.enable-utf8-names . للسماح بأحرف خاصة في أسماء التصنيفات التي تعد جزءًا من مسار URL، تعمل العلامة أيضًا على تمكين آلية تشفير محددة. يشبه هذا ترميز base64 لقيم التصنيف الموضحة أعلاه، ولكنه يعمل بشكل مختلف بالتفصيل لأسباب فنية وتاريخية. كما كان من قبل، يجب على مكتبات العملاء عادةً الاهتمام بالترميز. يعمل على النحو التالي:

• يبدأ اسم التصنيف الذي يحتوي على أحرف مشفرة بـ U__ .
• يتم ترميز كافة الأحرف غير القياسية (أي الأحرف بخلاف الأحرف والأرقام والشرطات السفلية) كشرطات سفلية تحيط بقيمة Unicode الخاصة بها، مثل _1F60A_ .
• يتم ترميز كافة الشرطات السفلية الموجودة مسبقًا كشرطة سفلية مزدوجة: __ .
• إذا كان اسم التصنيف يبدأ بـ U__ بالفعل، فيجب تشفير هذه الأحرف أيضًا، مما يؤدي إلى U___55_____ . (هذا U__ + _55_ (من أجل U ) + __ + __ ).
• اسم التصنيف الذي يبدأ بـ U__ في صيغته المشفرة، ولكنه يحتوي على تسلسلات غير صالحة (على سبيل المثال، U__in_xxx_valid ) يتم تركه دون تغيير.

على سبيل المثال، سيتم ترميز التسمية "foo.bar"="baz" على النحو التالي:

 /metrics/job/example/U__foo_2e_bar/baz

هذا الترميز متوافق مع ترميز base64 لقيم التسمية:

 /metrics/job/example/U__foo_2e_bar@base64/YmF6

لاحظ أن هذه الطريقة تحتوي على حالة حافة غير محتملة لم يتم التعامل معها بشكل صحيح: قد يستخدم دافع غير مدرك لآلية التشفير اسم تسمية يعد أيضًا إصدارًا مشفرًا صالحًا لاسم تسمية آخر. على سبيل المثال، إذا كان الدافع ينوي استخدام اسم التصنيف U__foo_2e_bar ، لكنه لم يشفره كـ U___55_____foo__2e__bar ، فسوف يقوم Pushgateway بفك تشفير U__foo_2e_bar إلى foo.bar . هذا هو السبب الرئيسي وراء اختيار فك التشفير عبر علامة --push.enable-utf8-names .

طريقة PUT

يتم استخدام PUT لدفع مجموعة من المقاييس. يتم استبدال جميع المقاييس التي تحتوي على مفتاح التجميع المحدد في عنوان URL بالمقاييس المدفوعة باستخدام PUT .

يحتوي نص الطلب على المقاييس التي سيتم دفعها إما كمخازن مؤقتة محددة للبروتوكول الثنائي أو بتنسيق نص مسطح بسيط (كلاهما في الإصدار 0.0.4، راجع مواصفات تنسيق عرض البيانات). ويتم التمييز بين المتغيرين عبر رأس Content-Type . (استخدم القيمة application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=delimited للمخازن المؤقتة للبروتوكول، وإلا فسيتم تجربة تنسيق النص كبديل احتياطي.)

رمز الاستجابة عند النجاح هو إما 200 أو 202 أو 400. وتعني الاستجابة 200 دفعة ناجحة، إما باستبدال مجموعة موجودة من المقاييس أو إنشاء مجموعة جديدة. يمكن أن تحدث استجابة 400 إذا كان الطلب مشوهًا أو إذا كانت المقاييس المدفوعة غير متوافقة مع المقاييس المدفوعة إلى مجموعات أخرى أو تتعارض مع مقاييس Pushgateway نفسها. يتم إرجاع تفسير في نص الاستجابة وتسجيل الدخول على مستوى الخطأ. يمكن أن يحدث 202 فقط إذا تم تعيين علامة --push.disable-consistency-check . في هذه الحالة، يتم وضع المقاييس المدفوعة في قائمة الانتظار فقط ولا يتم التحقق من تناسقها. ومع ذلك، فإن التناقضات ستؤدي إلى عمليات خدش فاشلة، كما هو موضح أعلاه.

في حالات نادرة، من الممكن أن ينتهي الأمر بـ Pushgateway بمجموعة غير متناسقة من المقاييس التي تم دفعها بالفعل. في هذه الحالة، يتم أيضًا رفض عمليات الدفع الجديدة باعتبارها غير متسقة حتى لو كان السبب هو المقاييس التي تم دفعها مسبقًا. احذف المقاييس المخالفة للخروج من هذا الموقف.

في حالة استخدام تنسيق protobuf، لا ترسل رسائل MetricFamily الأولية المكررة (أي أكثر من واحدة بنفس الاسم) في دفعة واحدة، لأنها ستحل محل بعضها البعض.

لاحظ أن Pushgateway لا يوفر أي ضمانات قوية بأن المقاييس المدفوعة ستستمر على القرص. (قد يتسبب تعطل الخادم في فقدان البيانات. أو تم تكوين Pushgateway بحيث لا يستمر في القرص على الإطلاق.)

يؤدي طلب PUT بنص فارغ إلى حذف جميع المقاييس باستخدام مفتاح التجميع المحدد بشكل فعال. ومع ذلك، وعلى النقيض من طلب DELETE الموضح أدناه، فإنه يقوم بتحديث مقاييس push_time_seconds .

طريقة POST

يعمل POST تمامًا مثل طريقة PUT ولكن يتم استبدال المقاييس التي تحمل نفس اسم المقاييس المدفوعة حديثًا فقط (من بين تلك التي لها نفس مفتاح التجميع).

يقوم طلب POST الذي يحتوي على نص فارغ فقط بتحديث مقاييس push_time_seconds ولكنه لا يغير أيًا من المقاييس التي تم دفعها مسبقًا.

طريقة DELETE

يتم استخدام DELETE لحذف المقاييس من Pushgateway. يجب ألا يحتوي الطلب على أي محتوى. يتم حذف كافة المقاييس التي تحتوي على مفتاح التجميع المحدد في عنوان URL.

رمز الاستجابة عند النجاح هو دائمًا 202. يتم وضع طلب الحذف في قائمة الانتظار فقط في تلك اللحظة. ليس هناك ما يضمن أنه سيتم تنفيذ الطلب فعليًا أو أن النتيجة ستصل إلى طبقة الثبات (على سبيل المثال، في حالة تعطل الخادم). ومع ذلك، فإن ترتيب طلب PUT / POST و DELETE مضمون، أي إذا كنت قد أرسلت طلب DELETE بنجاح ثم أرسلت PUT ، فمن المضمون أن تتم معالجة DELETE أولاً (والعكس صحيح).

يعد حذف مفتاح التجميع بدون مقاييس أمرًا محظورًا ولن يؤدي إلى حدوث خطأ.

طلب الضغط

قد يكون نص طلب POST أو PUT مضغوطًا بصيغة gzip أو snappy. أضف رأسًا Content-Encoding: gzip أو Content-Encoding: snappy للقيام بذلك.

أمثلة:

 echo " some_metric 3.14 " | gzip | curl -H ' Content-Encoding: gzip ' --data-binary @- http://pushgateway.example.org:9091/metrics/job/some_job
echo " some_metric 3.14 " | snzip | curl -H ' Content-Encoding: snappy ' --data-binary @- http://pushgateway.example.org:9091/metrics/job/some_job

واجهة برمجة تطبيقات المشرف

توفر Admin API وصولاً إداريًا إلى Pushgateway، ويجب تمكينها بشكل صريح عن طريق تعيين علامة --web.enable-admin-api .

عنوان URL

المنفذ الافتراضي الذي يستمع إليه Pushgateway هو 9091. يبدو المسار كما يلي:

 /api//admin/

• نقاط النهاية المتاحة:

HTTP_METHOD	API_VERSION	معالج	وصف
يضع	الإصدار 1	يمسح	يحذف جميع المقاييس بأمان من Pushgateway.

• على سبيل المثال، لمسح جميع المقاييس من Pushgateway:

    curl -X PUT http://pushgateway.example.org:9091/api/v1/admin/wipe
  

واجهة برمجة تطبيقات الاستعلام

تسمح واجهة برمجة تطبيقات الاستعلام بالوصول إلى المقاييس المدفوعة ومعلومات البناء ووقت التشغيل.

عنوان URL

 /api//

• نقاط النهاية المتاحة:

HTTP_METHOD	API_VERSION	معالج	وصف
يحصل	الإصدار 1	حالة	إرجاع معلومات البناء وإشارات سطر الأوامر ووقت البدء بتنسيق JSON.
يحصل	الإصدار 1	المقاييس	إرجاع مجموعات المقاييس المدفوعة بتنسيق JSON.

• على سبيل المثال :

    curl -X GET http://pushgateway.example.org:9091/api/v1/status | jq
    
    {
      "status": "success",
      "data": {
        "build_information": {
          "branch": "master",
          "buildDate": "20200310-20:14:39",
          "buildUser": "[email protected]",
          "goVersion": "go1.13.6",
          "revision": "eba0ec4100873d23666bcf4b8b1d44617d6430c4",
          "version": "1.1.0"
        },
        "flags": {
          "log.format": "logfmt",
          "log.level": "info",
          "persistence.file": "",
          "persistence.interval": "5m0s",
          "push.disable-consistency-check": "false",
          "web.enable-admin-api": "false",
          "web.enable-lifecycle": "false",
          "web.external-url": "",
          "web.listen-address": ":9091",
          "web.route-prefix": "",
          "web.telemetry-path": "/metrics"
        },
        "start_time": "2020-03-11T01:44:49.9189758+05:30"
      }
    }
    
    curl -X GET http://pushgateway.example.org:9091/api/v1/metrics | jq
    
    {
      "status": "success",
      "data": [
        {
          "labels": {
            "job": "batch"
          },
          "last_push_successful": true,
          "my_job_duration_seconds": {
            "time_stamp": "2020-03-11T02:02:27.716605811+05:30",
            "type": "GAUGE",
            "help": "Duration of my batch job in seconds",
            "metrics": [
              {
                "labels": {
                  "instance": "",
                  "job": "batch"
                },
                "value": "0.2721322309989773"
              }
            ]
          },
          "push_failure_time_seconds": {
            "time_stamp": "2020-03-11T02:02:27.716605811+05:30",
            "type": "GAUGE",
            "help": "Last Unix time when changing this group in the Pushgateway failed.",
            "metrics": [
              {
                "labels": {
                  "instance": "",
                  "job": "batch"
                },
                "value": "0"
              }
            ]
          },
          "push_time_seconds": {
            "time_stamp": "2020-03-11T02:02:27.716605811+05:30",
            "type": "GAUGE",
            "help": "Last Unix time when changing this group in the Pushgateway succeeded.",
            "metrics": [
              {
                "labels": {
                  "instance": "",
                  "job": "batch"
                },
                "value": "1.5838723477166057e+09"
              }
            ]
          }
        }
      ]
    }
  

واجهة برمجة تطبيقات الإدارة

توفر Pushgateway مجموعة من واجهات برمجة التطبيقات الإدارية لتسهيل الأتمتة والتكامل.

• نقاط النهاية المتاحة:

HTTP_METHOD	طريق	وصف
يحصل	/-/صحيح	يتم إرجاع 200 عندما تكون Pushgateway سليمة.
يحصل	/-/مستعد	يُرجع 200 عندما يكون Pushgateway جاهزًا لخدمة حركة المرور.

• يتم تعطيل نقطة النهاية التالية افتراضيًا ويمكن تمكينها عبر علامة --web.enable-lifecycle .

HTTP_METHOD	طريق	وصف
يضع	/-/يترك	يؤدي إلى إيقاف تشغيل Pushgateway بشكل رائع.

وبدلاً من ذلك، يمكن تشغيل إيقاف التشغيل بسلاسة عن طريق إرسال SIGTERM إلى عملية Pushgateway.

المقاييس المكشوفة

يعرض Pushgateway المقاييس التالية عبر --web.telemetry-path الذي تم تكوينه (الافتراضي: /metrics ):

• المقاييس المدفوعة.
• لكل مجموعة مدفوعة، يتم قياس push_time_seconds بالثواني ووقت push_failure_time_seconds كما هو موضح أعلاه.
• المقاييس المعتادة التي توفرها مكتبة عميل Prometheus Go، على سبيل المثال:
  • process_...
  • go_...
  • promhttp_metric_handler_requests_...
• عدد من المقاييس الخاصة بـ Pushgateway، كما هو موثق في المثال الموضح أدناه.

 # HELP pushgateway_build_info A metric with a constant '1' value labeled by version, revision, branch, and goversion from which pushgateway was built.
# TYPE pushgateway_build_info gauge
pushgateway_build_info{branch="master",goversion="go1.10.2",revision="8f88ccb0343fc3382f6b93a9d258797dcb15f770",version="0.5.2"} 1
# HELP pushgateway_http_push_duration_seconds HTTP request duration for pushes to the Pushgateway.
# TYPE pushgateway_http_push_duration_seconds summary
pushgateway_http_push_duration_seconds{method="post",quantile="0.1"} 0.000116755
pushgateway_http_push_duration_seconds{method="post",quantile="0.5"} 0.000192608
pushgateway_http_push_duration_seconds{method="post",quantile="0.9"} 0.000327593
pushgateway_http_push_duration_seconds_sum{method="post"} 0.001622878
pushgateway_http_push_duration_seconds_count{method="post"} 8
# HELP pushgateway_http_push_size_bytes HTTP request size for pushes to the Pushgateway.
# TYPE pushgateway_http_push_size_bytes summary
pushgateway_http_push_size_bytes{method="post",quantile="0.1"} 166
pushgateway_http_push_size_bytes{method="post",quantile="0.5"} 182
pushgateway_http_push_size_bytes{method="post",quantile="0.9"} 196
pushgateway_http_push_size_bytes_sum{method="post"} 1450
pushgateway_http_push_size_bytes_count{method="post"} 8
# HELP pushgateway_http_requests_total Total HTTP requests processed by the Pushgateway, excluding scrapes.
# TYPE pushgateway_http_requests_total counter
pushgateway_http_requests_total{code="200",handler="static",method="get"} 5
pushgateway_http_requests_total{code="200",handler="status",method="get"} 8
pushgateway_http_requests_total{code="202",handler="delete",method="delete"} 1
pushgateway_http_requests_total{code="202",handler="push",method="post"} 6
pushgateway_http_requests_total{code="400",handler="push",method="post"} 2

التنبيه على الدفعات الفاشلة

إنها فكرة جيدة بشكل عام أن يتم التنبيه على أن push_time_seconds متأخر كثيرًا عن المتوقع. سيؤدي هذا إلى اكتشاف كل من الدفعات الفاشلة بالإضافة إلى تعطل أدوات الدفع تمامًا.

لاكتشاف عمليات الدفع الفاشلة في وقت أبكر بكثير، قم بالتنبيه على push_failure_time_seconds > push_time_seconds .

يمكن أن تفشل الدفعات أيضًا لأنها مشوهة. وفي هذه الحالة، لن يصلوا مطلقًا إلى أي مجموعة قياس، وبالتالي لن يقوموا بتعيين أي مقاييس push_failure_time_seconds . لا تزال هذه الدفعات تُحسب على أنها pushgateway_http_requests_total{code="400",handler="push"} . يمكنك التنبيه بشأن rate هذا المقياس، ولكن يتعين عليك فحص السجلات لتحديد هوية الدافع المخالف.

TLS والمصادقة الأساسية

يدعم Pushgateway TLS والمصادقة الأساسية. يتيح ذلك تحكمًا أفضل في نقاط نهاية HTTP المختلفة.

لاستخدام TLS و/أو المصادقة الأساسية، تحتاج إلى تمرير ملف التكوين باستخدام المعلمة --web.config.file . تم توضيح تنسيق الملف في مستودع أدوات التصدير.

لاحظ أن إعدادات TLS والمصادقة الأساسية تؤثر على جميع نقاط نهاية HTTP: /metrics للاستخراج، وواجهة برمجة التطبيقات لدفع المقاييس عبر /metrics/...، وواجهة برمجة تطبيقات المشرف عبر /api/...، وواجهة مستخدم الويب.

تطوير

يقوم الثنائي العادي بتضمين ملفات الويب في دليل resources . لأغراض التطوير، من السهل أن يكون لديك برنامج ثنائي قيد التشغيل يستخدم تلك الملفات مباشرة (بحيث يمكنك رؤية تأثير التغييرات على الفور). للتبديل إلى الاستخدام المباشر، قم بإضافة -tags dev إلى مُدخل flags في .promu.yml ، ثم make build . قم بالتبديل مرة أخرى إلى الوضع "العادي" عن طريق الرجوع إلى التغييرات التي تم إجراؤها على .promu.yml وكتابة make assets .

المساهمة

إرشادات النمط ذات الصلة هي تعليقات مراجعة كود Go وقسم التنسيق والنمط في كتاب Peter Bourgon Go: أفضل الممارسات لبيئات الإنتاج.