PostgreSQL 플러그인

TLS 설정 위치

TLS 모드·CA·클라이언트 인증서와 키·서버 이름·인증서 검증 설정은 보안 > TLS에 표시합니다. 주소·포트 등 실제 연결 설정은 기존 구역에 남습니다. 이 분류 변경은 필드 이름, 저장 값, 기본값, 비밀값 처리와 조건부 표시·검증을 바꾸지 않습니다.

CloudNativePG exporter 프리셋

외부 수집 모드의 메트릭 설정에서 메트릭 소스를 먼저 선택한 뒤, **Exporter 프리셋 → CloudNativePG (CNPG)**를 선택합니다(metric_exporter=cnpg). 기본값은 postgres_exporter이며, Konduo 관리 수집은 자체 표준 매핑을 계속 사용합니다.

CNPG 프리셋은 공통 데이터베이스 통계 규칙을 재사용하고 연결 수·collector 상태· 설정 단위·WAL·복제 지표를 보정한 완전한 postgresql-cnpg-prometheus-pack-v1 팩을 반환합니다. PG17 전후 checkpointer counter 이름 차이를 처리합니다. prefix가 비어 있으면 실제 CNPG 이름을 사용합니다. 기존 cnpg_ prefix와 pg_ 교체 설정을 함께 사용해도 한 번만 적용합니다. job="konduo-postgresql" 및 필요한 pod·namespace·cluster 등 실제 수집 라벨로 범위를 제한하세요. 모든 지표에 cluster 라벨이 있다고 가정하지 않습니다.

매핑과 보정은 각 리소스에 독립적으로 보관합니다. 같은 메트릭 소스를 사용하는 다른 리소스의 보정에 영향을 받지 않습니다. exporter 프리셋을 선택한 뒤 진단하고 필요한 보정을 검증·적용하세요. 보정 공유는 JSON 내보내기/가져오기를 사용합니다. 내장 프리셋은 CNPG 기본 수집 정의를 대상으로 하며 임의의 사용자 SQL collector를 모두 지원한다고 보장하지 않습니다.

집계된 트랜잭션 시간에는 PID 식별 정보가 없습니다. PID 기반 차트, 마지막 replay 시각 및 세부 복구 충돌 차트는 기본 수집기의 미지원으로 명시하고 선택 패널의 when_available 정책으로 숨깁니다. 지원 지표의 빈 결과·stale·수집/쿼리 실패는 숨기지 않습니다. PG17 이후 일부 구형 bgwriter counter가 없어도 단순 부재만으로 미지원이라고 판단하지 않습니다.

근거: CNPG 모니터링, 기본 수집 정의.

기본 접근성 관측

리소스 개요는 메트릭 소스와 별개로 접근 가능·접근 불가·접근 미확인을 표시합니다. 성공한 접속 확인은 전체 멤버, 복제, 파티션이나 작업의 정상 상태를 보장하지 않습니다. 구체적인 도메인 상태는 진단과 도메인 경보에서 확인합니다. 기존 liveness/readiness 정보는 도메인 상세 증거이며 기본 접근성 경보의 조건이 아닙니다. 미확인은 발생 중인 경보를 복구시키지 않습니다.

TLS

TLS 전용 sslmode를 선택하고 tls_ca_cert에 사설 CA 인증서(PEM)를 입력하면 CA 파일 없이 서버를 검증할 수 있습니다. CA 입력 시 sslmode=require는 verify-full로 바뀌며, 인증서의 DNS 이름이 접속 주소와 다르면 tls_server_name을 지정할 수 있습니다. 상호 TLS에서는 tls_client_cert와 tls_client_key를 함께 입력합니다. tls_insecure_skip_verify=true는 대신 PGSSLROOTCERT를 포함한 서버 검증을 생략하지만 평문으로 전환하지 않습니다. sslmode=disable과 함께 사용할 수 없고 기본값은 꺼짐입니다.

같은 Prometheus 소스를 사용해도 각 리소스의 보정과 이력은 독립적입니다. 보정을 공유하려면 JSON 내보내기/가져오기를 사용하고 선택한 프리셋과 기본 팩 버전을 검토한 뒤 적용하세요. 기존 차트 키는 alias_of 별칭으로 표현하며 보정은 정규 postgres.* 키에 적용합니다. 진단은 instant/range를 각각 검증합니다. 데이터가 없다는 이유만으로 매핑 오류라고 판단하지 않으며 수집 상태, 라벨 조건, 연결 상태를 먼저 확인합니다.

차트 값 의미

Exporter 수집 상태의 0은 성공, 1은 실패이며 오류 건수가 아닙니다. 복제 역할과 로깅 설정은 각각의 의미를 가진 상태 문자열로 표시하고 건강도와 혼동하지 않습니다. 매핑팩 v4는 대상별 상태 관측을 보존합니다. 건수는 정수이고 퍼센트 게이지 범위는 0–100입니다.

개요는 연결·트랜잭션 요약 6개와 워크로드·쿼리 품질 추세 5개를 함께 보여줍니다(11개). 스토리지/WAL은 작은 값 4개, 전체 폭 데이터베이스 크기 비교와 체크포인트 추세 4개를 표시합니다(9개). 복제는 작은 값 4개와 로그 설정 이력을 포함한 추세 4개를 표시하고 설정 값 6개는 기본 접힘 행에 둡니다(14개).

개수·상태·시간은 숫자 카드, 연결 사용률은 백분율 게이지로 표시합니다. 전체 34개 패널 키·쿼리·단위와 저장한 개인화 배치는 유지합니다.

PostgreSQL 플러그인은 PostgreSQL 서버를 Konduo 리소스로 등록하고 접속, 복제, VACUUM, 잠금, 트랜잭션, 쿼리 활동을 운영 화면에 연결합니다.

특징

• 읽기 전용 SQL 쿼리로 서버 상태와 운영 스냅샷을 수집합니다.
• Prometheus 매핑팩과 Konduo 관리형 PostgreSQL 메트릭 수집을 지원합니다.
• 대시보드는 가용성 근거, 접속 압박, 트랜잭션 지속 시간, 잠금 활동, 복제 지연, 캐시/쓰기 동작을 중심으로 구성됩니다.
• 진단 화면은 접속, 권한, 메트릭 수집 범위, 복제, 테이블 팽창과 VACUUM 위험을 분리해서 보여줍니다.

등록 전 확인

• PostgreSQL 호스트, 포트, 데이터베이스, 사용자 이름, 비밀번호, TLS 설정을 준비합니다.
• 읽기 전용 진단 쿼리를 실행할 수 있는 최소 권한 계정을 사용합니다.
• 관리형 수집을 사용하려면 수집 쿼리가 운영 DB에 과도한 부하를 만들지 않도록 제한 시간을 조정합니다.
• 관리형 수집의 쓰기 대상으로 Prometheus를 사용할 경우 Prometheus를 --web.enable-remote-write-receiver 옵션으로 실행해야 합니다.

운영 팁

• 접속 압박과 최대 접속 수 설정을 같이 확인합니다.
• 복제 지연은 주 서버와 복제 서버 역할, WAL 수신기 상태, 적용 지연을 함께 봅니다.
• 장기 트랜잭션, 잠금 대기, VACUUM 지연은 단일 지표보다 진단 스냅샷과 메트릭 추세를 함께 보는 것이 좋습니다.
• 트랜잭션 유휴 경보는 pg_stat_activity의 백엔드 세션 문제로 해석합니다. 관리형 수집에서는 PID와 트랜잭션 시작 시각으로 동일 트랜잭션의 지속 여부를 판정하므로, 다른 트랜잭션으로 교체되면 경보 대기 시간도 새로 시작합니다. PID, 사용자, DB, 클라이언트, 마지막 쿼리, 트랜잭션 지속 시간을 함께 확인해야 합니다.

운영 화면

• 활동 화면은 세션 상태, 장기 실행 쿼리, 트랜잭션 지속 시간, 대기 이벤트를 운영자가 조치 가능한 단위로 보여줍니다.
• 트랜잭션 유휴 세션 화면은 idle in transaction 상태만 모아 PID, 사용자, DB, 애플리케이션, 클라이언트, 트랜잭션 시작 시각, 상태 변경 시각, 마지막 쿼리를 보여줍니다.
• 잠금 화면은 차단/피차단 관계와 잠금 모드를 드러내어 쿼리 취소 또는 세션 종료 판단을 돕습니다.
• 복제 화면은 주 서버와 대기 서버 역할, 재생/적용 지연, 수신기 상태, 아카이버 근거를 함께 보여줍니다.
• 저장소/VACUUM 화면은 데이터베이스 크기, 죽은 튜플, 자동 VACUUM, VACUUM/ANALYZE 필요성을 진단 근거와 연결합니다.
• 장애 조치 계획 근거는 현재 역할과 복제 상태를 확인하는 보조 정보이며 자동 장애 조치 오케스트레이션은 CE 범위가 아닙니다.

트랜잭션 유휴 대응

• PostgreSQL의 idle in transaction은 트랜잭션이 열린 상태로 백엔드 세션이 유휴 상태에 머무는 상황입니다. 실행 중인 쿼리가 없어 보여도 잠금, VACUUM 가시성, 접속 풀 고갈에 영향을 줄 수 있습니다.
• Konduo가 사용하는 자체 PostgreSQL 연결에는 기본적으로 idle_in_transaction_session_timeout을 설정해 Konduo 내부 버그가 무기한 유휴 트랜잭션을 남길 가능성을 줄입니다.
• 관리 수집 모드의 Long Transaction 경보는 현재 데이터베이스의 client backend만 대상으로 PID와 트랜잭션 시작 시각을 함께 추적합니다. PostgreSQL 백그라운드 작업과 idle in transaction 세션은 제외되며, 다른 트랜잭션이 이전 경보의 대기 시간을 이어받지 않습니다.
• 대상 PostgreSQL 리소스에서 경보가 발생하면 트랜잭션 유휴 세션 화면에서 PID와 소유 맥락을 먼저 확인합니다.
• 실행 중인 쿼리가 있으면 우선 쿼리 취소를 검토합니다. 순수 idle in transaction 상태는 취소할 실행 쿼리가 없으므로 애플리케이션 담당자 확인 또는 영향도 검토 후 백엔드 세션 종료가 현실적인 조치가 될 수 있습니다.
• 종료 전에는 사용자, 데이터베이스, 애플리케이션 이름, 클라이언트 주소, 마지막 쿼리, 트랜잭션 지속 시간을 근거로 남기고 감사 로그와 확인 문구 경계를 유지합니다.

진단과 알림 관점

• 진단은 접속/권한, 접속 압박, 잠금 경합, 장기 트랜잭션, VACUUM/테이블 팽창, 복제, WAL/체크포인트 위험을 나눠 표시합니다.
• 알림 규칙은 수집 상태, 접속 사용률, 장기 트랜잭션, 잠금 경합, 캐시/임시 파일 압박, 체크포인트/WAL 압박, 복제 지연, 아카이버 상태를 다룹니다.
• 관리형 수집은 읽기 전용 SQL 스냅샷을 postgres_exporter 계열 샘플로 변환하고 리소스 식별 라벨을 붙여 격리합니다.
• 과거 근거가 부족하면 PostgreSQL 상태를 정상으로 추정하지 않고 메트릭 소스 또는 매핑팩 상태를 확인합니다.

관리 경계

• 임의 SQL 콘솔은 제공하지 않습니다.
• 쿼리 취소, 백엔드 세션 종료, ANALYZE, VACUUM ANALYZE는 확인 문구, 사유, 안전 모드 해제가 필요한 관리 작업입니다.
• Konduo 런타임 데이터베이스로 표시한 리소스는 위 관리 변경 작업을 모두 차단합니다. 안전 모드는 확인 절차일 뿐 읽기 전용 데이터베이스 권한을 대신하지 않습니다.
• 트랜잭션 유휴 세션 종료는 사용자 트랜잭션을 중단할 수 있으므로 단순 경보 해소가 아니라 업무 영향도 검토 후 수행합니다.
• 스키마/테이블 변경, 사용자/역할 관리, 백업/복원, 복제 토폴로지 변경은 CE 운영 경계 밖입니다.
• 읽기 전용 계정으로도 일부 카탈로그 뷰 권한이 부족할 수 있으므로 진단 결과의 부분 근거를 권한 문제와 구분해 봅니다.

대표 시나리오

• 접속 포화가 발생하면 활성/유휴 세션, 최대 접속 수, 풀러 설정, 장기 트랜잭션을 함께 확인합니다.
• 트랜잭션 유휴 세션 경보가 발생하면 전용 화면에서 PID와 마지막 쿼리를 확인하고, 풀러 또는 애플리케이션 트랜잭션 경계를 점검합니다.
• 잠금 대기가 길어지면 차단 세션, 쿼리 지속 시간, 대기 이벤트, 업무 영향도를 확인하고 취소와 종료 중 더 낮은 위험 조치를 선택합니다.
• VACUUM 지연이 의심되면 죽은 튜플, 자동 VACUUM 활동, 트랜잭션 지속 시간, 테이블 크기 증가를 함께 봅니다.
• 복제 서버 지연은 WAL 생성량, 수신기 상태, 재생 지연, 네트워크/스토리지 지연을 묶어 판단합니다.

연결 사용률은 관측된 pg_settings_max_connections가 양수일 때 계산합니다. 용량 부재나 잘못된 0 값은 사용 불가로 남고, 유효한 용량이 있는 풀의 실제 연결 수가 0이면 0%로 표시합니다.

---

PostgreSQL Enterprise 확장

TLS 설정 위치

TLS 모드·CA·클라이언트 인증서와 키·서버 이름·인증서 검증 설정은 보안 > TLS에 표시합니다. 주소·포트 등 실제 연결 설정은 기존 구역에 남습니다. 이 분류 변경은 필드 이름, 저장 값, 기본값, 비밀값 처리와 조건부 표시·검증을 바꾸지 않습니다.

CloudNativePG exporter 프리셋

외부 수집 모드의 메트릭 설정에서 메트릭 소스를 먼저 선택한 뒤, **Exporter 프리셋 → CloudNativePG (CNPG)**를 선택합니다(metric_exporter=cnpg). 기본값은 postgres_exporter이며, Konduo 관리 수집은 자체 표준 매핑을 계속 사용합니다.

CNPG 프리셋은 공통 데이터베이스 통계 규칙을 재사용하고 연결 수·collector 상태· 설정 단위·WAL·복제 지표를 보정한 완전한 postgresql-cnpg-prometheus-pack-v1 팩을 반환합니다. PG17 전후 checkpointer counter 이름 차이를 처리합니다. prefix가 비어 있으면 실제 CNPG 이름을 사용합니다. 기존 cnpg_ prefix와 pg_ 교체 설정을 함께 사용해도 한 번만 적용합니다. job="konduo-postgresql" 및 필요한 pod·namespace·cluster 등 실제 수집 라벨로 범위를 제한하세요. 모든 지표에 cluster 라벨이 있다고 가정하지 않습니다.

매핑과 보정은 각 리소스에 독립적으로 보관합니다. 같은 메트릭 소스를 사용하는 다른 리소스의 보정에 영향을 받지 않습니다. exporter 프리셋을 선택한 뒤 진단하고 필요한 보정을 검증·적용하세요. 보정 공유는 JSON 내보내기/가져오기를 사용합니다. 내장 프리셋은 CNPG 기본 수집 정의를 대상으로 하며 임의의 사용자 SQL collector를 모두 지원한다고 보장하지 않습니다.

집계된 트랜잭션 시간에는 PID 식별 정보가 없습니다. PID 기반 차트, 마지막 replay 시각 및 세부 복구 충돌 차트는 기본 수집기의 미지원으로 명시하고 선택 패널의 when_available 정책으로 숨깁니다. 지원 지표의 빈 결과·stale·수집/쿼리 실패는 숨기지 않습니다. PG17 이후 일부 구형 bgwriter counter가 없어도 단순 부재만으로 미지원이라고 판단하지 않습니다.

근거: CNPG 모니터링, 기본 수집 정의.

기본 접근성 관측

리소스 개요는 메트릭 소스와 별개로 접근 가능·접근 불가·접근 미확인을 표시합니다. 성공한 접속 확인은 전체 멤버, 복제, 파티션이나 작업의 정상 상태를 보장하지 않습니다. 구체적인 도메인 상태는 진단과 도메인 경보에서 확인합니다. 기존 liveness/readiness 정보는 도메인 상세 증거이며 기본 접근성 경보의 조건이 아닙니다. 미확인은 발생 중인 경보를 복구시키지 않습니다.

TLS

TLS 전용 sslmode를 선택하고 tls_ca_cert에 사설 CA 인증서(PEM)를 입력하면 CA 파일 없이 서버를 검증할 수 있습니다. CA 입력 시 sslmode=require는 verify-full로 바뀌며, 인증서의 DNS 이름이 접속 주소와 다르면 tls_server_name을 지정할 수 있습니다. 상호 TLS에서는 tls_client_cert와 tls_client_key를 함께 입력합니다. tls_insecure_skip_verify=true는 대신 PGSSLROOTCERT를 포함한 서버 검증을 생략하지만 평문으로 전환하지 않습니다. sslmode=disable과 함께 사용할 수 없고 기본값은 꺼짐입니다.

같은 Prometheus 소스를 사용해도 각 리소스의 보정과 이력은 독립적입니다. 보정을 공유하려면 JSON 내보내기/가져오기를 사용하고 선택한 프리셋과 기본 팩 버전을 검토한 뒤 적용하세요. 기존 차트 키는 alias_of 별칭으로 표현하며 보정은 정규 postgres.* 키에 적용합니다. 진단은 instant/range를 각각 검증합니다. 데이터가 없다는 이유만으로 매핑 오류라고 판단하지 않으며 수집 상태, 라벨 조건, 연결 상태를 먼저 확인합니다.

차트 값 의미

Exporter 수집 상태의 0은 성공, 1은 실패이며 오류 건수가 아닙니다. 복제 역할과 로깅 설정은 각각의 의미를 가진 상태 문자열로 표시하고 건강도와 혼동하지 않습니다. 매핑팩 v4는 대상별 상태 관측을 보존합니다. 건수는 정수이고 퍼센트 게이지 범위는 0–100입니다.

개요는 연결·트랜잭션 요약 6개와 워크로드·쿼리 품질 추세 5개를 함께 보여줍니다(11개). 스토리지/WAL은 작은 값 4개, 전체 폭 데이터베이스 크기 비교와 체크포인트 추세 4개를 표시합니다(9개). 복제는 작은 값 4개와 로그 설정 이력을 포함한 추세 4개를 표시하고 설정 값 6개는 기본 접힘 행에 둡니다(14개).

개수·상태·시간은 숫자 카드, 연결 사용률은 백분율 게이지로 표시합니다. 전체 34개 패널 키·쿼리·단위와 저장한 개인화 배치는 유지합니다.

PostgreSQL Enterprise 확장은 PostgreSQL 리소스에 MCP 설명자, 고급 진단, 로그 근거 매핑, 메트릭 매핑, 이상 징후 규칙을 추가합니다. 세션, 잠금, 접속, 복제, 저장소, VACUUM 상태를 운영 근거로 정리합니다.

특징

• MCP에서 데이터베이스 정보, 모니터링 개요, 연결성 점검, 진단, 토폴로지, 메트릭 매핑을 제공합니다.
• 세션, 잠금, 접속, 설정, 복제, 저장소/VACUUM 근거를 진단에 포함합니다.
• 로그 근거 매핑으로 PostgreSQL 진단을 Enterprise 로그 소스와 연결합니다.
• 이상 징후 규칙은 선언형 메트릭 방식으로 PostgreSQL 논리 메트릭을 평가합니다.
• Community 기반 트랜잭션 유휴 세션 조회와 PID 기반 조치 경로를 Enterprise 로그 근거, MCP 조회, 이상 징후 분석과 연결합니다.

등록 전 확인

• Community PostgreSQL 연결과 읽기 권한이 정상이어야 합니다.
• Prometheus postgres 익스포터 매핑팩과 OpenSearch 로그 소스 연결을 준비합니다.
• 복제와 장애 조치 계획 맥락을 보려면 토폴로지 조회 권한을 확인합니다.

운영 팁

• 잠금 대기, 접속 포화, 복제 지연은 애플리케이션 배포와 VACUUM 상태를 함께 봅니다.
• 트랜잭션 유휴 세션 경보는 별도 트랜잭션 목록이 아니라 pg_stat_activity 백엔드 세션 근거로 해석합니다. 관리형 수집에서는 PID와 트랜잭션 시작 시각으로 동일 트랜잭션의 지속 여부를 판정하므로, 다른 트랜잭션으로 교체되면 경보 대기 시간도 새로 시작합니다.
• 관리 수집 모드의 Long Transaction 경보는 현재 데이터베이스의 client backend만 대상으로 PID와 트랜잭션 시작 시각을 함께 추적합니다. PostgreSQL 백그라운드 작업과 idle in transaction 세션은 제외되며, 다른 트랜잭션이 이전 경보의 대기 시간을 이어받지 않습니다.
• 순수 idle in transaction 상태는 취소할 실행 쿼리가 없을 수 있으므로 PID, 사용자, DB, 클라이언트, 마지막 쿼리, 트랜잭션 지속 시간과 애플리케이션 로그를 확인한 뒤 종료 여부를 판단합니다.
• 장애 조치 설명자는 계획과 인벤토리 맥락을 제공하며, 실제 상태 변경은 별도 권한과 감사 경계를 따릅니다.

운영 시나리오

• API 지연이나 트랜잭션 적체가 발생하면 세션, 잠금, 접속 풀, VACUUM, 복제 지연을 한 흐름으로 확인합니다.
• 트랜잭션 유휴 경보가 발생하면 전용 세션 목록에서 PID와 마지막 쿼리를 확인하고, 같은 시간대 OpenSearch 로그 근거로 애플리케이션 트랜잭션 경계를 추적합니다.
• 장애 분석 시 PostgreSQL 진단 결과를 OpenSearch 로그 근거와 연결해 같은 시간대의 애플리케이션/데이터베이스 오류를 비교합니다.
• 장애 조치 계획 맥락은 토폴로지와 인벤토리 확인용으로 사용하고, 실제 전환 절차는 승인된 운영 절차를 따릅니다.

경계

• Konduo 런타임 DB로 표시한 리소스는 쿼리 취소, 세션 종료, ANALYZE, VACUUM 관리 작업을 차단합니다. 안전 모드는 확인 절차이며 읽기 전용 DB 권한을 대신하지 않습니다.
• EE 확장 계층은 고급 진단, 로그 근거 매핑, 이상 징후 규칙 메타데이터를 제공하고, 파괴적 유지보수를 자동 실행하지 않습니다.
• PostgreSQL 메트릭 매핑이 없으면 저장소/VACUUM/복제 관련 이상 징후는 사용 불가 또는 부분 근거로 남겨야 합니다.
• 트랜잭션 유휴 세션 종료는 사용자 트랜잭션을 중단할 수 있으므로 Enterprise 상관관계 분석 결과만으로 자동 실행하지 않습니다.

연결 사용률은 관측된 pg_settings_max_connections가 양수일 때 계산합니다. 용량 부재나 잘못된 0 값은 사용 불가로 남고, 유효한 용량이 있는 풀의 실제 연결 수가 0이면 0%로 표시합니다.

MCP diagnostic execution effects

The run_diagnostics tool changes diagnostic execution and cooldown state. Its descriptor declares operation_class: diagnostic_lifecycle; MCP advertises readOnlyHint=false, destructiveHint=false and idempotentHint=false. Diagnostic queries retain read-only hints. Both queries and actions continue to require mcp:invoke and the existing resource permissions/audit checks. Safety hints do not change authorization or guarantee safe retries.

MCP tool input contracts

Connection checks, database metadata, replication inspection, failover planning, static catalogs, and maintenance operation inventory accept {}. Session and lock inspection expose pagination and row filters. Historical evidence declares lookback, metric_source_id, and log_source_id; topology accepts comma-separated host instance IDs. Dynamic selector and legacy alias inputs remain supported on the routes that consume them.

The advertised JSON Schema is checked before plugin dispatch. Omitted optional values retain plugin defaults. Arguments do not replace resource-instance authorization; stored connection credentials are supplied by Konduo. Open schemas are retained only for existing dynamic filters or aliases, and each advertised property describes its caller-facing meaning. Plugin result shapes can vary with product/version, available evidence, and partial failures; no stable outputSchema is promised for these dynamic responses. 클라이언트와 리소스 지원 범위는 Enterprise 소스 저장소의 enterprise/backend/docs/plugin-contract.md에 정의되어 있습니다.