본문으로 건너뛰기

설치 및 사용

DBX for Cloud, DBXC는 두 가지 주요 컴포넌트로 구성됩니다.

  • dbxc-agent: 클라우드 지표를 모니터링하는 백그라운드 서비스 (에이전트)
  • dbxc-ctl: 에이전트를 제어하는 CLI 도구 (시작, 중지, 상태 확인, 로그 조회)

에이전트 설치​

OSArchitecturePackage
Linuxamd64, arm64.tar.gz
Windows 10, Windows Server 2016 이상amd64.zip

설치 스크립트가 아키텍처(x86_64, aarch64)를 감지해 현재 경로의 dbxc 디렉토리에 설치합니다.

curl -fsSL https://repo.whatap.io/agent/dbx/cloud/install.sh | bash
cd dbxc

설치 후 dbxc 디렉토리에 config.yaml을 만들고 ./dbxc-ctl start로 실행합니다.

설정 파일 구조​

DBXC는 YAML 형식의 설정 파일을 통해 실행 구성을 정의합니다.

지원 형식​

DBXC는 단일/멀티 프로젝트 에이전트를 지원합니다.

  • YAML 형식 (.yaml, .yml)
  • 단일 파일: 하나의 에이전트 실행
  • 디렉토리: 다중 에이전트 실행

설정 파일 자동 탐색 순서​

  1. -c 옵션으로 지정된 파일/디렉토리
  2. config.yaml, config.yml (기본 파일)
  3. 현재 디렉토리의 모든 .yaml, .yml 파일

설정 파일 예시​

디렉토리 tree 예시
❯ tree
.
├── configs
│   ├── project-1.yml
│   └── project-2.yml
├── dbxc-agent
├── dbxc-ctl
├── dbxc.log
├── dbxc.pid

❯ ls -al
total 68456
drwxr-xr-x  8 kyw  staff       256  7 18 20:23 .
drwxr-xr-x  9 kyw  staff       288  7 18 20:10 ..
drwxr-xr-x  4 kyw  staff       128  7 18 20:23 configs
-rwxr-xr-x  1 kyw  staff  20174450  7 18 20:09 dbxc-agent
-rwxr-xr-x  1 kyw  staff   8565570  7 18 20:09 dbxc-ctl
-rw-------  1 kyw  staff   5574908  7 18 20:30 dbxc.log
-rw-r--r--  1 kyw  staff         5  7 18 20:23 dbxc.pid
yml 예시
input:
  csp: "aws" # 클라우드 서비스 제공자를 입력합니다.
  namespace: "rds"
  region: "ap-northeast-2"
  instances: # 명시한 인스턴스는 항상 수집합니다. 클러스터 내의 인스턴스를 이 속성에 명시하면, 오토스케일 여부와 관계없이 항상 수집합니다.
    - name: "mysql-rds"
      slow_query: true # 슬로우 쿼리 페이지를 사용하려면, true로 설정합니다.
  clusters:
    autoscale:
      enabled: false # 오토스케일이 활성화되면, 오토스케일된 인스턴스들을 수집 대상에서 추가하거나 삭제합니다.
      interval: 60 # 명시한 클러스터들의 오토스케일 체크 주기입니다. (단위: 초)
    names:
      - "database-cluster-name"
  metrics: # 수집할 메트릭을 입력합니다.
    - "CPUUtilization"
    - "FreeStorageSpace"
    - "FreeableMemory"
    - "ReadLatency"
    - "WriteLatency"
    - "ReadIOPS"
    - "WriteIOPS"
    - "NetworkReceiveThroughput"
    - "NetworkTransmitThroughput"
    - "FreeLocalStorage"
  logs:
    enabled: false # 로그 수집을 활성화하려면 true를 입력합니다.
    groups: # 원하는 AWS log group을 추가합니다.
      - "/aws/rds/cluster/database-cluster-name/error"
      - "/aws/lambda/MyLambda"

output: # 수집한 메트릭 데이터를 받는 WhaTap 정보를 입력합니다.
  license: "abcdefg-higjgkgjk-zxcvnbnbmc"
  host: "127.0.0.1"

에이전트 실행 및 제어 명령어​

에이전트 실행부터 상태 확인, 로그 조회까지 다양한 CLI 명령어를 제공합니다.

시작/종료​

# 설정 파일과 권한 사전 검증 (에이전트를 시작하지 않음)
dbxc-ctl validate -c project.yaml

# 에이전트 시작
dbxc-ctl start -c project.yaml        # 특정 설정 파일
dbxc-ctl start --config configs      # 다중 프로젝트 (디렉토리)
dbxc-ctl start                       # 기본 설정 파일 자동 탐색

# 에이전트 중지
dbxc-ctl stop

# 에이전트 재시작
dbxc-ctl restart -c project.yaml

상태 확인​

# 간단한 상태 확인
dbxc-ctl status
dbxc-ctl describe

로그 조회​

# 실시간 로그 조회
dbxc-ctl logs -f

# 특정 프로젝트의 로그만 조회
dbxc-ctl logs -c project.yaml

# 로그 레벨별 필터링
dbxc-ctl logs --level error

# 최근 100개 로그 조회
dbxc-ctl logs --tail 100

에이전트 시작 실패 시​

# 로그 확인
dbxc-ctl logs --level error

에이전트 상태 확인​

# 전체 상태 확인
dbxc-ctl describe

# 특정 에이전트 로그 확인
dbxc-ctl logs -c specific-config.yaml -f
팁

일반적인 문제 해결 방법

  • 포트 충돌: 기본 포트 53200 사용 중인지 확인
  • 설정 파일 오류: YAML 문법 확인
  • 권한 문제: 파일 읽기 권한 확인
  • PID 파일 잠금: 강제 종료 후 PID 파일 삭제

에이전트 로그·설정 전송​

에이전트는 문제 진단을 위해 자신의 warn/error 로그와 설정 파일(config.yaml) 내용을 와탭 수집 서버로 전송합니다. 설정 파일은 1시간마다 전송합니다. 기본으로 켜져 있으며, agent_logs 항목으로 끄거나 범위를 바꿀 수 있습니다.

config.yaml
agent_logs:
  send_config: true            # 설정 파일 전송 여부 (기본값: true)
  send_logs: true              # 에이전트 로그 전송 여부 (기본값: true)
  log_levels: ["warn", "error"] # 전송할 로그 레벨 (기본값: warn, error)

설정 파일에 NCP secretKey 같은 인증 정보를 넣는 경우, 외부 전송을 원하지 않으면 send_config: false로 설정합니다.

상세 기술 정보​

DBXC의 세부 명령어 구성 및 내부 시스템 동작 정보입니다.

명령어 구조​

dbxc-ctl은 다음 명령어를 지원합니다.

  • start: DBXC 에이전트 시작
  • stop: DBXC 에이전트 중지
  • restart: DBXC 에이전트 재시작
  • logs: 로그 조회
  • validate: 설정 파일과 AWS 권한(AssumeRole, 인스턴스 조회, logs.groups 조회) 사전 검증 후 종료
  • status 또는 describe: 에이전트 상태 확인
  • version: 버전 정보 확인
  • help: 도움말 출력

HTTP API 엔드포인트​

에이전트는 HTTP 엔드포인트를 제공합니다.

  • http://localhost:53200/health: 헬스체크
  • http://localhost:53200/status: 상태 정보
  • http://localhost:53200/logs: 로그 조회

로그 시스템​

  • 파일명: dbxc.log
  • 최대 크기: 10MB(파일당)
  • 최대 백업 파일 수: 7개(dbxc.log.1, dbxc.log.2, ... dbxc.log.7)
  • 보관 기간: 14일
  • 압축: 자동 압축 활성화(오래된 로그 파일은 .gz로 압축)
  • 시간대: 로컬 시간 사용

로그 파일이 10MB가 되면 자동으로 회전하고, 최대 7개의 백업 파일을 유지하며, 14일 이상 된 로그는 자동 삭제됩니다. 디스크 공간을 절약하기 위해 오래된 로그는 압축됩니다.

최종 수정: