Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

بروتوكولات Prometheus وPromQL

View as MarkdownEdit this pageReport an issueSet up docs MCP

كشف مقاييس خادم ClickHouse

هيّئ منفذًا مخصصًا عندما يحتاج خادم Prometheus إلى كشط مقاييس ClickHouse الخاصة:

<prometheus>
    <port>9363</port>
    <endpoint>/metrics</endpoint>
    <metrics>true</metrics>
    <asynchronous_metrics>true</asynchronous_metrics>
    <events>true</events>
    <errors>true</errors>
    <histograms>true</histograms>
    <dimensional_metrics>true</dimensional_metrics>
</prometheus>

يمكن استخدام القسم <prometheus.handlers> لإنشاء معالجات موسّعة إضافية على المنفذ نفسه. This section is similar to <http_handlers> but works for prometheus protocols:

<prometheus>
    <port>9363</port>
    <handlers>
        <my_rule_1>
            <url>/metrics</url>
            <handler>
                <type>expose_metrics</type>
                <metrics>true</metrics>
                <asynchronous_metrics>true</asynchronous_metrics>
                <events>true</events>
                <errors>true</errors>
                <histograms>true</histograms>
                <dimensional_metrics>true</dimensional_metrics>
                <labels>
                    <environment>production</environment>
                    <shard from_env="SHARD_NAME"></shard>
                </labels>
            </handler>
        </my_rule_1>
    </handlers>
</prometheus>

الإعدادات:

الاسم الافتراضي الوصف
port لا شيء المنفذ الذي يقدّم مقاييس ClickHouse.
endpoint /metrics نقطة نهاية HTTP لكشط المقاييس. تبدأ بـ /. يجب عدم استخدامها مع قسم <handlers>.
url / headers / method لا شيء عوامل التصفية المستخدمة للعثور على معالج مطابق للطلب. وهي مشابهة للحقول التي تحمل الأسماء نفسها في قسم <http_handlers>.
info true يعرض مقياس Gauge ClickHouse_Info مع تسميات هوية الخادم (name، version، version_describe، version_major، version_minor، version_patch).
metrics true يعرض المقاييس من system.metrics.
asynchronous_metrics true يعرض المقاييس من system.asynchronous_metrics.
events true يعرض المقاييس من system.events.
errors true يعرض أعداد الأخطاء من system.errors.
histograms true يعرض المقاييس من system.histogram_metrics.
dimensional_metrics true يعرض المقاييس من system.dimensional_metrics.
labels لا شيء تسميات ثابتة تُضاف إلى كل مقياس معروض. يحدد كل عنصر تابع تسمية واحدة: اسم العنصر هو اسم التسمية (ويجب أن يطابق [a-zA-Z_][a-zA-Z0-9_]*) وقيمة العنصر هي قيمة التسمية. تدعم قيم التسميات استبدالات الإعدادات القياسية مثل السمة from_env. يُرفض اسم التسمية عندما يبدأ بـ __ (محجوز بواسطة Prometheus)، أو عندما يتعارض مع تسمية تكتبها نقطة النهاية هذه بالفعل لأحد أقسامها المفعّلة. لذلك تتبع مجموعة الأسماء المحجوزة سطح التصدير النشط لنقطة النهاية: le عند تفعيل histograms؛ وتسميات ClickHouse_Info (name، version، version_describe، version_major، version_minor، version_patch) عند تفعيل info؛ وأي تسمية تستخدمها عائلة مقاييس مُدرَّج تكراري أو مقاييس متعددة الأبعاد معروضة (على سبيل المثال، group أو direction أو operation_type) عند تفعيل histograms أو dimensional_metrics. ولأنه يعتمد على ما تعرضه نقطة النهاية فعليًا، قد يكون الاسم صالحًا في نقطة نهاية ويُرفض في أخرى.

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

curl http://127.0.0.1:9363/metrics
غير مدعوم في ClickHouse Cloud

واجهة Prometheus HTTP واجهة برمجة تطبيقات وPromQL

يطبّق ClickHouse واجهة Prometheus HTTP واجهة برمجة تطبيقات على جدول TimeSeries. يتولى معالج واحد عمليات الكتابة والقراءة عن بُعد، واستعلامات PromQL الفورية، واستعلامات PromQL للنطاق.

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

فعِّل الإعداد allow_experimental_time_series_table للمستخدم الذي يُنشئ الجدول ويصل إليه:

SET allow_experimental_time_series_table = 1;

أنشئ قاعدة بيانات وجدولًا من نوع TimeSeries:

CREATE DATABASE prometheus;
CREATE TABLE prometheus.metrics ENGINE = TimeSeries;

لطلبات واجهة برمجة تطبيقات HTTP، فعِّل allow_experimental_time_series_table في ملف تعريف مستخدم واجهة برمجة التطبيقات.

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

هيِّئ معالجًا واحدًا قائمًا على توجيه البادئة على منفذ HTTP الرئيسي لـ ClickHouse:

<http_handlers>
    <defaults/>
    <rule>
        <url_prefix>/prometheus/api/v1</url_prefix>
        <handler>
            <type>prometheus_api_v1</type>
        </handler>
    </rule>
</http_handlers>

<defaults/> يحافظ على المعالجات المضمنة لنقاط النهاية، مثل /ping وطلبات SQL. تتيح البادئة أعلاه الوصول إلى هذه النقاط عبر معالج واحد:

نقطة النهاية الغرض
/prometheus/api/v1/write الكتابة عن بُعد في Prometheus
/prometheus/api/v1/read القراءة عن بُعد من Prometheus
/prometheus/api/v1/query استعلامات PromQL الفورية
/prometheus/api/v1/query_range استعلامات PromQL للنطاق
/prometheus/api/v1/series البيانات الوصفية للسلاسل
/prometheus/api/v1/metadata البيانات الوصفية لعائلة المقاييس

يحذف المثال database وtable من المعالج. يجب أن يتضمن كل طلب معلمة الاستعلام table. ويمكنه أيضًا تضمين database، أو استخدام اسم جدول مؤهل مثل prometheus.metrics، أو حذف قاعدة البيانات لاستخدام default. يتيح ذلك لمعالج واحد خدمة عدة جداول TimeSeries.

لاستخدام جدول ثابت واحد لكل طلب، هيّئه في المعالج:

<handler>
    <type>prometheus_api_v1</type>
    <database>prometheus</database>
    <table>metrics</table>
</handler>

لا يمكن تجاوز جدول مُهيأ في المعالج باستخدام معاملات الطلب.

إعدادات التوجيه والمعالج:

الاسم الافتراضي الوصف
url_prefix none قاعدة تصفية تطابق كل مسار طلب يبدأ بالبادئة المُهيأة.
table none اسم جدول TimeSeries. عند عدم تحديده، يجب أن يتضمن الطلب معلمة الاستعلام table. ويمكن أن يشمل الاسم المُهيأ قاعدة بيانات.
database none قاعدة البيانات التي تحتوي على الجدول. يمكن للطلب تحديدها كمعلمة استعلام. عند عدم تحديدها، يستخدم ClickHouse قاعدة البيانات من قيمة table المؤهلة، أو يلجأ إلى default.

استيعاب المقاييس عبر الكتابة عن بُعد

يدعم ClickHouse بروتوكول الكتابة عن بُعد لـ Prometheus. هيّئ Prometheus للكتابة إلى المعالج:

remote_write:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics
    basic_auth:
      username: default
      password: <password>

يرسل Prometheus العينات إلى جدول prometheus.metrics.

لتجميع البيانات من عدة طلبات كتابة عن بُعد متزامنة في عدد أقل من الأجزاء، فعّل عمليات الإدراج غير المتزامنة بإضافة إعداد async_insert إلى عنوان URL (أو بتفعيله في ملف تعريف المستخدم):

remote_write:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics&async_insert=1

لا يقرّ ClickHouse طلب الكتابة عن بُعد غير المتزامن إلا بعد تفريغ البيانات إلى جميع الجداول الداخلية لجدول TimeSeries، بغض النظر عن إعداد wait_for_async_insert: إذ يتعامل بروتوكول الكتابة عن بُعد مع الكتابة المُقَرّ بها على أنها دائمة. وإذا أخفق التفريغ، يُرجع الطلب خطأً ويعيد Prometheus محاولة إرساله.

الاستعلام باستخدام PromQL

استخدم نقطة نهاية الاستعلام الفوري لتقييم تعبير PromQL في نقطة زمنية محددة:

curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/query" \
  --data-urlencode "query=rate(http_requests_total[5m])" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"

استخدم نقطة نهاية استعلام النطاق لتقييم تعبير ضمن نطاق زمني:

curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/query_range" \
  --data-urlencode "query=rate(http_requests_total[5m])" \
  --data-urlencode "start=2026-08-15T12:00:00Z" \
  --data-urlencode "end=2026-08-15T13:00:00Z" \
  --data-urlencode "step=60s" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"

راجع ميزات PromQL المدعومة للاطلاع على قائمة الدالات وعوامل التجميع التي تستخدمها واجهة برمجة تطبيقات HTTP، ولهجة promql، ودالات الجداول.

Grafana

هيّئ مصدر بيانات Prometheus باستخدام عنوان URL أساسي ينتهي قبل /api/v1:

apiVersion: 1
datasources:
  - name: ClickHouse Prometheus
    type: prometheus
    access: proxy
    url: https://clickhouse.example.com:8443/prometheus
    basicAuth: true
    basicAuthUser: default
    jsonData:
      httpMethod: GET
      customQueryParameters: database=prometheus&table=metrics
    secureJsonData:
      basicAuthPassword: <password>

يُلحق Grafana المسارَين ‎/api/v1/query أو ‎/api/v1/query_range بعنوان URL الأساسي هذا، ويضيف customQueryParameters إلى كل طلب.

نقاط إدخال SQL

يستخدم ClickHouse محوّل PromQL نفسه لواجهة برمجة تطبيقات HTTP، ولهجة promql، ودالتي الجدول prometheusQuery وprometheusQueryRange.

شغّل PromQL مباشرةً باستخدام clickhouse-client:

clickhouse-client \
  --dialect promql \
  --promql_database prometheus \
  --promql_table metrics \
  --query 'rate(http_requests_total[5m])'

استخدم دوال الجداول لتضمين PromQL في استعلام SQL:

SELECT *
FROM prometheusQuery(
    prometheus.metrics,
    'rate(http_requests_total[5m])',
    now()
);

الاستعلام عن البيانات الوصفية للمقاييس

تعيد نقطة النهاية /prometheus/api/v1/metadata البيانات الوصفية للمقاييس المخزنة في الجدول الهدف Metrics ضمن جدول TimeSeries، وهي تشمل النوع ونص المساعدة ووحدة كل عائلة مقاييس. وتدعم معلمات Prometheus التالية في سلسلة استعلام URL:

المعلمة الوصف
metric تُرجع البيانات الوصفية لهذه العائلة من المقاييس فقط.
limit يحدّ من عدد عائلات المقاييس المُعادة. تعني القيمة السالبة عدم وجود حد، بينما لا تُرجع القيمة صفر أي عائلات مقاييس.
limit_per_metric يحدّ من عدد كائنات البيانات الوصفية المُعادة لكل عائلة مقاييس. تعني القيم الصفرية والسالبة عدم وجود حد.

الجدول الهدف الافتراضي Metrics هو جدول ReplacingMergeTree مرتب حسب اسم عائلة المقاييس، ويحتفظ بأحدث إدخال للبيانات الوصفية تمت كتابته لكل عائلة مقاييس. ولا تُعاد عدة إدخالات لكل عائلة إلا ما دام الجدول الهدف يحتفظ بها، أي قبل دمج أجزائه أو عند تعريف الجدول بمحرك يحافظ عليها.

curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/metadata" \
  --data-urlencode "metric=http_requests_total" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"

قراءة المقاييس عبر القراءة عن بُعد

يدعم ClickHouse بروتوكول القراءة عن بُعد لـ Prometheus على المسار /prometheus/api/v1/read.

هيّئ خادم Prometheus للقراءة من جدول TimeSeries نفسه:

remote_read:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/read?database=prometheus&table=metrics
    basic_auth:
      username: default
      password: <password>
Navigation