데이터베이스 수집기 등록

개요 — 무엇을 하나

Administration ▸ Collectors 는 InfraGuard 의 수집기 레지스트리(infr_collector 테이블)입니다. 하드코딩 크리덴셜·호스트맵을 코드에서 빼내 DB 에 변수화해 저장합니다. 수집기는 접근 방식(access) 으로 추상화됩니다.

access	용도	구동 화면
`web`	원격 에이전트 엔드포인트(tlx 프로브 · run_report)	Infra ▸ Health
`database`	등록 DB 에 직접 연결해 부하 지표 수집	Service ▸ Database · Infra ▸ Alerts
`agent`	내부망 대표 수집기(Redis + nginx‑vts)	Service ▸ Sessions · Service ▸ Web

이 문서는 access=database 수집기를 다룹니다. 등록된 DB 에 InfraGuard 앱이 주기적으로 접속해 SHOW GLOBAL STATUS · information_schema.processlist · information_schema.tables 를 읽고, 시계열을 infr_db_metric 에 적재합니다. 데이터 행 자체는 읽거나 쓰지 않습니다 — 부하·구조 지표만 봅니다.

DB 수집기는 DB 부하 모니터링 화면과 경보(Alerts)의 원천입니다. 여기서 DB 를 하나 등록하면 그 두 화면에 자동으로 나타납니다.

언제 쓰나

운영 중인 MySQL / MariaDB 인스턴스의 연결 포화·처리량·slow query·스키마 크기를 한 콘솔에서 관제하고 싶을 때.
새 DB 서버를 도입해 모니터링 대상에 넣을 때.
기존 .env 에 이미 있는 DB 자격을 재사용해 비밀을 다시 입력하지 않고 등록할 때(cred_ref=env:PREFIX).
여러 DB 를 한 번에 관리(공유 기본값 + 항목 배열)하고 싶을 때 — 그룹 편집기 사용.

화면 구성

수집기 목록은 접근 방식별로 카드가 뜹니다. access=database 행들은 하나의 "데이터베이스" 그룹 카드로 접혀 표시됩니다(개별 카드 난립 방지). 그룹 카드의 [편집]이 그룹 편집기(2탭)를 엽니다.

그룹 편집기 탭

탭	내용
기본설정(공유 접속 기본값)	`driver` · `port` · `database` · `username` · 대기 임계(`slow_time`) · `schedule` · `cred_ref` — 모든 DB 항목에 공통 적용
데이터베이스(항목 배열)	항목별 `alias` · 표시 이름 · `host`/IP · `driver`(override) · 실행 토글 · 비밀번호(write-only)

UI 에서는 한 장의 그룹 카드지만, 저장하면 각 항목이 개별 db@{alias} 행(access=database)으로 upsert 됩니다. 수집 파이프라인 · Service ▸ Database · 경보 타게팅은 모두 개별 수집기 단위로 동작합니다. 항목을 지우면 해당 db@ 행이 삭제됩니다.

개별 수집기 필드(`infr_collector`)

컬럼	의미
`key`	고유 키. DB 항목은 `db@{alias}` (예 `db@blue`) — 불변(경보가 key 로 타게팅하므로)
`title`	표시 이름(비우면 `{alias} DB`)
`access`	`database` 고정
`kind`	`metrics` 고정
`host_alias`	항목의 alias(호스트 라벨)
`feeds_table`	`infr_db_metric` 고정
`cred_ref`	자격 참조(예 `env:STATS_DB`) — 비우면 config + `secret_enc` 사용
`config`	`{driver, host, port, database, username, sample:{slow_time_sec, connect_timeout}}` (비밀 제외)
`secret_enc`	DB 비밀번호(Crypt · write‑only · 브라우저 미반환)
`is_run`	스케줄 활성 여부

사용법

1. 새 DB 등록(그룹 편집기)

Administration ▸ Collectors 로 이동.
"데이터베이스" 그룹 카드의 [편집] → 기본설정 탭에서 공유값을 채웁니다.
- driver: mysql 또는 mariadb
- port: 기본 3306
- database: 접속 기본 스키마일 뿐 — 비우면 information_schema 로 접속(수집 범위는 계정 권한이 결정)
- username: 모니터링 계정(예 infra_ro)
- 대기 임계(slow_time): 이 초 이상 실행 중인 쿼리를 "대기(밀림)"로 집계(1~60초, 기본 2)
- cred_ref: .env 자격 재사용 시 env:PREFIX
데이터베이스 탭 → [DB 추가] → 항목마다 alias(필수) · host/IP · 필요 시 비밀번호.
[저장]. 각 항목이 db@{alias} 행으로 생성/갱신됩니다.

2. 비밀 처리 — 두 갈래

(A) 비밀번호 직접 입력 — 폼의 비밀번호 필드에 입력하면 암호화되어 secret_enc 에 저장됩니다. 목록·API 응답에는 절대 평문이 나오지 않고 has_secret/has_db_pw 불리언만 노출됩니다.

비밀번호는 write‑only 입니다. 편집 시 비밀번호 칸을 비워 두면 기존 값이 그대로 보존됩니다(덮어쓰지 않음). 명시적으로 지우려면 삭제(clear) 옵션을 쓰세요.

(B) .env 자격 재사용(cred_ref=env:PREFIX) — 비밀번호를 DB 에 저장하지 않고 이미 .env 에 있는 자격 세트를 참조합니다. DbCollectorService::resolveConn() 이 다음 키를 읽습니다.

config 에 채워진 값이 우선하고, 비면 PREFIX_* env 로 보충합니다(host/port/database/username/password).

3. 서버 전역 대기 쿼리 — PROCESS 권한

핵심 두 지표(연결 포화율 = Threads_running/Threads_connected/max_connections, QPS·slow rate = ΔQuestions/ΔSlow_queries)는 기본(USAGE) 계정만으로도 수집됩니다. 그러나 서버 전역 대기 쿼리 집계와 전 스키마 크기 분석은 추가 권한이 필요합니다.

PROCESS 없음 → 자기 연결의 processlist 만 보임(waiting_scope=0).
PROCESS 있음 → 모든 세션 집계(waiting_scope=1, 서버 전역).

각 대상 DB 호스트에서 root 로 1회 실행하는 최소권한 계정 스크립트: sql/infr_db_monitor_grant.sql.

-- 전용 읽기 계정(접속 출처는 InfraGuard 앱 서버 IP 로 좁히는 것을 권장)
CREATE USER 'infra_ro'@'%' IDENTIFIED BY 'CHANGE_ME_TO_A_STRONG_SECRET';

-- 전역 관측 권한(데이터 접근 아님)
GRANT PROCESS, REPLICATION CLIENT ON *.* TO 'infra_ro'@'%';

-- 스키마 크기 분석(전 DB · 읽기 전용). 특정 DB 만이면 design.* 로 좁힘
GRANT SELECT ON *.* TO 'infra_ro'@'%';

-- blast-radius 격리 — 연결 독식 방지(2026-08-06 [1040] 사고 교훈)
ALTER USER 'infra_ro'@'%' WITH MAX_USER_CONNECTIONS 5;
FLUSH PRIVILEGES;

MariaDB 10.5+ 는 REPLICATION CLIENT 대신 BINLOG MONITOR 를 쓸 수 있습니다. PROCESS·SELECT 는 동일합니다.

4. 수집 실행·검증

수집은 infr:collect-db 아티즌 커맨드가 수행합니다. dev 런처(composer dev)의 스케줄러 pane 이 매분 호출합니다.

# 특정 수집기 1회 즉시 샘플(운영 정책 게이트 우회)
php artisan infr:collect-db --key=db@blue --force

# 전체 등록 DB(is_run=1) 정책에 따라 수집
php artisan infr:collect-db

수집 게이팅은 운영 정책이 결정합니다.

정책 키	기본값	의미
`db_collect_mode`	`economy`	`economy`=콘솔 사용자(프레즌스) 있을 때만 수집 · `always`=상시
`db_collect_interval_sec`	`60`	수집 주기(초, 최소 10)
`presence_window_sec`	—	마지막 활동 후 "사용자 있음" 유지 창

--key 로 특정 database 수집기를 테스트합니다. 웹 수집기용 [테스트]/[코드 동기화] 버튼은 access=web 전용이며 database 수집기에는 적용되지 않습니다 — 검증은 위 커맨드로 하세요.

5. 상태 판정 임계값

수집된 지표는 DbCollectorService::statusOf() 가 운영 정책의 임계값으로 up/degraded 를 판정합니다.

임계 키	기본값	초과 시
`db_degrade_conn_pct`	`80`	연결 포화율(%) ≥ → degraded
`db_degrade_running`	`40`	`threads_running` ≥ → degraded
`db_degrade_waiting`	`5`	대기 쿼리 수 ≥ → degraded
`db_degrade_slow_qps`	`1`	slow rate(/s) ≥ → degraded

데이터 소스

대상	테이블 / 원천	비고
수집기 레지스트리	`infr_collector` (마이그레이션 000201 + 000680)	`access`·`config`(JSON)·`secret_enc`(Crypt)
수집 시계열	`infr_db_metric` (마이그레이션 000681)	`SHOW GLOBAL STATUS` 파생 · qps/slow_qps delta
원격 DB 상태	`SHOW GLOBAL STATUS` · `SHOW VARIABLES max_connections`	각 등록 DB 에 직접 연결
대기 쿼리	`information_schema.processlist`	PROCESS 권한 시 서버 전역
스키마 크기	`information_schema.tables`	30분 장기 캐시(slow query 우회)

연결 누수 금지. DbCollectorService::withConn() 은 매 샘플마다 런타임 커넥션을 만들고 finally 에서 DB::purge 로 즉시 닫습니다. PDO 타임아웃(기본 5초)으로 원격 지연에 웹 요청/스케줄이 묶이지 않게 합니다. 무한 루프 데몬을 스케줄러로 spawn 하면 공유 MySQL 연결이 고갈됩니다(2026‑08‑06 [1040] Too many connections 사고).

권한

화면 접근·모든 CRUD: 관리자(admin, level ≥ 10) — CollectorController::isAdmin() 이 세션 infr_user_level >= 10 을 검사(demo=1 · staff=5 는 접근 불가).
실패 시 403. 저장·삭제·fill 은 모두 infr_audit_log/로그에 감사 기록됩니다.
fill/{key}(Inventory ▸ Tools 메시업으로 설정 주입)은 비밀 주입 예외(문서화된 §Option B)로 admin 전용 + 감사입니다.

자세한 레벨 체계는 RBAC 레벨을 참고하세요.

문제해결 · FAQ

대기 쿼리가 자기 연결만 보입니다 — PROCESS 권한이 없어 waiting_scope=0 입니다. sql/infr_db_monitor_grant.sql 로 부여하세요.
스키마 크기가 일부 DB 만 보입니다 — 전역 SELECT(또는 특정 DB SELECT) 권한이 필요합니다.
비밀번호를 바꿨는데 반영 안 됩니다 — 편집 시 비밀번호 칸을 비우면 기존 값이 보존됩니다. 새 값을 입력해야 교체됩니다.
economy 모드에서 카드가 잠깐 down(빨강) — 콘솔 사용자가 없어 수집이 잠시 밀린 것입니다. 진입 시 즉석 샘플(ensureFresh)이나 always 모드로 완화됩니다(§Service ▸ Database false‑red 방지).
key 를 바꾸고 싶습니다 — db@{alias} key 는 편집 시 불변입니다(경보 타게팅 안정성). 새 alias 로 항목을 추가하면 새 key 가 생성됩니다.
레벨 5 인데 접근이 거부됩니다 — 일부 안내 문구는 "레벨 5 이상"이라 표기되지만 실제 게이트는 admin(level ≥ 10) 입니다.