Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

تكامل Prometheus

تدعم هذه الميزة التكامل مع Prometheus لمراقبة خدمات ClickHouse Cloud. ويُتاح الوصول إلى مقاييس Prometheus عبر نقطة نهاية واجهة برمجة تطبيقات ClickHouse Cloud، ما يتيح لك الاتصال بأمان وتصدير المقاييس إلى مجمّع مقاييس Prometheus لديك. كما يمكن دمج هذه المقاييس مع لوحات المعلومات مثل Grafana وDatadog لعرضها بصريًا.

تُضمَّن مقاييس ClickPipes المرتبطة بخدمة إلى جانب مقاييس ClickHouse الخاصة بتلك الخدمة.

للبدء، أنشئ مفتاح واجهة برمجة تطبيقات.

إذا كنت تبحث عن نقطة النهاية المقابلة لخدمات ClickHouse Managed Postgres، فراجع نقطة نهاية Prometheus لـ ClickHouse Managed Postgres.

واجهة برمجة التطبيقات لنقطة نهاية Prometheus لاسترداد مقاييس ClickHouse Cloud

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

الطريقة المسار الوصف
GET https://api.clickhouse.cloud/v1/organizations/:organizationId/services/:serviceId/prometheus?filtered_metrics=[true | false] يعيد المقاييس لخدمة محددة
GET https://api.clickhouse.cloud/v1/organizations/:organizationId/prometheus?filtered_metrics=[true | false] مهمل. يعيد المقاييس لجميع الخدمات ضمن مؤسسة
GET https://api.clickhouse.cloud/v1/organizations/:organizationId/prometheus/discovery?filtered_metrics=[true | false] يعيد أهداف scrape في Prometheus لجميع الخدمات ضمن مؤسسة، بتنسيق اكتشاف الخدمات عبر HTTP

معلمات الطلب

الاسم الموقع النوع
معرّف المؤسسة عنوان نقطة نهاية uuid
معرّف الخدمة عنوان نقطة نهاية uuid (اختياري)
filtered_metrics معلمة query boolean (اختياري)

تتوفر مخططات الطلب والاستجابة الكاملة لهذه الـنقاط النهاية في مرجع Cloud واجهة برمجة تطبيقات.

المصادقة

استخدم مفتاح ClickHouse Cloud API الخاص بك لإجراء المصادقة الأساسية:

Username: <KEY_ID>
Password: <KEY_SECRET>
Example request
export KEY_SECRET=<key_secret>
export KEY_ID=<key_id>
export ORG_ID=<org_id>

# For all services in $ORG_ID
curl --silent --user $KEY_ID:$KEY_SECRET https://api.clickhouse.cloud/v1/organizations/$ORG_ID/prometheus?filtered_metrics=true

# For a single service only
export SERVICE_ID=<service_id>
curl --silent --user $KEY_ID:$KEY_SECRET https://api.clickhouse.cloud/v1/organizations/$ORG_ID/services/$SERVICE_ID/prometheus?filtered_metrics=true

استجابة نموذجية

# HELP ClickHouse_ServiceInfo Information about service, including cluster status and ClickHouse version
# TYPE ClickHouse_ServiceInfo untyped
ClickHouse_ServiceInfo{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",clickhouse_cluster_status="running",clickhouse_version="24.5",scrape="full"} 1

# HELP ClickHouseProfileEvents_Query Number of queries to be interpreted and potentially executed. Does not include queries that failed to parse or were rejected due to AST size limits, quota limits or limits on the number of simultaneously running queries. May include internal queries initiated by ClickHouse itself. Does not count subqueries.
# TYPE ClickHouseProfileEvents_Query counter
ClickHouseProfileEvents_Query{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 6

# HELP ClickHouseProfileEvents_QueriesWithSubqueries Count queries with all subqueries
# TYPE ClickHouseProfileEvents_QueriesWithSubqueries counter
ClickHouseProfileEvents_QueriesWithSubqueries{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 230

# HELP ClickHouseProfileEvents_SelectQueriesWithSubqueries Count SELECT queries with all subqueries
# TYPE ClickHouseProfileEvents_SelectQueriesWithSubqueries counter
ClickHouseProfileEvents_SelectQueriesWithSubqueries{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 224

# HELP ClickHouseProfileEvents_FileOpen Number of files opened.
# TYPE ClickHouseProfileEvents_FileOpen counter
ClickHouseProfileEvents_FileOpen{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 4157

# HELP ClickHouseProfileEvents_Seek Number of times the 'lseek' function was called.
# TYPE ClickHouseProfileEvents_Seek counter
ClickHouseProfileEvents_Seek{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 1840

# HELP ClickPipes_Info Always equal to 1. Label "clickpipe_state" contains the current state of the pipe: Stopped/Provisioning/Running/Paused/Failed
# TYPE ClickPipes_Info gauge
ClickPipes_Info{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent",clickpipe_status="Running"} 1

# HELP ClickPipes_SentEvents_Total Total number of records sent to ClickHouse
# TYPE ClickPipes_SentEvents_Total counter
ClickPipes_SentEvents_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 5534250

# HELP ClickPipes_SentBytesCompressed_Total Total compressed bytes sent to ClickHouse.
# TYPE ClickPipes_SentBytesCompressed_Total counter
ClickPipes_SentBytesCompressed_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name
="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 380837520
ClickPipes_SentBytesCompressed_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name

# HELP ClickPipes_FetchedBytes_Total Total uncompressed bytes fetched from the source.
# TYPE ClickPipes_FetchedBytes_Total counter
ClickPipes_FetchedBytes_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 873286202

# HELP ClickPipes_Errors_Total Total errors ingesting data.
# TYPE ClickPipes_Errors_Total counter
ClickPipes_Errors_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 0

# HELP ClickPipes_SentBytes_Total Total uncompressed bytes sent to ClickHouse.
# TYPE ClickPipes_SentBytes_Total counter
ClickPipes_SentBytes_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 477187967

# HELP ClickPipes_FetchedBytesCompressed_Total Total compressed bytes fetched from the source. If data is uncompressed at the source, this will equal ClickPipes_FetchedBytes_Total
# TYPE ClickPipes_FetchedBytesCompressed_Total counter
ClickPipes_FetchedBytesCompressed_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 873286202

# HELP ClickPipes_FetchedEvents_Total Total number of records fetched from the source.
# TYPE ClickPipes_FetchedEvents_Total counter
ClickPipes_FetchedEvents_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 5535376

تسميات المقاييس

تحتوي جميع المقاييس على التسميات التالية:

التسمية الوصف
clickhouse_org معرّف المؤسسة
clickhouse_service معرّف الخدمة
clickhouse_service_name اسم الخدمة

بالنسبة إلى ClickPipes، ستتضمن المقاييس أيضًا التسميات التالية:

التسمية الوصف
clickpipe_id معرّف ClickPipe
clickpipe_name اسم ClickPipe
clickpipe_source نوع مصدر ClickPipe

مقاييس المعلومات

يوفّر ClickHouse Cloud مقياسًا خاصًا باسم ClickHouse_ServiceInfo، وهو من نوع gauge وتكون قيمته دائمًا 1. يحتوي هذا المقياس على جميع تسميات المقاييس بالإضافة إلى التسميات التالية:

التسمية الوصف
clickhouse_cluster_status حالة الخدمة. ويمكن أن تكون إحدى القيم التالية: [awaking
clickhouse_version إصدار ClickHouse server الذي تعمل عليه الخدمة
scrape يشير إلى حالة آخر عملية جمع. ويمكن أن تكون إما full أو partial
full يشير إلى عدم وجود أي أخطاء أثناء آخر عملية جمع للمقاييس
partial يشير إلى وجود بعض الأخطاء أثناء آخر عملية جمع للمقاييس، ولم يُرجع سوى المقياس ClickHouse_ServiceInfo.

لن تؤدي طلبات استرجاع المقاييس إلى استئناف خدمة في حالة idle. وإذا كانت الخدمة في الحالة idle، فلن يُرجع سوى المقياس ClickHouse_ServiceInfo.

بالنسبة إلى ClickPipes، يوجد مقياس gauge مشابه باسم ClickPipes_Info يحتوي، بالإضافة إلى تسميات المقاييس، على التسميات التالية:

التسمية الوصف
clickpipe_state الحالة الحالية للمسار

تهيئة Prometheus

يجمع خادم Prometheus المقاييس من الأهداف المُهيأة وفق الفواصل الزمنية المحددة. فيما يلي مثال على إعداد خادم Prometheus لاستخدام نقطة نهاية Prometheus في ClickHouse Cloud:

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: "prometheus"
    static_configs:
    - targets: ["localhost:9090"]
  - job_name: "clickhouse"
    static_configs:
      - targets: ["api.clickhouse.cloud"]
    scheme: https
    params:
      filtered_metrics: ["true"]
    metrics_path: "/v1/organizations/<ORG_ID>/prometheus"
    basic_auth:
      username: <KEY_ID>
      password: <KEY_SECRET>
    honor_labels: true

لاحظ أن معلَمة الإعداد honor_labels يجب تعيينها إلى true لكي يُملأ وسم المثيل بشكل صحيح. بالإضافة إلى ذلك، ضُبطت filtered_metrics على true في المثال أعلاه، ولكن ينبغي تهيئتها وفقًا لتفضيل المستخدم.

الاكتشاف التلقائي للخدمات

ميزة Beta

تعرض نقطة نهاية الاكتشاف هدف جمع واحدًا لكل خدمة في مؤسستك، بتنسيق Prometheus لاكتشاف الخدمات عبر HTTP (http_sd). يُحدِّث Prometheus قائمة الأهداف عند كل عملية poll للاكتشاف ويجري جمعًا لكل هدف مُكتشَف، لذلك تُكتشف الخدمات المنشأة حديثًا تلقائيًا وتُزال الخدمات المحذوفة من قائمة الأهداف. ولا تُدرج إلا الخدمات التي يملك مفتاح واجهة برمجة تطبيقات صلاحية عرضها؛ وتُستبعد الخدمات التي يجري حذفها أو التي حُذفت بالفعل.

لاستخدامها، وجّه job http_sd_configs إلى نقطة نهاية الاكتشاف:

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: "clickhouse"
    http_sd_configs:
      - url: https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/prometheus/discovery
        refresh_interval: 60s
        basic_auth:
          username: <KEY_ID>
          password: <KEY_SECRET>
    basic_auth:
      username: <KEY_ID>
      password: <KEY_SECRET>
    honor_labels: true

اضبط basic_auth في كلا الموضعين: إذ تتولى الكتلة ضمن http_sd_configs مصادقة عمليات استقصاء الاكتشاف، بينما تتولى الكتلة في مهمة الجمع مصادقة جمع المقاييس لكل خدمة. وكما في التكوين الثابت، اضبط honor_labels: true لضمان تعبئة تسمية المثيل بشكل صحيح.

استجابة نموذجية للاكتشاف:

[
  {
    "targets": ["api.clickhouse.cloud"],
    "labels": {
      "__scheme__": "https",
      "__metrics_path__": "/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/prometheus",
      "__param_filtered_metrics": "true",
      "clickhouse_org_id": "<ORG_ID>",
      "clickhouse_service_id": "<SERVICE_ID>",
      "clickhouse_discovery_service_name": "my service"
    }
  }
]

تجمع الأهداف المكتشفة المقاييس باستخدام filtered_metrics=true. ولاكتشاف الأهداف التي تجمع المجموعة الكاملة من المقاييس، أضف ?filtered_metrics=false إلى URL الاكتشاف. تتوفر المواصفة الكاملة لنقطة النهاية في مرجع Cloud واجهة برمجة تطبيقات.

التكامل مع Grafana

لدى المستخدمين طريقتان أساسيتان للتكامل مع Grafana:

  • نقطة نهاية المقاييس – تمتاز هذه الطريقة بأنها لا تتطلب أي مكونات أو بنية تحتية إضافية. يقتصر هذا الخيار على Grafana Cloud، ولا يتطلب سوى endpoint URL لـ نقطة نهاية Prometheus في ClickHouse Cloud وبيانات الاعتماد.
  • Grafana Alloy - ‏Grafana Alloy هو توزيعة غير مرتبطة بمورّد معيّن من OpenTelemetry (OTel) Collector، ويحل محل Grafana Agent. ويمكن استخدامه كـ scraper، كما يمكن نشره ضمن بنيتك التحتية الخاصة، وهو متوافق مع أي نقطة نهاية Prometheus.

نوفّر أدناه إرشادات لاستخدام هذين الخيارين، مع التركيز على التفاصيل الخاصة بـ نقطة نهاية Prometheus في ClickHouse Cloud.

Grafana Cloud مع نقطة نهاية المقاييس

  • سجّل الدخول إلى حسابك في Grafana Cloud
  • أضف اتصالًا جديدًا باختيار نقطة نهاية المقاييس
  • اضبط عنوان URL الخاص بـ Scrape بحيث يشير إلى نقطة نهاية Prometheus، واستخدم المصادقة الأساسية لإعداد اتصالك باستخدام مفتاح واجهة برمجة تطبيقات/السر
  • اختبر الاتصال للتأكد من أنك قادر على الاتصال
تهيئة نقطة نهاية مقاييس Grafana

بعد إكمال التهيئة، ينبغي أن ترى المقاييس في القائمة المنسدلة التي يمكنك اختيارها لتهيئة لوحات المعلومات:

القائمة المنسدلة في مستكشف مقاييس Grafana

مخطط في مستكشف مقاييس Grafana

Grafana Cloud مع Alloy

إذا كنت تستخدم Grafana Cloud، فيمكن تثبيت Alloy بالانتقال إلى قائمة Alloy في Grafana واتباع الإرشادات المعروضة على الشاشة:

Grafana Alloy

من المفترض أن يُعِدّ ذلك Alloy باستخدام مكوّن prometheus.remote_write لإرسال البيانات إلى نقطة نهاية في Grafana Cloud باستخدام رمز مصادقة. بعد ذلك، لن يحتاج المستخدمون إلا إلى تعديل ملف إعداد Alloy (الموجود في /etc/alloy/config.alloy على Linux) لتضمين مكوّن scrape لـ نقطة نهاية Prometheus في ClickHouse Cloud.

يوضح ما يلي مثالاً لإعداد Alloy يتضمن مكوّن prometheus.scrape لجمع المقاييس من نقطة نهاية ClickHouse Cloud، بالإضافة إلى مكوّن prometheus.remote_write الذي يُضبط تلقائيًا. لاحظ أن مكوّن الإعداد basic_auth يحتوي على معرّف مفتاح Cloud واجهة برمجة تطبيقات والقيمة السرية الخاصة به باعتبارهما اسم المستخدم وكلمة المرور، على الترتيب.

prometheus.scrape "clickhouse_cloud" {
  targets = [{
  __address__ = "api.clickhouse.cloud",
  }]

  scheme       = "https"
  metrics_path = "/v1/organizations/<clickhouse_org_id>/prometheus"

  params = {
  "filtered_metrics" = ["true"],
  }

  honor_labels    = true
  scrape_interval = "30s"
  scrape_timeout  = "25s"

  basic_auth {
  username = "<clickhouse_api_key_id>"
  password = "<clickhouse_api_key_secret>"
  }

  forward_to = [prometheus.remote_write.grafana_cloud.receiver]
}

  prometheus.remote_write "grafana_cloud" {
  endpoint {
  url = "https://<grafana_prometheus_url>/api/prom/push"

  basic_auth {
  username = "<grafana_username>"
  password = "<grafana_api_token>"
  }
  }
}

لاحظ أنه يجب ضبط معلمة التهيئة honor_labels على true لكي يُملأ وسم المثيل بشكل صحيح.

Grafana المُدارة ذاتيًا مع Alloy

يمكن لمستخدمي Grafana المُدارة ذاتيًا العثور على تعليمات تثبيت وكيل Alloy هنا. نفترض أن المستخدمين قد أعدّوا Alloy لإرسال مقاييس Prometheus إلى الوجهة المطلوبة. يتولى المكوّن prometheus.scrape أدناه جعل Alloy يجمع المقاييس من نقطة نهاية ClickHouse Cloud. ونفترض أن prometheus.remote_write يستقبل المقاييس التي جُمعت. عدّل forward_to key ليشير إلى الوجهة المستهدفة إذا لم يكن موجودًا.

// prometheus.scrape component causes Alloy to scrape the ClickHouse Cloud Prometheus endpoint.
  // Adjust the forward_to key to match your remote_write receiver if it differs.
  prometheus.scrape "clickhouse_cloud" {
  targets = [{
  __address__ = "api.clickhouse.cloud",
  }]

  scheme       = "https"
  metrics_path = "/v1/organizations/<organizationId>/prometheus"

  params = {
  "filtered_metrics" = ["true"],
  }

  honor_labels = true

  basic_auth {
  username = "<KEY_ID>"
  password = "<KEY_SECRET>"
  }

  forward_to = [prometheus.remote_write.metrics_service.receiver]
}

بمجرد اكتمال الإعداد، ينبغي أن ترى المقاييس المتعلقة بـ ClickHouse في مستكشف المقاييس لديك:

مستكشف المقاييس في Grafana

تجدر الإشارة إلى أن معلمة الضبط honor_labels يجب ضبطها على true لكي تتم تعبئة وسم المثيل بشكل صحيح.

التكامل مع Datadog

يمكنك استخدام Agent وتكامل OpenMetrics في Datadog لجمع المقاييس من نقطة نهاية ClickHouse Cloud. فيما يلي مثال إعداد بسيط لهذا الـAgent وهذا التكامل. لكن يُرجى ملاحظة أنك قد ترغب في الاكتفاء باختيار المقاييس الأكثر أهمية بالنسبة إليك. أما المثال الشامل أدناه فسيصدّر عدة آلاف من تركيبات المقاييس والمثيلات، والتي سيتعامل معها Datadog على أنها مقاييس مخصصة.

init_config:

instances:
   - openmetrics_endpoint: 'https://api.clickhouse.cloud/v1/organizations/97a33bdb-4db3-4067-b14f-ce40f621aae1/prometheus?filtered_metrics=true'
     namespace: 'clickhouse'
     metrics:
         - '^ClickHouse.*'
     username: username
     password: password

تكامل Prometheus وDatadog
Navigation