InsForge Debug
백엔드의 관측 가능성 기본 요소(로그, 메트릭, DB 상태, 어드바이저, 정책, 메타데이터, 오류 객체, 배포 상태, AI 지원)를 결합하여 InsForge 프로젝트의 문제를 진단합니다. 이 스킬은 다음을 제공합니다:
- 각 디버그 기본 요소에 대한 참조(각각 하나의 관측 가능성 표면 —
references/아래) - 증상 레시피(아래) — 알려진 반응형 증상 및 사전 예방적 감사에 대한 기본 요소 시퀀스 명명
항상 npx -y @insforge/cli를 사용하세요 — CLI를 전역에 설치하지 마십시오.
가장 빠른 경로: AI 지원 분류(Triage)
사용자가 구체적인 설명(오류 메시지, 실패 URL, HTTP 상태)을 제공하면 InsForge 디버그 에이전트에 전달하십시오. 다른 기본 요소와 달리, 이 에이전트는 단순한 관찰이 아닌 제안을 반환합니다 — 제안에 인용된 기본 요소를 통해 진단을 검증한 후에 조치하십시오.
npx -y @insforge/cli diagnose --ai "<문제 설명>"
이것을 먼저 사용할 때와 건너뛰어야 할 때, 그리고 출력을 검증하는 방법은 references/ai-assisted.md를 참조하십시오.
디버그 기본 요소
각 기본 요소는 서로 다른 기본 데이터 소스에 의해 지원되는 독립적으로 질의 가능한 관측 가능성 표면입니다. 실제 진단은 기본 요소들의 조합입니다.
모든 명령어는 npx -y @insforge/cli ...를 통해 실행됩니다. 각 기본 요소 옆에 표시된 (명령어)는 실제 CLI 명령어입니다 — 기본 요소 이름은 개념 레이블이며, CLI 하위 명령어 이름이 아닙니다(예: "DB 상태"는 diagnose db이지 diagnose db-health가 아닙니다; "정책"은 db policies이지 diagnose policies가 아닙니다).
| 기본 요소 (명령어) | 결과 | 참조 |
|---|---|---|
로그 (logs <source>; 교차 소스 집계는 diagnose logs) | 5개 백엔드 소스(insforge.logs / postgREST.logs / postgres.logs / function.logs / function-deploy.logs)의 시간 순 이벤트 스트림 | references/logs.md |
메트릭 (diagnose metrics) | 1h / 6h / 24h / 7d 범위의 EC2 인스턴스 시계열(CPU / 메모리 / 디스크 / 네트워크) | references/metrics.md |
DB 상태 (diagnose db) | 7가지 명명된 검사(connections / slow-queries / bloat / size / index-usage / locks / cache-hit)를 통한 현재 Postgres 상태 | references/db-health.md |
어드바이저 (diagnose advisor --json) | 3가지 범주(security / performance / health)에 걸친 정적 스캔 문제 (ruleId / affectedObject / recommendation 포함) | references/advisor.md |
정책 (db policies) | pg_policies의 활성 RLS 규칙(명령어 및 역할별 USING / WITH CHECK) — 모든 정책을 덤프로 반환 | references/policies.md |
메타데이터 (metadata --json) | 선언적 백엔드 상태 덤프(인증 구성 / 테이블 / 버킷 / 함수 / AI 모델 / Realtime 채널) | references/metadata.md |
| 오류 객체 (명령어 없음 — SDK / HTTP 응답 읽기) | SDK 오류 봉투 + HTTP 상태 — 클라이언트에 표시되는 오류에서 올바른 로그 소스로의 라우팅 테이블 | references/error-objects.md |
배포 상태 (deployments list + deployments status <id> --json + logs function-deploy.logs) | 프론트엔드(Vercel) 배포 내역 + 배포별 메타데이터, 엣지 함수 배포 로그 | references/deploy-state.md |
AI 지원 (diagnose --ai "<description>") | 다른 기본 요소를 결합하는 LLM 에이전트 — 제안과 함께 진단 반환 | references/ai-assisted.md |
증상 레시피
각 레시피는 각 단계에서 "X를 찾으십시오"라는 한 줄 설명과 함께 기본 요소 호출 시퀀스입니다. 명령어 구문, 플래그 및 심층 해석은 위의 각 기본 요소 참조에 있습니다.
레시피: SDK가 { data: null, error: { code, message } } 반환
- error-objects — code/message/details를 읽습니다. code가
PGRST*로 시작하면 참조의 테이블을 사용하여 접두사로 라우팅합니다. - logs (error-objects 라우팅에 따른 일치하는 소스) — 오류 타임스탬프를 찾아 전체 백엔드 측 컨텍스트를 가져옵니다.
- db-health (
connections,locks,slow-queries) — 오류가 DB 문제(PostgREST 타임아웃, 잠금 충돌)를 암시하는 경우에만 수행합니다.
레시피: 특정 요청에 대한 HTTP 4xx/5xx 응답
- error-objects — HTTP 상태 라우팅 테이블을 사용하여 로그 소스를 선택합니다(각 상태는 고유한 경로를 가집니다. 429는 특별합니다).
- logs (해당 상태에 대한 올바른 소스) — 실패한 요청 줄과 오류를 찾습니다.
- metrics — 여러 엔드포인트에 걸친 5xx 패턴에 대해서만, 시스템 전체 부하 문제를 확인합니다.
레시피: RLS 액세스 문제(쓰기 시 403, 읽기 시 빈 결과)
동일한 버그, 두 가지 표면화. 쓰기(INSERT / UPDATE / DELETE)는 403과 함께 큰 소리로 실패합니다. 읽기(SELECT)는 조용히 빈 배열과 함께 실패합니다 — PostgREST는 거부된 행을 필터링하여 403을 반환하는 대신 요청이 성공한 것처럼 보이게 합니다(0행). 진단 경로는 1단계가 403 변형에만 적용된다는 점을 제외하면 동일합니다.
- logs (
postgREST.logs) — 403 변형만 해당: 테이블 및 역할 컨텍스트가 있는 정책 위반 이벤트를 찾습니다. 빈 결과 변형: 건너뜁니다 — 조용히 필터링된 행에 대한 오류가 기록되지 않습니다. - policies — 해당 테이블의 정책을 나열합니다. 실제 요청 및 사용된 JWT 클레임에 대해 USING / WITH CHECK를 검토합니다.
- metadata — auth 구성을 확인합니다(어떤 클레임이
auth.uid()/requesting_user_id()를 제공하는지; Clerk/Auth0 같은 타사 인증의 경우 제공자가 JWT 발급자로 등록되어 있습니까?). - db query (
db query "<sql>") — 빈 결과 변형만 해당: 서비스 역할(사용자 역할이 아님)로 쿼리하여 표시되어야 할 행이 실제로 존재하는지 확인합니다:npx -y @insforge/cli db query "SELECT id, user_id FROM <table>". "RLS가 모든 것을 필터링했음"과 "일치하는 데이터가 없음"을 구별합니다.
레시피: 로그인 실패 / OAuth 콜백 오류 / 토큰 만료
- logs (
insforge.logs) — 타임스탬프와 제공자 컨텍스트가 있는 인증 오류를 찾습니다. - metadata — 제공자가 활성화되어 있고 리디렉션 URL이 콜백 URL과 정확히 일치하는지 확인합니다(프로토콜 + 호스트 + 경로).
레시피: 엣지 함수 런타임 오류 / 타임아웃
- logs (
function.logs) — 오류 스택 및 실행 컨텍스트를 가져옵니다. - metadata — 함수가 존재하고
status: "active"인지 확인합니다. - (필요한 경우)
npx -y @insforge/cli functions code <slug>— 명백한 문제가 있는지 소스를 검사합니다.
레시피: functions deploy 실패
- deploy-state (
function-deploy.logs) — 빌드/푸시 오류를 찾습니다. - metadata — 함수가 활성 목록에 포함되었는지 확인합니다(부분 배포 감지).
레시피: deployments deploy 실패 (Vercel)
- deploy-state (
deployments list+status <id> --json) —status,metadata.webhookEventType및envVarKeys를 읽습니다. - 로컬
npm run build— 더 빠른 반복을 위해 동일한 오류를 로컬에서 재현합니다.
레시피: 단일 느린 쿼리 / 한 엔드포인트 느림
- logs (
postgres.logs) — 쿼리 텍스트와 타임스탬프를 찾습니다. - db-health (
slow-queries,index-usage) —slow-queries는 실행 중인 경우에만 포착합니다(>5초 스냅샷);index-usage에서 누락된 인덱스를 확인합니다. 이미 완료됨? advisor (--category performance --json)에는pg_stat_statements텍스트 + 평균 시간이 있습니다. 1단계에는 타임스탬프가 있습니다. - policies — RLS로 보호되는 테이블인 경우 정책이 숨겨진 조인을 추가하지 않는지 확인합니다.
레시피: "메모리가 약 80%이지만 느린 것은 없음"
- 예상된 현상입니다 — 먼저 그렇게 말하십시오. 전용 Postgres 인스턴스는 유휴 RAM을 공유 버퍼와 페이지 캐시로 전환합니다. 트래픽이 거의 없는 상태에서 꾸준히 높은 메모리는 누수가 아니라 정상 상태입니다(references/metrics.md, "메모리: 높음이 정상").
- metrics (
--range 24h) — 상승 추세 또는 OOM 죽음/재시작만 답을 바꿉니다. OOM 증거는postgres.logs에서 충돌-복구 후유증으로 발견됩니다("다른 서버 프로세스의 충돌로 인해 연결 종료" / "자동 복구 진행 중"). - OOM 증거가 있는 경우 해결책은 여유 공간 확보입니다: 유료 플랜으로 업그레이드하고 더 큰 인스턴스 크기를 선택하십시오(대시보드 → 프로젝트 설정 → 컴퓨팅 및 디스크). 실제 부하가 있는 가장 작은 인스턴스에서 OOM이 발생하는 것은 일반적이고 예상되는 현상입니다 — "메모리를 확보하기 위해 재시작"하지 마십시오.
레시피: 모든 응답 느림 / 높은 CPU/메모리 (활성 인시던트)
- metrics (
--range 1h) — 시스템 전체 압력을 확인합니다(CPU / 메모리 / 디스크). - db-health — DB가 가장 일반적인 병목입니다.
connections,locks,slow-queries를 확인합니다. - logs (
diagnose logs집계) — 스파이크 타임스탬프의 소스 전반에 걸친 오류 패턴. - advisor (
--severity critical) — 성능 저하를 설명할 수 있는 기존 알려진 문제.
레시피: Realtime 채널 연결 실패 / 메시지 누락
- logs (
insforge.logs) — WebSocket 오류 및 구독 실패. - metadata — 채널 패턴이 클라이언트가 구독하는 것과 일치하는지,
enabled: true인지 확인합니다. - policies — 기본 테이블의 RLS(Realtime은 행 변경을 전달합니다. RLS는 구독자가 볼 수 있는 행을 제어합니다).
레시피: 429 속도 제한
- error-objects — 429 상태를 확인합니다. 429에 대한 로그는 기록되지 않습니다.
Retry-After헤더도 반환되지 않습니다. 로그를 뒤지는 데 시간을 낭비하지 마십시오. - metrics (
--range 1h) — 전체 백엔드 부하 컨텍스트. - 수정은 항상 클라이언트 측: 디바운스, 배치, 지수 백오프, 재시도 루프 제거.
레시피: 특정 URL의 게이트웨이 타임아웃 (502 / 503 / 504)
드릴다운하기 전에 URL 하위 시스템별로 라우팅합니다:
| URL 패턴 | 드릴다운 대상 |
|---|---|
/api/database/records/... | logs (postgREST.logs → postgres.logs) + db-health (locks, slow-queries) |
/functions/<slug> | logs (function.logs) — 함수가 충돌-루핑 중일 수 있음 |
/api/auth/... | logs (insforge.logs) |
| 시스템 전체 스파이크 중 모든 경로 | metrics (--range 1h) |
작은 인스턴스에서 관련 없는 경로에 걸친 504: OOM을 먼저 의심하십시오. 데이터베이스, 인증 및 함수를 모두 동시에 때리는 간헐적 게이트웨이 타임아웃은 가장 작은 인스턴스 크기에서 고전적인 메모리 부족 신호입니다: 커널이 Postgres를 죽이고, 모든 진행 중인 요청이 충돌 복구가 실행되는 동안 게이트웨이에서 타임아웃되며, 다음 부하 스파이크에서 이 현상이 반복됩니다.
빠른 경로: npx -y @insforge/cli diagnose incident (Platform 로그인 필요). 보고서는 전적으로 클라우드 측에 구축됩니다 — Prometheus 스크래핑 기록, 플랫폼 기록, 아웃바운드 데이터베이스 프로브 — 따라서 인스턴스가 다운되었거나 꼬여 있어도 작동합니다. 바로 diagnose logs가 응답을 중단하는 상황입니다. 판결(oom_likely, platform_operation_in_progress, paused_or_suspended, metrics_stopped, down_unknown, no_incident_detected)과 증거 및 권장 조치를 반환합니다. oom_likely는 이미 플랫폼 측에서 아래 재시작/메모리 상관 관계 확인이 통과되었음을 의미합니다.
명령어를 사용할 수 없는 경우(이전 CLI/백엔드, --api-key 링크 모드), logs (postgres.logs)에서 충돌-복구 후유증을 통해 수동으로 확인합니다 — "다른 서버 프로세스의 충돌로 인해 연결 종료" / "자동 복구 진행 중" — 5xx 버스트와 시간 상관 관계를 확인: 복구 증거만으로는 깨끗하지 않은 Postgres 재시작만 증명하므로, 타임스탬프가 일치해야 OOM이 주요 진단이 됩니다(references/metrics.md). 해당 증거가 있으면 해결책은 재시도 루프가 아닌 여유 공간 확보입니다:
- 인스턴스를 업그레이드하십시오 —
npx -y @insforge/cli projects upgrade-instance <type>(nano→micro→small→medium→large→xl), 또는 대시보드 → 프로젝트 설정 → 컴퓨팅 및 디스크. 무료 플랜인 경우 먼저 유료 플랜으로 업그레이드한 다음 크기를 선택하십시오. 크기 조정은 요금을 변경하며 CLI는 대화형 확인을 요청합니다 — 먼저 사용자의 승인을 받은 다음 CLI 수준의--yes(npx의-y는 npm의 설치 플래그이므로 확인 건너뛰기와 다름)를 사용하여 무인 실행하십시오. 크기 조정은 비동기적입니다 —projects get을 폴링하여operation_status가 해제될 때까지 기다린 후 인시던트가 해결되었음을 선언하십시오. - 크기 조정은 변경의 일부로 프로젝트를 재시작합니다. 이는 꼬인 상태도 정리합니다 — 별도의 사용자 대상 재시작은 없으며, 단순 재시작은 다음 스파이크가 다시 OOM을 일으키기까지 몇 분밖에 벌지 못합니다. 가장 작은 크기에서 실제 부하 하의 OOM은 일반적이고 예상되는 현상이며 버그가 아닙니다.
레시피: 출시 전 / 사전 예방적 감사
Platform 로그인이 필요합니다(
npx -y @insforge/cli login). 프로젝트가--api-key를 통해 연결된 경우 사용할 수 없습니다 — 이 경우 수동 감사를 위해db-health+policies+metadata로 대체하십시오.
- advisor — 전체 스캔 후
--severity critical을 먼저, 그 다음 경고. - advisor (
--category security) — 보안 문제에 집중합니다. policies (RLS 적용 범위) 및 metadata (인증 구성, 공개 버킷, 비밀 존재 여부)와 교차 검증합니다. - advisor (
--category performance) — db-health (slow-queries,index-usage,bloat)와 교차 검증합니다. - advisor (
--category health) — metrics (7d동안의 리소스 추세)와 교차 검증합니다. - 수정 후 advisor를 다시 실행하고 해결된 각
ruleId에 대해isResolved: true를 확인합니다.
레시피: 시작점을 모르겠음
- ai-assisted (
diagnose --ai "<error 또는 URL>") — 시작 가설을 얻습니다. - 검증 — 진단이 명명한 기본 요소를 다시 확인합니다. 제안보다 기본 요소 관찰을 신뢰하십시오.
근본 원인이 InsForge 자체인 경우
일부 진단은 프로젝트 구성 오류가 아닌 InsForge 측 결함에서 끝납니다: 플랫폼 버그 또는 회귀, 잘못 작동하는 SDK 호출, 관찰된 동작과 모순되는 문서 또는 스킬, 또는 누락된 기능. 디버그 세션은 정확히 이러한 것들이 확인되는 곳입니다 — 증거가 있는 동안 보고하십시오:
npx -y @insforge/cli feedback --json \
--type bug --component backend --area db \
--title "<한 줄 요약>" \
--detail "<발생 상황 vs 예상, 최소 재현 코드>" \
--command "<실패한 호출>" \
--error "<로그의 원문 오류>"
명백한 인시던트(가동 중단/성능 저하)의 경우 diagnose incident에도 동일한 detail을 포함할 수 있습니다 (옵션 --detail "..."). 피드백은 플랫폼 대시보드에서 수집되며 작업 항목을 생성합니다. 증거가 사라지기 전인 지금이 가장 좋은 시간입니다.