이 페이지는 기계 번역되었습니다. 영어 원본을 읽어보세요. English

애플리케이션 개발자를 위한

어떤 쿼리를 먼저 최적화해야 할까요? 어떤 코드에서 오류가 발생했을까요? 충돌에서 누가 레코드를 점유하고 있을까요? 에이전트가 서버 자체의 trace와 통계에서 답을 수집합니다. 개발자는 브라우저에서 이를 확인하며 서버에 로그인하지 않습니다.

  • 1분 trace 파일
  • 하루 3개 윈도우 성능 보고서
  • 플랜 기준 쿼리 그룹화
  • 15분 충돌 검색
  • REST 스크립트 및 CI용 로컬 API

trace · process_traces · perf report

성능 보고서

에이전트는 항상 trace 세션을 열어 둡니다. 매분 출력을 파일로 압축하고 각 쿼리에 대한 합계를 계산합니다. 윈도우가 끝나면 에이전트는 분 단위 데이터를 보고서로 결합합니다: 가장 느린 쿼리와 fetches, reads, writes 기준으로 가장 무거운 쿼리입니다. 각 쿼리에는 실행 횟수가 표시됩니다.

  1. 1Trace 세션fbtracemgr가 항상 실행되며, watchdog이 끊긴 세션을 재시작합니다
  2. 2분 단위 파일1분에 한 번 압축된 trace 출력
  3. 3분 단위 합계각 쿼리별: 실행 횟수, 시간, fetches, reads, writes, marks
  4. 4윈도우 보고서윈도우 종료 후 5분 이내; 각 순위에 최대 20개 쿼리
  5. 5✓ HQ MonitorPerf Report 페이지; 상태 보고서에서 링크
하루 세 개의 보고서 윈도우: 아침 07:00–12:30, 낮 12:31–18:00, 밤 18:01–06:59; 에이전트는 5분마다 윈도우를 확인하므로 윈도우 종료 후 5분 이내에 보고서가 나타납니다
기본 윈도우. 아침, 낮, 밤. 에이전트 설정에서 윈도우와 그 개수를 변경할 수 있습니다. 데이터가 없는 분은 건너뛰며, 보고서는 여전히 작성됩니다.

플랜 기준으로 그룹화하는 이유

프로그램이 값을 SQL 텍스트에 직접 넣으면 각 값마다 새로운 텍스트가 생성됩니다. 실제 한 사례에서는 서로 다른 텍스트의 수가 분당 204개에서 83,825개로 늘어났습니다. 수천 개의 “서로 다른” 쿼리는 사실 하나의 플랜을 가진 하나의 쿼리입니다. 따라서 기본적으로 에이전트는 키를 기준으로 쿼리를 그룹화합니다: 주석을 제거한 SQL의 처음 10자와 실행 플랜입니다. 플랜이 없는 쿼리는 전체 텍스트를 유지합니다. 에이전트 설정의 “Perf group by” 필드에서 모드를 변경할 수 있습니다: 플랜 기준 또는 전체 SQL 텍스트 기준. 텍스트 기준으로 하면 파일과 보고서가 훨씬 커집니다. 아래 예시에서 모드를 전환하고 순위를 비교해 보세요.

1분 동안의 쿼리

    fetches 기준 순위

      보고서 표표시 내용
      소요 시간 기준 상위 SQL가장 느린 실행: 시간과 레코드 수.
      fetches, reads, writes 기준 상위 SQL윈도우 합계: 실행 횟수, 시간, fetches, reads, writes, marks; 전체 윈도우에서의 비율; 실행당 평균 및 최대값.
      프로세스 및 주소프로그램 및 클라이언트 주소별 부하: 연결, 시간, 서로 다른 플랜 및 쿼리 수.
      쿼리 행전체 SQL, PLAN, 파라미터 및 테이블별 통계: natural, index, update, insert, delete, backout, purge, expunge.
      탭의 10개 순위소요 시간, 빈도, 총 시간, fetches, reads, writes, 플랜, 태그, 프로시저 및 트리거. 각 지표에 대해 값의 분포를 볼 수 있습니다.
      샘플 실행실행 시점, 클라이언트, 주소, 데이터베이스. 실행이 오류로 끝났다면 오류가 표시되며, 각 쿼리에는 실패한 실행 횟수 카운터가 있습니다.
      시간별 실행윈도우의 각 시간대에 쿼리가 몇 번, 얼마나 오래 실행되었는지.
      데이터베이스서버의 데이터베이스별 합계 및 각 쿼리의 주요 데이터베이스.

      비교, 기록 및 요청 시 보고서

      윈도우 보고서는 “오늘 무엇이 무거웠는가”라는 질문에 답합니다. 세 가지 새로운 기능은 “무엇이 바뀌었는가”와 “이 시간에 무슨 일이 있었는가”라는 질문에 답합니다.

      • 두 윈도우 비교두 보고서를 나란히: 어떤 쿼리가 느려졌고, 어떤 쿼리가 나타났으며, 어떤 쿼리가 사라졌는지.
      • 30일간 쿼리 기록하나의 쿼리에 대해 시간과 실행 횟수가 윈도우마다 어떻게 변했는지.
      • 데이터베이스별 필터하나의 데이터베이스에 대한 보고서만. 데이터베이스 페이지의 링크가 보고서 페이지로 연결됩니다.
      • 해당 분의 trace로 이동보고서의 쿼리에서 해당 쿼리가 실행된 분의 trace로 이동합니다.
      • 요청 시 보고서Build report… 버튼은 최대 24시간 범위의 보고서를 작성합니다. 필터: 데이터베이스, 최소 소요 시간, 프로그램. 에이전트는 한 번에 하나의 보고서를 작성하며 최근 20개를 보관합니다.
      • 검색 및 다운로드쿼리 텍스트 검색 필드. 보고서의 원본 파일을 다운로드할 수 있습니다.
      • 불완전한 보고서 표시일부 trace 파일이 아직 도착하지 않았다면 보고서가 불완전한 것으로 표시됩니다. 보고서는 각 순위의 상위 항목만 유지하므로 페이지에는 “순위에 없음”으로 표시되며 “실행되지 않음”이 아닙니다.
      • 프로시저 및 트리거이 순위는 trace 설정에서 프로시저 및 트리거 종료 로깅을 켜면 채워집니다. 기본적으로 이 로깅은 꺼져 있습니다.
      • 상태 보고서에서Perf report 버튼이 해당 윈도우를 엽니다. 쿼리 행이 표시되며 첫 번째 행은 이미 펼쳐져 있습니다.
      • 쿼리와 테이블gstat 통계의 Queries 탭은 쿼리를 해당 쿼리가 읽는 테이블 및 인덱스와 연결합니다.
      • 데이터베이스 차트의 1분1분을 클릭하면 해당 1분 동안의 trace와 모든 연결에서 발생한 무거운 쿼리를 보여줍니다.
      • SQL 복사매개변수 유무와 관계없이 사용 중인 도구로 바로 복사할 수 있습니다. 데모 모드에서는 버튼이 숨겨집니다.

      trace · Errors

      클라이언트 데이터가 포함된 SQL 오류

      사용자가 "프로그램에서 오류가 났다"고 말합니다. Errors 페이지는 trace에서 발생한 각 Firebird 오류를 보여줍니다: 시간, 연결, 데이터베이스, 텍스트, 클라이언트. 프로그램 이름, 주소, Firebird 함수를 통해 코드에서 오류를 쉽게 찾을 수 있습니다.

      trace의 오류 블록

      2026-10-17T12:00:05.0000 (4521:0x7f..) ERROR AT JStatement::execute /db/shop.fdb (ATT_370201, SHOP_APP:NONE, UTF8, TCPv4:10.0.0.5/50123) C:\Shop\shop.exe:7712 335544665 : violation of PRIMARY or UNIQUE KEY constraint "UK_ITEM"

      Errors 페이지의 행

      tstmpattIDdb · errTxt 12:00370201/db/shop.fdb ×3 335544665 : violation of PRIMARY or UNIQUE KEY constraint "UK_ITEM" C:\Shop\shop.exe:7712 · 10.0.0.5/50123 · JStatement::execute

      • 동일한 오류 — 하나의 행1분, 데이터베이스, 오류 유형별로 하나의 행에 ×N 횟수가 표시됩니다. 힌트에는 처음 및 마지막 시간과 연결 수가 표시됩니다.
      • 필터텍스트, 데이터베이스, 프로그램, 주소, 함수별로 포함 및 제외할 수 있습니다. 프로그램이나 주소를 클릭하면 해당 오류만 유지됩니다.
      • CSV 내보내기필터가 적용된 모든 행을 BOM이 포함된 UTF-8로 내보냅니다. Excel에서 파일을 열면 바로 열로 구분되어 표시됩니다.
      • 프로그램이 없는 경우많은 JDBC 및 .NET 드라이버는 프로그램 이름을 전송하지 않습니다. 이 경우 클라이언트 행이 더 짧아집니다.

      trace_monitor_conflicts · find_deadlocks

      충돌 및 교착 상태

      "update conflicts with concurrent update" 오류만으로는 알 수 있는 것이 거의 없습니다. 다른 트랜잭션이 무엇을 했는지 알아야 합니다. 이를 위해 에이전트는 데이터 변경 및 오류를 위한 두 번째 trace 세션을 유지합니다. 15분마다 충돌을 검색하고 보고서를 작성합니다.

      트랜잭션 1001이 레코드를 변경했습니다. 1002가 동일한 레코드를 변경하려다 오류가 발생합니다. 보고서는 1001의 번호로 해당 쿼리를 찾습니다

      보고서 읽는 방법

      왼쪽에는 충돌이 발생한 분 목록이 있습니다. 각 그룹은 충돌을 일으킨 하나의 트랜잭션입니다: 트랜잭션 번호와 오류 시간.

      왼쪽 열에는 오류가 표시됩니다: 연결, 프로그램, Firebird 코드, 실패한 쿼리. 오른쪽 열에는 경쟁 트랜잭션의 성공한 쿼리가 표시됩니다: 시간, 연결, 트랜잭션 번호, 프로그램. 각 쿼리에는 SQL, 매개변수, 통계, 테이블이 있습니다.

      페이지 주소에 날짜와 분이 유지됩니다. 동료에게 링크를 보낼 수 있습니다.

      충돌 페이지. 왼쪽에 분, 오른쪽에 트랜잭션 그룹: 프로세스 및 오류 코드.
      매개변수기본값의미
      충돌 검색15분마다마지막 1분은 건너뜁니다: trace가 아직 기록 중입니다.
      검색 깊이3시간다른 트랜잭션의 쿼리를 검색할 때 충돌 이전 얼마나 많은 이력을 살펴볼지 지정합니다.
      원시 trace 보존6시간충돌 세션의 원시 파일이 서버에 쌓이지 않습니다. 보고서는 보관되어 HQ Monitor로 전송됩니다.

      gstat · indexes · metadata

      데이터베이스 변경 사항

      에이전트는 하루에 한 번 전체 gstat 통계를 수집합니다. HQ Monitor는 파일을 파싱합니다: 테이블 및 인덱스 크기, 레코드 버전, BLOB, 인덱스 깊이. "Analysis and recommendations" 탭은 무엇이 잘못되었고 무엇을 해야 하는지 알려줍니다.

      분석 및 권장 사항. 문제, 사례 수, 연결된 객체, 권장 사항 및 조치.
      추세. 최신 스냅샷 비교: 무엇이 증가했는지, 그리고 객체가 언제 25% 증가할지.
      탭개발자에게 제공하는 정보
      테이블데이터, 인덱스, BLOB의 크기, 레코드 수, 레코드 버전 수 및 한 레코드의 최대 버전 수.
      인덱스깊이, 페이지 수, 고유 값 수, 중복 값 수. 깊이 4는 노란색 행, 5 이상은 빨간색입니다.
      쿼리 및 링크어떤 쿼리가 테이블이나 인덱스를 읽는지. 스냅샷과 시간상 가까운 성능 보고서의 데이터.
      추세5, 10, 20 또는 30개 스냅샷 비교; 변화 임계값 10%, 2% 또는 0.5%. 세 개 이상의 스냅샷에서 산출한 "+25%" 예측.
      내보내기측정값이 담긴 JSON과 전체 분석이 담긴 Excel.
      • 인덱스 통계기본적으로 꺼져 있으며 에이전트 설정에서 켭니다. 켜면 6시간마다 에이전트가 비활성 인덱스와 선택도가 낮은 인덱스를 집계합니다. 복원 후 재구축되지 않은 인덱스는 상태 보고서에서 심각한 항목입니다.
      • 증가 예측데이터베이스 테이블의 "+25%" 칩은 가장 빠르게 증가하는 테이블 또는 인덱스를 표시하며 예측을 엽니다.
      • 스키마 내보내기에이전트가 isql -x로 데이터베이스 메타데이터를 내보내고 날짜별로 아카이브를 보관합니다.
      • 메타데이터 추적기본적으로 꺼져 있으며 에이전트 설정에서 켭니다. 6시간마다 에이전트가 새 스키마 내보내기를 이전 것과 비교하고 스키마가 변경된 시점을 기록합니다.

      LWM · MON$ · 클라이언트

      연결: 장기 트랜잭션과 클라이언트 버전

      잊힌 트랜잭션 하나가 데이터베이스 전체를 느리게 만듭니다: 레코드 버전이 쌓이고 가비지 컬렉션이 멈춥니다.

      에이전트는 매분 트랜잭션 카운터와 연결 데이터를 기록합니다. 데이터베이스 차트에서 트랜잭션이 오래 열려 있으면 Next − OAT가 증가합니다. 해당 분의 연결 테이블을 Act.Tran 기준으로 정렬하면 트랜잭션을 보유한 프로그램, 주소, 프로세스를 볼 수 있습니다. 카운터에 대한 자세한 내용은 서버 상태 페이지에 있습니다.

      에이전트는 하루에 한 번 어떤 클라이언트 라이브러리가 데이터베이스에 연결하는지, 각각 연결 수가 몇 개인지 읽습니다. "감지되지 않음. 구버전?" 행은 보통 구버전 클라이언트 라이브러리를 의미합니다.

      클라이언트 버전. 클라이언트의 버전 문자열과 연결 수. 에이전트 자체 연결은 별도 행으로 표시됩니다.
      • MON$ 지표매시간: 프로그램별 메모리, 메모리를 가장 많이 사용하는 5개 연결과 부하가 가장 높은 5개 연결.
      • 오탐 없는 구버전 클라이언트"구버전 클라이언트" 발견 항목은 fbclient 라이브러리만 집계합니다. fbclient 없이 동작하는 드라이버는 여기에 포함되지 않습니다.
      • 보고서의 장기 트랜잭션상태 보고서는 장기 트랜잭션과 Next − OAT 증가를 표시합니다. 발견 항목에는 사용자, 프로그램, 주소가 명시되며 연결을 끊는 명령이 함께 제공됩니다.

      Local API · Prometheus · HQbird MCP

      스크립트, CI, AI 어시스턴트

      HQ Monitor에서 보이는 모든 것은 자체 도구에서 사용할 수 있습니다. 에이전트의 Local API는 루프백에서만 수신하며 각 요청에는 Bearer 토큰이 필요합니다. 무거운 작업은 비동기로 실행됩니다: 응답이 작업 번호를 반환하고, 그 번호로 상태를 조회합니다. 에이전트는 서버를 변경하는 각 요청과 각 401 또는 403 거부를 감사 로그에 기록합니다. 읽기 요청은 로그에 기록되지 않습니다.

      # Local API 포트 = 10000 + Firebird 포트: 여기서는 Firebird가 3055를 사용하므로 13055
      # 서버 상태: 상태 보고서와 동일한 스냅샷
      curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/status
      # 최신 성능 보고서와 최신 충돌 보고서
      curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/artifacts/server/traces/perf-report/latest
      curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/artifacts/server/traces/deadlocks/latest
      # CI에서 마이그레이션 전에 백업을 실행하고 결과를 기다림
      curl -X POST -H "Authorization: Bearer $TOKEN" -d '{"job_id":"nightly","reason":"before migration"}' \
           http://127.0.0.1:13055/v1/jobs/vbackup/run
      curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/runs/<run_id>
      경로제공 내용
      /v1/status서버 상태 스냅샷, 전체 또는 섹션별(예: 백업).
      /v1/databases활성 데이터베이스 목록.
      /v1/artifacts/…에이전트 데이터: 분당 LWM(Light-weight Monitoring), gstat, 인덱스 통계, 지표, 최신 스키마 내보내기, 트레이스 보고서.
      /v1/jobs/{job}/run작업 실행: 백업, 복원, sweep, 데이터베이스 검사, 인덱스 통계 재계산, SQL 스크립트. 같은 키로 반복해도 작업이 두 번 실행되지 않습니다.

      Prometheus 지표는 Local API를 거치지 않습니다. 별도 주소를 사용합니다: 기본값은 127.0.0.1, 포트 25000 + Firebird 포트. 별도의 Bearer 토큰을 사용합니다. 내보내기는 기본적으로 꺼져 있으며 에이전트 설정에서 켭니다. 지표: LWM, CPU 및 메모리, 디스크, OS 제한, 임시 파일.

      IDE 속 AI 어시스턴트

      HQbird MCP는 Firebird와 에이전트 데이터를 Claude Code, Cursor, Codex 및 기타 MCP 클라이언트에 연결합니다. 어시스턴트는 에이전트 보고서를 확인하고 사람의 통제 아래 데이터베이스로 작업합니다: 위험한 작업은 사람이 확인합니다.

      쿼리

      실행 계획과 인덱스

      쿼리 실행 계획과 인덱스 조언, 인덱스 생성 후 실행 계획 재확인. 실행 전 쿼리 컴파일 검사.

      스키마

      두 데이터베이스 비교

      스키마 및 데이터 차이, 예를 들어 개발 환경과 테스트 스탠드 간 비교.

      마이그레이션

      계획, 확인, 롤백

      계획, 한 번의 확인, 롤백 계획이 포함된 마이그레이션.

      더 보기: HQbird MCP

      ← HQbird 2027 개요로 돌아가기 · 서버 상태 자세히 보기 →