Skip to content
Monithub DocsMonithub Docs

데이터베이스 연결

전체 문서 PDF

데이터베이스 카탈로그는 데이터베이스에 접근할 수 있는 환경에서 전용 Collector를 실행해 운영 메트릭을 읽습니다. 데이터베이스 로그, 쿼리 본문과 결과는 수집하지 않습니다.

카탈로그 수집 데이터 필요한 조회 권한
PostgreSQL 서버와 데이터베이스 상태 메트릭 pg_stat_database의 SELECT
MySQL / MariaDB 전역 상태와 InnoDB 메트릭 SHOW GLOBAL STATUS 실행
Redis 단일 endpoint의 기본 INFO 메트릭 INFO 실행

가능하면 애플리케이션 계정과 분리된 모니터링 계정을 사용하세요. Connect에는 endpoint, 사용자 이름, 비밀번호, 데이터베이스 이름과 인증서 경로를 입력하지 않습니다. 이 값은 Collector를 실행할 때만 환경 변수나 운영 중인 secret store로 전달합니다.

공통 연결 순서

Section titled “공통 연결 순서”
  1. Collector에서 접근 가능한 데이터베이스 endpoint와 모니터링 계정을 준비합니다.
  2. 카탈로그와 Collector를 실제로 실행할 환경을 선택합니다.
  3. 데이터베이스 전송 보안을 선택하고 수집 대상 이름과 운영 환경을 입력합니다.
  4. 설정 생성을 누르고 표시된 Collector 설정 전체를 otelcol-monithub.yaml로 저장합니다.
  5. 해당 카탈로그의 런타임 값을 환경 변수로 주입하고 Connect가 표시한 명령으로 Collector를 실행합니다.
  6. 한 번 이상 수집될 때까지 기다린 뒤 데이터 수집 확인에서 메트릭을 확인합니다.

문서의 축약 예시는 변수 이름과 적용 위치를 설명하기 위한 것입니다. Collector YAML과 설치·실행 명령은 현재 연결에서 생성된 내용을 사용하세요.

전송 보안 선택

Section titled “전송 보안 선택”
방식 준비할 항목 권장 상황
평문 TCP endpoint와 계정 정보 암호화가 필요 없는 신뢰된 사설망
서버 인증서 검증 TLS CA 인증서 암호화하고 서버 인증서를 검증할 때
클라이언트 인증서 mTLS CA, 클라이언트 인증서와 개인 키 서버와 Collector가 서로 인증할 때

평문 TCP는 전송 내용을 암호화하지 않습니다. 인터넷이나 신뢰할 수 없는 네트워크를 통과한다면 TLS 또는 mTLS를 사용하세요. TLS와 mTLS에서는 인증서 검증을 끄지 말고, Collector 프로세스나 컨테이너가 읽을 수 있는 인증서 경로를 지정합니다.

런타임 값 적용

Section titled “런타임 값 적용”

Linux와 macOS에서는 값이 들어 있는 파일을 Git에 커밋하지 말고 파일 권한을 제한한 뒤, Collector를 시작하는 셸이나 서비스 관리자에서 불러옵니다.

Terminal window
chmod 600 ./database-collector.env
set -a
. ./database-collector.env
set +a
otelcol-contrib --config ./otelcol-monithub.yaml

Docker를 선택했다면 같은 파일을 Connect가 생성한 --env-file 옵션에 사용합니다. YAML과 인증서는 생성된 명령처럼 읽기 전용으로 마운트하세요. Windows에서는 Connect가 표시한 PowerShell 환경 변수 블록과 실행 명령을 같은 세션에서 실행합니다.

PostgreSQL

Section titled “PostgreSQL”
PostgreSQL 카탈로그, Collector 실행 환경, 평문 TCP·TLS·mTLS 선택 영역이 순서대로 강조된 Connect 화면
  1. PostgreSQL을 선택합니다.
  2. 데이터베이스에 접근할 수 있는 환경에서 Collector를 바이너리로 실행할지 Docker로 실행할지 선택합니다.
  3. 실제 데이터베이스 연결 방식과 일치하는 전송 보안을 선택합니다.

Collector 실행 환경에 다음 값을 주입합니다. endpoint는 host:port 형식이며, 데이터베이스는 이 연결에서 수집할 하나를 지정합니다.

POSTGRESQL_ENDPOINT=db.internal:5432
POSTGRESQL_USERNAME=<monitoring-user>
POSTGRESQL_PASSWORD=<secret>
POSTGRESQL_DATABASE=<database>

모니터링 계정에는 pg_stat_database를 읽을 수 있는 SELECT 권한이 필요합니다. Connect가 생성하는 설정은 서버와 데이터베이스 메트릭만 수집하며 query sample, top query와 데이터베이스 로그는 활성화하지 않습니다.

MySQL / MariaDB

Section titled “MySQL / MariaDB”
MySQL 카탈로그, Collector 실행 환경, 데이터베이스 전송 보안 선택 영역이 순서대로 강조된 Connect 화면
  1. MySQL을 선택합니다. MariaDB도 같은 카탈로그를 사용합니다.
  2. 데이터베이스에 접근할 수 있는 Collector 실행 환경을 선택합니다.
  3. 실제 서버 설정에 맞는 전송 보안을 선택합니다.
MYSQL_ENDPOINT=db.internal:3306
MYSQL_USERNAME=<monitoring-user>
MYSQL_PASSWORD=<secret>
MYSQL_DATABASE=<database>

모니터링 계정은 SHOW GLOBAL STATUS를 실행할 수 있어야 합니다. 지원 대상은 MySQL 5.7.x, 8.0.x, 8.4.x, 9.x와 MariaDB 10.5.x~10.11.x, 11.x입니다. Connect 설정은 메트릭만 수집하며 query sample, top query와 statement event는 활성화하지 않습니다.

Redis

Section titled “Redis”
Redis 카탈로그, Collector 실행 환경, 데이터베이스 전송 보안 선택 영역이 순서대로 강조된 Connect 화면
  1. Redis를 선택합니다.
  2. Redis endpoint에 접근할 수 있는 Collector 실행 환경을 선택합니다.
  3. 실제 Redis 연결 방식에 맞는 전송 보안을 선택합니다.
REDIS_ENDPOINT=redis.internal:6379
REDIS_USERNAME=<acl-user>
REDIS_PASSWORD=<secret>

사용자 이름은 Redis 6 이상에서 ACL을 사용할 때 필요합니다. 모니터링 계정에는 INFO 실행 권한만 부여하고 애플리케이션 데이터 명령 권한은 주지 않는 것을 권장합니다. 수집되는 값은 서버 상태와 keyspace 요약 메트릭이며 key와 value는 읽지 않습니다.

Redis 연결 하나는 정적 endpoint 하나를 사용합니다. failover 등으로 endpoint가 변경되면 REDIS_ENDPOINT를 바꾸고 Collector를 다시 시작하세요. Sentinel이나 Cluster의 node를 자동으로 찾거나 endpoint를 자동 갱신하지 않습니다.

TLS 인증서 변수

Section titled “TLS 인증서 변수”

전송 보안에서 TLS 또는 mTLS를 선택했다면 같은 카탈로그의 기본 환경 변수에 아래 경로를 추가합니다.

카탈로그 TLS mTLS에서 추가
PostgreSQL POSTGRESQL_TLS_CA_FILE POSTGRESQL_TLS_CERT_FILE, POSTGRESQL_TLS_KEY_FILE
MySQL / MariaDB MYSQL_TLS_CA_FILE MYSQL_TLS_CERT_FILE, MYSQL_TLS_KEY_FILE
Redis REDIS_TLS_CA_FILE REDIS_TLS_CERT_FILE, REDIS_TLS_KEY_FILE

Docker에서는 호스트 경로가 아니라 컨테이너 안에서 보이는 인증서 경로를 환경 변수에 넣습니다. Connect가 생성한 실행 명령의 읽기 전용 인증서 mount와 경로가 일치하는지 확인하세요.

여러 대상과 관리형 데이터베이스

Section titled “여러 대상과 관리형 데이터베이스”

Connect 연결 하나는 PostgreSQL·MySQL은 endpoint 하나와 데이터베이스 하나, Redis는 정적 endpoint 하나를 기준으로 생성됩니다. 여러 대상을 한 Collector에서 수집하려면 먼저 각각 연결을 확인한 뒤 기존 Collector 설정을 직접 확장할 수 있습니다.

클라우드 관리형 데이터베이스도 공급자가 발급한 endpoint, 모니터링 계정과 CA 인증서를 같은 런타임 변수에 넣습니다. IAM 토큰 발급이나 공급자별 인증 설정은 해당 클라우드의 공식 절차를 따르세요.

연결 후 확인

Section titled “연결 후 확인”
증상 확인할 내용
연결 시간 초과 또는 거부 Collector 실행 위치에서 endpoint와 port에 접근 가능한지, 방화벽과 사설망 경로가 열려 있는지 확인합니다.
인증 실패 사용자 이름과 비밀번호, PostgreSQL SELECT, MySQL SHOW GLOBAL STATUS, Redis INFO 권한을 확인합니다.
인증서 검증 실패 CA가 서버 인증서를 발급한 CA인지, 인증서의 서버 이름이 endpoint와 일치하는지 확인합니다.
Docker에서 인증서를 찾지 못함 인증서의 읽기 전용 mount와 환경 변수에 적은 컨테이너 내부 경로가 같은지 확인합니다.
Collector는 실행되지만 메트릭이 없음 선택한 데이터베이스 이름과 endpoint를 확인하고 한 번 이상의 수집 주기가 지난 뒤 다시 확인합니다.

Collector 로그에 연결 오류가 없고 메트릭이 수집되면 데이터베이스 연결이 완료된 것입니다. 공통 상태와 재시도 방법은 연결 및 수집 확인을 참고하세요.