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

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

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

export const PrivatePreviewBadge = () => {
  return <div className="privatePreviewBadge">
            <div className="privatePreviewIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path d="M5.33301 6.66667V4.66667V4.66667C5.33301 3.194 6.52701 2 7.99967 2V2C9.47234 2 10.6663 3.194 10.6663 4.66667V4.66667V6.66667" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path d="M8.00033 9.33337V11.3334" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path fillRule="evenodd" clipRule="evenodd" d="M11.333 14H4.66634C3.92967 14 3.33301 13.4033 3.33301 12.6666V7.99996C3.33301 7.26329 3.92967 6.66663 4.66634 6.66663H11.333C12.0697 6.66663 12.6663 7.26329 12.6663 7.99996V12.6666C12.6663 13.4033 12.0697 14 11.333 14Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            {'معاينة خاصة'}
        </div>;
};

<PrivatePreviewBadge />

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

لعرض مقاييس ClickHouse الخاصة لكي يجمعها خادم Prometheus، راجع [نقطة نهاية مقاييس Prometheus](/ar/concepts/features/interfaces/prometheus-metrics).

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

تختلف خطوات الإعداد بين ClickHouse Cloud وClickHouse المُدار ذاتيًا. اتبع القسم الخاص بنوع النشر لديك.

<h3 id="prerequisites-cloud">
  ClickHouse Cloud
</h3>

<Note>
  دعم PromQL في ClickHouse Cloud متاح في private preview. الخدمات المشاركة في private preview مهيّأة مسبقًا بالإعداد `enable_time_series_table` وبنقاط نهاية واجهة برمجة تطبيقات Prometheus. أما خدمات ClickHouse Cloud الأخرى فلا تتضمّن هذه التهيئة، ولا يمكنك تفعيل هذه الميزة بنفسك على خدمة من هذا النوع. أما عبارة `SET enable_time_series_table` وتهيئة `http_handlers` الواردتان في الأقسام التالية فتنطبقان على عمليات النشر المُدارة ذاتيًا.
</Note>

في حال كانت خدمتك مشاركة في private preview، تابع من [إنشاء جدول TimeSeries](#create-a-timeseries-table). فالخدمة توفّر مسارات نقاط النهاية المذكورة في [جدول نقاط النهاية](#configure-prometheus-api).

<h3 id="enable-the-timeseries-setting">
  مُدار ذاتيًا: تفعيل إعداد TimeSeries
</h3>

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

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

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

<h3 id="configure-prometheus-api">
  مُدار ذاتيًا: تهيئة نقاط نهاية واجهة برمجة تطبيقات Prometheus
</h3>

هيِّئ معالجًا واحدًا قائمًا على توجيه البادئة على منفذ 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/format_query` | تنسيق تعبير PromQL |
| `/prometheus/api/v1/series` | البيانات الوصفية للسلاسل |
| `/prometheus/api/v1/metadata` | البيانات الوصفية لعائلة المقاييس |

يحذف المثال `database` و`table` من المعالج. يجب أن يتضمن كل طلب معلمة الاستعلام `table` (باستثناء `/format_query`، الذي يحلل تعبير PromQL المُعطى فقط ولا يحتاج إلى جدول). ويمكنه أيضًا تضمين `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`. |

<h3 id="create-a-timeseries-table">
  إنشاء جدول TimeSeries
</h3>

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

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

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

يدعم 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 محاولة إرساله.

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

استخدم نقطة نهاية الاستعلام الفوري لتقييم تعبير 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"
```

تقبل نقاط نهاية الاستعلام المعلمات أيضاً في متن نموذج. فبدون `--get`، يرسل curl المعلمات بصيغة `application/x-www-form-urlencoded` عبر `POST`:

```bash theme={null}
curl --user default:<password> \
  "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 وتنسيقه دون تقييمه:

```bash theme={null}
curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/format_query" \
  --data-urlencode "query=sum by(job)(http_requests_total{code=\"200\"})/2"
```

يُعاد التعبير مُسلسلاً من الاستعلام المُحلَّل، مع توحيد المسافات البيضاء، وإزالة التعليقات، وحذف الأقواس الزائدة، وتحويل المدد إلى أعداد بالثواني: `sum by (job) (http_requests_total{code="200"}) / 2`. لا تقوم نقطة النهاية هذه بتقييم التعبير، لذا فهي لا تحتاج إلى المعلمتين `database` و`table`.

راجع [ميزات PromQL المدعومة](/ar/reference/functions/table-functions/prometheusQueryRange#supported-promql-features) للاطلاع على قائمة الدالات وعوامل التجميع التي تستخدمها واجهة برمجة تطبيقات HTTP، ولهجة `promql`، ودالات الجداول.

<h3 id="grafana">
  Grafana
</h3>

هيّئ مصدر بيانات 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: POST
      customQueryParameters: database=prometheus&table=metrics
    secureJsonData:
      basicAuthPassword: <password>
```

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

عند استخدام `httpMethod: POST`، يرسل Grafana معلمات الاستعلام في متن الطلب. ويقرأ ClickHouse متن الطلب واستعلام عنوان URL معًا، لذا يظل `customQueryParameters` ساريًا. استخدم `POST` لتعبيرات PromQL الطويلة، لأن عنوان URL له حد أقصى للطول.

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

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

يستخدم 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()
);
```

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

تعيد نقطة النهاية `/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"
```

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

يدعم 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>
```