postgres_exporter

مصدر خادم PostgreSQL

مصدر Prometheus لمقاييس خادم PostgreSQL.

إصدارات PostgreSQL التي تم اختبارها بواسطة CI: 11 ، 12 ، 13 ، 14 ، 15 ، 16

بداية سريعة

هذه الحزمة متاحة لـ Docker:

 # Start an example database
docker run --net=host -it --rm -e POSTGRES_PASSWORD=password postgres
# Connect to it
docker run 
  --net=host 
  -e DATA_SOURCE_URI="localhost:5432/postgres?sslmode=disable" 
  -e DATA_SOURCE_USER=postgres 
  -e DATA_SOURCE_PASS=password 
  quay.io/prometheuscommunity/postgres-exporter

اختبار مع:

curl " http://localhost:9187/metrics "

مثال التكوين بروميثيوس:

 scrape_configs :
  - job_name : postgres
    static_configs :
      - targets : ["127.0.0.1:9187"] # Replace IP with the hostname of the docker container if you're running the container in a separate network

استخدم الآن DATA_SOURCE_PASS_FILE مع ملف مثبت يحتوي على كلمة المرور لمنع وجود كلمة المرور في متغير البيئة.

يتم تشغيل عملية الحاوية باستخدام uid/gid 65534 (مهم لأذونات الملف).

دعم متعدد الأهداف (تجريبي)

هذه الميزة في مرحلة تجريبية وقد تتطلب تغييرات في الإصدارات المستقبلية. ردود الفعل هي موضع ترحيب.

يدعم هذا المصدر النمط متعدد الأهداف. يسمح هذا بتشغيل مثيل واحد لهذا المصدر لأهداف Postgres متعددة. يعد استخدام الوظيفة متعددة الأهداف لهذا المُصدِّر أمرًا اختياريًا ومخصصًا للحالات التي يكون فيها من المستحيل تثبيت المُصدِّر كأداة جانبية، على سبيل المثال الخدمات المُدارة بواسطة SaaS.

لاستخدام وظيفة الأهداف المتعددة، أرسل طلب http إلى نقطة النهاية /probe?target=foo:5432 حيث يتم تعيين الهدف على DSN لمثيل postgres لاستخراج المقاييس منها.

لتجنب وضع معلومات حساسة مثل اسم المستخدم وكلمة المرور في عنوان URL، يتم دعم وحدات المصادقة المكونة مسبقًا عبر قسم auth_modules في ملف التكوين. يمكن استخدام auth_modules لـ DSNs مع نقطة النهاية /probe عن طريق تحديد المعلمة ?auth_module=foo http.

مثال التكوين بروميثيوس:

 scrape_configs :
  - job_name : ' postgres '
    static_configs :
      - targets :
        - server1:5432
        - server2:5432
    metrics_path : /probe
    params :
      auth_module : [foo]
    relabel_configs :
      - source_labels : [__address__]
        target_label : __param_target
      - source_labels : [__param_target]
        target_label : instance
      - target_label : __address__
        replacement : 127.0.0.1:9116  # The postgres exporter's real hostname:port. 

ملف التكوين

يتحكم ملف التكوين في سلوك المصدر. يمكن ضبطه باستخدام علامة سطر الأوامر --config.file والإعدادات الافتراضية هي postgres_exporter.yml .

auth_modules

يحدد هذا القسم معلمات المصادقة والاتصال المعينة مسبقًا لاستخدامها في نقطة النهاية متعددة الأهداف. auth_modules عبارة عن خريطة للوحدات النمطية حيث يكون المفتاح هو المعرف الذي يمكن استخدامه في نقطة النهاية /probe . حاليًا يتم دعم نوع userpass فقط.

مثال:

 auth_modules :
  foo1 : # Set this to any name you want
    type : userpass
    userpass :
      username : first
      password : firstpass
    options :
      # options become key=value parameters of the DSN
      sslmode : disable 

البناء والتشغيل

 git clone https://github.com/prometheus-community/postgres_exporter.git
cd postgres_exporter
make build
./postgres_exporter <flags>

لبناء صورة Docker:

 make promu
promu crossbuild -p linux/amd64 -p linux/armv7 -p linux/arm64 -p linux/ppc64le
make docker

سيؤدي هذا إلى إنشاء صورة عامل الإرساء كـ prometheuscommunity/postgres_exporter:${branch} .

أعلام

• help إظهار المساعدة الحساسة للسياق (جرب أيضًا --help-long و --help-man).

• [no-]collector.database تمكين مجمع database (الافتراضي: ممكّن).

• [no-]collector.database_wraparound قم بتمكين مُجمع database_wraparound (الافتراضي: معطل).

• [no-]collector.locks تمكين مجمع locks (الافتراضي: ممكّن).

• [no-]collector.long_running_transactions تمكين مُجمع long_running_transactions (الافتراضي: معطل).

• [no-]collector.postmaster قم بتمكين مُجمِّع postmaster (الافتراضي: معطل).

• [no-]collector.process_idle قم بتمكين مُجمِّع process_idle (الافتراضي: معطل).

• [no-]collector.replication تمكين مجمع replication (الافتراضي: ممكّن).

• [no-]collector.replication_slot تمكين أداة تجميع replication_slot (الافتراضي: ممكّن).

• [no-]collector.stat_activity_autovacuum تمكين مجمع stat_activity_autovacuum (الافتراضي: معطل).

• [no-]collector.stat_bgwriter تمكين مجمع stat_bgwriter (الافتراضي: ممكّن).

• [no-]collector.stat_database تمكين مجمع stat_database (الافتراضي: ممكّن).

• [no-]collector.stat_statements تمكين مجمع stat_statements (الافتراضي: معطل).

• [no-]collector.stat_user_tables تمكين مجمع stat_user_tables (الافتراضي: ممكّن).

• [no-]collector.stat_wal_receiver تمكين مجمع stat_wal_receiver (الافتراضي: معطل).

• [no-]collector.statio_user_indexes تمكين مُجمع statio_user_indexes (الافتراضي: معطل).

• [no-]collector.statio_user_tables تمكين مُجمع statio_user_tables (الافتراضي: ممكّن).

• [no-]collector.wal تمكين جامع wal (الافتراضي: ممكّن).

• [no-]collector.xlog_location قم بتمكين مُجمع xlog_location (الافتراضي: معطل).

• config.file قم بتعيين مسار ملف التكوين. الافتراضي هو postgres_exporter.yml

• web.systemd-socket استخدم مستمعي تنشيط مأخذ توصيل systemd بدلاً من مستمعي المنافذ (Linux فقط). الافتراضي false

• web.listen-address عنوان للاستماع إليه لواجهة الويب والقياس عن بعد. الافتراضي هو :9187 .

• ملف التكوين web.config.file لاستخدام TLS و/أو المصادقة الأساسية. تم توضيح تنسيق الملف في مستودع أدوات التصدير.

• web.telemetry-path المسار الذي يتم من خلاله كشف المقاييس. الافتراضي هو /metrics .

• disable-default-metrics استخدم فقط المقاييس المقدمة من queries.yaml عبر --extend.query-path . الافتراضي false .

• disable-settings-metrics استخدم العلامة إذا كنت لا تريد حذف pg_settings . الافتراضي false .

• auto-discover-databases (مهمل) ما إذا كان سيتم اكتشاف قواعد البيانات الموجودة على الخادم ديناميكيًا. الافتراضي false .

• extend.query-path (DEPRECATED) المسار إلى ملف YAML الذي يحتوي على استعلامات مخصصة للتشغيل. راجع queries.yaml للحصول على أمثلة للتنسيق.

• لا تقم بتشغيل dumpmaps - اطبع التمثيل الداخلي للخرائط المترية. مفيد عند تصحيح أخطاء ملف استعلامات مخصص.

• constantLabels (مهملة) تسميات لتعيينها في جميع المقاييس. قائمة بأزواج label=value ، مفصولة بفواصل.

• version إظهار إصدار التطبيق.

• exclude-databases (مهملة) قائمة قواعد البيانات المطلوب إزالتها عند تمكين قواعد بيانات الاكتشاف التلقائي.

• include-databases (مهملة) قائمة قواعد البيانات التي سيتم تضمينها فقط عند تمكين قواعد بيانات الاكتشاف التلقائي.

• log.level قم بتعيين مستوى التسجيل: واحد من debug info warn error .

• log.format قم بتعيين تنسيق السجل: أحد logfmt و json .

متغيرات البيئة

تقوم متغيرات البيئة التالية بتكوين المُصدِّر:

• DATA_SOURCE_NAME التنسيق القديم الافتراضي. يقبل نموذج URI ووسائط نموذج key=value. قد يحتوي عنوان URI على اسم المستخدم وكلمة المرور للاتصال بهما.

• DATA_SOURCE_URI بديل لـ DATA_SOURCE_NAME الذي يقبل اسم المضيف حصريًا بدون مكون اسم المستخدم وكلمة المرور. على سبيل المثال، my_pg_hostname أو my_pg_hostname:5432/postgres?sslmode=disable .

• DATA_SOURCE_URI_FILE نفس ما هو مذكور أعلاه ولكنه يقرأ URI من ملف.

• DATA_SOURCE_USER عند استخدام DATA_SOURCE_URI ، يتم استخدام متغير البيئة هذا لتحديد اسم المستخدم.

• DATA_SOURCE_USER_FILE نفس الشيء، لكنه يقرأ اسم المستخدم من الملف.

• DATA_SOURCE_PASS عند استخدام DATA_SOURCE_URI ، يتم استخدام متغير البيئة هذا لتحديد كلمة المرور للاتصال بها.

• DATA_SOURCE_PASS_FILE نفس ما ورد أعلاه ولكنه يقرأ كلمة المرور من الملف.

• PG_EXPORTER_WEB_TELEMETRY_PATH المسار الذي سيتم من خلاله عرض المقاييس. الافتراضي هو /metrics .

• PG_EXPORTER_DISABLE_DEFAULT_METRICS استخدم فقط المقاييس المقدمة من queries.yaml . يمكن أن تكون القيمة true أو false . الافتراضي false .

• PG_EXPORTER_DISABLE_SETTINGS_METRICS استخدم العلامة إذا كنت لا تريد حذف pg_settings . يمكن أن تكون القيمة true أو false . الافتراضي false .

• PG_EXPORTER_AUTO_DISCOVER_DATABASES (موقوف) ما إذا كان سيتم اكتشاف قواعد البيانات على الخادم ديناميكيًا. يمكن أن تكون القيمة true أو false . الافتراضي false .

• PG_EXPORTER_EXTEND_QUERY_PATH المسار إلى ملف YAML الذي يحتوي على استعلامات مخصصة للتشغيل. راجع queries.yaml للحصول على أمثلة للتنسيق.

• PG_EXPORTER_CONSTANT_LABELS (مهملة) التصنيفات التي سيتم تعيينها في جميع المقاييس. قائمة بأزواج label=value ، مفصولة بفواصل.

• PG_EXPORTER_EXCLUDE_DATABASES (مهملة) قائمة مفصولة بفواصل من قواعد البيانات المراد إزالتها عند تمكين autoDiscoverDatabases. الافتراضي هو سلسلة فارغة.

• PG_EXPORTER_INCLUDE_DATABASES (مهملة) قائمة مفصولة بفواصل من قواعد البيانات التي سيتم تضمينها فقط عند تمكين autoDiscoverDatabases. الافتراضي هو سلسلة فارغة، يعني السماح للجميع.

• PG_EXPORTER_METRIC_PREFIX بادئة يتم استخدامها لكل من المقاييس الافتراضية التي تم تصديرها بواسطة postgres-exporter. الافتراضي هو pg

سيتم استبدال الإعدادات التي تم تعيينها بواسطة متغيرات البيئة التي تبدأ بـ PG_ بواسطة علامة CLI المقابلة إذا تم توفيرها.

تعيين اسم مصدر بيانات خادم Postgres

يجب تعيين اسم مصدر بيانات خادم PostgreSQL عبر متغير البيئة DATA_SOURCE_NAME .

لتشغيله محليًا على تثبيت Debian/Ubuntu الافتراضي، سيعمل هذا (قم بالتبديل إلى البرنامج النصي init حسب الاقتضاء):

 sudo -u postgres DATA_SOURCE_NAME="user=postgres host=/var/run/postgresql/ sslmode=disable" postgres_exporter

يمكنك أيضًا تعيين قائمة بالمصادر لاستخراج مثيلات مختلفة من إعداد المصدر الواحد. ما عليك سوى تحديد سلسلة مفصولة بفواصل.

 sudo -u postgres DATA_SOURCE_NAME="port=5432,port=6432" postgres_exporter

راجع وحدة github.com/lib/pq للتعرف على طرق أخرى لتنسيق سلسلة الاتصال.

إضافة مقاييس جديدة

سيحاول المُصدِّر تصدير مقاييس إضافية ديناميكيًا إذا تمت إضافتها في المستقبل، ولكن سيتم وضع علامة عليها على أنها "غير مكتوبة". يمكن إنشاء خرائط مترية إضافية بسهولة من وثائق Postgres عن طريق نسخ الجداول واستخدام مقتطف Python التالي:

 x = """tab separated raw text of a documentation table"""
for l in StringIO ( x ):
    column , ctype , description = l . split ( ' t ' )
    print """"{0}" : {{ prometheus.CounterValue, prometheus.NewDesc("pg_stat_database_{0}", "{2}", nil, nil) }}, """ . format ( column . strip (), ctype , description . strip ())

اضبط قيمة نوع قيمة بروميثيوس الناتج بشكل مناسب. ويساعد ذلك في بناء مقاييس توثيق ذاتي غنية للمصدر.

إضافة مقاييس جديدة عبر ملف التكوين (موقوف)

تم إهمال هذه الميزة لصالح وظائف المجمع المضمنة. لمراقبة قاعدة بيانات SQL العامة، راجع sql_exporter.

تحدد وسيطة سطر الأوامر -extend.query-path ملف YAML الذي يحتوي على استعلامات إضافية ليتم تشغيلها. يتم توفير بعض الأمثلة في query.yaml.

تعطيل المقاييس الافتراضية

للعمل مع إصدارات postgres غير المدعومة رسميًا (مثل 8.2.15)، أو متغيرات postgres (مثل Greenplum)، يمكنك تعطيل المقاييس الافتراضية باستخدام علامة --disable-default-metrics . يؤدي هذا إلى إزالة جميع المقاييس المضمنة، ويستخدم فقط المقاييس المحددة بواسطة الاستعلامات في ملف queries.yaml الذي تقدمه (لذلك يجب عليك توفير واحدة، وإلا فلن يقوم المُصدّر بإرجاع أي شيء سوى الحالات الداخلية وليس قاعدة بياناتك).

اكتشاف قواعد البيانات تلقائيًا (موقوف)

لاستخراج المقاييس من جميع قواعد البيانات الموجودة على خادم قاعدة البيانات، يمكن اكتشاف DSN لقاعدة البيانات ديناميكيًا عبر العلامة --auto-discover-databases . عندما يكون صحيحًا، SELECT datname FROM pg_database WHERE datallowconn = true AND datistemplate = false and datname != current_database() لجميع DSN's التي تم تكوينها. من النتيجة يتم إنشاء مجموعة جديدة من DSN والتي يتم من خلالها استخراج المقاييس.

بالإضافة إلى ذلك، يضيف الخيار --exclude-databases إمكانية تصفية النتيجة من الاكتشاف التلقائي لتجاهل قواعد البيانات التي لا تحتاج إليها.

إذا كنت تريد تضمين مجموعة فرعية فقط من قواعد البيانات، فيمكنك استخدام الخيار --include-databases . لا يزال المُصدِّر يقدم طلبًا إلى جدول pg_database ، لكنه لا يستخرج منه إلا إذا كانت قاعدة البيانات موجودة في قائمة التضمين.

التشغيل كمستخدم غير متميز

لتتمكن من جمع المقاييس من طرق العرض pg_stat* كمستخدم غير متميز في إصدارات خادم PostgreSQL >= 10، يمكنك منح الأدوار المضمنة pg_monitor أو pg_read_all_stats للمستخدم. إذا كنت بحاجة إلى مراقبة خوادم PostgreSQL الأقدم، فسيتعين عليك إنشاء وظائف وطرق عرض كمستخدم متميز، وتعيين الأذونات بشكل منفصل لكل منها.

 -- To use IF statements, hence to be able to check if the user exists before
-- attempting creation, we need to switch to procedural SQL (PL/pgSQL)
-- instead of standard SQL.
-- More: https://www.postgresql.org/docs/9.3/plpgsql-overview.html
-- To preserve compatibility with <9.0, DO blocks are not used; instead,
-- a function is created and dropped.
CREATE OR REPLACE FUNCTION __tmp_create_user () returns void as $$
BEGIN
  IF NOT EXISTS (
          SELECT                       -- SELECT list can stay empty for this
          FROM   pg_catalog . pg_user
          WHERE  usename = ' postgres_exporter ' ) THEN
    CREATE USER postgres_exporter ;
  END IF;
END;
$$ language plpgsql;

SELECT __tmp_create_user();
DROP FUNCTION __tmp_create_user();

ALTER USER postgres_exporter WITH PASSWORD ' password ' ;
ALTER USER postgres_exporter SET SEARCH_PATH TO postgres_exporter,pg_catalog;

-- If deploying as non-superuser (for example in AWS RDS), uncomment the GRANT
-- line below and replace <MASTER_USER> with your root user.
-- GRANT postgres_exporter TO <MASTER_USER>;

GRANT CONNECT ON DATABASE postgres TO postgres_exporter;

قم بتشغيل الأمر التالي إذا كنت تستخدم إصدارات PostgreSQL >= 10

 GRANT pg_monitor to postgres_exporter;

قم بتشغيل أوامر SQL التالية فقط إذا كنت تستخدم إصدارات PostgreSQL الأقدم من 10. في PostgreSQL، تعمل العروض بأذونات المستخدم الذي قام بإنشائها حتى تتمكن من العمل كحواجز أمنية. يجب إنشاء الوظائف لمشاركة هذه البيانات مع المستخدم غير المتميز. سيؤدي إنشاء طرق العرض فقط إلى إغفال الأجزاء الأكثر أهمية من البيانات.

 CREATE SCHEMA IF NOT EXISTS postgres_exporter;
GRANT USAGE ON SCHEMA postgres_exporter TO postgres_exporter;

CREATE OR REPLACE FUNCTION get_pg_stat_activity () RETURNS SETOF pg_stat_activity AS
$$ SELECT * FROM pg_catalog . pg_stat_activity ; $$
LANGUAGE sql
VOLATILE
SECURITY DEFINER;

CREATE OR REPLACE VIEW postgres_exporter .pg_stat_activity
AS
  SELECT * from get_pg_stat_activity();

GRANT SELECT ON postgres_exporter . pg_stat_activity TO postgres_exporter;

CREATE OR REPLACE FUNCTION get_pg_stat_replication () RETURNS SETOF pg_stat_replication AS
$$ SELECT * FROM pg_catalog . pg_stat_replication ; $$
LANGUAGE sql
VOLATILE
SECURITY DEFINER;

CREATE OR REPLACE VIEW postgres_exporter .pg_stat_replication
AS
  SELECT * FROM get_pg_stat_replication();

GRANT SELECT ON postgres_exporter . pg_stat_replication TO postgres_exporter;

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
CREATE OR REPLACE FUNCTION get_pg_stat_statements () RETURNS SETOF pg_stat_statements AS
$$ SELECT * FROM public . pg_stat_statements ; $$
LANGUAGE sql
VOLATILE
SECURITY DEFINER;

CREATE OR REPLACE VIEW postgres_exporter .pg_stat_statements
AS
  SELECT * FROM get_pg_stat_statements();

GRANT SELECT ON postgres_exporter . pg_stat_statements TO postgres_exporter;

ملحوظة
تذكر استخدام اسم قاعدة بيانات postgres في سلسلة الاتصال:

 DATA_SOURCE_NAME=postgresql://postgres_exporter:password@localhost:5432/postgres?sslmode=disable

تشغيل الاختبارات

 # Run the unit tests
make test
# Start the test database with docker
docker run -p 5432:5432 -e POSTGRES_DB=circle_test -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=test -d postgres
# Run the integration tests
DATA_SOURCE_NAME='postgresql://postgres:test@localhost:5432/circle_test?sslmode=disable' GOOPTS='-v -tags integration' make test