[작업] MySQL 읽기 전용 진단 tool 구현

[worud8457]

목적

#12의 공통 Tool Core를 사용해 AMDC 진단 에이전트가 MySQL의 database, foreground connection, active transaction과 InnoDB data lock wait를 읽기 전용으로 조회할 수 있게 합니다.

LLM은 등록된 도구와 구조화된 입력만 선택합니다. 실행 SQL은 YAML 카탈로그에 고정하고 모든 필터 값은 prepared binding으로 전달합니다.

구현된 도구

Database

• mysql_list_databases: 조회 가능한 비시스템 database 목록

Processlist

• mysql_get_all_processlist: 유휴 연결을 포함한 전체 foreground connection
• mysql_get_active_processlist: 현재 비유휴 foreground connection
• mysql_get_processlist_by_database: 특정 database를 기본 database로 사용하는 connection
• mysql_get_processlist_by_connection_id: 관측된 connection ID 하나

Transaction

• mysql_get_all_transactions: 전체 활성 InnoDB transaction
• mysql_get_transactions_by_connection_id: 특정 connection의 활성 transaction
• mysql_get_transaction_by_transaction_id: 특정 InnoDB transaction ID 하나

Lock wait

• mysql_get_all_lock_waits: 전체 InnoDB data lock wait 관계
• mysql_get_lock_waits_by_database: 특정 database의 lock wait 관계
• mysql_get_lock_waits_by_table: 특정 database와 table의 lock wait 관계
• mysql_get_lock_waits_by_connection_id: waiter 또는 blocker가 특정 connection인 관계

확인된 현재 상태

• MySQL 진단 계정으로 performance_schema와 information_schema를 직접 조회합니다.
• 전체 조회와 조건별 조회를 분리해 전체 조회 도구가 알 수 없는 식별자를 요구하지 않습니다.
• processlist, transaction, lock wait 결과는 비율이나 장애 점수를 계산하지 않고 원본 행과 적용된 조회 범위를 반환합니다.
• 격리된 로컬 DB에서 row lock wait, 미종료 유휴 transaction, 장시간 실행 query와 다수 idle connection을 재현했습니다.
• blocker 2개, waiter 4개와 6개 wait edge를 반환하고 루트 blocker까지 연결되는 것을 확인했습니다.
• SELECT SLEEP(120)을 실행한 connection ID와 실행 시간을 processlist에서 확인했습니다.
• 유휴 transaction의 connection ID와 동일 database의 Sleep connection 12개를 확인했습니다.
• 구현 및 검증 결과는 a4bbda7 (refactor(tools): refine MySQL diagnostic readers)에 반영했습니다.

공통 실행 계약

• 입력 스키마와 고정 SELECT를 YAML에 선언합니다.
• 등록되지 않은 입력과 범위를 벗어난 limit을 실행 전에 거부합니다.
• 입력값은 SQL 문자열에 결합하지 않고 prepared binding으로 전달합니다.
• 실행 timeout, 최대 행 수, 최대 출력 크기와 정제된 오류를 적용합니다.
• provider 원본 오류와 연결 자격증명을 결과 및 로그에 노출하지 않습니다.
• timeout 또는 중단 시 조회 connection을 정리합니다.
• dev/prod별 서버 소유 연결 설정을 사용하고 prod 연결은 CA 검증 TLS를 요구합니다.

제외 범위

• LLM이 작성한 SQL 또는 임의 statement 실행
• COMMIT, ROLLBACK, KILL, 설정 변경과 데이터 수정
• Prometheus 기반 MySQL 시계열 메트릭
• 과거 slow query 및 이미 해소된 deadlock 이력
• AMDB Backend의 database/user 메타데이터 API
• ProxySQL connection pool 및 query digest 조회
• 진단 결론, 장애 점수와 비율 계산

검증 결과

• npm test: 39개 통과
• npm run typecheck: 통과
• npm run build: 통과
• 잘못된 ID, 미지원 필드와 범위 밖 limit 거부 확인
• timeout, 권한 오류, 출력 크기 초과와 민감정보 포함 결과 처리 확인
• 12개 병렬 fake call의 connection 격리 및 종료 확인
• 실제 MySQL 장애 시나리오 결과를 Discord amdc 채널에서 확인

현재 확인된 제한사항

• 여러 connection과 transaction 상세 조회를 동시에 fan-out했을 때 일부 조회가 source_request_failed로 실패했습니다. 모델이 전체 transaction 조회로 보완해 최종 진단은 완료했지만 동시 실행 제한 또는 재시도 정책 검토가 필요합니다.
• 과거 이력과 정상 기준선은 현재 시점 MySQL 조회만으로 판단할 수 없으며 향후 Prometheus 및 로그 도구와 연계해야 합니다.
• 모델의 최종 domain 표시와 Discord 문구는 Tool 실행이 아닌 보고서 계층의 별도 문제입니다.

완료 조건

• 선언된 12개 MySQL 직접 조회 도구의 입력 스키마와 SQL 실행이 일치합니다.
• 전체 조회 도구는 알 수 없는 database 또는 connection ID 입력을 요구하지 않습니다.
• 특정 조회 도구는 전달된 database, table, connection 및 transaction 식별자를 정확히 prepared binding합니다.
• 격리된 lock wait에서 blocker와 waiter 관계를 반환합니다.
• 활성 transaction과 foreground connection을 원본 행으로 반환합니다.
• 잘못된 입력과 쓰기 동작이 실행 전에 거부됩니다.
• timeout·출력 제한·오류 정제·연결 정리가 자동화 테스트로 검증됩니다.
• 병렬 상세 조회 실패 원인을 해결하고 재현 가능한 검증 결과를 PR에 기록합니다.

[worud8457]

도구 확장 커밋 검증 (2026-09-18)

3dd4b33을 feature/jaekyung/langchain-tool에 푸시했습니다. Prometheus 12개와 ProxySQL 13개 도구, 공통 실행 검증, 로컬 검증 스크립트·문서를 포함합니다.

커밋 대상만 별도로 추출한 환경(macOS / Node v26.5.0)에서 npm test 49개 통과, npm run typecheck, npm run build, git diff --cached --check 통과를 확인했습니다. 전체 로컬 작업본의 50개 테스트와 달리 리포트 변경 테스트 1개는 이 커밋에 포함하지 않았습니다.

기존 MySQL prepared binding·timeout·출력 제한·오류 정제·connection cleanup 회귀 테스트도 통과했습니다. 기존 실제 MySQL 병렬 상세 조회 실패 원인은 이번에 해결/재검증하지 않았으므로 #13 마지막 항목은 미체크로 유지합니다.

진단 출력 계약, Discord 출력 변경 및 tool_call_id 구현은 제외했습니다. develop 병합이나 서버 배포는 하지 않았습니다. 이전 live 검증 및 한계는 docs/prometheus-proxysql-tools.md를 참고하세요.