postgres_exporter

PostgreSQL 서버 내보내기

PostgreSQL 서버 측정항목을 위한 Prometheus 내보내기 도구입니다.

CI 테스트 PostgreSQL 버전: 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 "

Prometheus 구성 예시:

 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 관리 서비스와 같이 내보내기를 사이드카로 설치할 수 없는 경우를 위한 것입니다.

다중 대상 기능을 사용하려면 메트릭을 스크랩할 postgres 인스턴스의 DSN으로 대상이 설정된 엔드포인트 /probe?target=foo:5432 로 http 요청을 보냅니다.

URL에 사용자 이름 및 비밀번호와 같은 민감한 정보를 입력하지 않도록 사전 구성된 인증 모듈은 구성 파일의 auth_modules 섹션을 통해 지원됩니다. DSN용 auth_modules는 ?auth_module=foo http 매개변수를 지정하여 /probe 엔드포인트와 함께 사용할 수 있습니다.

Prometheus 구성 예시:

 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 는 /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

그러면 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 --extend.query-path 통해 queries.yaml 에서 제공된 메트릭만 사용하십시오. 기본값은 false 입니다.

• disable-settings-metrics pg_settings 긁어 모으고 싶지 않으면 플래그를 사용하십시오. 기본값은 false 입니다.

• auto-discover-databases (사용 중단됨) 서버에서 데이터베이스를 동적으로 검색할지 여부입니다. 기본값은 false 입니다.

• extend.query-path (사용 중단됨) 실행할 사용자 정의 쿼리가 포함된 YAML 파일의 경로입니다. 형식의 예는 queries.yaml 확인하세요.

• dumpmaps 실행하지 마십시오 - 메트릭 맵의 내부 표현을 인쇄합니다. 사용자 정의 쿼리 파일을 디버깅할 때 유용합니다.

• constantLabels (DEPRECATED) 모든 측정항목에 설정할 라벨입니다. 쉼표로 구분된 label=value 쌍의 목록입니다.

• version 애플리케이션 버전을 표시합니다.

• exclude-databases (사용 중단됨) autoDiscoverDatabases가 활성화된 경우 제거할 데이터베이스 목록입니다.

• include-databases (사용 중단됨) autoDiscoverDatabases가 활성화된 경우에만 포함할 데이터베이스 목록입니다.

• 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 모듈을 참조하세요.

새 측정항목 추가

내보내기는 나중에 추가되는 추가 측정항목을 동적으로 내보내려고 시도하지만 해당 측정항목은 "유형이 지정되지 않음"으로 표시됩니다. 테이블을 복사하고 다음 Python 코드 조각을 사용하여 Postgres 설명서에서 추가 측정항목 맵을 쉽게 만들 수 있습니다.

 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 ())

결과 prometheus 값 유형의 값을 적절하게 조정하십시오. 이는 수출업체를 위한 풍부한 자체 문서화 측정항목을 구축하는 데 도움이 됩니다.

구성 파일을 통해 새 측정항목 추가(지원 중단됨)

이 기능은 내장된 수집기 기능을 위해 더 이상 사용되지 않습니다. 일반 SQL 데이터베이스 모니터링에 대해서는 sql_exporter를 참조하세요.

-extend.query-path 명령줄 인수는 실행할 추가 쿼리가 포함된 YAML 파일을 지정합니다. 몇 가지 예는 query.yaml에 제공됩니다.

기본 측정항목 비활성화

공식적으로 지원되지 않는 postgres 버전(예: 8.2.15) 또는 postgres 변형(예: Greenplum)을 사용하려면 --disable-default-metrics 플래그를 사용하여 기본 측정항목을 비활성화할 수 있습니다. 이렇게 하면 내장된 모든 측정항목이 제거되고 사용자가 제공한 queries.yaml 파일의 쿼리에 의해 정의된 측정항목만 사용됩니다(따라서 사용자가 하나를 제공해야 합니다. 그렇지 않으면 내보내기가 데이터베이스가 아닌 내부 상태만 반환합니다).

데이터베이스 자동 검색(지원 중단됨)

데이터베이스 서버의 모든 데이터베이스에서 메트릭을 스크랩하려면 --auto-discover-databases 플래그를 통해 데이터베이스 DSN을 동적으로 검색할 수 있습니다. true인 경우 SELECT datname FROM pg_database WHERE datallowconn = true AND datistemplate = false and datname != current_database() 구성된 모든 DSN에 대해 실행됩니다. 결과로부터 메트릭이 스크랩되는 새로운 DSN 세트가 생성됩니다.

또한 --exclude-databases 옵션은 자동 검색 결과를 필터링하여 필요하지 않은 데이터베이스를 삭제할 수 있는 기능을 추가합니다.

데이터베이스의 하위 집합만 포함하려면 --include-databases 옵션을 사용할 수 있습니다. 내보내기는 여전히 pg_database 테이블에 요청하지만 데이터베이스가 포함 목록에 있는 경우에만 스크랩합니다.

슈퍼유저가 아닌 사용자로 실행

PostgreSQL 서버 버전 >= 10에서 슈퍼유저가 아닌 사용자로 pg_stat* 뷰에서 측정항목을 수집하려면 사용자에게 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;

10 이전의 PostgreSQL 버전을 사용하는 경우에만 다음 SQL 명령을 실행하십시오. 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