Google AlloyDB 관리형 Postgres용 Database Monitoring 설정하기
이 페이지에서는 Google AlloyDB에서 호스팅하는 Postgres 데이터베이스에 Database Monitoring을 설정하는 방법을 설명드릴게요. Database Monitoring은 쿼리 메트릭, 쿼리 샘플, explain plan, 데이터베이스 상태, 장애 조치, 이벤트 등을 노출해 Postgres 데이터베이스에 대한 깊은 가시성을 제공합니다.
에이전트는 읽기 전용 사용자로 로그인해 데이터베이스에서 직접 원격 측정을 수집해요. Postgres 데이터베이스에 Database Monitoring을 활성화하려면 다음 단계를 따르세요.
- 데이터베이스 파라미터 구성하기
- 에이전트에 데이터베이스 액세스 권한 부여하기
- 에이전트 설치 및 구성하기
- AlloyDB 통합 설치하기
출처: 문서
본문
시작하기 전에 (Before you begin)
- 지원되는 PostgreSQL 버전: 14, 15, 16, 17, 18
- 지원되는 Agent 버전: 7.36.1+
- 성능 영향: Database Monitoring의 기본 Agent 구성은 보수적이지만, 수집 간격이나 쿼리 샘플링 비율 같은 설정을 필요에 맞게 조정할 수 있어요. 대부분의 워크로드에서 에이전트는 데이터베이스 쿼리 실행 시간의 1% 미만, CPU의 1% 미만을 차지합니다. Database Monitoring은 기본 Agent 위에서 통합으로 실행돼요 (벤치마크 참고).
- 프록시, 로드 밸런서, 커넥션 풀러: Datadog Agent는 모니터링 대상 호스트에 직접 연결해야 해요. 자체 호스팅 데이터베이스의 경우
127.0.0.1이나 소켓을 사용하세요. 에이전트는pgbouncer같은 프록시, 로드 밸런서, 커넥션 풀러를 통해 데이터베이스에 연결하면 안 돼요. 에이전트가 실행 중에 다른 호스트에 연결하면(장애 조치, 로드 밸런싱 등의 경우) 에이전트는 두 호스트 사이의 통계 차이를 계산해 부정확한 메트릭을 만들어내요. - 데이터 보안 고려 사항: 에이전트가 데이터베이스에서 수집하는 데이터와 이를 안전하게 유지하는 방법은 민감 정보 (Sensitive information) 문서를 참고하세요.
Postgres 설정 구성하기
데이터베이스 플래그 (Database flags)에서 다음 파라미터를 구성한 뒤 서버를 재시작해야 설정이 적용돼요. 이 파라미터에 대한 자세한 내용은 Postgres 문서를 참고하세요.
필수 파라미터
| 파라미터 | 값 | 설명 |
|---|---|---|
track_activity_query_size |
4096 |
더 큰 쿼리 수집에 필요합니다. pg_stat_activity의 SQL 텍스트 크기를 늘립니다. 기본값으로 두면 1024자보다 긴 쿼리는 수집되지 않아요. |
선택 파라미터
| 파라미터 | 값 | 설명 |
|---|---|---|
pg_stat_statements.track |
all |
저장된 프로시저와 함수 내부의 statement 추적을 활성화합니다. |
pg_stat_statements.max |
10000 |
pg_stat_statements에서 추적되는 정규화된 쿼리 수를 늘립니다. 다양한 클라이언트의 다양한 유형의 쿼리가 많은 대용량 데이터베이스에 권장됩니다. |
pg_stat_statements.track_utility |
off |
PREPARE, EXPLAIN 같은 유틸리티 명령을 비활성화합니다. 이 값을 off로 설정하면 SELECT, UPDATE, DELETE 같은 쿼리만 추적됩니다. |
track_io_timing |
on |
쿼리의 블록 읽기/쓰기 시간 수집을 활성화합니다. |
에이전트에 액세스 권한 부여하기
Datadog Agent는 통계와 쿼리를 수집하기 위해 데이터베이스 서버에 대한 읽기 전용 액세스가 필요해요.
Postgres가 복제된다면 클러스터의 프라이머리 데이터베이스 서버(라이터)에서 다음 SQL 명령을 실행하세요. 에이전트는 연결하는 데이터베이스와 관계없이 서버의 모든 데이터베이스에서 원격 측정을 수집할 수 있어요. 에이전트가 다른 데이터베이스에 고유한 데이터에 대한 사용자 지정 쿼리를 실행할 필요가 없다면 기본 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;
{% alert level="info" %}
추가 테이블을 쿼리해야 하는 데이터 수집이나 사용자 지정 메트릭의 경우, 해당 테이블에 대한 SELECT 권한을 datadog 사용자에게 부여해야 할 수 있어요. 예: grant SELECT on <TABLE_NAME> to datadog;. 자세한 내용은 PostgreSQL 사용자 지정 메트릭 수집을 참고하세요.
{% /alert %}
explain plan 함수 만들기
에이전트가 explain plan을 수집할 수 있도록 모든 데이터베이스에 다음 함수를 만드세요.
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;
컬럼 통계 함수 만들기
에이전트가 pg_stats에서 컬럼 수준의 테이블 통계를 수집할 수 있도록 모든 데이터베이스에 다음 함수를 만드세요.
CREATE OR REPLACE FUNCTION datadog.column_statistics()
RETURNS TABLE (
schemaname name, tablename name, attname name,
n_distinct real, avg_width integer, null_frac real,
inherited boolean, correlation real, most_common_freqs real[]
) AS
$$ SELECT schemaname, tablename, attname, n_distinct, avg_width, null_frac,
inherited, correlation, most_common_freqs
FROM pg_catalog.pg_stats
WHERE schemaname NOT IN ('pg_catalog', 'information_schema'); $$
LANGUAGE sql
SECURITY DEFINER
SET search_path = pg_catalog, pg_temp;
함수가 준비되면 Postgres 인스턴스 구성에서 수집을 활성화하세요.
instances:
- dbm: true
...
collect_column_statistics:
enabled: true
튜닝 옵션은 고급 설정 (Advanced Configuration)을 참고하세요.
비밀번호를 안전하게 저장하기
Vault 같은 비밀 관리 소프트웨어로 비밀번호를 저장하세요. 그러면 에이전트 설정 파일에서 이 비밀번호를 ENC[<SECRET_NAME>]로 참조할 수 있어요. 예: ENC[datadog_user_database_password]. 자세한 내용은 비밀 관리 (Secrets Management)를 참고하세요.
이 페이지의 예시는 비밀번호가 저장된 비밀의 이름으로 datadog_user_database_password를 사용합니다. 비밀번호를 평문으로 참조하는 것도 가능하지만 권장되지는 않아요.
데이터베이스 권한 검증하기
권한이 올바른지 확인하려면 다음 명령을 실행해 에이전트 사용자가 데이터베이스에 연결하고 핵심 테이블을 읽을 수 있는지 확인하세요.
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 사용자를 만들 때 입력한 비밀번호를 사용하세요.
에이전트 설치 및 구성하기
AlloyDB 호스트를 모니터링하려면 인프라에 Datadog Agent를 설치하고 각 인스턴스에 원격으로 연결하도록 구성하세요. 에이전트가 데이터베이스 위에서 실행될 필요는 없고, 연결만 하면 돼요. 여기에 언급되지 않은 추가 설치 방법은 Agent 설치 지침을 참고하세요.
{% tab title="Host" %}
호스트에서 실행되는 에이전트에 대해 Database Monitoring 메트릭 수집을 구성하려면 (예: 에이전트가 Google AlloyDB 데이터베이스에서 수집하기 위해 작은 GCE 인스턴스를 프로비저닝하는 경우):
-
postgres.d/conf.yaml파일을 편집해host/port를 가리키고 모니터링할 마스터를 설정하세요. 모든 구성 옵션은 샘플 postgres.d/conf.yaml을 참고하세요.postgres.d디렉토리의 위치는 운영 체제에 따라 달라요. 자세한 내용은 Agent 구성 디렉토리를 참고하세요.init_config: instances: - dbm: true host: '<INSTANCE_ADDRESS>' port: 5432 username: datadog password: 'ENC[datadog_user_database_password]' gcp: project_id: '<PROJECT_ID>' instance_id: '<INSTANCE_ID>' ## 선택: `custom_queries`가 필요하면 다른 데이터베이스에 연결 # dbname: '<DB_NAME>' -
에이전트를 재시작하세요.
{% /tab %}
{% tab title="Docker" %}
Google Cloud Run 같은 Docker 컨테이너에서 실행되는 에이전트에 대해 통합을 구성하는 방법은 여러 가지가 있으며, 모두 Docker 구성 문서에 자세히 설명되어 있어요.
아래 예시는 Docker 라벨과 Autodiscovery 템플릿으로 Postgres 통합을 구성하는 방법을 보여줍니다.
참고: 라벨 자동 탐지가 동작하려면 에이전트가 Docker 소켓에 대한 읽기 권한이 있어야 해요.
커맨드 라인 (Command line)
커맨드 라인에서 다음 명령을 실행해 에이전트를 시작하세요. 플레이스홀더 값을 계정과 환경의 값으로 바꾸세요.
export DD_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export DD_AGENT_VERSION=<AGENT_VERSION>
docker run -e "DD_API_KEY=${DD_API_KEY}" \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-l com.datadoghq.ad.check_names='["postgres"]' \
-l com.datadoghq.ad.init_configs='[{}]' \
-l com.datadoghq.ad.instances='[{
"dbm": true,
"host": "<INSTANCE_ADDRESS>",
"port": 5432,
"username": "datadog",
"password": "<UNIQUEPASSWORD>",
"gcp": {
"project_id": "<PROJECT_ID>",
"instance_id": "<INSTANCE_ID>"
}
}]' \
registry.datadoghq.com/agent:${DD_AGENT_VERSION}
Dockerfile
라벨은 Dockerfile에서도 지정할 수 있어요. 그러면 인프라 구성을 바꾸지 않고도 사용자 지정 에이전트를 빌드하고 배포할 수 있습니다.
FROM registry.datadoghq.com/agent:<AGENT_VERSION>
LABEL "com.datadoghq.ad.check_names"='["postgres"]'
LABEL "com.datadoghq.ad.init_configs"='[{}]'
LABEL "com.datadoghq.ad.instances"='[{"dbm": true, "host": "<INSTANCE_ADDRESS>", "port": 5432,"username": "datadog","password": "ENC[datadog_user_database_password]", "gcp": {"project_id": "<PROJECT_ID>", "instance_id": "<INSTANCE_ID>"}}]'
datadog 사용자의 비밀번호가 평문으로 노출되지 않게 하려면 에이전트의 비밀 관리 패키지를 사용하고 비밀번호를 ENC[] 구문으로 선언하세요. 또는 Autodiscovery 템플릿 변수 문서를 참고해 비밀번호를 환경 변수로 제공할 수도 있어요.
{% /tab %}
{% tab title="Kubernetes" %}
Kubernetes 클러스터를 실행 중이라면 Datadog Cluster Agent를 사용해 Database Monitoring을 활성화하세요.
참고: 진행하기 전에 Datadog Cluster Agent에 클러스터 점검이 활성화되어 있는지 확인하세요.
아래는 다양한 Datadog Cluster Agent 배포 방법으로 Postgres 통합을 구성하는 단계별 지침입니다.
Operator
Kubernetes 및 Integrations의 Operator 지침을 참고로, 아래 단계에 따라 Postgres 통합을 설정하세요.
-
다음 구성으로
datadog-agent.yaml파일을 만들거나 업데이트하세요.apiVersion: datadoghq.com/v2alpha1 kind: DatadogAgent metadata: name: datadog spec: global: clusterName: <CLUSTER_NAME> site: <DD_SITE> credentials: apiSecret: secretName: datadog-agent-secret keyName: api-key features: clusterChecks: enabled: true override: nodeAgent: image: name: agent tag: <AGENT_VERSION> clusterAgent: extraConfd: configDataMap: postgres.yaml: |- cluster_check: true init_config: instances: - host: <INSTANCE_ADDRESS> port: 5432 username: datadog password: 'ENC[datadog_user_database_password]' dbm: true gcp: project_id: '<PROJECT_ID>' instance_id: '<INSTANCE_ID>' -
다음 명령으로 변경 사항을 Datadog Operator에 적용하세요.
kubectl apply -f datadog-agent.yaml
Helm
Kubernetes 및 Integrations의 Helm 지침을 참고로, 아래 단계에 따라 Postgres 통합을 설정하세요.
-
datadog-values.yaml파일(Cluster Agent 설치 지침에서 사용)을 다음 구성으로 업데이트하세요.clusterAgent: confd: postgres.yaml: |- cluster_check: true init_config: instances: - dbm: true host: <INSTANCE_ADDRESS> port: 5432 username: datadog password: 'ENC[datadog_user_database_password]' gcp: project_id: '<PROJECT_ID>' instance_id: '<INSTANCE_ID>' clusterChecksRunner: enabled: true -
다음 명령으로 위 설정 파일을 사용해 에이전트를 배포하세요.
helm install datadog-agent -f datadog-values.yaml datadog/datadog
{% alert level="info" %}
Windows에서는 helm install 명령에 --set targetSystem=windows를 추가하세요.
{% /alert %}
마운트된 파일로 구성하기
마운트된 설정 파일로 클러스터 점검을 구성하려면 /conf.d/postgres.yaml 경로에 설정 파일을 Cluster Agent 컨테이너에 마운트하세요.
cluster_check: true # 이 플래그를 포함해야 해요
init_config:
instances:
- dbm: true
host: '<INSTANCE_ADDRESS>'
port: 5432
username: datadog
password: 'ENC[datadog_user_database_password]'
gcp:
project_id: '<PROJECT_ID>'
instance_id: '<INSTANCE_ID>'
Kubernetes 서비스 어노테이션으로 구성하기
파일을 마운트하는 대신 인스턴스 구성을 Kubernetes Service로 선언할 수 있어요. Kubernetes에서 실행되는 에이전트에 대해 이 점검을 구성하려면 다음 구문으로 서비스를 만드세요.
Autodiscovery 어노테이션 v2
apiVersion: v1
kind: Service
metadata:
name: postgres
labels:
tags.datadoghq.com/env: '<ENV>'
tags.datadoghq.com/service: '<SERVICE>'
annotations:
ad.datadoghq.com/service.check_names: '["postgres"]'
ad.datadoghq.com/service.init_configs: '[{}]'
ad.datadoghq.com/service.instances: |
[
{
"dbm": true,
"host": "<INSTANCE_ADDRESS>",
"port": 5432,
"username": "datadog",
"password": "ENC[datadog_user_database_password]",
"gcp": {
"project_id": "<PROJECT_ID>",
"instance_id": "<INSTANCE_ID>"
}
}
]
spec:
ports:
- port: 5432
protocol: TCP
targetPort: 5432
name: postgres
자세한 내용은 Autodiscovery 어노테이션을 참고하세요.
Cluster Agent는 이 구성을 자동으로 등록하고 Postgres 점검을 실행하기 시작해요. {% /tab %}
project_id와 instance_id 필드 설정에 대한 추가 정보는 Postgres 통합 스펙을 참고하세요.
에이전트 설정 검증하기
에이전트의 status 하위 명령을 실행해 Checks 섹션에서 postgres를 찾아보세요. 또는 Databases 페이지를 방문해 시작할 수 있어요.
예시 에이전트 구성 (Example Agent Configurations)
하나의 에이전트가 여러 호스트에 연결하기
단일 에이전트 호스트를 구성해 여러 원격 데이터베이스 인스턴스에 연결하는 것은 흔한 일이에요 (DBM용 에이전트 설치 아키텍처 참고). 여러 호스트에 연결하려면 Postgres 통합 구성에서 호스트별로 항목을 만드세요.
{% alert level="info" %} Datadog은 하나의 에이전트가 30개 이하의 데이터베이스 인스턴스를 모니터링할 것을 권장합니다. 벤치마크에 따르면 t4g.medium EC2 인스턴스(2 CPU, 4GB RAM)에서 실행되는 하나의 에이전트가 30개의 RDS db.t3.medium 인스턴스(2 CPU, 4GB RAM)를 성공적으로 모니터링할 수 있어요. {% /alert %}
init_config:
instances:
- dbm: true
host: example-service-primary.example-host.com
port: 5432
username: datadog
password: 'ENC[datadog_user_database_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: 'ENC[datadog_user_database_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: 'ENC[datadog_user_database_password]'
tags:
- 'env:prod'
- 'team:team-discovery'
- 'service:example-service'
[...]
데이터베이스 호스트의 여러 데이터베이스 모니터링하기
database_autodiscovery 옵션을 사용해 에이전트가 호스트의 모든 데이터베이스를 발견해 모니터링하게 할 수 있어요. include 또는 exclude 필드를 지정해 발견되는 데이터베이스 범위를 좁힐 수 있어요. 자세한 내용은 샘플 postgres.d/conf.yaml을 참고하세요.
init_config:
instances:
- dbm: true
host: example-service-primary.example-host.com
port: 5432
username: datadog
password: 'ENC[datadog_user_database_password]'
database_autodiscovery:
enabled: true
# 선택적으로 include 필드를 설정해
# 발견하려는 데이터베이스 집합을 지정
include:
- mydb.*
- example.*
tags:
- 'env:prod'
- 'team:team-discovery'
- 'service:example-service'
사용자 지정 쿼리 실행하기
사용자 지정 메트릭을 수집하려면 custom_queries 옵션을 사용하세요. 자세한 내용은 샘플 postgres.d/conf.yaml을 참고하세요.
init_config:
instances:
- dbm: true
host: localhost
port: 5432
username: datadog
password: 'ENC[datadog_user_database_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'
여러 데이터베이스의 relation 메트릭 모니터링하기
relation 메트릭(postgresql.seq_scans, postgresql.dead_rows, postgresql.index_rows_read, postgresql.table_size 등)을 수집하려면 에이전트가 각 데이터베이스에 연결하도록 구성해야 해요 (기본적으로 에이전트는 postgres 데이터베이스에만 연결합니다).
모든 데이터베이스에서 DBM 원격 측정을 수집하도록 단일 "DBM" 인스턴스를 지정하세요. 각 데이터베이스 이름을 지정하지 않으려면 database_autodiscovery 옵션을 사용하세요.
init_config:
instances:
# 이 인스턴스는 "DBM" 인스턴스입니다. 모든 논리적 데이터베이스에 연결하고,
# 모든 데이터베이스의 DBM 원격 측정을 보냅니다
- dbm: true
host: example-service-primary.example-host.com
port: 5432
username: datadog
password: 'ENC[datadog_user_database_password]'
database_autodiscovery:
enabled: true
exclude:
- ^users$
- ^inventory$
relations:
- relation_regex: .*
# 이 인스턴스는 `users` 데이터베이스에서만 데이터를 수집하고
# "2022_"로 시작하는 테이블의 relation 메트릭을 수집합니다
- host: example-service-primary.example-host.com
port: 5432
username: datadog
password: 'ENC[datadog_user_database_password]'
dbname: users
dbstrict: true
relations:
- relation_regex: 2022_.*
relkind:
- r
- i
# 이 인스턴스는 `inventory` 데이터베이스에서만 데이터를 수집하고
# 지정된 테이블의 relation 메트릭만 수집합니다
- host: example-service-primary.example-host.com
port: 5432
username: datadog
password: 'ENC[datadog_user_database_password]'
dbname: inventory
dbstrict: true
relations:
- relation_name: products
- relation_name: external_seller_products
스키마 수집 (Collecting schemas)
이 기능을 활성화하려면 collect_schemas 옵션을 사용하세요. 또한 에이전트가 각 논리적 데이터베이스에 연결하도록 구성해야 해요.
각 논리적 데이터베이스를 지정하지 않으려면 database_autodiscovery 옵션을 사용하세요. 자세한 내용은 샘플 postgres.d/conf.yaml을 참고하세요.
init_config:
# 이 인스턴스는 `users` 데이터베이스에서만 데이터를 수집하고
# 지정된 테이블의 relation 메트릭만 수집합니다
instances:
- dbm: true
host: example-service-primary.example-host.com
port: 5432
username: datadog
password: 'ENC[datadog_user_database_password]'
dbname: users
dbstrict: true
collect_schemas:
enabled: true
relations:
- products
- external_seller_products
# 이 인스턴스는 모든 논리적 데이터베이스를 자동으로 감지하고
# 모든 테이블의 relation 메트릭을 수집합니다
- dbm: true
host: example-service–replica-1.example-host.com
port: 5432
username: datadog
password: 'ENC[datadog_user_database_password]'
database_autodiscovery:
enabled: true
collect_schemas:
enabled: true
relations:
- relation_regex: .*
프록시를 통한 호스트 작업
에이전트가 Cloud SQL Auth proxy 같은 프록시를 통해 연결해야 한다면, 모든 원격 측정이 데이터베이스 인스턴스가 아닌 프록시의 호스트 이름으로 태그됩니다. reported_hostname 옵션을 사용해 에이전트가 감지한 호스트 이름의 사용자 지정 재정의를 설정하세요.
init_config:
instances:
- dbm: true
host: localhost
port: 5000
username: datadog
password: 'ENC[datadog_user_database_password]'
reported_hostname: example-service-primary
- dbm: true
host: localhost
port: 5001
username: datadog
password: 'ENC[datadog_user_database_password]'
reported_hostname: example-service-replica-1
AlloyDB 통합 설치하기
AlloyDB에서 더 포괄적인 데이터베이스 메트릭을 수집하려면 AlloyDB 통합을 설치하세요 (선택 사항).
트러블슈팅
설명한 대로 통합과 에이전트를 설치하고 구성했는데 예상대로 동작하지 않으면 트러블슈팅 문서를 참고하세요.
더 알아보기 (Learn more)
추가로 도움이 되는 문서, 링크, 글: