Skip to content
Monithub DocsMonithub Docs

데이터베이스 연결

전체 문서 PDF

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

카탈로그 수집 데이터 모니터링 계정 필수 조건
PostgreSQL 서버와 선택한 데이터베이스 상태 메트릭 선택한 데이터베이스 연결과 pg_stat_database의 SELECT
MySQL MySQL·MariaDB 서버 전역 상태와 지원되는 성능 메트릭 선택한 데이터베이스 접근과 SHOW GLOBAL STATUS 실행
Redis 서버 상태와 keyspace 요약 메트릭 INFO all 실행

애플리케이션 계정과 분리된 모니터링 계정을 준비하세요. 데이터베이스 주소, 계정과 인증서 경로는 Connect에 입력하지 않고 Collector 실행 환경에 전달합니다. 이미 Collector를 운영 중이라면 기존 Collector에 추가에서 설정 병합 방법을 확인하세요.

공통 연결 순서

Section titled “공통 연결 순서”
  1. Collector에서 접근 가능한 데이터베이스 주소와 모니터링 계정을 준비합니다.
  2. 카탈로그와 Collector를 실제로 실행할 환경을 선택합니다.
  3. 데이터베이스 전송 보안을 선택하고 수집 대상 이름과 운영 환경을 입력합니다.
  4. 설정 생성 후 바이너리 방식은 OS·CPU에 맞는 Collector를 설치하고, 표시된 YAML 전체를 otelcol-monithub.yaml로 저장합니다.
  5. 아래 실행 환경 안내에 따라 데이터베이스 연결 값을 적용하고 Collector를 실행합니다.
  6. 한 번 이상 수집될 때까지 기다린 뒤 데이터 수집 확인을 실행합니다.

문서의 환경 변수 예시는 KEY=value 형식으로 값과 변수 이름을 설명합니다. 실제 적용에는 선택한 실행 환경에서 생성된 환경 변수 블록, YAML과 설치·실행 명령을 사용하세요.

전송 보안 선택

Section titled “전송 보안 선택”

데이터베이스 전송 보안 옆 정보 버튼을 누르면 현재 선택에 필요한 파일, 적용 방식과 관리 주체를 확인할 수 있습니다.

방식 준비할 항목 작동 방식
평문 TCP 데이터베이스 주소와 계정 정보 인증서 없이 데이터베이스에 연결합니다.
서버 인증서 검증 TLS CA 인증서 CA 인증서로 데이터베이스 서버를 검증합니다.
클라이언트 인증서 mTLS CA, 클라이언트 인증서와 개인 키 서버와 Collector가 서로 인증서를 검증합니다.

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

Monithub는 인증서를 발급·업로드·보관하지 않습니다. 인증서 파일과 개인 키는 사용자가 Collector 실행 환경에서 관리하고, 설정 생성 후 표시되는 예시 경로를 실제 파일 경로로 바꿉니다.

PostgreSQL 설정 계획에서 평문 TCP, TLS, mTLS 전송 보안 선택지를 펼친 화면 mTLS에 필요한 파일과 적용 방식, 관리 주체를 보여주는 인증서 도움말

런타임 값 적용

Section titled “런타임 값 적용”

Connect가 표시한 환경 변수 블록의 예시 값을 실제 연결 정보로 바꾸세요. 변수 이름은 아래 카탈로그별 안내에서 확인할 수 있습니다.

환경 변수는 Collector 프로세스에 전달해야 합니다. 터미널에서 확인한 뒤 서비스로 운영할 때도 해당 서비스에 같은 값을 설정하세요. 연결 정보 파일은 Git에 커밋하지 않고 기존 비밀정보 관리 방식으로 보관합니다.

Linux와 macOS

Section titled “Linux와 macOS”
  1. 선택한 OS의 export 환경 변수 블록을 database-collector.env에 저장하고 예시 값을 바꿉니다.
  2. 파일 권한을 제한하고 현재 셸에 불러옵니다.
  3. Connect가 생성한 설정 파일 경로로 Collector를 실행합니다.
Terminal window
chmod 600 ./database-collector.env
. ./database-collector.env
otelcol-contrib --config ./otelcol-monithub.yaml

Windows

Section titled “Windows”
  1. Connect가 표시한 PowerShell 환경 변수 블록의 예시 값을 바꿉니다.
  2. Collector를 실행할 PowerShell 세션에서 환경 변수 블록을 먼저 실행합니다.
  3. 같은 PowerShell 세션에서 실행 파일과 설정 파일의 경로를 지정합니다.
Terminal window
./otelcol-contrib.exe --config ./otelcol-monithub.yaml

Docker

Section titled “Docker”
  1. Docker용 KEY=value 블록을 database-collector.env에 저장하고 예시 값을 바꿉니다. 이 파일에는 export나 PowerShell 문법을 넣지 않습니다.
  2. Connect가 생성한 {REPLACE_WITH_POSTGRESQL_ENV_FILE_PATH}, {REPLACE_WITH_MYSQL_ENV_FILE_PATH} 또는 {REPLACE_WITH_REDIS_ENV_FILE_PATH}를 저장한 파일의 실제 경로로 바꾸세요.
  3. YAML과 인증서는 생성된 명령처럼 읽기 전용으로 마운트합니다.
  4. 인증서 환경 변수에는 호스트 경로가 아니라 컨테이너 내부 경로를 입력합니다.

TLS는 CA 파일, mTLS는 CA와 클라이언트 인증서·개인 키 파일을 준비합니다. 실행 명령의 {REPLACE_WITH_CA_FILE_PATH} 등은 Docker 호스트의 실제 파일 경로로 바꾸고, 환경 변수의 /certs/ca.crt 등은 생성된 컨테이너 내부 경로를 유지하세요.

데이터베이스 주소는 Collector 컨테이너 안에서 접근 가능한 주소여야 합니다. localhost는 Collector 컨테이너 자신을 가리킵니다.

  • 다른 DB 컨테이너에 연결: 같은 사용자 정의 Docker 네트워크에 참여시키고 DB 서비스 이름과 컨테이너 포트를 사용합니다. 생성된 docker run의 이미지 이름 앞에 --network 실제_네트워크_이름을 추가하세요.
  • 별도 DB 서버에 연결: 컨테이너에서 접근 가능한 서버 주소와 포트를 사용합니다. TLS에서는 주소의 호스트 이름이 서버 인증서와 일치해야 합니다.

환경 변수 파일을 바꿨다면 새 값으로 컨테이너를 다시 생성합니다. 기존 컨테이너를 단순 재시작하는 것만으로 --env-file의 변경 내용을 다시 읽지는 않습니다.

실행 파일과 설정 파일 경로

Section titled “실행 파일과 설정 파일 경로”
  • 공통: 설정 파일은 --config에 절대 경로나 현재 폴더 기준 상대 경로로 지정합니다.
  • Linux와 macOS: otelcol-contrib를 /usr/local/bin처럼 PATH에 포함된 위치에 설치하면 작업 폴더와 관계없이 실행할 수 있습니다.
  • Windows: ./otelcol-contrib.exe는 실행 파일이 현재 폴더에 있다는 뜻입니다. 다른 폴더에서 실행한다면 실행 파일과 설정 파일의 경로를 각각 지정합니다.
  • Docker: 호스트의 실행 파일을 사용하지 않습니다. Connect가 제공하는 Collector 이미지와 volume mount 경로를 사용합니다.

PostgreSQL

Section titled “PostgreSQL”

아래 변수에 데이터베이스 주소와 계정을 지정합니다. 주소는 host:port 형식이며, 데이터베이스는 이 연결에서 수집할 하나를 지정합니다.

POSTGRESQL_ENDPOINT=db.internal:5432
POSTGRESQL_USERNAME={REPLACE_WITH_MONITORING_USER}
POSTGRESQL_PASSWORD={REPLACE_WITH_SECRET}
POSTGRESQL_DATABASE={REPLACE_WITH_DATABASE}

모니터링 계정은 지정한 데이터베이스에 연결할 수 있고 pg_stat_database를 조회할 수 있어야 합니다. Connect는 계정과 권한을 변경하지 않습니다. 생성되는 설정은 서버·데이터베이스 메트릭을 수집하며 쿼리 샘플과 데이터베이스 로그 수집은 활성화하지 않습니다.

separateSchemaAttr 경고가 표시될 때

Collector 0.158.0에서 Feature gate receiver.postgresql.separateSchemaAttr is not enabled 경고가 표시될 수 있습니다. 이 메시지만으로 메트릭 수집 실패를 의미하지는 않습니다. 별도 연결 오류가 없다면 기본 설정으로 수집 결과를 먼저 확인하세요.

데이터베이스·스키마 속성의 표현을 변경할 목적이라면 실행 인자에 다음 옵션을 추가할 수 있습니다. 기존 대시보드·필터에서 사용하는 속성에 영향이 있으므로, 경고를 없애기 위해 변경할 필요는 없습니다.

Terminal window
otelcol-contrib \
  --feature-gates=receiver.postgresql.separateSchemaAttr \
  --config ./otelcol-monithub.yaml

Windows·서비스 관리자는 Collector 실행 인자에, Docker는 이미지 이름 뒤의 Collector 인자에 같은 옵션을 추가합니다.

MySQL

Section titled “MySQL”

플랫폼에는 MySQL 카탈로그로 표시됩니다. MariaDB도 같은 Receiver를 사용하므로 지원 버전에서는 같은 환경 변수와 적용 절차를 따릅니다.

MYSQL_ENDPOINT=db.internal:3306
MYSQL_USERNAME={REPLACE_WITH_MONITORING_USER}
MYSQL_PASSWORD={REPLACE_WITH_SECRET}
MYSQL_DATABASE={REPLACE_WITH_DATABASE}

모니터링 계정은 MYSQL_DATABASE에 지정한 데이터베이스를 선택할 수 있고 SHOW GLOBAL STATUS를 실행할 수 있어야 합니다. Connect는 계정이나 권한을 변경하지 않으므로 아래 명령을 모니터링 계정으로 실행해 미리 확인하세요.

SHOW GRANTS FOR CURRENT_USER;
USE <database>;
SHOW GLOBAL STATUS;

USE가 실패하면 데이터베이스 이름을 확인한 뒤, 운영 환경의 권한 정책에 맞는 최소 권한을 데이터베이스 관리자에게 요청하세요. Receiver는 서버 전역 상태와 활성화된 스토리지 엔진에서 제공하는 성능 정보를 읽습니다. InnoDB가 비활성화되어 있거나 다른 스토리지 엔진을 사용하면 InnoDB 관련 메트릭은 표시되지 않을 수 있지만, 다른 메트릭 수집이 실패했다는 뜻은 아닙니다.

지원 대상은 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는 활성화하지 않습니다. 따라서 이 선택 기능에 필요한 추가 performance_schema 조회 권한은 현재 기본 설정의 필수 조건이 아닙니다.

Redis

Section titled “Redis”
REDIS_ENDPOINT=redis.internal:6379
REDIS_USERNAME={REPLACE_WITH_ACL_USER}
REDIS_PASSWORD={REPLACE_WITH_SECRET}

REDIS_USERNAME은 Redis 6 이상의 ACL 사용자 이름입니다. 사용자 이름 없이 비밀번호만 사용하는 구성이라면 이 값을 빈 문자열로 설정합니다. Docker 환경 변수 파일은 REDIS_USERNAME=, Linux/macOS는 export REDIS_USERNAME='', PowerShell은 $env:REDIS_USERNAME = ''로 적용하세요. 예시의 {REPLACE_WITH_ACL_USER}를 그대로 남기지 않습니다.

모니터링 계정은 INFO all을 실행할 수 있어야 합니다. 수집되는 값은 서버 상태와 keyspace 요약 메트릭이며 개별 키와 값은 읽지 않습니다.

Redis 주소가 바뀌면 REDIS_ENDPOINT를 수정하고 새 값으로 Collector를 실행하세요. Docker는 환경 변수 파일을 적용해 컨테이너를 다시 생성합니다.

TLS 인증서 변수

Section titled “TLS 인증서 변수”

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

카탈로그 TLS mTLS에서 추가
PostgreSQL POSTGRESQL_TLS_CA_FILE POSTGRESQL_TLS_CERT_FILE, POSTGRESQL_TLS_KEY_FILE
MySQL 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의 서버 주소와 데이터베이스 하나, Redis의 서버 주소 하나를 기준으로 생성됩니다. 여러 대상을 같은 Collector에서 수집하려면 각 연결의 기존 Collector에 추가 절차를 따릅니다.

클라우드 관리형 데이터베이스도 공급자가 제공한 주소, 모니터링 계정과 CA 인증서를 같은 변수에 넣습니다. 생성된 설정은 사용자 이름·비밀번호 기반입니다. IAM 등 별도 인증을 사용한다면 공급자의 인증 절차와 Collector 지원 설정을 추가로 확인해야 합니다.

연결 후 확인

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

Collector 로그에 연결 오류가 없고 메트릭이 수집되면 데이터베이스 연결이 완료된 것입니다. 공통 확인 순서는 연결 및 수집 확인을 참고하세요.