본문 바로가기
WIKI 기술 지식 베이스

Postgres용 DBM 설정 문제 해결

원문 보기 위키 갱신

이 페이지는 Postgres로 Database Monitoring을 설정하고 사용할 때 흔히 겪는 문제와 해결 방법을 다뤄요. Datadog는 최신 안정 Agent 버전을 유지하고 최신 설정 문서를 따를 것을 권장해요. Agent 버전 출시에 따라 문서가 바뀔 수 있기 때문이에요.

출처: 문서

본문

흔한 문제 진단

Database Monitoring 설정 후 데이터가 표시되지 않아요

설정 안내에 따라 Agent를 설정했는데도 데이터가 보이지 않는다면, 대부분 Agent 설정이나 API 키에 문제가 있을 가능성이 커요. 문제 해결 가이드에 따라 Agent에서 데이터를 받고 있는지 확인하세요.

시스템 메트릭 같은 다른 데이터는 받지만 Database Monitoring 데이터(쿼리 메트릭, 쿼리 샘플 등)를 받지 못한다면 Agent나 데이터베이스 설정에 문제가 있을 가능성이 있어요. 설정 안내의 예제와 Agent 설정이 일치하는지 확인하고, 설정 파일 위치를 다시 점검하세요.

디버깅하려면 먼저 Agent status 명령을 실행해서 수집되어 Datadog로 전송되는 데이터에 대한 디버깅 정보를 수집하세요.

설정 파일이 유효한지 Config Errors 섹션을 확인하세요. 예를 들어 다음은 인스턴스 설정이 없거나 파일이 유효하지 않음을 나타내요:

  Config Errors
  ==============
    postgres
    -----
      Configuration file contains no valid instances

설정이 유효하다면 출력은 다음과 같아요:

=========
Collector
=========
  Running Checks
  ==============
    postgres (8.0.5)
    ----------------
      Instance ID: postgres:d3dceb9fd36fd57e [OK]
      Configuration Source: file:/etc/datadog-agent/conf.d/postgres.d/conf.yaml
      Total Runs: 16,538
      Metric Samples: Last Run: 186, Total: 2,844,362
      Events: Last Run: 0, Total: 0
      Database Monitoring Query Metrics: Last Run: 2, Total: 24,274
      Database Monitoring Query Samples: Last Run: 1, Total: 17,921
      Service Checks: Last Run: 1, Total: 16,538
      Average Execution Time : 1.765s
      Last Execution Date : 2021-07-26 19:16:58 UTC (1627327018000)
      Last Successful Execution Date : 2021-07-26 19:16:58 UTC (1627327018000)
      metadata:
        version.major: 10
        version.minor: 17
        version.patch: 0
        version.raw: 10.17
        version.scheme: semver

출력에 다음 줄이 있고 값이 0보다 큰지 확인하세요:

Database Monitoring Query Metrics: Last Run: 2, Total: 24,274
Database Monitoring Query Samples: Last Run: 1, Total: 17,921

Agent 설정이 올바르다고 확신하면, 데이터베이스 통합 실행을 시도할 때 발생한 경고나 오류가 있는지 Agent 로그를 확인하세요.

또한 Datadog Agent에서 check CLI 명령을 실행해서 오류가 있는지 출력을 검사할 수도 있어요:

# For self-hosted installations of the Agent
DD_LOG_LEVEL=debug DBM_THREADED_JOB_RUN_SYNC=true datadog-agent check postgres -t 2
DD_LOG_LEVEL=debug DBM_THREADED_JOB_RUN_SYNC=true datadog-agent check mysql -t 2
DD_LOG_LEVEL=debug DBM_THREADED_JOB_RUN_SYNC=true datadog-agent check sqlserver -t 2

# For container-based installations of the Agent
DD_LOG_LEVEL=debug DBM_THREADED_JOB_RUN_SYNC=true agent check postgres -t 2
DD_LOG_LEVEL=debug DBM_THREADED_JOB_RUN_SYNC=true agent check mysql -t 2
DD_LOG_LEVEL=debug DBM_THREADED_JOB_RUN_SYNC=true agent check sqlserver -t 2

쿼리 메트릭이 없어요

쿼리 메트릭 데이터 누락을 진단하는 다음 단계를 진행하기 전에 Agent가 정상적으로 실행 중인지, Agent 데이터 누락을 진단하는 단계를 따랐는지 확인하세요. 쿼리 메트릭 누락의 가능한 원인은 아래와 같아요.

pg_stat_statements 확장이 로드되지 않음

pg_stat_statements 확장이 로드되지 않았어요. 이 확장은 Postgres 설정의 shared_preload_libraries를 통해 로드해야 해요 (참고: 이 변수를 수정한 후 적용하려면 서버 재시작이 필요해요). 확장 로드 방법에 대한 자세한 내용은 설정 안내를 참고해요.

pg_stat_statements 확장이 데이터베이스에 생성되지 않음

pg_stat_statements 확장이 올바른 데이터베이스에 설치되지 않았어요. Agent가 연결하는 모든 데이터베이스에서 CREATE EXTENSION pg_stat_statements를 실행해야 해요. 기본적으로 Agent는 postgres 데이터베이스에 연결해요. 설정에서 이 변수를 구성하는 자세한 내용은 설정 안내를 참고해요.

pg_stat_statements가 설치되어 datadog 사용자가 접근 가능한지 확인하려면 postgres 데이터베이스에 연결해서 datadog 사용자로 쿼리해보세요. 행이 하나 이상 성공적으로 반환되어야 해요. 예:

psql -h localhost -U datadog -d postgres -c "select * from pg_stat_statements LIMIT 1;"

Agent 설정에서 기본 postgres가 아닌 다른 dbname을 지정했다면 해당 데이터베이스에서 CREATE EXTENSION pg_stat_statements를 실행해야 해요.

대상 데이터베이스에 확장을 만들었는데도 여전히 이 경고가 보인다면, 확장이 datadog 사용자가 접근할 수 없는 스키마에 생성되었을 수 있어요. 다음 명령으로 pg_stat_statements가 어느 스키마에 생성되었는지 확인하세요:

psql -h localhost -U datadog -d postgres -c "select nspname from pg_extension, pg_namespace where extname = 'pg_stat_statements' and pg_extension.extnamespace = pg_namespace.oid;"

그런 다음 다음 명령으로 datadog 사용자에게 보이는 스키마를 확인하세요:

psql -h localhost -U datadog -d <your_database> -c "show search_path;"

datadog 사용자의 search_path에 pg_stat_statements 스키마가 보이지 않는다면 추가해야 해요. 예 ( <schema_with_pg_stat_statements>를 pg_stat_statements가 있는 스키마로 바꾸세요) :

ALTER ROLE datadog SET search_path = "$user",public,<schema_with_pg_stat_statements>;

특정 쿼리가 없어요

일부 쿼리 데이터는 있지만 Database Monitoring에서 기대하는 특정 쿼리나 쿼리 세트가 보이지 않는다면 이 가이드를 따라가세요.

가능한 원인 해결 방법
Postgres 9.6에서 datadog 사용자가 실행한 쿼리만 보인다면 인스턴스 설정에 일부 설정이 누락되었을 가능성이 있어요. Postgres 9.6 인스턴스를 모니터링하려면 Datadog Agent 인스턴스 설정이 초기 설정 가이드에서 만든 함수를 기반으로 pg_stat_statements_view: datadog.pg_stat_statements()와 pg_stat_activity_view: datadog.pg_stat_activity() 설정을 사용해야 해요. 이 함수는 모든 데이터베이스에 생성되어야 해요.
Datadog 사용자가 다른 사용자의 쿼리를 볼 수 있는 충분한 접근 권한이 없어요. Datadog 사용자는 pg_stat_activity 같은 테이블에 접근하려면 pg_monitor 역할이 있어야 해요. Datadog 사용자에게 이 역할이 있는지 확인하세요: GRANT pg_monitor TO datadog.
해당 쿼리가 "top query"가 아니라서 선택한 시간대에 총 실행 시간 합계가 상위 200개 정규화 쿼리에 들지 않아요. 쿼리가 "Other Queries" 행으로 그룹화될 수 있어요. 어떤 쿼리가 추적되는지 자세한 내용은 수집된 데이터를 참고해요. 추적되는 top query 수는 Datadog 지원팀에 문의하면 늘릴 수 있어요.
쿼리가 SELECT, INSERT, UPDATE, DELETE가 아니에요. 비유틸리티 함수는 기본적으로 추적되지 않아요. 이를 수집하려면 Postgres 파라미터 pg_stat_statements.track_utility를 all로 설정하세요. 자세한 내용은 Postgres 문서를 참고해요.
쿼리가 함수나 저장 프로시저 안에서 실행돼요. 함수나 프로시저 안에서 실행되는 쿼리를 추적하려면 설정 파라미터 pg_stat_statements.track을 on으로 설정하세요. 자세한 내용은 Postgres 문서를 참고해요.
pg_stat_statements.max Postgres 설정 파라미터가 워크로드에 비해 너무 낮을 수 있어요. 짧은 시간에 정규화된 쿼리가 대량으로 실행되면(10초 안에 수천 개의 고유 정규화 쿼리), pg_stat_statements의 버퍼가 모든 정규화 쿼리를 담지 못할 수 있어요. 이 값을 늘리면 추적되는 정규화 쿼리의 범위가 넓어지고 생성된 SQL의 높은 churn 영향이 줄어들어요. 참고: 컬럼 이름 순서가 없는 쿼리나 가변 길이 ARRAY를 사용하는 쿼리는 정규화 쿼리 churn 속도를 크게 높일 수 있어요. 예를 들어 SELECT ARRAY[1,2]와 SELECT ARRAY[1,2,3]은 pg_stat_statements에서 별도의 쿼리로 추적돼요. 이 설정 튜닝에 대한 자세한 내용은 고급 설정을 참고해요.
Agent가 마지막으로 재시작된 이후 쿼리가 한 번만 실행되었어요. 쿼리 메트릭은 Agent 재시작 후 두 개의 개별 10초 간격에서 한 번 이상 실행된 후에만 내보내져요.

쿼리 샘플이 잘려요

더 긴 쿼리는 데이터베이스 설정 때문에 전체 SQL 텍스트가 표시되지 않을 수 있어요. 워크로드에 맞게 일부 튜닝이 필요해요.

Postgres 설정 track_activity_query_size는 Postgres가 저장하고 Agent에 노출하는 SQL 문장의 최대 크기를 나타내요. 기본적으로 이 값은 1024바이트예요. 이 값을 4096으로 올리면 대부분의 워크로드에서 대부분의 쿼리를 포착해요. 하지만 쿼리가 복잡하거나 긴 배열을 사용한다면 더 높은 값이 적합할 수 있어요.

예를 들어 데이터베이스는 많은 항목이 있는 배열이 있는 쿼리를 잘라낼 수 있어요:

SELECT DISTINCT address FROM customers WHERE id = ANY(ARRAY[11, 12, 13, … , 9999, 10000 ]) LIMIT 5

결과적인 정규화 쿼리는 앱에서 다음과 같이 표시돼요:

SELECT DISTINCT address FROM customers WHERE id = ANY(ARRAY[ ?

이를 피하려면 track_activity_query_size 설정을 쿼리의 예상 최대 텍스트 크기를 수용할 만큼 크게 올리세요. 자세한 내용은 Postgres 런타임 통계 문서를 참고해요.

실행 계획이 없는 쿼리가 있어요

일부 또는 모든 쿼리에 계획이 없을 수 있어요. 지원되지 않는 쿼리 명령, 지원되지 않는 클라이언트 애플리케이션의 쿼리, 오래된 Agent, 불완전한 데이터베이스 설정이 원인일 수 있어요. 실행 계획 누락의 가능한 원인은 아래와 같아요.

실행 함수 누락

문제: Agent가 데이터베이스의 datadog 스키마에 필요한 함수를 실행할 수 없어요.

해결: Agent가 쿼리를 수집할 수 있는 모든 데이터베이스에 datadog.explain_statement(...) 함수가 존재해야 해요.

Agent가 실행 계획을 수집할 수 있도록 모든 데이터베이스에 함수를 생성하세요.

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

BEGIN
   SET TRANSACTION READ ONLY;

   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;

Agent가 지원되지 않는 버전을 실행 중

Agent가 7.36.1 이상을 실행 중인지 확인하세요. Datadog는 새 기능, 성능 개선, 보안 업데이트를 활용하기 위해 Agent를 정기적으로 업데이트할 것을 권장해요.

쿼리가 잘림

샘플 쿼리 텍스트 크기를 늘리는 방법은 잘린 쿼리 샘플 섹션을 참고해요.

Postgres 확장 쿼리 프로토콜

클라이언트가 Postgres 확장 쿼리 프로토콜이나 prepared statement를 사용하면, 파싱된 쿼리와 원시 바인드 파라미터가 분리되어 있기 때문에 Datadog Agent가 실행 계획을 수집할 수 없어요. 이 문제를 해결할 수 있는 몇 가지 옵션은 아래와 같아요.

Postgres 12 이상에서는 Postgres 통합 설정에서 다음 파라미터가 기본적으로 활성화되어 Agent가 실행 계획을 수집할 수 있어요:

query_samples:
  explain_parameterized_queries: true
  ...

Postgres 12 이전 버전에서는 이 파라미터를 지원하지 않아요. 하지만 클라이언트가 simple query 프로토콜을 강제로 사용하는 옵션을 제공한다면 Datadog Agent가 실행 계획을 수집할 수 있어요.

언어 클라이언트 Simple query 프로토콜 설정
Go pgx PreferSimpleProtocol을 설정해 simple query 프로토콜로 전환하세요 (ConnConfig 문서 참조). 또는 QuerySimpleProtocol 플래그를 Query 또는 Exec 호출의 첫 번째 인자로 적용해 쿼리나 호출 단위로 적용할 수도 있어요.
Java Postgres JDBC Client preferQueryMode = simple을 설정해 simple query 프로토콜로 전환하세요 (PreferQueryMode 문서 참조).
Python asyncpg 확장 쿼리 프로토콜을 사용하며 비활성화할 수 없어요. prepared statement를 비활성화해도 문제가 해결되지 않아요. 실행 계획 수집을 활성화하려면 DB 클라이언트에 전달하기 전에 psycopg sql(또는 SQL 값을 올바르게 이스케이프하는 비슷한 SQL 포맷터)로 SQL 쿼리를 포맷하세요.
Python psycopg psycopg2는 확장 쿼리 프로토콜을 사용하지 않으므로 실행 계획을 문제없이 수집해야 해요. psycopg3은 기본적으로 확장 쿼리 프로토콜을 사용하며 비활성화할 수 없어요. prepared statement를 비활성화해도 문제가 해결되지 않아요. 실행 계획 수집을 활성화하려면 DB 클라이언트에 전달하기 전에 psycopg sql로 SQL 쿼리를 포맷하세요.
Node node-postgres 확장 쿼리 프로토콜을 사용하며 비활성화할 수 없어요. Datadog Agent가 실행 계획을 수집할 수 있게 하려면 node-postgres에 전달하기 전에 pg-format으로 SQL 쿼리를 포맷하세요.

쿼리가 Agent 인스턴스 설정에서 무시하는 데이터베이스에 있음

쿼리가 Agent 인스턴스 설정 ignore_databases에서 무시하는 데이터베이스에 있어요. rdsadmin, azure_maintenance 같은 기본 데이터베이스는 ignore_databases 설정에서 무시돼요. 이 데이터베이스의 쿼리는 샘플이나 실행 계획이 없어요. 인스턴스 설정에서 이 설정의 값과 예제 설정 파일의 기본값을 확인하세요.

참고: postgres 데이터베이스도 7.41.0 미만 Agent 버전에서는 기본적으로 무시돼요.

쿼리를 설명할 수 없음

BEGIN, COMMIT, SHOW, USE, ALTER 같은 일부 쿼리는 데이터베이스에서 유효한 실행 계획을 생성하지 못해요. 실행 계획을 지원하는 쿼리는 SELECT, UPDATE, INSERT, DELETE, REPLACE뿐이에요.

쿼리가 상대적으로 드물거나 빠르게 실행됨

쿼리가 데이터베이스 총 실행 시간에서 큰 비중을 차지하지 않아서 샘플링 대상으로 선택되지 않았을 수 있어요. 쿼리를 포착하려면 샘플링 비율을 높여보세요.

애플리케이션이 어떤 스키마를 쿼리할지 지정하기 위해 search path에 의존

Postgres는 pg_stat_activity에서 현재 search path를 노출하지 않기 때문에, Datadog Agent는 실행 중인 Postgres 프로세스에 어떤 search path가 사용되는지 알 수 없어요. 이 제한의 해결 방법은 Postgres 통합 설정에 정의된 사용자의 search path를 스키마를 포함하도록 변경하는 거예요.

ALTER ROLE datadog SET search_path = "$user",public,schema1,schema2,etc;

create extension pg_stat_statements에서 설정 실패

create extension pg_stat_statements의 예제 오류 출력:

create extension pg_stat_statements;
ERROR:  could not open extension control file "<path>/share/postgresql/extension/pg_stat_statements.control": No such file or directory
SQL State: 58P01

이 오류는 pg_stat_statements 확장을 포함하는 postgresql-contrib 패키지가 없을 때 발생해요. 누락된 패키지를 설치하는 방법은 호스트 배포판과 Postgres 버전에 따라 달라요. 예를 들어 Ubuntu에서 Postgres 10용 contrib 패키지를 설치하려면:

sudo apt-get install postgresql-contrib-10

자세한 내용은 해당 버전의 Postgres contrib 문서를 참고해요.

Agent의 쿼리가 느리거나 데이터베이스에 미치는 영향이 커요

Database Monitoring의 기본 Agent 설정은 보수적이지만, 수집 간격이나 쿼리 샘플링 비율 같은 설정은 필요에 맞게 조정할 수 있어요. 대부분의 워크로드에서 Agent는 데이터베이스의 쿼리 실행 시간의 1% 미만, CPU의 1% 미만을 차지합니다. Agent 쿼리가 더 많은 리소스를 필요로 하는 가능한 이유는 아래와 같아요.

pg_stat_statements.max 값이 높음

pg_stat_statements.max의 권장 값은 10000이에요. 이 설정을 더 높게 설정하면 수집 쿼리가 더 오래 실행되어 쿼리 타임아웃과 쿼리 메트릭 수집 공백이 생길 수 있어요. Agent가 이 경고를 보고하면 데이터베이스의 pg_stat_statements.max가 10000으로 설정되어 있는지 확인하세요.

목록에서 데이터베이스가 없거나 병합됨

Datadog는 데이터베이스 메트릭에 db 태그를 지정해서 각 메트릭이 어느 데이터베이스에 속하는지 식별해요. 커스텀 db 태그를 적용하면 이 데이터베이스별 값이 덮어써져서 모든 메트릭이 단일 db 값을 공유해요. 그러면 데이터베이스가 하나의 항목으로 합쳐지고 개별 데이터베이스가 Database Monitoring의 Databases 목록에 나타나지 않을 수 있어요.

데이터베이스별 db 값을 복원하려면 커스텀 db 태그를 제거해서 Datadog가 데이터베이스별로 태그를 채우도록 하세요.