데이터베이스 모니터링을 사용해 쿼리 메트릭, 쿼리 샘플, 실행 계획, 데이터베이스 상태, 장애 조치, 이벤트를 노출시켜 Postgres 데이터베이스를 상세히 가시화할 수 있습니다.

에이전트에서는 데이터베이스에 읽기 전용 사용자로 로그인해 원격 분석 데이터를 직접 수집합니다. Postgres 데이터베이스에서 데이터베이스 모니터링을 사용하려면 다음 단계를 따르세요.

1. 데이터베이스 파라미터 설정
2. 에이전트가 데이터베이스에 액세스할 수 있도록 권한 부여
3. 에이전트 설치

시작 전에 참고 사항

지원되는 PostgreSQL 버전

9.6, 10, 11, 12, 13, 14

필수 구성 요소

Postgres 추가 제공 모듈이 설치되어야 합니다. 대부분 설치할 시에 기본적으로 포함되어 있으나 일반적이지 않은 방법으로 설치하는 경우 적절한 postgresql-contrib 패키지 버전을 추가로 설치해야 할 수 있습니다.

지원되는 에이전트 버전

7.36.1+

성능에 미치는 영향

데이터베이스 모니터링을 위한 기본 에이전트 설정은 보수적이지만 수집 간격 및 쿼리 샘플 등 설정을 조정해 요구 사항을 더 잘 충족할 수 있습니다. 대부분의 워크로드의 경우 에이전트는 데이터베이스에서 쿼리 실행 시간의 1% 미만, CPU 비율의 1% 미만을 차지합니다.

데이터베이스 모니터링은 기본 에이전트에서 통합으로 실행됩니다(벤치마크 참조).

프록시, 로드 밸런서, 연결 풀러

에이전트는 모니터링 중인 호스트에 직접 연결해야 합니다. 자체 호스팅 데이트베이스는 127.0.0.1이나 소켓을 통해 연결하는 것이 좋습니다. 에이전트를 프록시, 로드 밸런pgbouncer와 같은 연결 풀러로 연결하지 마세요. 이는 클라이언트 애플리케이션에 안티 패턴일 수 있으나 각 에이전트가 기본 호스트 이름을 알고 있어야 하며, 장애 조치 시에도 수명 기간 동안에는 단일 호스트에 연결되어야 합니다. Datadog 에이전트가 실행되는 동안 다른 호스트에 연결되면 메트릭 값이 올바르지 않게 됩니다.

데이터 보안 고려사항

에이전트가 데이터베이스에서 어떤 정보를 수집하고 어떻게 보안을 확보하는지 알아보려면 민감한 정보를 참고하세요.

Postgres 설정 구성

postgresql.conf 파일에서 다음 파라미터를 설정합니다. 서버를 재시작해야 설정이 적용됩니다. 이 파라미터에 관한 더 자세한 정보는 Postgres 설명서를 참고하세요.

에이전트 액세스 허용

Datadog 에이전트가 통계와 쿼리를 수집하려면 데이터베이스 서버에 읽기 전용 액세스가 필요합니다.

Postgres가 복제되면 다음 SQL 명령을 주 데이터베이스 서버(쓰기 권한자)에서 실행해야 합니다. 데이터베이스 서버에서 에이전트를 연결할 PostgreSQL 데이베이스를 선택하세요. 어떤 데이터베이스에 연결하든 에이전트는 서버에 있는 모든 데이터베이스에서 원격 분석 데이터를 수집하기 때문에 기본값인 postgres 데이터베이스에 연결하는 것이 좋습니다. 에이전트에서 특정 데이터베이스의 커스텀 쿼리를 실행하고 싶을 경우에만 다른 데이터베이스를 선택하세요.

선택한 데이터베이스에 슈퍼 사용자(또는 충분한 권한이 있는 다른 사용자)로 연결합니다. 예를 들어 선택한 데이터베이스가 postgres면 다음을 실행하여 psql을 이용해 postgres 사용자로 연결합니다.

psql -h mydb.example.com -d postgres -U postgres

datadog 사용자를 생성합니다.

CREATE USER datadog WITH password '<PASSWORD>';

CREATE SCHEMA datadog;
GRANT USAGE ON SCHEMA datadog TO datadog;
GRANT USAGE ON SCHEMA public TO datadog;
GRANT pg_monitor TO datadog;
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

CREATE SCHEMA datadog;
GRANT USAGE ON SCHEMA datadog TO datadog;
GRANT USAGE ON SCHEMA public TO datadog;
GRANT SELECT ON pg_stat_database TO datadog;
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

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

에이전트가 실행 계획을 수집하려면 모든 데이터베이스에 함수를 생성해야 합니다.

CREATE OR REPLACE FUNCTION datadog.explain_statement(
   l_query TEXT,
   OUT explain JSON
)
RETURNS SETOF JSON AS
$$
DECLARE
curs REFCURSOR;
plan JSON;

BEGIN
   OPEN curs FOR EXECUTE pg_catalog.concat('EXPLAIN (FORMAT JSON) ', l_query);
   FETCH curs INTO plan;
   CLOSE curs;
   RETURN QUERY SELECT plan;
END;
$$
LANGUAGE 'plpgsql'
RETURNS NULL ON NULL INPUT
SECURITY DEFINER;

확인

권한이 정확한지 확인하려면 다음 명령을 실행해 에이전트 사용자가 데이터베이스에 연결하고 코어 테이블을 읽을 수 있는지 확인합니다.

psql -h localhost -U datadog postgres -A \
  -c "select * from pg_stat_database limit 1;" \
  && echo -e "\e[0;32mPostgres connection - OK\e[0m" \
  || echo -e "\e[0;31mCannot connect to Postgres\e[0m"
psql -h localhost -U datadog postgres -A \
  -c "select * from pg_stat_activity limit 1;" \
  && echo -e "\e[0;32mPostgres pg_stat_activity read OK\e[0m" \
  || echo -e "\e[0;31mCannot read from pg_stat_activity\e[0m"
psql -h localhost -U datadog postgres -A \
  -c "select * from pg_stat_statements limit 1;" \
  && echo -e "\e[0;32mPostgres pg_stat_statements read OK\e[0m" \
  || echo -e "\e[0;31mCannot read from pg_stat_statements\e[0m"

psql -h localhost -U datadog postgres -A \
  -c "select * from pg_stat_database limit 1;" \
  && echo -e "\e[0;32mPostgres connection - OK\e[0m" \
  || echo -e "\e[0;31mCannot connect to Postgres\e[0m"
psql -h localhost -U datadog postgres -A \
  -c "select * from pg_stat_activity limit 1;" \
  && echo -e "\e[0;32mPostgres pg_stat_activity read OK\e[0m" \
  || echo -e "\e[0;31mCannot read from pg_stat_activity\e[0m"
psql -h localhost -U datadog postgres -A \
  -c "select * from pg_stat_statements limit 1;" \
  && echo -e "\e[0;32mPostgres pg_stat_statements read OK\e[0m" \
  || echo -e "\e[0;31mCannot read from pg_stat_statements\e[0m"

암호 입력 메시지가 나타나면 datadog 사용자를 생성할 때 입력한 암호를 사용합니다.

에이전트 설치하기

Datadog 에이전트를 설치하면 Postgres용 데이터베이스 모니터링에 필요한 Postgres 검사도 설치됩니다. Postgres 데이터베이스 호스트에 아직 에이전트를 설치하지 않았다면 에이전트 설치 지침을 참고하세요.

1. 에이전트의 conf.d/postgres.d/conf.yaml 파일을 편집해 host/port를 가리키도록 하고, 모니터링할 호스트를 설정합니다. 사용할 수 있는 모든 설정 옵션을 보려면 postgres.d/conf.yaml 샘플을 참고하세요.

init_config:
instances:
  - dbm: true
    host: localhost
    port: 5432
    username: datadog
    password: '<PASSWORD>'
    ## Optional: Connect to a different database if needed for `custom_queries`
    # dbname: '<DB_NAME>'

init_config:
instances:
  - dbm: true
    host: localhost
    port: 5432
    username: datadog
    password: '<PASSWORD>'
    pg_stat_statements_view: datadog.pg_stat_statements()
    pg_stat_activity_view: datadog.pg_stat_activity()
    ## Optional: Connect to a different database if needed for `custom_queries`
    # dbname: '<DB_NAME>'

2. 에이전트를 다시 시작합니다.

로그 수집(선택 사항)

PostgreSQL 로깅 기본값은 stderr이며, 로그에 상세 정보를 포함하지 않습니다. 파일에 로그줄 접두사로 지정한 추가 상세 정보를 로깅하는 것이 좋습니다. 더 자세한 정보를 보려면 PostgreSQL 설명서에서 해당 토픽을 참고하세요.

1. /etc/postgresql/<VERSION>/main/postgresql.conf 파일에서 로깅을 설정합니다. 문 출력과 같은 정기적인 로그 결과를 보려면 로그 섹션에서 다음 파라미터의 주석 처리를 제거합니다.

     logging_collector = on
     log_directory = 'pg_log'  # directory where log files are written,
                               # can be absolute or relative to PGDATA
     log_filename = 'pg.log'   # log file name, can include pattern
     log_statement = 'all'     # log all queries
     #log_duration = on
     log_line_prefix= '%m [%p] %d %a %u %h %c '
     log_file_mode = 0644
     ## For Windows
     #log_destination = 'eventlog'
   

2. 더 자세한 기간 메트릭을 수집하여 Datadog 인터페이스에서 이를 검색할 수 있도록 하려면 문 자체와 함께 설정해야 합니다. 아래 권고 설정을 위와 비교하면 log_statement와 log_duration 옵션에서 주석 처리가 제거되었음을 알 수 있습니다. 이와 관련한 논의 내용을 보려면 여기를 참고하세요.

   이 설정에서는 모든 문의 로그를 기록합니다. 특정 시간이 걸린 문만 로그하도록 출력을 줄이려면 log_min_duration_statement 값을 원하는 최소 밀리초로 설정합니다(전체 SQL 문을 로깅해도 되는지 조직 프라이버시 요구 조건을 확인하세요).

     log_min_duration_statement = 0    # -1 is disabled, 0 logs all statements
                                       # and their durations, > 0 logs only
                                       # statements running at least this number
                                       # of milliseconds
     #log_statement = 'all'
     #log_duration = on
   

3. Datadog 에이전트에서 로그 수집은 기본적으로 사용하지 않도록 설정되어 있습니다. datadog.yaml파일에서 로그 수집을 사용하도록 설정합니다.

   logs_enabled: true
   

4. conf.d/postgres.d/conf.yaml 파일에서 다음 설정 블록을 추가 및 편집해 PostgreSQL 로그를 수집합니다.

   logs:
     - type: file
       path: "<LOG_FILE_PATH>"
       source: postgresql
       service: "<SERVICE_NAME>"
       #To handle multi line that starts with yyyy-mm-dd use the following pattern
       #log_processing_rules:
       #  - type: multi_line
       #    pattern: \d{4}\-(0?[1-9]|1[012])\-(0?[1-9]|[12][0-9]|3[01])
       #    name: new_log_start_with_date
   

   service와 path 파라미터 값을 내 환경에 맞게 변경하세요. 사용할 수 있는 설정 옵션을 모두 보려면 Postgres.d/conf.yaml 샘플을 참고하세요.

5. 에이전트를 다시 시작합니다.

검증

에이전트 상태 하위 명령을 실행하고 Checks 섹션 아래에서 postgres를 찾으세요. 또는 데이터베이스 페이지에서 시작할 수도 있습니다.

에이전트 설정 예시

One agent connecting to multiple hosts

It is common to configure a single Agent host to connect to multiple remote database instances (see Agent installation architectures for DBM). To connect to multiple hosts, create an entry for each host in the Postgres integration config. In these cases, Datadog recommends limiting the number of instances per Agent to a maximum of 10 database instances to guarantee reliable performance.

init_config:
instances:
  - dbm: true
    host: example-service-primary.example-host.com
    port: 5432
    username: datadog
    password: '<PASSWORD>'
    tags:
      - 'env:prod'
      - 'team:team-discovery'
      - 'service:example-service'
  - dbm: true
    host: example-service–replica-1.example-host.com
    port: 5432
    username: datadog
    password: '<PASSWORD>'
    tags:
      - 'env:prod'
      - 'team:team-discovery'
      - 'service:example-service'
  - dbm: true
    host: example-service–replica-2.example-host.com
    port: 5432
    username: datadog
    password: '<PASSWORD>'
    tags:
      - 'env:prod'
      - 'team:team-discovery'
      - 'service:example-service'
    [...]

Monitoring multiple databases on a database host

Use the database_autodiscovery option to permit the Agent to discover all databases on your host to monitor. You can specify include or exclude fields to narrow the scope of databases discovered. See the sample postgres.d/conf.yaml for more details.

init_config:
instances:
  - dbm: true
    host: example-service-primary.example-host.com
    port: 5432
    username: datadog
    password: '<PASSWORD>'
    database_autodiscovery:
      enabled: true
      # Optionally, set the include field to specify
      # a set of databases you are interested in discovering
      include:
        - mydb.*
        - example.*
    tags:
      - 'env:prod'
      - 'team:team-discovery'
      - 'service:example-service'

Storing passwords securely

While it is possible to declare passwords directly in the Agent configuration files, it is a more secure practice to encrypt and store database credentials elsewhere using secret management software such as Vault. The Agent is able to read these credentials using the ENC[] syntax. Review the secrets management documentation for the required setup to store these credentials. The following example shows how to declare and use those credentials:

init_config:
instances:
  - dbm: true
    host: localhost
    port: 5432
    username: datadog
    password: 'ENC[datadog_user_database_password]'

Running custom queries

To collect custom metrics, use the custom_queries option. See the sample postgres.d/conf.yaml for more details.

init_config:
instances:
  - dbm: true
    host: localhost
    port: 5432
    username: datadog
    password: '<PASSWORD>'
    custom_queries:
    - metric_prefix: employee
      query: SELECT age, salary, hours_worked, name FROM hr.employees;
      columns:
        - name: custom.employee_age
          type: gauge
        - name: custom.employee_salary
           type: gauge
        - name: custom.employee_hours
           type: count
        - name: name
           type: tag
      tags:
        - 'table:employees'

Monitoring relation metrics for multiple databases

In order to collect relation metrics (such as postgresql.seq_scans, postgresql.dead_rows, postgresql.index_rows_read, and postgresql.table_size), the Agent must be configured to connect to each database (by default, the Agent only connects to the postgres database).

Specify a single “DBM” instance to collect DBM telemetry from all databases. Use the database_autodiscovery option to avoid specifying each database name.

init_config:
instances:
  # This instance is the "DBM" instance. It will connect to the
  # all logical databases, and send DBM telemetry from all databases
  - dbm: true
    host: example-service-primary.example-host.com
    port: 5432
    username: datadog
    password: '<PASSWORD>'
    database_autodiscovery:
      enabled: true
      exclude:
        - ^users$
        - ^inventory$
    relations:
      - relation_regex: .*
  # This instance only collects data from the `users` database
  # and collects relation metrics from tables prefixed by "2022_"
  - host: example-service-primary.example-host.com
    port: 5432
    username: datadog
    password: '<PASSWORD>'
    dbname: users
    dbstrict: true
    relations:
      - relation_regex: 2022_.*
        relkind:
          - r
          - i
  # This instance only collects data from the `inventory` database
  # and collects relation metrics only from the specified tables
  - host: example-service-primary.example-host.com
    port: 5432
    username: datadog
    password: '<PASSWORD>'
    dbname: inventory
    dbstrict: true
    relations:
      - relation_name: products
      - relation_name: external_seller_products

Collecting schemas

To enable this feature, use the collect_schemas option. You must also configure the Agent to connect to each logical database.

Use the database_autodiscovery option to avoid specifying each logical database. See the sample postgres.d/conf.yaml for more details.

init_config:
# This instance only collects data from the `users` database
# and collects relation metrics only from the specified tables
instances:
  - dbm: true
    host: example-service-primary.example-host.com
    port: 5432
    username: datadog
    password: '<PASSWORD>'
    dbname: users
    dbstrict: true
    collect_schemas:
      enabled: true
    relations:
      - products
      - external_seller_products
  # This instance detects every logical database automatically
  # and collects relation metrics from every table
  - dbm: true
    host: example-service–replica-1.example-host.com
    port: 5432
    username: datadog
    password: '<PASSWORD>'
    database_autodiscovery:
      enabled: true
    collect_schemas:
      enabled: true
    relations:
      - relation_regex: .*

Working with hosts through a proxy

If the Agent must connect through a proxy such as the Cloud SQL Auth proxy, all telemetry is tagged with the hostname of the proxy rather than the database instance. Use the reported_hostname option to set a custom override of the hostname detected by the Agent.

init_config:
instances:
  - dbm: true
    host: localhost
    port: 5000
    username: datadog
    password: '<PASSWORD>'
    reported_hostname: example-service-primary
  - dbm: true
    host: localhost
    port: 5001
    username: datadog
    password: '<PASSWORD>'
    reported_hostname: example-service-replica-1

트러블슈팅

설명에 따라 통합과 에이전트를 설치하고 설정했는데 제대로 작동하지 않는 경우 트러블슈팅을 참고하세요.

참고 자료

Additional helpful documentation, links, and articles:

기본 Postgres 통합설명서