> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> دعم واجهة برمجة تطبيقات HTTP لـ Prometheus في ClickHouse: الكتابة والقراءة عن بُعد، واستعلامات PromQL، ومقاييس الخادم.

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

export const CloudNotSupportedBadge = () => {
  return <a href="https://clickhouse.com/docs/products/cloud/guides/cloud-compatibility#list-of-unsupported-features" className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            غير مدعوم في ClickHouse Cloud
        </a>;
};

<div id="expose">
  ## كشف مقاييس خادم ClickHouse
</div>

<Note>
  إذا كنت تستخدم ClickHouse Cloud، يمكنك كشف المقاييس لـ Prometheus باستخدام [تكامل Prometheus](/ar/products/cloud/features/monitoring/prometheus).
</Note>

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

```xml theme={null}
<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>`](/ar/concepts/features/interfaces/http) but works for prometheus protocols:

```xml theme={null}
<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>`](/ar/concepts/features/interfaces/http).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `info`                       | true       | يعرض مقياس Gauge `ClickHouse_Info` مع تسميات هوية الخادم (`name`، `version`، `version_describe`، `version_major`، `version_minor`، `version_patch`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `metrics`                    | true       | يعرض المقاييس من [`system.metrics`](/ar/reference/system-tables/metrics).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `asynchronous_metrics`       | true       | يعرض المقاييس من [`system.asynchronous_metrics`](/ar/reference/system-tables/asynchronous_metrics).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `events`                     | true       | يعرض المقاييس من [`system.events`](/ar/reference/system-tables/events).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `errors`                     | true       | يعرض أعداد الأخطاء من [`system.errors`](/ar/reference/system-tables/errors).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `histograms`                 | true       | يعرض المقاييس من [`system.histogram_metrics`](/ar/reference/system-tables/histogram_metrics).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `dimensional_metrics`        | true       | يعرض المقاييس من [`system.dimensional_metrics`](/ar/reference/system-tables/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`. ولأنه يعتمد على ما تعرضه نقطة النهاية فعليًا، قد يكون الاسم صالحًا في نقطة نهاية ويُرفض في أخرى. |

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

```bash theme={null}
curl http://127.0.0.1:9363/metrics
```

<CloudNotSupportedBadge />

<div id="prometheus-http-api-and-promql">
  ## واجهة Prometheus HTTP واجهة برمجة تطبيقات وPromQL
</div>

يطبّق ClickHouse واجهة Prometheus HTTP واجهة برمجة تطبيقات على جدول [`TimeSeries`](/ar/reference/engines/table-engines/integrations/time-series). يتولى معالج واحد عمليات الكتابة والقراءة عن بُعد، واستعلامات PromQL الفورية، واستعلامات PromQL للنطاق.

<div id="prerequisites">
  ### المتطلبات الأساسية
</div>

فعِّل الإعداد [`allow_experimental_time_series_table`](/ar/reference/settings/session-settings/allow-experimental#allow_experimental_time_series_table) للمستخدم الذي يُنشئ الجدول ويصل إليه:

```sql theme={null}
SET allow_experimental_time_series_table = 1;
```

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

```sql theme={null}
CREATE DATABASE prometheus;
CREATE TABLE prometheus.metrics ENGINE = TimeSeries;
```

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

<div id="configure-prometheus-api">
  ### تهيئة واجهة برمجة تطبيقات Prometheus
</div>

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

```xml theme={null}
<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`.

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

```xml theme={null}
<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`. |

<div id="remote-write">
  ### استيعاب المقاييس عبر الكتابة عن بُعد
</div>

يدعم ClickHouse [بروتوكول الكتابة عن بُعد لـ Prometheus](https://prometheus.io/docs/specs/remote_write_spec/). هيّئ Prometheus للكتابة إلى المعالج:

```yaml theme={null}
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`.

لتجميع البيانات من عدة طلبات كتابة عن بُعد متزامنة في عدد أقل من الأجزاء، فعّل [عمليات الإدراج غير المتزامنة](/ar/reference/settings/session-settings/async-insert#async_insert) بإضافة إعداد `async_insert` إلى عنوان URL (أو بتفعيله في ملف تعريف المستخدم):

```yaml theme={null}
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`](/ar/reference/settings/session-settings/wait-for#wait_for_async_insert): إذ يتعامل بروتوكول الكتابة عن بُعد مع الكتابة المُقَرّ بها على أنها دائمة. وإذا أخفق التفريغ، يُرجع الطلب خطأً ويعيد Prometheus محاولة إرساله.

<div id="promql-query-support">
  ### الاستعلام باستخدام PromQL
</div>

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

```bash theme={null}
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"
```

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

```bash theme={null}
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 المدعومة](/ar/reference/functions/table-functions/prometheusQueryRange#supported-promql-features) للاطلاع على قائمة الدالات وعوامل التجميع التي تستخدمها واجهة برمجة تطبيقات HTTP، ولهجة `promql`، ودالات الجداول.

<div id="grafana">
  #### Grafana
</div>

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

```yaml theme={null}
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` إلى كل طلب.

<Note>
  لا تُنفَّذ إلا نقطتا نهاية الاستعلام ‎`/api/v1/query` و‎`/api/v1/query_range` ونقاط نهاية البيانات الوصفية ‎`/api/v1/series` و‎`/api/v1/labels` و‎`/api/v1/metadata`. تتطلب ‎`/api/v1/series` محدِّد سلاسل واحدًا على الأقل من `match[]`، وتدعم المعلمات الاختيارية `start` و`end` و`limit`، وتُرجع اتحاد السلاسل المطابقة لكل محدِّد. تقبل ‎`/api/v1/labels` المعلمات نفسها، مع كون `match[]` اختياريًا، وتُرجع أسماء التسميات المرتبة للسلاسل المطابقة (أو لجميع السلاسل عند عدم تقديم أي محددات). أما نقطة نهاية قيم التسميات (‎`/api/v1/label/<name>/values`) التي يستخدمها مصدر بيانات Prometheus في Grafana لتصفّح التسميات ومتغيرات القوالب والإكمال التلقائي في أداة إنشاء الاستعلامات، فهي غير منفَّذة وتُرجع خطأً. اكتب تعبيرات PromQL في وضع الشيفرة بدلاً من أداة إنشاء الاستعلامات.
</Note>

<div id="sql-entry-points">
  #### نقاط إدخال SQL
</div>

يستخدم ClickHouse محوّل PromQL نفسه لواجهة برمجة تطبيقات HTTP، ولهجة `promql`، ودالتي الجدول [`prometheusQuery`](/ar/reference/functions/table-functions/prometheusQuery) و[`prometheusQueryRange`](/ar/reference/functions/table-functions/prometheusQueryRange).

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

```bash theme={null}
clickhouse-client \
  --dialect promql \
  --promql_database prometheus \
  --promql_table metrics \
  --query 'rate(http_requests_total[5m])'
```

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

```sql theme={null}
SELECT *
FROM prometheusQuery(
    prometheus.metrics,
    'rate(http_requests_total[5m])',
    now()
);
```

<div id="metadata">
  ### الاستعلام عن البيانات الوصفية للمقاييس
</div>

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

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

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

```bash theme={null}
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"
```

<div id="remote-read">
  ### قراءة المقاييس عبر القراءة عن بُعد
</div>

يدعم ClickHouse [بروتوكول القراءة عن بُعد لـ Prometheus](https://prometheus.io/docs/prometheus/latest/querying/remote_read_api/) على المسار `/prometheus/api/v1/read`.

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

```yaml theme={null}
remote_read:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/read?database=prometheus&table=metrics
    basic_auth:
      username: default
      password: <password>
```